AirCoding/AirPlan/docs/architecture/solution-architecture.md

Solution Architecture

Date: 2026-05-27 Status: Formal V1 architecture derived from AirCoding Architecture Baseline V1

1. Overview

AirCoding is a self-owned local AI coding agent/runtime. It is not a Claude Code plugin wrapper. The product provides a Claude Code-quality execution layer, OpenCode/OpenTUI-inspired terminal UI, project-local session persistence, multi-agent orchestration, and language/toolchain capability packages.

The V1 architecture is Linux-first, TypeScript/Bun-based, event-driven, and project-local by default. C++ is the first deep language profile, while the runtime remains language-agnostic through toolchain-* capability packages.

Core value path:

User requirement
  → Main Agent clarification and routing
  → Architecture Designer for design/interface decisions
  → Scheduler task graph and wave planning
  → Executor/Reviewer/Debugger/Compactor/ExperienceMiner workers
  → ToolRegistry + PermissionEngine + EventStore
  → project-local DB/artifacts/evidence
  → TUI/HUD ProjectionStore

2. Architecture Sources of Truth

This document summarizes the formal architecture. Detailed V1 baselines remain authoritative for implementation contracts.

Precedence rule:

1. interface-contracts-v1.md wins for TypeScript public interface shape.
2. db-schema-v1.md wins for SQLite persistence shape.
3. event-registry-v1.md wins for event names and payloads.
4. tool-registry-v1.md wins for tool names and tool I/O schemas.
5. runtime-semantics-v1.md wins for cross-cutting runtime behavior.
6. c4/module.md and c4/code-view.md win for package/component boundaries.
7. ADR files win for accepted design decisions they explicitly cover.
8. baselineV1.md remains the narrative baseline and decision index.

Area	Source
Overall baseline	AirPlan/docs/architecture/baselineV1.md
Interface contracts	AirPlan/docs/architecture/interface-contracts-v1.md
Runtime semantics	AirPlan/docs/architecture/runtime-semantics-v1.md
C4/module/code view	AirPlan/docs/architecture/c4/module.md, AirPlan/docs/architecture/c4/code-view.md
DB schema	AirPlan/docs/architecture/db-schema-v1.md
Event registry	AirPlan/docs/architecture/event-registry-v1.md
Tool registry	AirPlan/docs/architecture/tool-registry-v1.md
Scheduler state machine	AirPlan/docs/architecture/scheduler-state-machine-v1.md
Prompt layering	AirPlan/docs/architecture/prompt-layering-v1.md
Provider matrix	AirPlan/docs/architecture/provider-capability-matrix-v1.md
Error taxonomy	AirPlan/docs/architecture/error-taxonomy-v1.md
Artifact naming	AirPlan/docs/architecture/artifact-naming-v1.md
Scope escalation	AirPlan/docs/architecture/scope-escalation-v1.md
Security model	AirPlan/docs/architecture/security-model-v1.md
Capability trust	AirPlan/docs/architecture/capability-trust-v1.md
Platform matrix	AirPlan/docs/architecture/cross-platform-matrix-v1.md

3. Architectural Principles

1. Execution quality follows Claude Code. File edits are read-before-edit, exact, conservative, small, and verified before completion.
2. OpenCode is a UI/runtime reference, not a business-state dependency. Reuse visual patterns and OpenTUI/Solid primitives, not OpenCode's session/sync state model.
3. Project-local source of truth. Session state, artifacts, backups, and project rules live under project .air/.
4. Events drive live behavior; SQLite drives recovery. EventBus is live transport; domain tables and durable events are the source of truth.
5. Workers are isolated child processes. Executor, Reviewer, Debugger, Compactor, and ExperienceMiner run as independent Bun processes over NDJSON IPC.
6. Main Agent remains responsive. Long-running background work is delegated to Scheduler/workers.
7. Architecture changes are explicit. Implementation-only changes may continue silently; interface/architecture/product changes route through Architecture Designer and/or user confirmation.
8. Tool/capability boundaries are permissioned. Built-in and future plugin tools all pass through ToolRegistry and PermissionEngine.
9. Provider boundary is isolated. Internal messages are Anthropic canonical; adapters convert at provider boundary.
10. Evidence is first-class. Build/test/debug/review outputs become artifacts and evidence refs before completion claims.

4. Major Containers

CLI Container

Package: packages/cli

Responsibilities:

• command entrypoint
• startup and first-run initialization
• Doctor invocation
• project discovery and .air initialization
• resource loading
• TUI/runtime bootstrap

Interfaces:

• CLI commands
• local filesystem
• runtime service initialization

TUI/HUD Container

Package: packages/tui

Responsibilities:

