How radiiduration/ai-company-os works
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: index.ts API · events.ts Domain services · App.tsx Web UI · task-runner.ts Task runner
Components 19
Runtime services
The deployable processes that handle requests, orchestration, background execution, and native shell packaging.
- API · Main backend orchestration surface for product domains, auth, workflows, and integrations.
apps/api/src/index.ts - Web UI · Browser-based command center for humans to observe and steer company state.
apps/web/src/App.tsx - Sovereign browser · Native desktop shell scaffold around the browser experience.
apps/sovereign-browser/src-tauri/src/main.rs - Worker · 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 · Magic-link, OAuth, session, and crypto/middleware support for backend identity handling.
apps/api/src/auth/index.ts - Postgres · Primary relational system of record behind the API.
apps/api/prisma/schema.prisma - Redis · Ephemeral state for queues, caching, locks, and workflow coordination.
apps/api/src/redis.ts - Workflows · Task and workflow coordination across governance gates, async execution, and releases.
apps/api/src/services/workflows.ts - Task runner · Executes routed work units and departmental actions for the background process boundary.
apps/api/src/services/task-runner.ts - Model router · Routes model/provider requests through a central service boundary.
apps/api/src/services/model-router.ts - GitHub · Webhook and provider boundary for repository events and source-driven workflows.
apps/api/src/services/github-provider.ts - Vercel · Deployment visibility and orchestration integration for release feedback loops.
apps/api/src/services/vercel-deployments.ts - API routes · 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 · 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 · Common types and message contracts used across apps and services.
packages/shared/src/index.ts - Prompts · 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 · Core product and governance rules defining how the system should operate.
CONSTITUTION.md - System docs · Primary design and product documentation for vision, workflows, architecture, and security.
docs/06_system_architecture.md - Kiro specs · Formal requirements, designs, and task specs that shape implementation boundaries.
.kiro/specs/ai-company-full-product/requirements.md
Connections 24
- 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.