✦
┌─────────┐ │ View │ └────┬────┘ │ ┌────▼────┐ │ViewModel│ └────┬────┘ │ ┌────▼────┐ │ Service │ └─────────┘

Architecture Overview

MVVM pattern with SwiftUI, async/await, and Supabase.

╔═══════════╗ ║ ARCHON ║ ╠═══════════╣ ║ SwiftUI ║ ║ MVVM ║ ║ Async ║ ╚═══════════╝
Developer Docs Archon iOS · Swift · SwiftUI API v1

Architecture Overview

MVVM pattern with SwiftUI, async/await, and Supabase.

MVVM Architecture

Archon uses a clean MVVM (Model-View-ViewModel) architecture with SwiftUI for the view layer and async/await for all asynchronous operations.

┌──────────────────────────────────────────────────────────┐
│                      ARCHON MVVM                         │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────────────────────────────────────────┐     │
│  │                   SwiftUI Views                 │     │
│  │  (Pure, declarative — no business logic)        │     │
│  └────────────────────┬────────────────────────────┘     │
│                       │ @StateObject / @ObservedObject    │
│  ┌────────────────────▼────────────────────────────┐     │
│  │                  ViewModels                     │     │
│  │  (ObservableObject, drives UI state)            │     │
│  │  - @Published properties for bindings           │     │
│  │  - async methods for actions                    │     │
│  └────────────────────┬────────────────────────────┘     │
│                       │ Protocol injection                │
│  ┌────────────────────▼────────────────────────────┐     │
│  │              Service Layer (API)                │     │
│  │  (APIClientProtocol — real or mock)             │     │
│  └────────────────────┬────────────────────────────┘     │
│                       │ HTTP / Supabase                   │
│  ┌────────────────────▼────────────────────────────┐     │
│  │               Supabase Backend                  │     │
│  │  (PostgreSQL, Auth, Realtime, Edge Functions)   │     │
│  └─────────────────────────────────────────────────┘     │
│                                                          │
└──────────────────────────────────────────────────────────┘

Data Flow

Data flows unidirectionally through the architecture:

1. User Action
A button tap or gesture in the SwiftUI View triggers a method on the ViewModel.
2. ViewModel Processes
The ViewModel calls the API service via APIClientProtocol, awaits the response, and updates @Published properties.
3. View Reacts
SwiftUI observes the @Published changes and re-renders the affected views automatically.

App Lifecycle

Archon follows the standard SwiftUI App lifecycle:

Launch
ArchonApp.swift creates the root ContentView and injects the API client and authentication state.
Authentication Check
On launch, the app checks for a stored session in the iOS Keychain. If valid, it proceeds to the main tab interface. If not, it presents the onboarding/auth flow.
Main Interface
The main TabView loads with the Builder, Projects, and Settings tabs. Each tab has its own ViewModel.

Supabase Integration

Archon uses Supabase as its backend, providing:

🔐
Authentication
Email/password and Apple Sign In via Supabase Auth. Sessions stored in iOS Keychain.
🗄
Database
PostgreSQL for projects, tasks, chat messages, and user profiles. Row-level security enforced.
⚡
Edge Functions
Server-side AI processing, model routing, and credit management via Deno Edge Functions.
🔄
Realtime
WebSocket subscriptions for live task progress updates and chat streaming.

Key Patterns

Protocol-Oriented API
All API communication goes through APIClientProtocol, enabling mock injection for tests and previews.
Async/Await Everywhere
No completion handlers. All network calls, database operations, and auth flows use structured concurrency.
Codable Models
All data models conform to Codable with consistent snake_case ↔ camelCase key mapping.
Dependency Injection
ViewModels receive their dependencies (API client, auth manager) via init parameters, not singletons.

Project Structure

Archon/
├── App/
│   └── ArchonApp.swift
├── Models/
│   ├── ArchonProject.swift
│   ├── ArchonTask.swift
│   ├── ChatMessage.swift
│   ├── TaskEvent.swift
│   └── APIError.swift
├── ViewModels/
│   ├── BuilderViewModel.swift
│   ├── ProjectsViewModel.swift
│   └── SettingsViewModel.swift
├── Views/
│   ├── MainTabView.swift
│   ├── Builder/
│   ├── Projects/
│   └── Settings/
├── Services/
│   ├── APIClientProtocol.swift
│   ├── APIClient.swift
│   ├── MockAPIClient.swift
│   └── AuthManager.swift
├── Utilities/
│   ├── KeychainHelper.swift
│   └── DateFormatter+.swift
└── Resources/
    └── Assets.xcassets