• OpenTUI/Solid user interface
• Main Agent conversation surface
• progress, task, agent, diff, and evidence display
• permission prompts and blocker reports
• HUD/statusline projection

Interfaces:

• ProjectionStore read API
• Main Agent UI channel
• Permission prompt UI

Constraints:

• TUI consumes ProjectionStore only.
• TUI does not query SQLite or EventBus directly.
• TUI does not own scheduling state.

Runtime Container

Package: packages/runtime

Responsibilities:

• Main Agent orchestration shell
• Architecture Designer integration
• Scheduler
• child process management
• EventBus and EventStore
• SessionStore/domain repositories
• ToolRegistry
• PermissionEngine
• CapabilityRegistry
• ContextAssembler
• ArtifactStore and EvidenceStore
• ProjectionStore producer side

Interfaces:

• packages/contracts
• packages/llm
• packages/toolchain-*
• SQLite
• project filesystem
• child process stdio IPC

LLM Container

Package: packages/llm

Responsibilities:

• provider configuration
• provider adapters
• Anthropic canonical message handling
• OpenAI/OpenRouter/ollama/custom endpoint conversion
• capability matrix validation
• streaming/tool-use conversion
• token counting hooks where available

Interfaces:

• ProviderAdapter API
• ProviderCapabilityMatrix
• runtime LLM request API

Toolchain C++ Container

Package: packages/toolchain-cpp

Responsibilities:

• C++ project detection
• CMake configure/build orchestration
• Ninja-first, Make fallback strategy
• CTest/GoogleTest execution
• cppcheck static analysis
• clangd CLI queries
• compiler/linker diagnostic parsing
• build/test/debug evidence production

Interfaces:

• Capability manifest
• ToolRegistry tools under cpp.*
• shell command runner
• diagnostics/artifacts/evidence stores

Contracts Container

Package: packages/contracts

Responsibilities:

• compileable shared TypeScript interfaces
• RuntimeEvent, TaskSpec, WorkerResult, ToolDefinition, ArtifactRef, EvidenceRef
• error, provider, project, IPC, UI types

Dependency rule:

• All packages may depend on contracts.
• contracts must not depend on domain implementation packages.

5. Runtime Agents

Main Agent

User-facing coordinator. It handles conversation, progress summaries, requirement changes, direct foreground tasks, and escalation presentation. It does not perform long-running background work.

Architecture Designer

Owns architecture planning, impact assessment, ADR/C4/plan/todo alignment, and design/interface change review. It may edit planning/architecture documents, not implementation code.

Scheduler

Owns TaskGraph loading, wave planning, dependency handling, write-area conflict handling, retry strategy, child worker dispatch, heartbeat monitoring, merge coordination, and restart recovery.

Executor

Performs scoped implementation/build/test tasks with Claude Code-style execution discipline and structured WorkerResult output.

Reviewer

Read-only reviewer for correctness, security, scope control, architecture compliance, and evidence sufficiency. It produces review reports and follow-up tasks.

Debugger

Diagnoses failures using logs, diagnostics, artifacts, command output, GUI/network evidence, and may fix only within assigned write scope.

Compactor

Performs copy-on-write context compaction. It produces summaries while preserving original messages for explicit backtracking.

ExperienceMiner

Extracts project rules, skill candidates, and debug knowledge from verified repeated patterns and evidence.

6. Data Architecture

Project layout:

<project>/.air/
  shared/
    project.json
    permissions.yaml
    compaction-rules.md
    rules/
    plan/
  local/
    sessions/<session-id>/
      session.db
      artifacts/
    backups/
    debug-records.db
    learned-memory.db
    workspaces/
    tmp/
    locks/

Session DB path:

<project>/.air/local/sessions/<session-id>/session.db

Core data groups:

Group	Tables
session/conversation	sessions, messages, message_drafts, summaries
orchestration	events, tasks, task_dependencies, task_attempts, agents, workspaces
execution evidence	tool_runs, command_runs, artifacts, diagnostics, evidence_refs
UI recovery	ui_state
schema	schema_meta

SQLite V1 settings:

PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA foreign_keys = OFF;

Durable event insert and corresponding domain table update must be in the same transaction.

7. Control Flow Architecture

Startup Flow

CLI starts
  → detect platform and config
  → load resources/prompts/capabilities
  → open or initialize project .air
  → run read-only Doctor
  → open session DB
  → hydrate ProjectionStore from DB
  → start TUI/Main Agent/runtime services

Normal Execution Flow

User request
  → Main Agent classifies intent
  → direct answer or architecture/task planning
  → Scheduler creates/loads TaskGraph
  → ContextAssembler builds agent context
  → Scheduler dispatches child worker over NDJSON IPC
  → worker uses ToolRegistry
  → ToolRegistry enforces PermissionEngine
  → tools emit events/artifacts/evidence
  → worker returns WorkerResult
  → Scheduler retries/merges/reviews/continues
  → Main Agent reports outcome

