Archon System Architecture and Package Reference

┌─────────────────────────────────────────────┐
│  Platform Adapters (Web UI, Telegram,       │
│         GitHub, Slack, Discord, CLI)        │
│   • IPlatformAdapter interface              │
│   • Web: SSE streaming + REST API           │
│   • Others: Platform-specific messaging     │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│            Orchestrator                     │
│   • Route slash commands → Command Handler  │
│   • Route AI queries → Assistant Clients    │
│   • Manage session lifecycle                │
│   • Stream responses back to platforms      │
│   • Emit workflow events to Web UI          │
└──────────────┬──────────────────────────────┘
               │
       ┌───────┼────────┐
       │       │        │
       ▼       ▼        ▼
┌───────────┐ ┌───────────────┐ ┌───────────────────┐
│ Command   │ │ AI Agent      │ │ Isolation         │
│ Handler   │ │ Providers     │ │ Providers         │
│           │ │               │ │                   │
│ (Slash    │ │ IAgent-       │ │ IIsolationProvider│
│ commands) │ │ Provider      │ │ (worktree, etc.)  │
└─────┬─────┘ └───────┬───────┘ └─────────┬─────────┘
      │               │                   │
      └───────────────┼───────────────────┘
                      ▼
┌─────────────────────────────────────────────┐
│    SQLite (default) / PostgreSQL (8 tables) │
│  • Codebases  • Conversations  • Sessions   │
│  • Isolation Envs • Workflow Runs           │
│  • Workflow Events • Messages               │
│  • Codebase Env Vars                        │
└─────────────────────────────────────────────┘

