# hack-ink/decodex architecture

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

- Interactive diagram: https://gitdiagram.com/hack-ink/decodex
- Repository: https://github.com/hack-ink/decodex

## Overview

1. **Workspace shape**
   - This is a Rust-first monorepo centered on `apps/decodex`, with three other executable products: `apps/radar`, `apps/decodex-publisher`, and the macOS app in `apps/decodex-app`.
   - The repo also includes a static Astro site in `site/`, installable Codex plugins in `plugins/`, and authoritative docs/specs in `docs/`.

2. **Core runtime: `decodex` CLI + daemon**
   - `apps/decodex` is the main runtime and CLI binary.
   - It is both an operator command surface and a local control-plane daemon (`decodex serve`) that schedules retained work, polls external systems, publishes snapshots, and serves local APIs/UI.

3. **Persistent state boundary**
   - The runtime keeps authoritative local state in a SQLite-backed store under the `state/` subsystem.
   - That store persists run control, review records, runtime events, autonomy objects, leases, account metadata, and derived projections.
   - The key architectural boundary is: external systems are observed and reconciled into local state first; the daemon then drives dispatch from that local state.

4. **Operator control plane**
   - `decodex serve` exposes the local operator listener on HTTP.
   - It serves the dashboard at `/` and `/dashboard`, liveness at `/livez`, account APIs for the Decodex App, and a WebSocket control channel at `/dashboard/control`.
   - This is the human-facing coordination layer for snapshots, control actions, and live activity updates.

5. **MCP gateway**
   - The `mcp/` subsystem is a protocol gateway for desktop/CLI clients.
   - It serves resources, prompts, and tools over stdio or streamable HTTP, with capability profiles that gate what operations are exposed.
   - Architecturally, it is a read/plan/operate/admin facade over the same runtime state and control logic, not a separate engine.

6. **Execution and orchestration**
   - The `orchestrator/` subtree is the main policy engine for retained lanes and loop execution.
   - It coordinates scheduling, run cycles, lane control, dispatch policy, recovery, reconciliation, and status projection.
   - It also owns the HTTP/operator integration, worktree lifecycle, and the logic that decides whether a project/run is active, stalled, or needs recovery.

7. **External integrations**
   - The runtime integrates with Linear, GitHub, Git, and Codex app-server / app helper APIs.
   - These are not treated as isolated adapters; they feed into orchestration, status projection, and retained lane state.
   - The data flow is typically: poll or receive external facts → normalize into local state → project into dashboard/status/MCP resources → decide whether to dispatch or recover.

8. **Account management**
   - The `accounts/` and `agent/codex_accounts/` areas manage the shared Codex account pool, login state, token/usage tracking, and selection policy.
   - The native macOS app in `apps/decodex-app` is a UI over these account APIs and the shared local runtime state.
   - Account identity, privacy-preserving display names, usage history, and auth failure handling are all modeled as local Decodex state rather than project-local config.

9. **Autonomy and research pipeline**
   - The repo has a distinct autonomy model: `autonomy_objective`, `autonomy_proposal`, `autonomy_signal`, `loop_contract`, `execution_program`, `program_intake`, and `research_design`.
   - The flow is intentionally staged: draft or compile a contract, promote it if accepted, then materialize executable work through program intake.
   - This separates non-executable research/proposal artifacts from executable Linear/program state.

10. **Recovery and hygiene**
   - `recovery/`, `maintenance/`, `archive_hygiene/`, and related orchestration modules handle failure recovery, stale state cleanup, ghost lane repair, worktree cleanup, and log/evidence retention.
   - These are bounded subsystems that repair or reconcile local/runtime state after interrupted runs, stale worktrees, or terminal failures.
   - They support the daemon’s “keep running safely” posture without conflating cleanup with normal execution.

11. **Public site vs runtime**
   - `site/` is a static Astro site for the public product surface and download entry.
   - It is explicitly separate from the runtime and does not own scheduling, tracker writes, or local operator state.
   - Publication is externalized; the site is a presentation boundary, not part of the operational control plane.

12. **Auxiliary tools**
   - `apps/radar` is a standalone analysis/ledger tool for release validation, upstream review, signal rendering, and artifact tracking.
   - `apps/decodex-publisher` is a separate CLI for social candidate validation, reservation, and post publishing workflows.
   - Both are adjacent tools in the ecosystem, but they are not the main runtime loop.

13. **Plugins and docs as governance layers**
   - `plugins/` packages reusable skills and policies consumed by Codex workflows.
   - `docs/spec`, `docs/runbook`, `docs/reference`, and `docs/decisions` define the governing contracts, operating procedures, current behavior, and design rationale.
   - In architecture terms, docs and plugins are part of the control surface and policy boundary around the runtime, not mere commentary.

