workout-app

Architecture

High-level shape of the app. Read this when you’re about to make a structural decision; otherwise jump straight to the relevant folder README.

Layers

┌─────────────────────────────────────────────┐
│ Views  (Features/*/<Screen>View.swift)      │  SwiftUI, declarative
├─────────────────────────────────────────────┤
│ View Models  (*ViewModel.swift, @Observable)│  per-feature, when needed
├─────────────────────────────────────────────┤
│ Services  (protocol seams)                  │  FoodResolving, …
├─────────────────────────────────────────────┤
│ Persistence  (SwiftData @Model)             │  PersistenceController owns container
└─────────────────────────────────────────────┘

• Views read SwiftData via @Query for lists, push mutations through their view-model.
• View-models own free-text input state, Tasks for async work, and the imperative SwiftData writes (insert / update / delete).
• Services are protocols. Concretes are picked once, in App/AppEnvironment.swift.
• Persistence: a single ModelContainer (Services/Persistence/PersistenceController.swift). Both @Query and modelContext come from this container.

Navigation

No tab bar. RootView (in App/) holds a MenuDestination enum and swaps the visible feature screen based on what the user picks in the menu sheet. Each feature can host its own NavigationStack if it needs one — the root stays flat.

Backend wiring

Reference: BACKEND_SETUP.md.

iOS  ──► FoodResolving protocol  ──► (offline) MockFoodResolver
                                  ──► (configured) RemoteFoodResolver
                                            │
                                            ▼
                                   Supabase Edge Function
                                            │
                                            ▼
                                AI Gateway → LLM provider

iOS NEVER holds an LLM API key. The backend Edge Function:

1. Normalizes the input.
2. Looks up the canonical food in Postgres (full-text + pgvector).
3. Calls the AI only on miss.
4. Validates the AI’s JSON.
5. Caches the resolved food per 100g/100ml.
6. Returns the resolved nutrition.

Why SwiftData (not Core Data)

• Native, declarative, owns the schema in Swift code (no .xcdatamodeld artifact to manage in xcodegen).
• iOS 17+ requirement matches our deployment target.
• Migration story is acceptable for additive schema changes (which is most of the runway here).
• Tradeoff: less mature — for predicates we keep them simple. We use string-backed enums to avoid migration pain when adding cases.

Why no Combine

SwiftUI bindings + @Observable cover the reactive surface. Async work uses Task + async/await. There’s no need for Combine here.

Folder conventions

• One feature, one folder under Features/.
• One service area, one folder under Services/. Each has a protocol + at least one concrete (Mock + Live).
• Tests for a feature live in WorkoutAppTests/<Feature>Tests.swift.

Don’t

• Don’t introduce a tab bar.
• Don’t import Foundation networking from a feature view — go through a service.
• Don’t store nutrition values inline on the user — use UserProfile for targets, FoodLogEntry for actuals.
• Don’t deepen the navigation past one stack per feature.