# coleam00/archon architecture

> Architecture diagram of the GitHub repository coleam00/archon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coleam00/archon
- Repository: https://github.com/coleam00/archon
- Video tour (about a minute): https://gitdiagram.com/coleam00/archon/video

## Overview

#### Purpose and Entry Points
Archon is a Bun/TypeScript monorepo for deterministic AI-coding workflows: YAML-defined DAGs combine AI-agent prompts with bash, scripts, loops, approvals, and Git operations. Primary user entry points are the CLI (`packages/cli/src/cli.ts`), HTTP server (`packages/server/src/index.ts`), and React dashboard (`packages/web/src/main.tsx`). Project-local workflow assets live under `.archon/workflows/` and `.archon/commands/`.

#### Interaction and Adapter Boundary
Inputs arrive from CLI, web, and chat/forge integrations, normalized behind adapter packages before reaching core orchestration. The server exposes REST/webhook routes and bridges persisted workflow updates to the web transport; chat adapters translate Slack, Telegram, Discord, GitHub, Gitea, and GitLab semantics.
- `packages/adapters/src/index.ts`
- `packages/server/src/routes/api.ts`
- `packages/server/src/routes/webhooks.ts`

#### Core Orchestration
The core orchestrator owns conversation context, session lifecycle, prompt construction, command dispatch, agent invocation, and message delivery. It is the central control boundary: adapters should not directly manage provider processes or workflow state.
- `packages/core/src/orchestrator/orchestrator.ts`
- `packages/core/src/orchestrator/prompt-builder.ts`
- `packages/core/src/handlers/command-handler.ts`

#### Workflow Definition, Planning, and Execution
Workflow YAML is discovered from bundled, global, and repository locations; repository definitions can override defaults. Loader/validator stages expand includes, validate schemas and requirements, resolve node models/inputs/output references, then execute a dependency DAG with conditions, retries, subruns, loops, approvals, deterministic nodes, and emitted events.
- `packages/workflows/src/loader.ts`
- `packages/workflows/src/validator.ts`
- `packages/workflows/src/dag-executor.ts`

Bundled process templates are concrete product behavior, not merely examples: `.archon/workflows/defaults/archon-idea-to-pr.yaml`, `.archon/workflows/defaults/archon-fix-github-issue.yaml`, and corresponding reusable prompt commands in `.archon/commands/defaults/`.

#### AI Provider Runtime
A provider registry abstracts assistant-specific launch, configuration, capabilities, session continuation, native tools, MCP, structured output, and OAuth. Supported first-party implementations include Claude and Codex; community providers include Copilot, OpenCode, and Pi. Providers are typically local CLI/runtime integrations, while models and credentials are external services.
- `packages/providers/src/registry.ts`
- `packages/providers/src/claude/provider.ts`
- `packages/providers/src/codex/provider.ts`

#### Isolation and Git Boundary
Each run can execute against an isolated checkout. Isolation selects in-place or container backends and worktree providers; Git operations provide repository/branch/forge primitives. This boundary prevents concurrent workflow runs from modifying the same working tree and contains agent command execution.
- `packages/isolation/src/backend-router.ts`
- `packages/isolation/src/providers/worktree.ts`
- `packages/git/src/worktree.ts`

Docker-based execution is supported through `packages/isolation/docker/runner.Dockerfile`; deployment uses `docker-compose.yml` and `Dockerfile`.

#### Persistence, Identity, and Operations
Core persistence supports SQLite and PostgreSQL, recording codebases, conversations, messages, sessions, isolation environments, workflow runs/events, node sessions, and encrypted/provider credentials. Migrations define the durable compatibility contract. Server auth and GitHub-auth bootstrapping establish multi-user and external-forge boundaries.
- `packages/core/src/db/connection.ts`
- `packages/core/src/db/workflows.ts`
- `migrations/000_combined.sql`
- `packages/server/src/auth/instance.ts`
- `packages/server/src/github-auth-bootstrap.ts`

The dashboard consumes APIs and live run/event streams to provide chat, monitoring, workflow execution views, and visual authoring; it remains a client of server/core rather than an execution authority.
- `packages/web/src/App.tsx`
- `packages/web/src/components/workflows/WorkflowExecution.tsx`
- `packages/web/src/components/workflows/WorkflowBuilder.tsx`

