file-structure

File Structure Rules

Line Limit

• Target: 150 lines per file — aim for this
• Hard limit: 200 lines — files exceeding 200 lines MUST be split using extensions (View+Sections.swift)
• Files between 150-200 lines are acceptable if splitting would hurt readability

Body as Table of Contents

The body property should read like a table of contents — only referencing computed properties, not containing implementation:

// Good
var body: some View {
    VStack {
        headerSection
        contentSection
        footerSection
    }
}

// Bad — implementation directly in body
var body: some View {
    VStack {
        HStack {
            Image(systemName: "person")
            Text(user.name)
                .font(AppTheme.Fonts.headline)
            Spacer()
            Button("Edit") { showEdit = true }
        }
        // ... 80+ more lines
    }
}

Extension Splitting Pattern

When a view grows beyond 150 lines, split into extensions by section:

// ProfileView.swift — main file
struct ProfileView: View {
    @State var viewModel: ProfileViewModel

    var body: some View {
        ScrollView {
            headerSection
            statsSection
            settingsSection
        }
    }
}

// ProfileView+Sections.swift — extracted sections
extension ProfileView {
    var headerSection: some View { ... }
    var statsSection: some View { ... }
    var settingsSection: some View { ... }
}

Directory Structure

Models/              → Data model structs (with static sampleData)
Shared/              → Shared utility types (e.g. Loadable.swift)
Config/              → App configuration (e.g. AppConfig.swift with API keys, endpoints)
Repositories/<Entity>/ → Repository protocols + concrete implementations, grouped by entity
                       (e.g. Repositories/Users/UserRepository.swift,
                             Repositories/Users/LocalUserRepository.swift)
                       External-service repositories only when that service is explicitly configured
Theme/               → AppTheme.swift only
Services/<Domain>/   → Domain services (Auth, Networking, etc.) — NOT in Features/
Features/<Name>/     → Co-locate View + ViewModel (e.g. Features/TodoList/TodoListView.swift)
Features/Common/     → Shared reusable views used by multiple features
App/                 → @main app entry point only