# radiiduration/ai-company-os architecture

> Architecture diagram of the GitHub repository radiiduration/ai-company-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/radiiduration/ai-company-os
- Repository: https://github.com/radiiduration/ai-company-os

## Overview

1. **What this repo is**
   - This is a monorepo for an “AI company” operating system: not a single agent, but a set of specialized departments, release gates, War Room coordination, memory, and deployment workflows.
   - The architecture is intentionally split into a control plane, a UI shell, a background worker, and a native browser shell.

2. **Top-level structure**
   - `apps/api` is the core backend.
   - `apps/web` is the browser-based dashboard/command center.
   - `apps/worker` is a separate process for task execution.
   - `apps/sovereign-browser` is a Tauri-based desktop shell, currently scaffolded.
   - `packages/shared` provides cross-app types.
   - `prompts/` and `docs/` encode the company/agent operating model and product architecture.

3. **Backend control plane**
   - `apps/api` is the main orchestration surface, built with **Hono** and **Prisma**.
   - It owns the HTTP routes for the major product domains: auth, organizations, projects, repositories, templates, governance, gates, evaluations, memory, release packets, War Room, GitHub webhooks, and a worker API.
   - This is the center of the system where business state, workflow state, and integration state converge.

4. **Authentication and session boundary**
   - Auth is a dedicated subsystem under `apps/api/src/auth`, with support for:
     - magic-link login,
     - OAuth,
     - session handling,
     - crypto/middleware helpers.
   - There is also a `dev-user` helper, which suggests a local-development shortcut or seeded identity path.
   - Authentication is part of the API boundary, not the UI, so the backend likely owns identity verification and session issuance.

5. **Persistence and state**
   - Prisma (`apps/api/prisma/schema.prisma`) indicates a relational database as the primary system of record.
   - `src/redis.ts` shows Redis is used for ephemeral or coordination state such as queues, caching, locks, or workflow coordination.
   - The domain modules `events`, `usage`, `memory`, `evaluations`, `evidence`, and `workflows` imply the backend maintains an event-ledger style model alongside ordinary relational records.

6. **Execution and workflow engine**
   - The execution path is split across `services/execution.ts`, `services/task-runner.ts`, `services/workflows.ts`, and `routes/worker.ts`.
   - This suggests a model where the API creates and tracks tasks/workflows, while the worker process performs asynchronous departmental actions.
   - `gates`, `release-packet`, `war-room`, and `evaluations` indicate that work is not just “run a job,” but passes through explicit governance and approval checkpoints.

7. **AI/provider abstraction**
   - `services/model-router.ts` is a key architectural boundary: it likely routes requests to different model providers or model tiers rather than hard-coding one LLM.
   - The presence of department prompts in `prompts/` reinforces that AI behavior is configured by role-specific prompt contracts.
   - This repo treats model interaction as an internal service, not something embedded directly in UI code.

8. **External integrations**
   - `routes/github-webhooks.ts` and `services/github-provider.ts` make GitHub an important integration point for repo events and execution workflows.
   - `services/vercel-deployments.ts` indicates deployment orchestration/visibility around Vercel.
   - These integrations are part of the product’s execution loop: source changes come from GitHub, and deploy status can feed back into release gating and truth-pack generation.

9. **Worker process**
   - `apps/worker` is a separate Node service, likely polling/consuming tasks from the API/queue boundary.
   - Its existence means the system is designed for asynchronous departmental execution rather than purely synchronous API requests.
   - In the architecture diagram, this should be shown as a background executor connected to the API, not to the browser directly.

10. **Web dashboard**
   - `apps/web` is a Vite/React dashboard used as the human command center.
   - The readme calls it the “dashboard preview,” so it appears to be a UI for observing company state, workflows, approvals, and operational status.
   - It talks to the API; it does not appear to own business logic.

11. **Desktop/browser shell**
   - `apps/sovereign-browser` is a Tauri application with Rust code under `src-tauri`.
   - This is a native shell layer for the browser experience, currently scaffolded and not the primary runtime.
   - It should be shown separately from the web app because it introduces a desktop packaging/runtime boundary.