Main entry points: [`packages/core/src/orchestrator/orchestrator.ts`](https://github.com/coleam00/archon/blob/dev/packages/core/src/orchestrator/orchestrator.ts) (Orchestrator), [`packages/workflows/src/dag-executor.ts`](https://github.com/coleam00/archon/blob/dev/packages/workflows/src/dag-executor.ts) (DAG Executor), [`packages/server/src/routes/api.ts`](https://github.com/coleam00/archon/blob/dev/packages/server/src/routes/api.ts) (API Routes), [`packages/providers/src/registry.ts`](https://github.com/coleam00/archon/blob/dev/packages/providers/src/registry.ts) (Provider Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry &amp; Integration"]
  node_cli["CLI<br/>[cli.ts]"]
  node_server["HTTP Server<br/>REST and webhook host<br/>[index.ts]"]
  node_web["Dashboard<br/>React client<br/>[main.tsx]"]
  node_api_routes["API Routes<br/>server routes<br/>[api.ts]"]
  node_webhook_routes["Webhook Routes<br/>server routes<br/>[webhooks.ts]"]
  node_adapters{{"Integration Adapters<br/>chat and forge adapters<br/>[index.ts]"}}
end

subgraph group_core["Core Control"]
  node_orchestrator{{"Orchestrator<br/>control boundary<br/>[orchestrator.ts]"}}
  node_prompt_builder["Prompt Builder<br/>prompt construction<br/>[prompt-builder.ts]"]
  node_command_handler["Command Handler<br/>command dispatch<br/>[command-handler.ts]"]
end

subgraph group_workflow["Workflow Engine"]
  node_workflow_loader["Workflow Loader<br/>definition discovery<br/>[loader.ts]"]
  node_workflow_validator["Workflow Validator<br/>planning validation<br/>[validator.ts]"]
  node_dag_executor{{"DAG Executor<br/>workflow runtime<br/>[dag-executor.ts]"}}
  node_bundled_workflows["Bundled Workflows<br/>YAML process templates"]
end

subgraph group_execution["Agent Execution"]
  node_provider_registry{{"Provider Registry<br/>AI provider abstraction<br/>[registry.ts]"}}
  node_claude_provider["Claude Provider<br/>provider implementation<br/>[provider.ts]"]
  node_codex_provider["Codex Provider<br/>provider implementation<br/>[provider.ts]"]
  node_isolation_router{{"Isolation Router<br/>execution isolation<br/>[backend-router.ts]"}}
  node_git_worktrees["Git Worktrees<br/>Git isolation primitive<br/>[worktree.ts]"]
end

subgraph group_state["State &amp; Operations"]
  node_persistence[("Core Persistence<br/>[connection.ts]")]
  node_workflow_store[("Workflow Run Store<br/>workflow persistence<br/>[workflows.ts]")]
  node_migrations["Database Migrations<br/>durable schema contract<br/>[000_combined.sql]"]
  node_auth["Server Auth<br/>identity and GitHub bootstrap<br/>[instance.ts]"]
end

node_cli -->|"commands"| node_orchestrator
node_web -->|"REST and live streams"| node_api_routes
node_server -->|"hosts"| node_api_routes
node_server -->|"hosts"| node_webhook_routes
node_api_routes -->|"normalizes input"| node_adapters
node_webhook_routes -->|"normalizes events"| node_adapters
node_adapters -->|"normalized interactions"| node_orchestrator
node_orchestrator -->|"builds prompts"| node_prompt_builder
node_orchestrator -->|"dispatches commands"| node_command_handler
node_command_handler -->|"starts workflows"| node_workflow_loader
node_bundled_workflows -->|"default definitions"| node_workflow_loader
node_workflow_loader -->|"loaded definitions"| node_workflow_validator
node_workflow_validator -->|"execution plan"| node_dag_executor
node_orchestrator -->|"invokes agents"| node_provider_registry
node_provider_registry -->|"selects"| node_claude_provider
node_provider_registry -->|"selects"| node_codex_provider
node_dag_executor -->|"AI nodes"| node_provider_registry
node_dag_executor -->|"isolated runs"| node_isolation_router
node_isolation_router -->|"worktree backend"| node_git_worktrees
node_orchestrator -->|"sessions and messages"| node_persistence
node_dag_executor -->|"runs and events"| node_workflow_store
node_workflow_store -->|"uses"| node_persistence
node_migrations -.->|"defines schema"| node_persistence
node_server -->|"authenticates users"| node_auth
node_api_routes -->|"run updates"| node_workflow_store

click node_cli "https://github.com/coleam00/archon/blob/dev/packages/cli/src/cli.ts"
click node_server "https://github.com/coleam00/archon/blob/dev/packages/server/src/index.ts"
click node_web "https://github.com/coleam00/archon/blob/dev/packages/web/src/main.tsx"
click node_api_routes "https://github.com/coleam00/archon/blob/dev/packages/server/src/routes/api.ts"
click node_webhook_routes "https://github.com/coleam00/archon/blob/dev/packages/server/src/routes/webhooks.ts"
click node_adapters "https://github.com/coleam00/archon/blob/dev/packages/adapters/src/index.ts"
click node_orchestrator "https://github.com/coleam00/archon/blob/dev/packages/core/src/orchestrator/orchestrator.ts"
click node_prompt_builder "https://github.com/coleam00/archon/blob/dev/packages/core/src/orchestrator/prompt-builder.ts"
click node_command_handler "https://github.com/coleam00/archon/blob/dev/packages/core/src/handlers/command-handler.ts"
click node_workflow_loader "https://github.com/coleam00/archon/blob/dev/packages/workflows/src/loader.ts"
click node_workflow_validator "https://github.com/coleam00/archon/blob/dev/packages/workflows/src/validator.ts"
click node_dag_executor "https://github.com/coleam00/archon/blob/dev/packages/workflows/src/dag-executor.ts"
click node_bundled_workflows "https://github.com/coleam00/archon/blob/dev/.archon/workflows/defaults/archon-idea-to-pr.yaml"
click node_provider_registry "https://github.com/coleam00/archon/blob/dev/packages/providers/src/registry.ts"
click node_claude_provider "https://github.com/coleam00/archon/blob/dev/packages/providers/src/claude/provider.ts"
click node_codex_provider "https://github.com/coleam00/archon/blob/dev/packages/providers/src/codex/provider.ts"
click node_isolation_router "https://github.com/coleam00/archon/blob/dev/packages/isolation/src/backend-router.ts"
click node_git_worktrees "https://github.com/coleam00/archon/blob/dev/packages/git/src/worktree.ts"
click node_persistence "https://github.com/coleam00/archon/blob/dev/packages/core/src/db/connection.ts"
click node_workflow_store "https://github.com/coleam00/archon/blob/dev/packages/core/src/db/workflows.ts"
click node_migrations "https://github.com/coleam00/archon/blob/dev/migrations/000_combined.sql"
click node_auth "https://github.com/coleam00/archon/blob/dev/packages/server/src/auth/instance.ts"

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_cli,node_server,node_web,node_api_routes,node_webhook_routes,node_adapters toneBlue
class node_orchestrator,node_prompt_builder,node_command_handler toneAmber
class node_workflow_loader,node_workflow_validator,node_dag_executor,node_bundled_workflows toneMint
class node_provider_registry,node_claude_provider,node_codex_provider,node_isolation_router,node_git_worktrees toneRose
class node_persistence,node_workflow_store,node_migrations,node_auth toneIndigo
```

## Components

### Entry & Integration

- [CLI](https://github.com/coleam00/archon/blob/dev/packages/cli/src/cli.ts): Bun CLI · Primary local user entry point. · `packages/cli/src/cli.ts`
- [HTTP Server](https://github.com/coleam00/archon/blob/dev/packages/server/src/index.ts): REST and webhook host · Serves APIs, webhooks, authentication, and live updates. · `packages/server/src/index.ts`
- [Dashboard](https://github.com/coleam00/archon/blob/dev/packages/web/src/main.tsx): React client · Chat, run monitoring, execution, and workflow authoring UI. · `packages/web/src/main.tsx`
- [API Routes](https://github.com/coleam00/archon/blob/dev/packages/server/src/routes/api.ts): server routes · `packages/server/src/routes/api.ts`
- [Webhook Routes](https://github.com/coleam00/archon/blob/dev/packages/server/src/routes/webhooks.ts): server routes · `packages/server/src/routes/webhooks.ts`
- [Integration Adapters](https://github.com/coleam00/archon/blob/dev/packages/adapters/src/index.ts): chat and forge adapters · Normalizes Slack, Telegram, Discord, and forge semantics. · `packages/adapters/src/index.ts`

### Core Control

- [Orchestrator](https://github.com/coleam00/archon/blob/dev/packages/core/src/orchestrator/orchestrator.ts): control boundary · Owns sessions, context, dispatch, agent invocation, and delivery. · `packages/core/src/orchestrator/orchestrator.ts`
- [Prompt Builder](https://github.com/coleam00/archon/blob/dev/packages/core/src/orchestrator/prompt-builder.ts): prompt construction · `packages/core/src/orchestrator/prompt-builder.ts`
- [Command Handler](https://github.com/coleam00/archon/blob/dev/packages/core/src/handlers/command-handler.ts): command dispatch · `packages/core/src/handlers/command-handler.ts`

### Workflow Engine

- [Workflow Loader](https://github.com/coleam00/archon/blob/dev/packages/workflows/src/loader.ts): definition discovery · Finds layered YAML definitions and expands includes. · `packages/workflows/src/loader.ts`
- [Workflow Validator](https://github.com/coleam00/archon/blob/dev/packages/workflows/src/validator.ts): planning validation · Validates requirements and resolves node references, models, and inputs. · `packages/workflows/src/validator.ts`
- [DAG Executor](https://github.com/coleam00/archon/blob/dev/packages/workflows/src/dag-executor.ts): workflow runtime · Runs dependency nodes, conditions, retries, loops, approvals, and subruns. · `packages/workflows/src/dag-executor.ts`
- [Bundled Workflows](https://github.com/coleam00/archon/blob/dev/.archon/workflows/defaults/archon-idea-to-pr.yaml): YAML process templates · Default idea-to-PR and issue-fix workflows are product behavior. · `.archon/workflows/defaults/archon-idea-to-pr.yaml`

### Agent Execution

- [Provider Registry](https://github.com/coleam00/archon/blob/dev/packages/providers/src/registry.ts): AI provider abstraction · Selects providers and manages capabilities, sessions, tools, MCP, and OAuth. · `packages/providers/src/registry.ts`
- [Claude Provider](https://github.com/coleam00/archon/blob/dev/packages/providers/src/claude/provider.ts): provider implementation · `packages/providers/src/claude/provider.ts`
- [Codex Provider](https://github.com/coleam00/archon/blob/dev/packages/providers/src/codex/provider.ts): provider implementation · `packages/providers/src/codex/provider.ts`
- [Isolation Router](https://github.com/coleam00/archon/blob/dev/packages/isolation/src/backend-router.ts): execution isolation · Selects in-place, container, and worktree execution backends. · `packages/isolation/src/backend-router.ts`
- [Git Worktrees](https://github.com/coleam00/archon/blob/dev/packages/git/src/worktree.ts): Git isolation primitive · Provides isolated repository and branch checkouts. · `packages/git/src/worktree.ts`

### State & Operations

- [Core Persistence](https://github.com/coleam00/archon/blob/dev/packages/core/src/db/connection.ts): SQLite and PostgreSQL data layer · Stores conversations, sessions, credentials, environments, workflow runs, and events. · `packages/core/src/db/connection.ts`
- [Workflow Run Store](https://github.com/coleam00/archon/blob/dev/packages/core/src/db/workflows.ts): workflow persistence · `packages/core/src/db/workflows.ts`
- [Database Migrations](https://github.com/coleam00/archon/blob/dev/migrations/000_combined.sql): durable schema contract · `migrations/000_combined.sql`
- [Server Auth](https://github.com/coleam00/archon/blob/dev/packages/server/src/auth/instance.ts): identity and GitHub bootstrap · `packages/server/src/auth/instance.ts`

## Connections

- CLI → Orchestrator: commands
- Dashboard → API Routes: REST and live streams
- HTTP Server → API Routes: hosts
- HTTP Server → Webhook Routes: hosts
- API Routes → Integration Adapters: normalizes input
- Webhook Routes → Integration Adapters: normalizes events
- Integration Adapters → Orchestrator: normalized interactions
- Orchestrator → Prompt Builder: builds prompts
- Orchestrator → Command Handler: dispatches commands
- Command Handler → Workflow Loader: starts workflows
- Bundled Workflows → Workflow Loader: default definitions
- Workflow Loader → Workflow Validator: loaded definitions
- Workflow Validator → DAG Executor: execution plan
- Orchestrator → Provider Registry: invokes agents
- Provider Registry → Claude Provider: selects
- Provider Registry → Codex Provider: selects
- DAG Executor → Provider Registry: AI nodes
- DAG Executor → Isolation Router: isolated runs
- Isolation Router → Git Worktrees: worktree backend
- Orchestrator → Core Persistence: sessions and messages
- DAG Executor → Workflow Run Store: runs and events
- Workflow Run Store → Core Persistence: uses
- Database Migrations → Core Persistence: defines schema
- HTTP Server → Server Auth: authenticates users
- API Routes → Workflow Run Store: run updates · Bridges persisted workflow updates to dashboard clients.
