# 10x-app-builder/10x architecture

> Architecture diagram of the GitHub repository 10x-app-builder/10x, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/10x-app-builder/10x
- Repository: https://github.com/10x-app-builder/10x

## Overview

#### Purpose and Entry Points
10x is a native macOS 14+ SwiftUI application that turns conversational requirements into generated iOS SwiftUI projects, then builds and previews them in an iOS Simulator. The app entry point is `10x-macos/TenXAppApp.swift`; root navigation/tab ownership is `10x-macos/ContentView.swift`. The Xcode project is `10x-macos.xcodeproj/project.pbxproj`.

#### Application State and Workspace
`BuilderViewModel` is the central observable state machine for a project workspace: chats, generation lifecycle, project mode, preview, production/review flows, and persistence coordination. Its split extensions isolate major workflow domains while sharing project state.
- `10x-macos/ViewModels/BuilderViewModel.swift`
- `10x-macos/ViewModels/BuilderViewModel+Generation.swift`
- `10x-macos/ViewModels/BuilderViewModel+Projects.swift`

The UI is SwiftUI and organized around home/project selection, builder chat, and preview panels:
- `10x-macos/Views/HomeView.swift`
- `10x-macos/Views/BuilderView.swift`
- `10x-macos/Views/Preview/PreviewPanelView.swift`

#### Generation Agent Boundary
The client runs the agentic loop locally. A user message reaches the view model, which invokes `GenerationService`; streamed model events and tool calls are converted into workspace/chat state. Prompts distinguish plan versus build behavior, while tool definitions constrain callable local capabilities.
- `10x-macos/Services/Builder/GenerationService.swift`
- `10x-macos/Services/Builder/BuilderPrompts.swift`
- `10x-macos/Services/Builder/BuilderToolDefinitions.swift`

The remote boundary is a thin HTTP API/proxy rather than direct model integration. `APIClient` handles regular and streaming requests; stream payloads map into builder event models.
- `10x-macos/Services/APIClient.swift`
- `10x-macos/Models/BuilderStreamEvent.swift`
- `10x-macos/Models/BuilderChat.swift`

#### Local Tool Execution and Project Files
Tool calls cross from model-directed intent to privileged local filesystem/process operations through `ToolExecutor`. This layer performs generated-source mutation/search and supports build-fix/context workflows; generated project metadata describes workspace and dependency/environment state.
- `10x-macos/Services/Builder/ToolExecutor.swift`
- `10x-macos/Services/Builder/BuilderBuildFixSupport.swift`
- `10x-macos/Models/ProjectWorkspaceDescriptor.swift`

Local persistence is separate from remote API state: project messages, file trees, plans, and environment data are stored under each generated project’s `tenx/` area. Existing projects can enter through an importer and filesystem changes can be observed.
- `10x-macos/Services/LocalProjectStore.swift`
- `10x-macos/Services/ExistingProjectImporter.swift`
- `10x-macos/Services/FileSystemWatcher.swift`

#### Build and Simulator Preview Pipeline
Generated sources are scaffolded into an Xcode project through bundled XcodeGen, then compiled, installed, launched, and screen-captured using Xcode command-line/simulator services. Preview results return to the builder UI.
- `10x-macos/Services/XcodePreviewService.swift`
- `10x-macos/Services/SimulatorPreviewService.swift`
- `10x-macos/Models/PreviewScreenCapture.swift`

This is a hard runtime boundary: the host macOS app requires Xcode, an installed iPhone Simulator runtime, bundled `xcodegen`, and permission to manipulate local project files/processes.

#### Identity, Integrations, and Product Services
Authentication state is managed separately from workspace generation, with credentials persisted in Keychain and hosted identity provided by Supabase. Project generation can also provision/manage Supabase and Superwall integrations.
- `10x-macos/ViewModels/AuthManager.swift`
- `10x-macos/Services/AuthKeychainStore.swift`
- `10x-macos/Services/SupabaseManagementService.swift`
- `10x-macos/Services/SuperwallManagementService.swift`

Configuration supplies API, Supabase, hosted-download, and updater endpoints:
- `10x-macos/Config.swift`
- `10x-macos/Configuration/Development.xcconfig`
- `10x-macos/Configuration/Production.xcconfig`