12. **Shared contracts and governance docs**
   - `packages/shared` contains common types, especially `AgentMessage`-style shared contracts referenced in the readme.
   - `docs/` and `CONSTITUTION.md` are not just documentation; they define the system’s operating rules, product scope, and architecture.
   - The `.kiro/specs` folders suggest formalized design/requirements/task specs that shape implementation boundaries.

13. **Operational environment**
   - The repo is set up for local multi-service development with Docker Compose, plus separate dev commands for API, web, worker, and browser.
   - `vercel.json` indicates at least some deployment configuration is repository-managed.
   - The architecture is therefore a multi-process local stack with explicit service boundaries, not a single all-in-one app.

14. **How to draw the main diagram**
   - Put the **API** at the center as the system of record and orchestration hub.
   - Connect **Web UI** and **Tauri shell** to the API as human interfaces.
   - Connect the **Worker** to the API/queue/Redis as the async executor.
   - Show **Postgres/Prisma** and **Redis** behind the API.
   - Show **GitHub** and **Vercel** as external systems integrated through dedicated backend services.
   - Show **shared types**, **prompts**, and **docs/constitution** as cross-cutting design inputs rather than runtime services.

Main entry points: [`apps/api/src/index.ts`](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/index.ts) (API), [`apps/api/src/services/events.ts`](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/events.ts) (Domain services), [`apps/web/src/App.tsx`](https://github.com/radiiduration/ai-company-os/blob/main/apps/web/src/App.tsx) (Web UI), [`apps/api/src/services/task-runner.ts`](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/task-runner.ts) (Task runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime services"]
  node_api["API<br/>Hono control plane<br/>[index.ts]"]
  node_web["Web UI<br/>React dashboard<br/>[App.tsx]"]
  node_browser["Sovereign browser<br/>Tauri shell<br/>[main.rs]"]
  node_worker["Worker<br/>background process<br/>[index.ts]"]
end

subgraph group_backend["Backend control plane"]
  node_auth["Auth<br/>identity boundary<br/>[index.ts]"]
  node_db[("Postgres<br/>Prisma store<br/>[schema.prisma]")]
  node_redis[("Redis<br/>coordination state<br/>[redis.ts]")]
  node_workflows["Workflows<br/>execution engine<br/>[workflows.ts]"]
  node_tasks["Task runner<br/>job execution<br/>[task-runner.ts]"]
  node_modelrouter["Model router<br/>AI abstraction<br/>[model-router.ts]"]
  node_github["GitHub<br/>integration<br/>[github-provider.ts]"]
  node_vercel["Vercel<br/>deployment integration"]
  node_api_routes["API routes<br/>domain endpoints<br/>[auth.ts]"]
  node_api_services["Domain services<br/>business logic<br/>[events.ts]"]
end

subgraph group_contracts["Shared contracts"]
  node_shared["Shared types<br/>cross-app contracts<br/>[index.ts]"]
  node_prompts["Prompts<br/>role contracts<br/>[README.md]"]
end

subgraph group_governance["Governance and specs"]
  node_constitution["Constitution<br/>operating rules<br/>[CONSTITUTION.md]"]
  node_docs["System docs<br/>architecture docs"]
  node_specs["Kiro specs<br/>design specs<br/>[requirements.md]"]
end

node_web -->|"API calls"| node_api
node_browser -->|"shells"| node_web
node_api -->|"uses"| node_auth
node_api -->|"persists"| node_db
node_api -->|"coordinates"| node_redis
node_api -->|"exposes"| node_api_routes
node_api -->|"implements"| node_api_services
node_api -->|"orchestrates"| node_workflows
node_workflows -->|"dispatches"| node_tasks
node_worker -->|"runs"| node_tasks
node_tasks -->|"polls"| node_redis
node_api -->|"routes AI"| node_modelrouter
node_api -->|"integrates"| node_github
node_api -->|"tracks deploys"| node_vercel
node_api_services -->|"calls"| node_modelrouter
node_api_services -->|"reads/writes"| node_db
node_api_services -->|"signals"| node_redis
node_shared -->|"contracts"| node_web
node_shared -->|"contracts"| node_api
node_prompts -->|"guides"| node_modelrouter
node_constitution -->|"governs"| node_api
node_docs -->|"describes"| node_api
node_specs -->|"specifies"| node_api
node_docs -->|"defines"| node_prompts

click node_api "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/index.ts"
click node_auth "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/auth/index.ts"
click node_db "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/prisma/schema.prisma"
click node_redis "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/redis.ts"
click node_workflows "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/workflows.ts"
click node_tasks "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/task-runner.ts"
click node_modelrouter "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/model-router.ts"
click node_github "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/github-provider.ts"
click node_vercel "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/vercel-deployments.ts"
click node_web "https://github.com/radiiduration/ai-company-os/blob/main/apps/web/src/App.tsx"
click node_browser "https://github.com/radiiduration/ai-company-os/blob/main/apps/sovereign-browser/src-tauri/src/main.rs"
click node_shared "https://github.com/radiiduration/ai-company-os/blob/main/packages/shared/src/index.ts"
click node_prompts "https://github.com/radiiduration/ai-company-os/blob/main/prompts/README.md"
click node_constitution "https://github.com/radiiduration/ai-company-os/blob/main/CONSTITUTION.md"
click node_docs "https://github.com/radiiduration/ai-company-os/blob/main/docs/06_system_architecture.md"
click node_specs "https://github.com/radiiduration/ai-company-os/blob/main/.kiro/specs/ai-company-full-product/requirements.md"
click node_worker "https://github.com/radiiduration/ai-company-os/blob/main/apps/worker/src/index.ts"
click node_api_routes "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/routes/auth.ts"
click node_api_services "https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/events.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_api,node_web,node_browser,node_worker toneBlue
class node_auth,node_db,node_redis,node_workflows,node_tasks,node_modelrouter,node_github,node_vercel,node_api_routes,node_api_services toneAmber
class node_shared,node_prompts toneMint
class node_constitution,node_docs,node_specs toneRose
```

## Components

### Runtime services

The deployable processes that handle requests, orchestration, background execution, and native shell packaging.

- [API](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/index.ts): Hono control plane · Main backend orchestration surface for product domains, auth, workflows, and integrations. · `apps/api/src/index.ts`
- [Web UI](https://github.com/radiiduration/ai-company-os/blob/main/apps/web/src/App.tsx): React dashboard · Browser-based command center for humans to observe and steer company state. · `apps/web/src/App.tsx`
- [Sovereign browser](https://github.com/radiiduration/ai-company-os/blob/main/apps/sovereign-browser/src-tauri/src/main.rs): Tauri shell · Native desktop shell scaffold around the browser experience. · `apps/sovereign-browser/src-tauri/src/main.rs`
- [Worker](https://github.com/radiiduration/ai-company-os/blob/main/apps/worker/src/index.ts): background process · Separate Node process for asynchronous task consumption and execution. · `apps/worker/src/index.ts`

### Backend control plane

API-side domains, state stores, and execution services centered in apps/api.

- [Auth](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/auth/index.ts): identity boundary · Magic-link, OAuth, session, and crypto/middleware support for backend identity handling. · `apps/api/src/auth/index.ts`
- [Postgres](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/prisma/schema.prisma): Prisma store · Primary relational system of record behind the API. · `apps/api/prisma/schema.prisma`
- [Redis](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/redis.ts): coordination state · Ephemeral state for queues, caching, locks, and workflow coordination. · `apps/api/src/redis.ts`
- [Workflows](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/workflows.ts): execution engine · Task and workflow coordination across governance gates, async execution, and releases. · `apps/api/src/services/workflows.ts`
- [Task runner](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/task-runner.ts): job execution · Executes routed work units and departmental actions for the background process boundary. · `apps/api/src/services/task-runner.ts`
- [Model router](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/model-router.ts): AI abstraction · Routes model/provider requests through a central service boundary. · `apps/api/src/services/model-router.ts`
- [GitHub](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/github-provider.ts): integration · Webhook and provider boundary for repository events and source-driven workflows. · `apps/api/src/services/github-provider.ts`
- [Vercel](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/vercel-deployments.ts): deployment integration · Deployment visibility and orchestration integration for release feedback loops. · `apps/api/src/services/vercel-deployments.ts`
- [API routes](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/routes/auth.ts): domain endpoints · Major product surfaces exposed by the backend: auth, orgs, projects, repos, governance, gates, memory, release packets, war room, and worker APIs. · `apps/api/src/routes/auth.ts`
- [Domain services](https://github.com/radiiduration/ai-company-os/blob/main/apps/api/src/services/events.ts): business logic · Core backend services for events, evaluations, evidence, memory, usage, war room, and seeding. · `apps/api/src/services/events.ts`

### Shared contracts

Cross-app code and operating-model inputs that shape behavior across the repo.

- [Shared types](https://github.com/radiiduration/ai-company-os/blob/main/packages/shared/src/index.ts): cross-app contracts · Common types and message contracts used across apps and services. · `packages/shared/src/index.ts`
- [Prompts](https://github.com/radiiduration/ai-company-os/blob/main/prompts/README.md): role contracts · Department-specific prompt definitions and global preamble shaping agent behavior. · `prompts/README.md`

### Governance and specs

Docs, constitution, and formal specs that define the operating model and architecture.

- [Constitution](https://github.com/radiiduration/ai-company-os/blob/main/CONSTITUTION.md): operating rules · Core product and governance rules defining how the system should operate. · `CONSTITUTION.md`
- [System docs](https://github.com/radiiduration/ai-company-os/blob/main/docs/06_system_architecture.md): architecture docs · Primary design and product documentation for vision, workflows, architecture, and security. · `docs/06_system_architecture.md`
- [Kiro specs](https://github.com/radiiduration/ai-company-os/blob/main/.kiro/specs/ai-company-full-product/requirements.md): design specs · Formal requirements, designs, and task specs that shape implementation boundaries. · `.kiro/specs/ai-company-full-product/requirements.md`

## Connections

- Web UI → API: API calls · Dashboard reads and drives state through the backend control plane.
- Sovereign browser → Web UI: shells · Desktop shell wraps the web experience.
- API → Auth: uses · API delegates identity and session flows to the auth subsystem.
- API → Postgres: persists · Backend stores system-of-record state in the relational database.
- API → Redis: coordinates · Backend uses Redis for coordination and ephemeral workflow state.
- API → API routes: exposes · HTTP surface for product domains and integrations.
- API → Domain services: implements · Domain logic is concentrated in service modules.
- API → Workflows: orchestrates · API coordinates workflow lifecycle and gate-driven execution.
- Workflows → Task runner: dispatches · Workflow engine sends async work to the executor boundary.
- Worker → Task runner: runs · Separate worker process performs background task execution.
- Task runner → Redis: polls · Task execution likely relies on Redis-backed coordination/queue state.
- API → Model router: routes AI · Backend centralizes model/provider selection through the router service.
- API → GitHub: integrates · GitHub webhooks and provider logic feed repo-driven workflows.
- API → Vercel: tracks deploys · Deployment state informs release and governance flows.
- Domain services → Model router: calls · Business services can invoke model routing as part of AI-driven operations.
- Domain services → Postgres: reads/writes · Domain services persist and retrieve workflow, memory, and evaluation state.
- Domain services → Redis: signals · Services use ephemeral coordination for jobs and workflow state.
- Shared types → Web UI: contracts · Shared types keep UI and backend payloads aligned.
- Shared types → API: contracts · Backend and other apps share common message and domain types.
- Prompts → Model router: guides · Role-specific prompts shape AI behavior behind the model boundary.
- Constitution → API: governs · Operating rules constrain backend behavior and product scope.
- System docs → API: describes · Architecture and workflow documentation explain the backend system.
- Kiro specs → API: specifies · Formal specs define implementation intent and boundaries.
- System docs → Prompts: defines · Prompting standards and agent roles are documented as part of the operating model.