# parnish007/imperium architecture

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

- Interactive diagram: https://gitdiagram.com/parnish007/imperium
- Repository: https://github.com/parnish007/imperium

## Overview

Imperium is a local supervisor that mediates between a director or owner and coding agents. Its main workflow queues instructions, polls agent activity to establish delivery and record events, then separates a completion claim from snapshot-based verification and human acceptance. The graph also includes approvals, per-reader feeds, liveness, isolation, notifications, dashboard, and backup capabilities documented in the README. Relationships among unsampled subsystems are included only where documented; source excerpts do not expose every daemon route or runtime call.

Main entry points: [`src/imperium/journal.py`](https://github.com/parnish007/imperium/blob/main/src/imperium/journal.py) (Hash-chain journal), [`src/imperium/engine.py`](https://github.com/parnish007/imperium/blob/main/src/imperium/engine.py) (Polling engine), [`src/imperium/rounds.py`](https://github.com/parnish007/imperium/blob/main/src/imperium/rounds.py) (Work rounds), [`src/imperium/cli.py`](https://github.com/parnish007/imperium/blob/main/src/imperium/cli.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_director_mcp["Director MCP<br/>[director_mcp.py]"]
  node_dashboard["Read-only dashboard<br/>[app.js]"]
  node_notifications["Notifications<br/>[notify.py]"]
end

subgraph group_service["Control service"]
  node_daemon["Local daemon API<br/>[daemon.py]"]
  node_client["API client<br/>[client.py]"]
  node_transport["Local transport<br/>[transport.py]"]
  node_tokens["Bearer tokens<br/>[tokens.py]"]
end

subgraph group_delivery["Agent delivery"]
  node_engine["Polling engine<br/>[engine.py]"]
  node_opencode["OpenCode adapter<br/>[opencode.py]"]
  node_acp["ACP adapter<br/>[acp.py]"]
  node_outbox["Message outbox<br/>[outbox.py]"]
end

subgraph group_assurance["Evidence and assurance"]
  node_rounds["Work rounds<br/>[rounds.py]"]
  node_verification["Trusted verification<br/>[verify.py]"]
  node_snapshots["Workspace snapshots<br/>[snapshot.py]"]
  node_approvals["Permission approvals<br/>[approvals.py]"]
  node_liveness["Agent liveness<br/>[liveness.py]"]
end

subgraph group_operations["Operations"]
  node_journal["Hash-chain journal<br/>[journal.py]"]
  node_feeds["Event feeds<br/>[feeds.py]"]
  node_store[("SQLite store<br/>[store.py]")]
  node_backup["Backup and restore<br/>[backup.py]"]
  node_retention["Event retention<br/>[retention.py]"]
end

node_director(("Director"))
node_owner(("Owner"))
node_agent(("Coding agent"))

node_owner -->|"runs commands"| node_cli
node_director -->|"uses tools"| node_director_mcp
node_cli -->|"calls API"| node_daemon
node_director_mcp -->|"uses client"| node_client
node_client -->|"sends requests"| node_transport
node_client -->|"selects credentials"| node_tokens
node_owner -->|"views status"| node_dashboard
node_owner -->|"receives alerts"| node_notifications
node_daemon -->|"runs supervision"| node_engine
node_engine -->|"polls and dispatches"| node_opencode
node_engine -->|"polls and dispatches"| node_acp
node_agent -->|"serves HTTP"| node_opencode
node_agent -->|"speaks ACP"| node_acp
node_engine -->|"delivers queued work"| node_outbox
node_cli -->|"manages rounds"| node_rounds
node_rounds -->|"queues round messages"| node_outbox
node_rounds -->|"requests checks"| node_verification
node_verification -->|"checks snapshot"| node_snapshots
node_daemon -->|"handles approvals"| node_approvals
node_engine -->|"reports activity"| node_liveness
node_engine -->|"records observations"| node_journal
node_outbox -->|"records transitions"| node_journal
node_rounds -->|"records round events"| node_journal
node_approvals -->|"records decisions"| node_journal
node_journal -->|"persists events"| node_store
node_feeds -->|"reads events"| node_journal
node_notifications -->|"reads feed"| node_feeds
node_backup -->|"backs up database"| node_store
node_retention -->|"prunes events"| node_journal

click node_cli "https://github.com/parnish007/imperium/blob/main/src/imperium/cli.py"
click node_director_mcp "https://github.com/parnish007/imperium/blob/main/src/imperium/director_mcp.py"
click node_dashboard "https://github.com/parnish007/imperium/blob/main/src/imperium/dashboard/app.js"
click node_notifications "https://github.com/parnish007/imperium/blob/main/src/imperium/notify.py"
click node_daemon "https://github.com/parnish007/imperium/blob/main/src/imperium/daemon.py"
click node_client "https://github.com/parnish007/imperium/blob/main/src/imperium/client.py"
click node_transport "https://github.com/parnish007/imperium/blob/main/src/imperium/transport.py"
click node_tokens "https://github.com/parnish007/imperium/blob/main/src/imperium/tokens.py"
click node_engine "https://github.com/parnish007/imperium/blob/main/src/imperium/engine.py"
click node_opencode "https://github.com/parnish007/imperium/blob/main/src/imperium/opencode.py"
click node_acp "https://github.com/parnish007/imperium/blob/main/src/imperium/acp.py"
click node_outbox "https://github.com/parnish007/imperium/blob/main/src/imperium/outbox.py"
click node_rounds "https://github.com/parnish007/imperium/blob/main/src/imperium/rounds.py"
click node_verification "https://github.com/parnish007/imperium/blob/main/src/imperium/verify.py"
click node_snapshots "https://github.com/parnish007/imperium/blob/main/src/imperium/snapshot.py"
click node_approvals "https://github.com/parnish007/imperium/blob/main/src/imperium/approvals.py"
click node_liveness "https://github.com/parnish007/imperium/blob/main/src/imperium/liveness.py"
click node_journal "https://github.com/parnish007/imperium/blob/main/src/imperium/journal.py"
click node_feeds "https://github.com/parnish007/imperium/blob/main/src/imperium/feeds.py"
click node_store "https://github.com/parnish007/imperium/blob/main/src/imperium/store.py"
click node_backup "https://github.com/parnish007/imperium/blob/main/src/imperium/backup.py"
click node_retention "https://github.com/parnish007/imperium/blob/main/src/imperium/retention.py"

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_director_mcp,node_dashboard,node_notifications toneBlue
class node_daemon,node_client,node_transport,node_tokens toneAmber
class node_engine,node_opencode,node_acp,node_outbox toneMint
class node_rounds,node_verification,node_snapshots,node_approvals,node_liveness toneRose
class node_journal,node_feeds,node_store,node_backup,node_retention,node_director,node_owner,node_agent toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/parnish007/imperium/blob/main/src/imperium/cli.py): `src/imperium/cli.py`
- [Director MCP](https://github.com/parnish007/imperium/blob/main/src/imperium/director_mcp.py): `src/imperium/director_mcp.py`
- [Read-only dashboard](https://github.com/parnish007/imperium/blob/main/src/imperium/dashboard/app.js): `src/imperium/dashboard/app.js`
- [Notifications](https://github.com/parnish007/imperium/blob/main/src/imperium/notify.py): `src/imperium/notify.py`

### Control service

- [Local daemon API](https://github.com/parnish007/imperium/blob/main/src/imperium/daemon.py): `src/imperium/daemon.py`
- [API client](https://github.com/parnish007/imperium/blob/main/src/imperium/client.py): `src/imperium/client.py`
- [Local transport](https://github.com/parnish007/imperium/blob/main/src/imperium/transport.py): `src/imperium/transport.py`
- [Bearer tokens](https://github.com/parnish007/imperium/blob/main/src/imperium/tokens.py): `src/imperium/tokens.py`

### Agent delivery

- [Polling engine](https://github.com/parnish007/imperium/blob/main/src/imperium/engine.py): `src/imperium/engine.py`
- [OpenCode adapter](https://github.com/parnish007/imperium/blob/main/src/imperium/opencode.py): `src/imperium/opencode.py`
- [ACP adapter](https://github.com/parnish007/imperium/blob/main/src/imperium/acp.py): `src/imperium/acp.py`
- [Message outbox](https://github.com/parnish007/imperium/blob/main/src/imperium/outbox.py): `src/imperium/outbox.py`

### Evidence and assurance

- [Work rounds](https://github.com/parnish007/imperium/blob/main/src/imperium/rounds.py): `src/imperium/rounds.py`
- [Trusted verification](https://github.com/parnish007/imperium/blob/main/src/imperium/verify.py): `src/imperium/verify.py`
- [Workspace snapshots](https://github.com/parnish007/imperium/blob/main/src/imperium/snapshot.py): `src/imperium/snapshot.py`
- [Permission approvals](https://github.com/parnish007/imperium/blob/main/src/imperium/approvals.py): `src/imperium/approvals.py`
- [Agent liveness](https://github.com/parnish007/imperium/blob/main/src/imperium/liveness.py): `src/imperium/liveness.py`

### Operations

- [Hash-chain journal](https://github.com/parnish007/imperium/blob/main/src/imperium/journal.py): `src/imperium/journal.py`
- [Event feeds](https://github.com/parnish007/imperium/blob/main/src/imperium/feeds.py): `src/imperium/feeds.py`
- [SQLite store](https://github.com/parnish007/imperium/blob/main/src/imperium/store.py): `src/imperium/store.py`
- [Backup and restore](https://github.com/parnish007/imperium/blob/main/src/imperium/backup.py): `src/imperium/backup.py`
- [Event retention](https://github.com/parnish007/imperium/blob/main/src/imperium/retention.py): `src/imperium/retention.py`

### Other components

- **Director**
- **Owner**
- **Coding agent**

## Connections

- Owner → CLI: runs commands (evidence: `README.md`)
- Director → Director MCP: uses tools (evidence: `README.md`)
- CLI → Local daemon API: calls API (evidence: `src/imperium/cli.py`)
- Director MCP → API client: uses client (evidence: `src/imperium/director_mcp.py`)
- API client → Local transport: sends requests (evidence: `src/imperium/client.py`)
- API client → Bearer tokens: selects credentials (evidence: `src/imperium/client.py`)
- Owner → Read-only dashboard: views status (evidence: `README.md`)
- Owner → Notifications: receives alerts (evidence: `README.md`)
- Local daemon API → Polling engine: runs supervision (evidence: `README.md`)
- Polling engine → OpenCode adapter: polls and dispatches (evidence: `src/imperium/engine.py`)
- Polling engine → ACP adapter: polls and dispatches (evidence: `src/imperium/engine.py`)
- Coding agent → OpenCode adapter: serves HTTP (evidence: `README.md`)
- Coding agent → ACP adapter: speaks ACP (evidence: `README.md`)
- Polling engine → Message outbox: delivers queued work (evidence: `src/imperium/engine.py`)
- CLI → Work rounds: manages rounds (evidence: `README.md`)
- Work rounds → Message outbox: queues round messages (evidence: `src/imperium/rounds.py`)
- Work rounds → Trusted verification: requests checks (evidence: `README.md`)
- Trusted verification → Workspace snapshots: checks snapshot (evidence: `src/imperium/verify.py`)
- Local daemon API → Permission approvals: handles approvals (evidence: `src/imperium/daemon.py`)
- Polling engine → Agent liveness: reports activity (evidence: `src/imperium/engine.py`)
- Polling engine → Hash-chain journal: records observations (evidence: `README.md`)
- Message outbox → Hash-chain journal: records transitions (evidence: `src/imperium/outbox.py`)
- Work rounds → Hash-chain journal: records round events (evidence: `src/imperium/rounds.py`)
- Permission approvals → Hash-chain journal: records decisions (evidence: `src/imperium/approvals.py`)
- Hash-chain journal → SQLite store: persists events (evidence: `src/imperium/journal.py`)
- Event feeds → Hash-chain journal: reads events (evidence: `src/imperium/feeds.py`)
- Notifications → Event feeds: reads feed (evidence: `src/imperium/notify.py`)
- Backup and restore → SQLite store: backs up database (evidence: `src/imperium/backup.py`)
- Event retention → Hash-chain journal: prunes events (evidence: `src/imperium/retention.py`)
