# theprimeagen/oligarchy architecture

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

- Interactive diagram: https://gitdiagram.com/theprimeagen/oligarchy
- Repository: https://github.com/theprimeagen/oligarchy

## Overview

Oligarchy explores QEMU-backed agent testing: tests are driven against managed QEMU sessions, with automation, fleet services, persistence, and result views around that work. The sampled entry points establish server routes, runtime services, and selected startup tasks; the README and tree identify additional product surfaces, but do not document their internal wiring. Accordingly, the graph keeps those capabilities visible while omitting uncertain call paths.

Main entry points: [`apps/automation-server/src/main.ts`](https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/main.ts) (Automation server), [`packages/db/src/schema.ts`](https://github.com/theprimeagen/oligarchy/blob/master/packages/db/src/schema.ts) (PostgreSQL state), [`apps/qemu-server/src/main.ts`](https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-server/src/main.ts) (QEMU server), [`apps/qemu-reverse-proxy/src/main.ts`](https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-reverse-proxy/src/main.ts) (QEMU proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_dashboard["Dashboard<br/>[dashboard.tsx]"]
  node_qemu_proxy["QEMU proxy<br/>[main.ts]"]
  node_proxy_routes["Proxy handlers<br/>[handlers.ts]"]
  node_proxy_router["Proxy router<br/>[router.ts]"]
  node_automation_server["Automation server<br/>[main.ts]"]
  node_automation_handlers["Automation handlers<br/>[handlers.ts]"]
  node_worker["Job worker<br/>[worker.ts]"]
  node_backlog["Backlog watcher<br/>[backlog.ts]"]
end

subgraph group_execution["Execution fleet"]
  node_qemu_server["QEMU server<br/>[main.ts]"]
  node_qemu_handlers["QEMU handlers<br/>[handlers.ts]"]
  node_qemu_runtime["QEMU runtime<br/>[qemu.ts]"]
  node_automation_client["Automation client<br/>[main.ts]"]
  node_client_sessions["Client sessions<br/>[sessions.ts]"]
end

subgraph group_workflow["Test workflow"]
  node_driver["Test driver<br/>[main.ts]"]
  node_driver_loop["Driver loop<br/>[loop.ts]"]
  node_session_cli["Session CLI<br/>[main.ts]"]
  node_viz["Terminal viewer<br/>[main.ts]"]
end

subgraph group_platform["State and integrations"]
  node_db[("PostgreSQL state<br/>[schema.ts]")]
  node_linear["Linear"]
  node_qemu_host["QEMU host"]
end

node_operator(("Operator"))

node_operator -->|"views results"| node_dashboard
node_operator -->|"runs tests"| node_driver
node_operator -->|"operates session"| node_session_cli
node_operator -->|"views session"| node_viz
node_dashboard -->|"queries"| node_db
node_qemu_proxy -->|"serves routes"| node_proxy_routes
node_proxy_routes -->|"delegates"| node_proxy_router
node_qemu_proxy -->|"provides stores"| node_db
node_qemu_proxy -->|"connects"| node_linear
node_automation_server -->|"serves routes"| node_automation_handlers
node_automation_server -->|"starts dispatch"| node_worker
node_automation_server -->|"starts watcher"| node_backlog
node_automation_server -->|"provides stores"| node_db
node_automation_server -->|"connects"| node_linear
node_qemu_server -->|"serves routes"| node_qemu_handlers
node_qemu_server -->|"provides service"| node_qemu_runtime
node_qemu_server -->|"uses host"| node_qemu_host
node_qemu_server -->|"provides stores"| node_db
node_automation_client -->|"provides sessions"| node_client_sessions
node_automation_client -->|"connects proxy"| node_qemu_proxy
node_automation_client -->|"provides stores"| node_db
node_driver -->|"runs loop"| node_driver_loop
node_driver -->|"provides test store"| node_db

click node_dashboard "https://github.com/theprimeagen/oligarchy/blob/master/apps/dashboard/src/dashboard.tsx"
click node_qemu_proxy "https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-reverse-proxy/src/main.ts"
click node_proxy_routes "https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-reverse-proxy/src/handlers.ts"
click node_proxy_router "https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-reverse-proxy/src/router.ts"
click node_automation_server "https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/main.ts"
click node_automation_handlers "https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/handlers.ts"
click node_worker "https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/worker.ts"
click node_backlog "https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/backlog.ts"
click node_qemu_server "https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-server/src/main.ts"
click node_qemu_handlers "https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-server/src/handlers.ts"
click node_qemu_runtime "https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-server/src/qemu/qemu.ts"
click node_automation_client "https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-client/src/main.ts"
click node_client_sessions "https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-client/src/sessions.ts"
click node_driver "https://github.com/theprimeagen/oligarchy/blob/master/src/driver/main.ts"
click node_driver_loop "https://github.com/theprimeagen/oligarchy/blob/master/src/driver/loop.ts"
click node_session_cli "https://github.com/theprimeagen/oligarchy/blob/master/src/session/main.ts"
click node_viz "https://github.com/theprimeagen/oligarchy/blob/master/apps/viz/src/main.ts"
click node_db "https://github.com/theprimeagen/oligarchy/blob/master/packages/db/src/schema.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_dashboard,node_qemu_proxy,node_proxy_routes,node_proxy_router,node_automation_server,node_automation_handlers,node_worker,node_backlog toneBlue
class node_qemu_server,node_qemu_handlers,node_qemu_runtime,node_automation_client,node_client_sessions toneAmber
class node_driver,node_driver_loop,node_session_cli,node_viz toneMint
class node_db,node_linear,node_qemu_host toneRose
class node_operator toneIndigo
```

## Components

### Control plane

- [Dashboard](https://github.com/theprimeagen/oligarchy/blob/master/apps/dashboard/src/dashboard.tsx): `apps/dashboard/src/dashboard.tsx`
- [QEMU proxy](https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-reverse-proxy/src/main.ts): `apps/qemu-reverse-proxy/src/main.ts`
- [Proxy handlers](https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-reverse-proxy/src/handlers.ts): `apps/qemu-reverse-proxy/src/handlers.ts`
- [Proxy router](https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-reverse-proxy/src/router.ts): `apps/qemu-reverse-proxy/src/router.ts`
- [Automation server](https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/main.ts): `apps/automation-server/src/main.ts`
- [Automation handlers](https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/handlers.ts): `apps/automation-server/src/handlers.ts`
- [Job worker](https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/worker.ts): `apps/automation-server/src/worker.ts`
- [Backlog watcher](https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-server/src/backlog.ts): `apps/automation-server/src/backlog.ts`

### Execution fleet

- [QEMU server](https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-server/src/main.ts): `apps/qemu-server/src/main.ts`
- [QEMU handlers](https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-server/src/handlers.ts): `apps/qemu-server/src/handlers.ts`
- [QEMU runtime](https://github.com/theprimeagen/oligarchy/blob/master/apps/qemu-server/src/qemu/qemu.ts): `apps/qemu-server/src/qemu/qemu.ts`
- [Automation client](https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-client/src/main.ts): `apps/automation-client/src/main.ts`
- [Client sessions](https://github.com/theprimeagen/oligarchy/blob/master/apps/automation-client/src/sessions.ts): `apps/automation-client/src/sessions.ts`

### Test workflow

- [Test driver](https://github.com/theprimeagen/oligarchy/blob/master/src/driver/main.ts): `src/driver/main.ts`
- [Driver loop](https://github.com/theprimeagen/oligarchy/blob/master/src/driver/loop.ts): `src/driver/loop.ts`
- [Session CLI](https://github.com/theprimeagen/oligarchy/blob/master/src/session/main.ts): `src/session/main.ts`
- [Terminal viewer](https://github.com/theprimeagen/oligarchy/blob/master/apps/viz/src/main.ts): `apps/viz/src/main.ts`

### State and integrations

- [PostgreSQL state](https://github.com/theprimeagen/oligarchy/blob/master/packages/db/src/schema.ts): `packages/db/src/schema.ts`
- **Linear**
- **QEMU host**

### Other components

- **Operator**

## Connections

- Operator → Dashboard: views results
- Operator → Test driver: runs tests
- Operator → Session CLI: operates session
- Operator → Terminal viewer: views session
- Dashboard → PostgreSQL state: queries
- QEMU proxy → Proxy handlers: serves routes
- Proxy handlers → Proxy router: delegates
- QEMU proxy → PostgreSQL state: provides stores
- QEMU proxy → Linear: connects
- Automation server → Automation handlers: serves routes
- Automation server → Job worker: starts dispatch
- Automation server → Backlog watcher: starts watcher
- Automation server → PostgreSQL state: provides stores
- Automation server → Linear: connects
- QEMU server → QEMU handlers: serves routes
- QEMU server → QEMU runtime: provides service
- QEMU server → QEMU host: uses host
- QEMU server → PostgreSQL state: provides stores
- Automation client → Client sessions: provides sessions
- Automation client → QEMU proxy: connects proxy
- Automation client → PostgreSQL state: provides stores
- Test driver → Driver loop: runs loop
- Test driver → PostgreSQL state: provides test store