packages/
├── cli/            @archon/cli          Command-line interface
├── server/         @archon/server       HTTP server, REST API, Web adapter
├── core/           @archon/core         Shared business logic, DB, orchestrator
├── workflows/      @archon/workflows    Workflow engine (loader, executor, DAG)
├── providers/      @archon/providers    AI agent providers (Claude, Codex, Pi)
├── adapters/       @archon/adapters     Platform adapters (Slack, Telegram, GitHub, Discord)
├── isolation/      @archon/isolation    Worktree isolation types, providers, resolver
├── git/            @archon/git          Git operations — no @archon/* deps
├── paths/          @archon/paths        Path resolution, logger factory — zero @archon/* deps
└── web/            @archon/web          React frontend (Vite + Tailwind + shadcn/ui)

@archon/paths          (leaf — no @archon/* deps; pino + dotenv allowed)
    │
@archon/git            (depends on @archon/paths)
    │
@archon/isolation      (depends on @archon/git + @archon/paths)
@archon/providers      (AI SDK deps; exports contract subpath @archon/providers/types)
@archon/workflows      (depends on @archon/git + @archon/paths + @archon/providers/types)
    │
@archon/core           (depends on @archon/providers for AI)
    │
@archon/adapters       (depends on @archon/core)
    │
@archon/server         (depends on @archon/adapters; serves static @archon/web)
    │
@archon/cli            (depends on @archon/server for the serve command)

export interface IPlatformAdapter {
  sendMessage(conversationId: string, message: string, metadata?: MessageMetadata): Promise<void>;
  ensureThread(originalConversationId: string, messageContext?: unknown): Promise<string>;
  getStreamingMode(): 'stream' | 'batch';
  getPlatformType(): string;
  start(): Promise<void>;
  stop(): void;
  sendStructuredEvent?(conversationId: string, event: MessageChunk): Promise<void>;
  emitRetract?(conversationId: string): Promise<void>;
}

export interface IAgentProvider {
  sendQuery(
    prompt: string,
    cwd: string,
    resumeSessionId?: string,
    options?: SendQueryOptions
  ): AsyncGenerator<MessageChunk>;

  getType(): string;
  getCapabilities(): ProviderCapabilities;
}

export type MessageChunk =
  | { type: 'assistant'; content: string }
  | { type: 'system'; content: string }
  | { type: 'thinking'; content: string }
  | { type: 'result'; sessionId?: string; tokens?: TokenUsage; cost?: number; ... }
  | { type: 'rate_limit'; rateLimitInfo: Record<string, unknown> }
  | { type: 'tool'; toolName: string; toolInput?: Record<string, unknown>; toolCallId?: string }
  | { type: 'tool_result'; toolName: string; toolOutput: string; toolCallId?: string }
  | { type: 'workflow_dispatch'; workerConversationId: string; workflowName: string }

pending → running → completed
                 → failed → (resume skips completed, retries failed)
                 → skipped (when: condition false, or trigger_rule not met)
pending → (paused at approval gate) → resumed → running

remote_agent_codebases
├── id (UUID)
├── name (VARCHAR)
├── repository_url (VARCHAR)
├── default_cwd (VARCHAR)
├── ai_assistant_type (VARCHAR)       -- registered provider id
└── commands (JSONB)                  -- {name: {path, description}}

remote_agent_conversations
├── id (UUID)
├── platform_type (VARCHAR)           -- 'web' | 'telegram' | 'github' | 'slack' | 'discord'
├── platform_conversation_id (VARCHAR)
├── codebase_id (UUID → codebases.id)
├── cwd (VARCHAR)
├── ai_assistant_type (VARCHAR)       -- LOCKED at creation
├── title (VARCHAR)
├── deleted_at (TIMESTAMP)            -- soft-delete
└── UNIQUE(platform_type, platform_conversation_id)

remote_agent_sessions
├── id (UUID)
├── conversation_id (UUID → conversations.id)
├── codebase_id (UUID → codebases.id)
├── ai_assistant_type (VARCHAR)
├── assistant_session_id (VARCHAR)    -- SDK session ID for resume
├── active (BOOLEAN)                  -- only one active per conversation
├── parent_session_id (UUID → sessions.id)
├── transition_reason (TEXT)          -- why this session was created
└── metadata (JSONB)                  -- {lastCommand: "plan-feature", ...}

remote_agent_isolation_environments
├── id (UUID)
├── codebase_id (UUID → codebases.id)
├── workflow_type (VARCHAR)
├── workflow_id (VARCHAR)
├── working_path (VARCHAR)
├── branch_name (VARCHAR)
├── status (VARCHAR)                  -- 'active' | 'destroyed'
└── metadata (JSONB)

remote_agent_workflow_runs
├── id (UUID)
├── conversation_id (UUID → conversations.id)
├── codebase_id (UUID → codebases.id)
├── workflow_name (VARCHAR)
├── status (VARCHAR)                  -- 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
├── parent_conversation_id (UUID)
└── metadata (JSONB)

remote_agent_workflow_events
├── id (UUID)
├── workflow_run_id (UUID → workflow_runs.id)
├── event_type (VARCHAR)
├── step_index (INTEGER)
├── step_name (VARCHAR)
├── data (JSONB)
└── created_at (TIMESTAMP)

remote_agent_messages
├── id (UUID)
├── conversation_id (UUID → conversations.id)
├── role (VARCHAR)                    -- 'user' | 'assistant'
├── content (TEXT)
├── metadata (JSONB)                  -- {toolCalls: [{name, input, duration}]}
└── created_at (TIMESTAMP)

remote_agent_codebase_env_vars
├── id (UUID)
├── codebase_id (UUID → codebases.id)
├── key (VARCHAR)
├── value (TEXT)                      -- encrypted at rest
└── UNIQUE(codebase_id, key)

1. First message       → transitionSession(conversationId, 'first-message', {...})
2. AI responds         → updateSession(session.id, aiSessionId)
3. Next message        → getActiveSession() returns existing; resume with aiSessionId
4. User sends /reset   → deactivateSession(); next message creates fresh session
5. plan → execute      → transitionSession(conversationId, 'plan-to-execute', {...})
                         parent_session_id links back to planning session

~/.archon/
├── workspaces/
│   └── owner/repo/
│       ├── source/          Cloned repo (or symlink to local path)
│       ├── worktrees/       Git worktrees per branch
│       ├── artifacts/
│       │   └── runs/{id}/   Per-run artifacts ($ARTIFACTS_DIR)
│       └── logs/            Workflow execution logs
├── workflows/               Home-scoped workflows (global scope)
├── commands/                Home-scoped commands (global scope)
├── scripts/                 Home-scoped scripts (global scope)
├── web-dist/<version>/      Cached web UI (archon serve, binary only)
├── archon.db                SQLite database (default)
└── config.yaml              Global configuration

.archon/                     Repo-level (in any repository)
├── commands/                Custom command files (.md)
├── workflows/               Workflow definitions (.yaml)
├── scripts/                 Named scripts (.ts for bun, .py for uv)
├── state/                   Cross-run state (gitignored)
└── config.yaml              Repo-specific configuration