14. **Overall system diagram**
   - The clean mental model is: local SQLite-backed runtime state at the center; external systems (Linear/GitHub/Git/Codex app-server) feeding it; orchestration deciding dispatch/recovery; operator UI and MCP exposing it; and auxiliary tools plus docs/plugins surrounding it as governance and specialized workflows.

Main entry points: [`apps/decodex/src/orchestrator.rs`](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator.rs) (Orchestrator), [`apps/decodex/src/state.rs`](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/state.rs) (Local state), [`apps/decodex/src/main.rs`](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/main.rs) (decodex CLI), [`docs/spec/index.md`](https://github.com/hack-ink/decodex/blob/main/docs/spec/index.md) (Docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Decodex runtime"]
  node_n_main["decodex CLI<br/>Rust binary<br/>[main.rs]"]
  node_n_cli["Commands<br/>CLI surface<br/>[cli.rs]"]
  node_n_orchestrator{{"Orchestrator<br/>policy engine<br/>[orchestrator.rs]"}}
  node_n_state[("Local state<br/>SQLite store<br/>[state.rs]")]
  node_n_mcp["MCP gateway<br/>protocol facade<br/>[mcp.rs]"]
  node_n_operator_http["Operator HTTP<br/>control plane<br/>[operator_http.rs]"]
  node_n_status["Status<br/>projection layer<br/>[status.rs]"]
  node_n_lanes["Lane control<br/>dispatch control<br/>[lane_control.rs]"]
  node_n_run_cycle["Run cycle<br/>execution loop<br/>[run_cycle.rs]"]
  node_n_recovery["Recovery<br/>repair flows<br/>[recovery.rs]"]
  node_n_accounts["Accounts<br/>account pool<br/>[accounts.rs]"]
  node_n_autonomy["Autonomy<br/>research model"]
end

subgraph group_grp_integrations["External integrations"]
  node_n_tracker["Tracker<br/>Linear bridge<br/>[tracker.rs]"]
  node_n_github["GitHub<br/>[github.rs]"]
  node_n_gitops["Git ops<br/>git/worktree ops<br/>[git_ops.rs]"]
  node_n_app_server["App server<br/>Codex bridge<br/>[app_server.rs]"]
  node_n_app_helper["App helper<br/>native helper"]
end

subgraph group_grp_adjacent["Adjacent apps"]
  node_n_decodex_app["decodex-app<br/>SwiftUI app<br/>[DecodexApp.swift]"]
  node_n_radar["radar<br/>Rust tool<br/>[main.rs]"]
  node_n_publisher["publisher<br/>Rust tool<br/>[main.rs]"]
end

subgraph group_grp_governance["Governance surface"]
  node_n_site["Public site<br/>Astro site<br/>[index.astro]"]
  node_n_plugins["Plugins<br/>policy packs<br/>[plugin.json]"]
  node_n_docs["Docs<br/>[index.md]"]
end

node_n_main -->|"dispatches to"| node_n_cli
node_n_main -->|"boots"| node_n_orchestrator
node_n_main -->|"persists in"| node_n_state
node_n_orchestrator -->|"reads/writes"| node_n_state
node_n_orchestrator -->|"projects"| node_n_status
node_n_orchestrator -->|"controls"| node_n_lanes
node_n_orchestrator -->|"runs"| node_n_run_cycle
node_n_orchestrator -->|"repairs"| node_n_recovery
node_n_orchestrator -->|"ingests"| node_n_tracker
node_n_orchestrator -->|"integrates"| node_n_github
node_n_orchestrator -->|"uses"| node_n_gitops
node_n_orchestrator -->|"bridges"| node_n_app_server
node_n_state -->|"stores"| node_n_accounts
node_n_state -->|"stores"| node_n_autonomy
node_n_state -->|"records"| node_n_recovery
node_n_mcp -->|"reads"| node_n_state
node_n_mcp -->|"operates over"| node_n_orchestrator
node_n_operator_http -->|"serves"| node_n_status
node_n_operator_http -->|"serves data from"| node_n_state
node_n_decodex_app -->|"connects to"| node_n_operator_http
node_n_app_helper -->|"supports"| node_n_decodex_app
node_n_publisher -->|"coordinates with"| node_n_state
node_n_radar -->|"analyzes"| node_n_github
node_n_site -.->|"documents"| node_n_docs
node_n_plugins -->|"extends"| node_n_mcp
node_n_docs -.->|"specifies"| node_n_orchestrator
node_n_docs -.->|"separates"| node_n_site

click node_n_main "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/main.rs"
click node_n_cli "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/cli.rs"
click node_n_orchestrator "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator.rs"
click node_n_state "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/state.rs"
click node_n_mcp "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/mcp.rs"
click node_n_operator_http "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/operator_http.rs"
click node_n_status "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/status.rs"
click node_n_lanes "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/lane_control.rs"
click node_n_run_cycle "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/run_cycle.rs"
click node_n_recovery "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/recovery.rs"
click node_n_accounts "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/accounts.rs"
click node_n_autonomy "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/autonomy_objective.rs"
click node_n_tracker "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/tracker.rs"
click node_n_github "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/github.rs"
click node_n_gitops "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/git_ops.rs"
click node_n_app_server "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/agent/app_server.rs"
click node_n_app_helper "https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/bin/decodex-app-helper.rs"
click node_n_decodex_app "https://github.com/hack-ink/decodex/blob/main/apps/decodex-app/Sources/DecodexApp/DecodexApp.swift"
click node_n_radar "https://github.com/hack-ink/decodex/blob/main/apps/radar/src/main.rs"
click node_n_publisher "https://github.com/hack-ink/decodex/blob/main/apps/decodex-publisher/src/main.rs"
click node_n_site "https://github.com/hack-ink/decodex/blob/main/site/src/pages/index.astro"
click node_n_plugins "https://github.com/hack-ink/decodex/blob/main/plugins/decodex/.codex-plugin/plugin.json"
click node_n_docs "https://github.com/hack-ink/decodex/blob/main/docs/spec/index.md"

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_n_main,node_n_cli,node_n_orchestrator,node_n_state,node_n_mcp,node_n_operator_http,node_n_status,node_n_lanes,node_n_run_cycle,node_n_recovery,node_n_accounts,node_n_autonomy toneBlue
class node_n_tracker,node_n_github,node_n_gitops,node_n_app_server,node_n_app_helper toneAmber
class node_n_decodex_app,node_n_radar,node_n_publisher toneMint
class node_n_site,node_n_plugins,node_n_docs toneRose
```

## Components

### Decodex runtime

Main CLI daemon, orchestration, state, and local control planes.

- [decodex CLI](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/main.rs): Rust binary · Primary operator command surface and daemon entrypoint. · `apps/decodex/src/main.rs`
- [Commands](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/cli.rs): CLI surface · Operator commands for control, recovery, intake, and account actions. · `apps/decodex/src/cli.rs`
- [Orchestrator](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator.rs): policy engine · Retained-lane scheduler, dispatch policy, run cycles, recovery, and status projection. · `apps/decodex/src/orchestrator.rs`
- [Local state](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/state.rs): SQLite store · Authoritative persistent boundary for runs, reviews, events, leases, accounts, and projections. · `apps/decodex/src/state.rs`
- [MCP gateway](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/mcp.rs): protocol facade · Tools, prompts, resources, and capability-gated access over shared runtime state. · `apps/decodex/src/mcp.rs`
- [Operator HTTP](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/operator_http.rs): control plane · Local dashboard, account APIs, liveness, snapshot delivery, and WebSocket control channel. · `apps/decodex/src/orchestrator/operator_http.rs`
- [Status](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/status.rs): projection layer · Derived run, lane, worktree, queue, and recovery views for operator-facing presentation. · `apps/decodex/src/orchestrator/status.rs`
- [Lane control](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/lane_control.rs): dispatch control · Lane selection, interrupts, steering, and retained execution coordination. · `apps/decodex/src/orchestrator/lane_control.rs`
- [Run cycle](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/run_cycle.rs): execution loop · Prepares, executes, and completes retained runs and project ticks. · `apps/decodex/src/orchestrator/run_cycle.rs`
- [Recovery](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/recovery.rs): repair flows · Recoveries for stale active runs, ghost lanes, handoffs, and terminal failures. · `apps/decodex/src/recovery.rs`
- [Accounts](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/accounts.rs): account pool · Shared Codex account identity, login state, usage tracking, and selection policy. · `apps/decodex/src/accounts.rs`
- [Autonomy](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/autonomy_objective.rs): research model · Objectives, proposals, signals, contracts, and execution-program intake/promotion. · `apps/decodex/src/autonomy_objective.rs`

### External integrations

Systems observed and reconciled into Decodex state.

- [Tracker](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/tracker.rs): Linear bridge · Linear issue tracking, record projections, privacy classification, and public text rendering. · `apps/decodex/src/tracker.rs`
- [GitHub](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/github.rs): GitHub bridge · Repository, branch, comment, and merge/readback integration used by orchestration and recovery. · `apps/decodex/src/github.rs`
- [Git ops](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/orchestrator/git_ops.rs): git/worktree ops · Branching, selection, diagnostics, rewrites, and worktree lifecycle used by the runtime. · `apps/decodex/src/orchestrator/git_ops.rs`
- [App server](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/agent/app_server.rs): Codex bridge · Protocol bridge to the Codex app-server/runtime, including turn loop and preflight. · `apps/decodex/src/agent/app_server.rs`
- [App helper](https://github.com/hack-ink/decodex/blob/main/apps/decodex/src/bin/decodex-app-helper.rs): native helper · Small binary used by the macOS app to bridge into the local runtime. · `apps/decodex/src/bin/decodex-app-helper.rs`

### Adjacent apps

Separate products in the repository ecosystem.

- [decodex-app](https://github.com/hack-ink/decodex/blob/main/apps/decodex-app/Sources/DecodexApp/DecodexApp.swift): SwiftUI app · macOS client UI over account APIs and shared operator/runtime state. · `apps/decodex-app/Sources/DecodexApp/DecodexApp.swift`
- [radar](https://github.com/hack-ink/decodex/blob/main/apps/radar/src/main.rs): Rust tool · Release validation, upstream review, artifact tracking, and ledger analysis. · `apps/radar/src/main.rs`
- [publisher](https://github.com/hack-ink/decodex/blob/main/apps/decodex-publisher/src/main.rs): Rust tool · Social candidate validation, reservation, and publish workflows. · `apps/decodex-publisher/src/main.rs`

### Governance surface

Docs, plugins, and public site that shape behavior and usage.

- [Public site](https://github.com/hack-ink/decodex/blob/main/site/src/pages/index.astro): Astro site · Static product surface and download entry, separate from the runtime control plane. · `site/src/pages/index.astro`
- [Plugins](https://github.com/hack-ink/decodex/blob/main/plugins/decodex/.codex-plugin/plugin.json): policy packs · Reusable skills, references, and hooks consumed by Codex workflows. · `plugins/decodex/.codex-plugin/plugin.json`
- [Docs](https://github.com/hack-ink/decodex/blob/main/docs/spec/index.md): specs/docs · Authoritative contracts, runbooks, decisions, and reference material. · `docs/spec/index.md`

## Connections

- decodex CLI → Commands: dispatches to · The binary exposes the operator command surface and daemon entrypoints.
- decodex CLI → Orchestrator: boots · Core runtime logic is centered in the orchestrator.
- decodex CLI → Local state: persists in · Daemon state is backed by the local SQLite store.
- Orchestrator → Local state: reads/writes · Orchestration reconciles external facts into local state before dispatch.
- Orchestrator → Status: projects · The orchestrator derives operator-facing status and dashboard views.
- Orchestrator → Lane control: controls · Lane policy governs retained execution and steering.
- Orchestrator → Run cycle: runs · Retained work is advanced through scheduled run cycles.
- Orchestrator → Recovery: repairs · Stale or interrupted work is recovered through repair flows.
- Orchestrator → Tracker: ingests · Tracker facts feed status projection and retained lane state.
- Orchestrator → GitHub: integrates · GitHub events and repository state inform orchestration and recovery.
- Orchestrator → Git ops: uses · Worktree and branch operations support run execution and repair.
- Orchestrator → App server: bridges · Codex app-server protocol is surfaced through orchestration.
- Local state → Accounts: stores · Account identity, login state, and usage history are persisted locally.
- Local state → Autonomy: stores · Autonomy objectives, proposals, signals, and programs live in local state.
- Local state → Recovery: records · Recovery decisions and repair metadata are written as runtime state.
- MCP gateway → Local state: reads · MCP resources and projections are backed by the same runtime state.
- MCP gateway → Orchestrator: operates over · MCP tools plan, inspect, and act through the runtime control logic.
- Operator HTTP → Status: serves · HTTP dashboard and live views are rendered from status projections.
- Operator HTTP → Local state: serves data from · Operator APIs expose local persisted state and snapshots.
- decodex-app → Operator HTTP: connects to · The macOS app is a UI over local operator APIs and dashboard sockets.
- App helper → decodex-app: supports · Native helper bridges the app to local runtime capabilities.
- publisher → Local state: coordinates with · Publishing workflow uses local runtime state and reservations.
- radar → GitHub: analyzes · Radar consumes GitHub and release artifacts for validation workflows.
- Public site → Docs: documents · Public site is governed by repo contracts and documentation.
- Plugins → MCP gateway: extends · Plugins define skills and policies used by Codex-facing workflows.
- Docs → Orchestrator: specifies · Specs and runbooks define the intended behavior of the runtime.
- Docs → Public site: separates · Docs explicitly distinguish the public site from the operational control plane.
