MVVM with SwiftUI is Apple's recommended pattern. It keeps views declarative, ViewModels testable, and avoids the complexity of third-party frameworks. For Archon's scope, MVVM provides the right balance of structure and simplicity.

Protocol-oriented design enables mock injection for unit tests and SwiftUI previews. ViewModels don't know or care whether they're talking to a real server or a mock — they just use the protocol. This makes every ViewModel fully testable without network calls.

Currently, Archon requires a network connection for core features (AI chat, project sync). Failed network requests show error states with retry options. A future version may add offline caching for project files using local persistence.

Swift 6 strict concurrency requires explicit actor isolation. ViewModels update @Published properties that drive UI, so they must run on the main actor. This prevents data races and ensures UI updates happen on the main thread.

Add a new TabItem in MainTabView.swift, create the ViewModel and View following conventions, and wire the API client. See Adding Features for the full walkthrough.

Add a method to APIClient and MockAPIClient that calls request() with the appropriate method, path, and body. If it's a new resource, add the Codable model to Models/ first.

The APIClient maps HTTP status codes to APIError cases. ViewModels catch these and set @Published errorMessage properties, which views display as alert banners or inline errors.

When a request returns 401, the client attempts a silent token refresh using the stored refresh token. If refresh succeeds, the original request is retried. If refresh fails, the user is redirected to the sign-in screen.

Supabase (PostgreSQL) uses snake_case for column names. Swift conventions use camelCase. The shared JSONDecoder with .convertFromSnakeCase handles the mapping automatically — you never need to use CodingKeys for standard properties.

Use MockAPIClient's requestStream() method. Configure it with an array of Data chunks that simulate the SSE event stream. The ViewModel processes these the same way as real server events.

In Xcode: Cmd + U. From the terminal: xcodebuild test -project Archon.xcodeproj -scheme Archon -destination 'platform=iOS Simulator,name=iPhone 16'. See Testing guide.

Test the ViewModel (happy path, error path, edge cases), model decoding (against fixture JSON), and the API client method (correct request construction). UI tests are optional but welcome for critical flows.

Add a property to MockAPIClient (e.g., widgetsToReturn) and handle the corresponding path in the request() method. Then set the property in your test's setUp() or test method.

Yes, using ViewInspector or Xcode's built-in UI testing. For most cases, testing the ViewModel is sufficient since views are thin and declarative. Focus view tests on complex layout logic or accessibility.

The GitHub Actions workflow runs all tests on every PR. See .github/workflows/test.yml for the configuration. Tests must pass before merging.

Fork the repo, create a feature branch, make your changes, and open a PR. See Contributing guide for the full process, code style rules, and PR template.

Use feature/short-description, fix/short-description, or docs/short-description. Keep it lowercase with hyphens. Example: feature/add-widget-screen.

Absolutely. Those are specifically scoped for new contributors. Comment on the issue to let others know you're working on it, then submit a PR when ready.

Standard Swift style enforced by SwiftLint. No force unwraps in production code. Meaningful variable names. Keep functions under 40 lines. See Contributing guide for the full style guide.

Typically 1-3 business days for initial review. Simple fixes may be reviewed same-day. For larger features, expect iterative feedback over a few days.