#### Distribution and Evaluation
Sparkle updates are integrated into the macOS artifact; release CI builds, signs/notarizes, produces DMGs/appcasts, and deploys channel content to Vercel.
- `10x-macos/SparkleUpdater.swift`
- `.github/workflows/release-channel.yml`
- `scripts/release/publish-release.sh`

A separate Swift CLI drives end-to-end builder evaluation suites, reusing the builder stack rather than being part of the desktop runtime.
- `10x-evals/main.swift`
- `10x-evals/EvalRunner.swift`
- `evals/smoke-suite.yml`

Main entry points: [`10x-macos/ViewModels/BuilderViewModel.swift`](https://github.com/10x-app-builder/10x/blob/main/10x-macos/ViewModels/BuilderViewModel.swift) (Builder workspace), [`10x-macos/Services/Builder/GenerationService.swift`](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/Builder/GenerationService.swift) (Generation service), [`10x-macos/Services/Builder/ToolExecutor.swift`](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/Builder/ToolExecutor.swift) (Tool executor), [`10x-macos/Services/LocalProjectStore.swift`](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/LocalProjectStore.swift) (Local project store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["macOS App"]
  node_app["10x App<br/>SwiftUI entry<br/>[TenXAppApp.swift]"]
  node_navigation["Root navigation<br/>SwiftUI shell<br/>[ContentView.swift]"]
  node_workspace["Builder workspace<br/>observable state"]
  node_builder_ui["Builder UI<br/>SwiftUI view<br/>[BuilderView.swift]"]
  node_preview_ui["Preview panel<br/>SwiftUI view"]
  node_auth["Auth manager<br/>identity state<br/>[AuthManager.swift]"]
end

subgraph group_agent["Generation Agent"]
  node_generation["Generation service<br/>agent loop"]
  node_prompts_tools["Agent prompts &amp; tools<br/>agent contract"]
  node_api["API client<br/>HTTP streaming client<br/>[APIClient.swift]"]
  node_events["Chat stream events<br/>event models"]
end

subgraph group_local["Local Project Runtime"]
  node_executor["Tool executor<br/>privileged local tools<br/>[ToolExecutor.swift]"]
  node_project_store[("Local project store<br/>workspace persistence")]
  node_importer["Project importer<br/>filesystem intake"]
  node_watcher["Filesystem watcher<br/>change observer"]
  node_xcode_build["Xcode build pipeline<br/>scaffold and build"]
  node_simulator["Simulator preview<br/>device runtime"]
  node_capture["Preview capture<br/>preview model"]
end

subgraph group_platform["Identity &amp; Delivery"]
  node_keychain[("Keychain credentials<br/>credential store")]
  node_supabase["Supabase management<br/>integration service"]
  node_superwall["Superwall management<br/>integration service"]
  node_updater["Sparkle updater<br/>app updates"]
  node_release["Release channel<br/>CI publishing"]
end

subgraph group_evals["Evaluation"]
  node_eval_runner["Evaluation runner<br/>Swift CLI<br/>[EvalRunner.swift]"]
  node_smoke_suite["Smoke suite<br/>evaluation spec<br/>[smoke-suite.yml]"]
end

node_app -->|"starts"| node_navigation
node_navigation -->|"owns"| node_workspace
node_workspace -->|"drives"| node_builder_ui
node_workspace -->|"supplies preview"| node_preview_ui
node_workspace -->|"submits messages"| node_generation
node_generation -->|"uses"| node_prompts_tools
node_generation -->|"streams requests"| node_api
node_api -->|"maps payloads"| node_events
node_events -->|"updates chat state"| node_workspace
node_generation -->|"executes tool calls"| node_executor
node_executor -->|"reads and writes"| node_project_store
node_workspace -->|"persists workspace"| node_project_store
node_importer -->|"imports into"| node_project_store
node_watcher -->|"reports changes"| node_workspace
node_executor -->|"requests build"| node_xcode_build
node_xcode_build -->|"installs app"| node_simulator
node_simulator -->|"captures screen"| node_capture
node_capture -->|"returns preview"| node_workspace
node_auth -->|"persists credentials"| node_keychain
node_workspace -.->|"provisions integration"| node_supabase
node_workspace -.->|"provisions integration"| node_superwall
node_release -->|"publishes appcast"| node_updater
node_eval_runner -->|"reuses builder stack"| node_generation
node_smoke_suite -->|"defines scenarios"| node_eval_runner

click node_app "https://github.com/10x-app-builder/10x/blob/main/10x-macos/TenXAppApp.swift"
click node_navigation "https://github.com/10x-app-builder/10x/blob/main/10x-macos/ContentView.swift"
click node_workspace "https://github.com/10x-app-builder/10x/blob/main/10x-macos/ViewModels/BuilderViewModel.swift"
click node_builder_ui "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Views/BuilderView.swift"
click node_preview_ui "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Views/Preview/PreviewPanelView.swift"
click node_auth "https://github.com/10x-app-builder/10x/blob/main/10x-macos/ViewModels/AuthManager.swift"
click node_generation "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/Builder/GenerationService.swift"
click node_prompts_tools "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/Builder/BuilderPrompts.swift"
click node_api "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/APIClient.swift"
click node_events "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Models/BuilderStreamEvent.swift"
click node_executor "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/Builder/ToolExecutor.swift"
click node_project_store "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/LocalProjectStore.swift"
click node_importer "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/ExistingProjectImporter.swift"
click node_watcher "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/FileSystemWatcher.swift"
click node_xcode_build "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/XcodePreviewService.swift"
click node_simulator "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/SimulatorPreviewService.swift"
click node_capture "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Models/PreviewScreenCapture.swift"
click node_keychain "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/AuthKeychainStore.swift"
click node_supabase "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/SupabaseManagementService.swift"
click node_superwall "https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/SuperwallManagementService.swift"
click node_updater "https://github.com/10x-app-builder/10x/blob/main/10x-macos/SparkleUpdater.swift"
click node_release "https://github.com/10x-app-builder/10x/blob/main/.github/workflows/release-channel.yml"
click node_eval_runner "https://github.com/10x-app-builder/10x/blob/main/10x-evals/EvalRunner.swift"
click node_smoke_suite "https://github.com/10x-app-builder/10x/blob/main/evals/smoke-suite.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_navigation,node_workspace,node_builder_ui,node_preview_ui,node_auth toneBlue
class node_generation,node_prompts_tools,node_api,node_events toneAmber
class node_executor,node_project_store,node_importer,node_watcher,node_xcode_build,node_simulator,node_capture toneMint
class node_keychain,node_supabase,node_superwall,node_updater,node_release toneRose
class node_eval_runner,node_smoke_suite toneIndigo
```

## Components

### macOS App

- [10x App](https://github.com/10x-app-builder/10x/blob/main/10x-macos/TenXAppApp.swift): SwiftUI entry · `10x-macos/TenXAppApp.swift`
- [Root navigation](https://github.com/10x-app-builder/10x/blob/main/10x-macos/ContentView.swift): SwiftUI shell · `10x-macos/ContentView.swift`
- [Builder workspace](https://github.com/10x-app-builder/10x/blob/main/10x-macos/ViewModels/BuilderViewModel.swift): observable state · Owns chats, generation, projects, preview, and review state. · `10x-macos/ViewModels/BuilderViewModel.swift`
- [Builder UI](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Views/BuilderView.swift): SwiftUI view · `10x-macos/Views/BuilderView.swift`
- [Preview panel](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Views/Preview/PreviewPanelView.swift): SwiftUI view · `10x-macos/Views/Preview/PreviewPanelView.swift`
- [Auth manager](https://github.com/10x-app-builder/10x/blob/main/10x-macos/ViewModels/AuthManager.swift): identity state · `10x-macos/ViewModels/AuthManager.swift`

### Generation Agent

- [Generation service](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/Builder/GenerationService.swift): agent loop · Streams model-directed plans, builds, and tool calls into workspace state. · `10x-macos/Services/Builder/GenerationService.swift`
- [Agent prompts & tools](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/Builder/BuilderPrompts.swift): agent contract · Defines plan/build behavior and permitted local capabilities. · `10x-macos/Services/Builder/BuilderPrompts.swift`
- [API client](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/APIClient.swift): HTTP streaming client · `10x-macos/Services/APIClient.swift`
- [Chat stream events](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Models/BuilderStreamEvent.swift): event models · `10x-macos/Models/BuilderStreamEvent.swift`

### Local Project Runtime

- [Tool executor](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/Builder/ToolExecutor.swift): privileged local tools · Mutates and searches generated sources for build and context workflows. · `10x-macos/Services/Builder/ToolExecutor.swift`
- [Local project store](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/LocalProjectStore.swift): workspace persistence · Stores messages, plans, file trees, and environment data under tenx/. · `10x-macos/Services/LocalProjectStore.swift`
- [Project importer](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/ExistingProjectImporter.swift): filesystem intake · `10x-macos/Services/ExistingProjectImporter.swift`
- [Filesystem watcher](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/FileSystemWatcher.swift): change observer · `10x-macos/Services/FileSystemWatcher.swift`
- [Xcode build pipeline](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/XcodePreviewService.swift): scaffold and build · Uses bundled XcodeGen and Xcode command-line services. · `10x-macos/Services/XcodePreviewService.swift`
- [Simulator preview](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/SimulatorPreviewService.swift): device runtime · Installs, launches, and captures the generated iOS app. · `10x-macos/Services/SimulatorPreviewService.swift`
- [Preview capture](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Models/PreviewScreenCapture.swift): preview model · `10x-macos/Models/PreviewScreenCapture.swift`

### Identity & Delivery

- [Keychain credentials](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/AuthKeychainStore.swift): credential store · `10x-macos/Services/AuthKeychainStore.swift`
- [Supabase management](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/SupabaseManagementService.swift): integration service · `10x-macos/Services/SupabaseManagementService.swift`
- [Superwall management](https://github.com/10x-app-builder/10x/blob/main/10x-macos/Services/SuperwallManagementService.swift): integration service · `10x-macos/Services/SuperwallManagementService.swift`
- [Sparkle updater](https://github.com/10x-app-builder/10x/blob/main/10x-macos/SparkleUpdater.swift): app updates · `10x-macos/SparkleUpdater.swift`
- [Release channel](https://github.com/10x-app-builder/10x/blob/main/.github/workflows/release-channel.yml): CI publishing · Builds, signs, notarizes, publishes DMGs and appcasts. · `.github/workflows/release-channel.yml`

### Evaluation

- [Evaluation runner](https://github.com/10x-app-builder/10x/blob/main/10x-evals/EvalRunner.swift): Swift CLI · Runs end-to-end builder evaluation suites outside the desktop runtime. · `10x-evals/EvalRunner.swift`
- [Smoke suite](https://github.com/10x-app-builder/10x/blob/main/evals/smoke-suite.yml): evaluation spec · `evals/smoke-suite.yml`

## Connections

- 10x App → Root navigation: starts
- Root navigation → Builder workspace: owns
- Builder workspace → Builder UI: drives
- Builder workspace → Preview panel: supplies preview
- Builder workspace → Generation service: submits messages
- Generation service → Agent prompts & tools: uses
- Generation service → API client: streams requests
- API client → Chat stream events: maps payloads
- Chat stream events → Builder workspace: updates chat state
- Generation service → Tool executor: executes tool calls
- Tool executor → Local project store: reads and writes
- Builder workspace → Local project store: persists workspace
- Project importer → Local project store: imports into
- Filesystem watcher → Builder workspace: reports changes
- Tool executor → Xcode build pipeline: requests build
- Xcode build pipeline → Simulator preview: installs app
- Simulator preview → Preview capture: captures screen
- Preview capture → Builder workspace: returns preview
- Auth manager → Keychain credentials: persists credentials
- Builder workspace → Supabase management: provisions integration
- Builder workspace → Superwall management: provisions integration
- Release channel → Sparkle updater: publishes appcast
- Evaluation runner → Generation service: reuses builder stack
- Smoke suite → Evaluation runner: defines scenarios