Requirement Change Flow

User changes requirement
  → requirement.changed event
  → Scheduler pauses affected work
  → Architecture Designer assesses if needed
  → implementation-level change continues silently
  → architecture/product-level change routes to user confirmation/replan

Recovery Flow

Process/session restarts
  → open session DB
  → load running/interrupted tasks and agents
  → inspect child process liveness when possible
  → emit agent.lost/task.failed or reconnect/resume
  → preserve unmerged workspaces
  → rebuild Scheduler queues
  → hydrate ProjectionStore

8. Tool and Capability Architecture

ToolRegistry provides stable schema-validated built-ins:

fs.*, shell.*, git.*, project.*, cpp.*, debug.*,
gui.*, network.*, artifact.*, context.*, permission.*, doctor.*

CapabilityRegistry adds built-in and future plugin capabilities through manifests. Capability dependencies are declared in manifests but installed/fixed by Doctor, never by arbitrary plugin scripts.

Every tool call follows:

model/agent request
  → schema validation
  → PermissionEngine evaluation
  → tool execution
  → tool/command/artifact/evidence events
  → structured ToolResult

9. Prompt and Provider Architecture

ContextAssembler emits Anthropic canonical messages with L0-L9 layers:

runtime invariant
role/mode
safety and permission policy
project rules/user preferences
architecture baseline/current plan
task spec/acceptance criteria
relevant code/artifacts/evidence
recent conversation/decision context
tool result history/diagnostics
immediate instruction

Provider adapters convert canonical messages at the LLM boundary. Conversion omissions are recorded. Required unsupported capabilities block before model call.

Model selection is capability-based and can be Scheduler-forced or agent-selected within allowed constraints.

10. Security Architecture

Security boundary summary:

• LLM output is untrusted until validated.
• Tools are the only path to filesystem/shell/network effects.
• PermissionEngine evaluates all writes, execution, network, system-sensitive, and credential access.
• Symlinks are resolved by realpath before risk classification.
• .git/ is protected by default.
• Build directories are allowed project write areas.
• Project-outside writes require backup.
• Credentials and system-sensitive operations require explicit confirmation.
• No automatic upload of logs, artifacts, debug knowledge, or doctor bundles.

11. Platform Architecture

V1.0.0 Alpha is Linux-first:

Platform	Support
Linux x86_64	tier 1
Linux arm64	tier 2
WSL2	tier 2
macOS	experimental
Windows native	experimental/post-MVP

Shell/process/C++ tooling in V1.0.0 Alpha targets POSIX-like Linux behavior.

12. Quality and Validation Architecture

Validation layers:

unit tests → integration fixture replay → real LLM E2E release gate

Execution completion requires evidence appropriate to the task:

• build command result
• test command result
• static analysis result where configured
• debug evidence where failures occur
• review report for significant changes
• artifact/evidence refs for claims

Release gate for tier-1 Linux must cover startup, project init, child IPC, session DB, artifacts/events, C++ configure/build/test, TUI startup, and real LLM E2E behavior.

13. Key Risks and Mitigations

Risk	Mitigation
Execution quality below Claude Code	Align edit primitives, tool lifecycle, read-before-edit, verification discipline
Context explosion	copy-on-write compaction, ContextAssembler budgets, artifact refs
Scheduler complexity	V1 state machine and V1.0.0 Alpha cut line; advanced optimization deferred
Tool/plugin safety	ToolRegistry + PermissionEngine + capability trust model
Provider feature mismatch	Provider capability matrix and conversion report
Lost worker/process	heartbeat, task attempts, restart recovery
Merge conflicts across parallel workers	write-area planning, worktrees, merge events, repair/escalation
Debug evidence too large/noisy	artifact naming/layout, evidence refs, summaries
Platform drift	Linux tier-1 release matrix and Doctor platform report

14. V1.0.0 Alpha Architecture Boundaries

In scope for V1.0.0 Alpha:

Bun monorepo
contracts package
runtime services
project-local SQLite/artifacts
EventStore/EventBus/ProjectionStore
Main Agent shell
Scheduler/worker IPC
ToolRegistry/PermissionEngine
complete C++ development workflow
local/built-in plugin and capability foundation
TUI/HUD startup and projections
provider adapters
Doctor read-only/fix framework
GUI/network evidence tools
release gate and binary tarball packaging

Deferred beyond V1.0.0 Alpha:

third-party plugin registry/signing
container sandboxing
advanced semantic merge
multi-machine scheduling
Windows-native deep support
production-grade bitmap image generation providers
browser/computer-use automation
learned retry optimizer