# arttribute/common-os architecture

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

- Interactive diagram: https://gitdiagram.com/arttribute/common-os
- Repository: https://github.com/arttribute/common-os

## Overview

1. **Monorepo layout**
   - This is a TypeScript pnpm workspace with three product surfaces in `apps/` and five shared packages in `packages/`.
   - The architectural split is clear: control plane API, operator UI, agent runtime/daemon, and reusable SDK/CLI/cloud abstractions.

2. **Control plane API (`apps/api`)**
   - The API is the system’s backend hub. It exposes fleet, agent, task, event, wallet, session, and auth routes.
   - It is a Hono-based Node service that persists domain state in MongoDB via Mongoose models under `src/db/models`.
   - The API is also the event ingestion point for agents and the broadcast source for the live world stream.

3. **Domain state and persistence**
   - Mongo collections model the core objects: tenants, fleets, agents, sessions, tasks, messages, events, world state, wallets, and human messages.
   - `memory.ts` suggests a non-persistent or demo/in-memory implementation used for local or fallback behavior.
   - World state is not just computed client-side; it is stored and served from the API as a snapshot that the UI can reconcile against.

4. **Authentication and identity**
   - The repo supports Privy-backed tenant auth plus two token classes: tenant API keys and agent-scoped tokens.
   - Human operators use tenant credentials to manage fleets; agents use injected tokens to call daemon-only and event routes.
   - This creates a hard boundary between fleet administration and agent runtime capabilities.

5. **Fleet and agent lifecycle**
   - Fleet creation, agent deployment, updates, and termination all flow through the API.
   - Provisioning is handled by services in `apps/api/src/services`, with cloud-specific logic abstracted behind provider code and a runner service.
   - The agent deploy path is the main infrastructure control loop: API request → provisioning service → cloud runtime/pod creation → agent bootstraps back into the control plane.

6. **Agent runtime inside pods**
   - `apps/runner` is a Cloud Run service that wraps agent-commons execution.
   - `apps/api/agent` contains the container image and entrypoint used for agent pods.
   - `packages/daemon` is the process that runs inside each agent pod, handling task polling, heartbeats, health monitoring, file watching, and event emission back to the API.

7. **P2P communication path**
   - The system integrates Gensyn AXL as a direct agent-to-agent messaging layer.
   - Each pod runs an AXL node, registers its multiaddr with the control plane, and exchanges messages peer-to-peer rather than through a central broker.
   - The API persists message history and peer metadata, but the actual transport is decentralized.

8. **World simulation and live UI (`apps/web`)**
   - The web app is a Next.js 15 frontend that combines a React HUD with a Phaser-based isometric world.
   - `WorldScene`, `UIScene`, and the HUD components render agents, movement, objects, and task state as a spatial simulation.
   - Zustand stores and `useWorldConnection` subscribe to the API’s WebSocket stream and keep the simulation in sync with server events.

9. **Event-driven data flow**
   - Agents emit events to `POST /events`, the API stores them and rebroadcasts them over WebSocket, and the UI consumes them in real time.
   - This is the primary cross-cutting flow for task lifecycle, movement, state changes, file changes, and messages.
   - The same event stream powers both the visual world and the operational dashboards.

10. **Client tooling (`packages/cli` and `packages/sdk`)**
    - `@common-os/cli` provides the `cos` command for operators: auth, fleet management, agent deployment, task submission, logs, and world inspection.
    - `@common-os/sdk` provides typed clients for both human operators and in-pod agents, so the same control plane can be used from UI, CLI, and runtime code.
    - These packages are thin client boundaries over the API rather than separate services.

11. **Cloud/provider abstraction**
    - `@common-os/cloud` contains AWS and GCP provider implementations, indicating the platform is designed to launch agent workloads across cloud backends.
    - Deployment assets and CI/CD are split by component with Dockerfiles, Cloud Build configs, and GitHub Actions workflows.
    - The repo is therefore not just an app; it is a deployment platform with infrastructure orchestration, runtime packaging, and a real-time operator experience.

12. **Important product boundary**
    - The architecture intentionally separates “control plane” concerns from “embodied simulation” concerns.
    - The API and runtime packages own truth, permissions, and provisioning; the web app is a projection of that truth into a spatial interface.
    - That separation is what makes the system diagrammatic: operations happen in the backend, but their consequences are visualized live in the world UI.

Main entry points: [`apps/api/src/routes/events.ts`](https://github.com/arttribute/common-os/blob/main/apps/api/src/routes/events.ts) (Event Ingest), [`apps/api/src/routes/fleets.ts`](https://github.com/arttribute/common-os/blob/main/apps/api/src/routes/fleets.ts) (Routes), [`apps/api/src/services/provisioner.ts`](https://github.com/arttribute/common-os/blob/main/apps/api/src/services/provisioner.ts) (Provisioner), [`apps/web/components/WorldClient.tsx`](https://github.com/arttribute/common-os/blob/main/apps/web/components/WorldClient.tsx) (World Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps_api["Control Plane"]
  node_api_entry["API Server<br/>hono node service<br/>[index.ts]"]
  node_api_auth["Auth<br/>middleware<br/>[auth.ts]"]
  node_api_routes["Routes<br/>http api<br/>[fleets.ts]"]
  node_api_events["Event Ingest<br/>realtime api<br/>[events.ts]"]
  node_api_stream["World Stream<br/>websocket<br/>[stream.ts]"]
  node_api_db[("Mongo DB<br/>persistence<br/>[mongo.ts]")]
  node_api_models["Domain Models<br/>mongoose models<br/>[index.ts]"]
  node_api_world["World State<br/>projection service<br/>[world.ts]"]
  node_api_provision["Provisioner<br/>fleet provisioning<br/>[provisioner.ts]"]
  node_api_cloudinit["Cloud Init<br/>bootstrapping<br/>[cloud-init.ts]"]
end

subgraph group_apps_web["Operator UI"]
  node_web_world["World Page<br/>next.js page<br/>[page.tsx]"]
  node_web_client["World Client<br/>client bridge<br/>[WorldClient.tsx]"]
  node_web_scene["World Scene<br/>phaser scene<br/>[WorldScene.ts]"]
  node_web_ws["World Sync<br/>realtime hook"]
  node_web_store["World Store<br/>state store<br/>[worldStore.ts]"]
end

subgraph group_runtime["Runtime"]
  node_runner["Runner<br/>cloud run service<br/>[index.ts]"]
  node_agent_image["Agent Image<br/>container entrypoint<br/>[entrypoint.sh]"]
  node_daemon["Daemon<br/>agent process<br/>[daemon.ts]"]
end

subgraph group_shared["Shared Packages"]
  node_cli["CLI<br/>operator tool<br/>[cli.ts]"]
  node_sdk["SDK<br/>typed client<br/>[index.ts]"]
  node_cloud["Cloud Abstraction<br/>provider library<br/>[factory.ts]"]
  node_event_schema["Event Schema<br/>contracts<br/>[index.ts]"]
end

node_api_entry -->|"uses"| node_api_auth
node_api_entry -->|"mounts"| node_api_routes
node_api_routes -->|"reads/writes"| node_api_db
node_api_db -->|"uses"| node_api_models
node_api_routes -->|"ingests"| node_api_events
node_api_events -->|"rebroadcasts"| node_api_stream
node_api_events -->|"updates"| node_api_world
node_api_provision -->|"builds"| node_api_cloudinit
node_api_provision -->|"delegates"| node_cloud
node_api_provision -->|"starts"| node_runner
node_api_provision -->|"boots"| node_agent_image
node_runner -->|"executes"| node_daemon
node_daemon -->|"emits"| node_api_events
node_daemon -->|"uses"| node_sdk
node_cli -->|"wraps"| node_sdk
node_sdk -->|"calls"| node_api_routes
node_web_world -->|"contains"| node_web_client
node_web_client -->|"subscribes"| node_web_ws
node_web_ws -->|"connects"| node_api_stream
node_web_client -->|"drives"| node_web_scene
node_web_scene -->|"reads/writes"| node_web_store
node_web_client -->|"queries"| node_api_routes
node_sdk -->|"posts"| node_api_events
node_event_schema -->|"defines"| node_api_events
node_event_schema -->|"defines"| node_daemon

click node_api_entry "https://github.com/arttribute/common-os/blob/main/apps/api/src/index.ts"
click node_api_auth "https://github.com/arttribute/common-os/blob/main/apps/api/src/middleware/auth.ts"
click node_api_routes "https://github.com/arttribute/common-os/blob/main/apps/api/src/routes/fleets.ts"
click node_api_events "https://github.com/arttribute/common-os/blob/main/apps/api/src/routes/events.ts"
click node_api_stream "https://github.com/arttribute/common-os/blob/main/apps/api/src/routes/stream.ts"
click node_api_db "https://github.com/arttribute/common-os/blob/main/apps/api/src/db/mongo.ts"
click node_api_models "https://github.com/arttribute/common-os/blob/main/apps/api/src/db/models/index.ts"
click node_api_world "https://github.com/arttribute/common-os/blob/main/apps/api/src/services/world.ts"
click node_api_provision "https://github.com/arttribute/common-os/blob/main/apps/api/src/services/provisioner.ts"
click node_api_cloudinit "https://github.com/arttribute/common-os/blob/main/apps/api/src/services/cloud-init.ts"
click node_runner "https://github.com/arttribute/common-os/blob/main/apps/runner/src/index.ts"
click node_agent_image "https://github.com/arttribute/common-os/blob/main/apps/api/agent/entrypoint.sh"
click node_daemon "https://github.com/arttribute/common-os/blob/main/packages/daemon/src/daemon.ts"
click node_web_world "https://github.com/arttribute/common-os/blob/main/apps/web/app/world/page.tsx"
click node_web_client "https://github.com/arttribute/common-os/blob/main/apps/web/components/WorldClient.tsx"
click node_web_scene "https://github.com/arttribute/common-os/blob/main/apps/web/game/scenes/WorldScene.ts"
click node_web_ws "https://github.com/arttribute/common-os/blob/main/apps/web/hooks/useWorldConnection.ts"
click node_web_store "https://github.com/arttribute/common-os/blob/main/apps/web/store/worldStore.ts"
click node_cli "https://github.com/arttribute/common-os/blob/main/packages/cli/src/cli.ts"
click node_sdk "https://github.com/arttribute/common-os/blob/main/packages/sdk/src/index.ts"
click node_cloud "https://github.com/arttribute/common-os/blob/main/packages/cloud/src/factory.ts"
click node_event_schema "https://github.com/arttribute/common-os/blob/main/packages/event-schema/src/index.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_entry,node_api_auth,node_api_routes,node_api_events,node_api_stream,node_api_db,node_api_models,node_api_world,node_api_provision,node_api_cloudinit toneBlue
class node_web_world,node_web_client,node_web_scene,node_web_ws,node_web_store toneAmber
class node_runner,node_agent_image,node_daemon toneMint
class node_cli,node_sdk,node_cloud,node_event_schema toneRose
```

## Components

### Control Plane

Backend API, persistence, provisioning, and agent runtime image.

- [API Server](https://github.com/arttribute/common-os/blob/main/apps/api/src/index.ts): hono node service · Main control-plane entrypoint mounting auth, fleet, agent, task, message, wallet, session, event, and stream routes. · `apps/api/src/index.ts`
- [Auth](https://github.com/arttribute/common-os/blob/main/apps/api/src/middleware/auth.ts): middleware · Tenant authentication and token resolution boundary for operator and agent requests. · `apps/api/src/middleware/auth.ts`
- [Routes](https://github.com/arttribute/common-os/blob/main/apps/api/src/routes/fleets.ts): http api · Primary route layer for auth, fleets, agents, tasks, sessions, messages, wallets, events, stream, and agent runtime. · `apps/api/src/routes/fleets.ts`
- [Event Ingest](https://github.com/arttribute/common-os/blob/main/apps/api/src/routes/events.ts): realtime api · Stores agent events and rebroadcasts them to live consumers. · `apps/api/src/routes/events.ts`
- [World Stream](https://github.com/arttribute/common-os/blob/main/apps/api/src/routes/stream.ts): websocket · Broadcast channel for world state and operational updates consumed by the UI. · `apps/api/src/routes/stream.ts`
- [Mongo DB](https://github.com/arttribute/common-os/blob/main/apps/api/src/db/mongo.ts): persistence · Mongo connection and data access layer for control-plane state. · `apps/api/src/db/mongo.ts`
- [Domain Models](https://github.com/arttribute/common-os/blob/main/apps/api/src/db/models/index.ts): mongoose models · Collections for tenants, fleets, agents, sessions, tasks, messages, events, wallets, and world state. · `apps/api/src/db/models/index.ts`
- [World State](https://github.com/arttribute/common-os/blob/main/apps/api/src/services/world.ts): projection service · Maintains the server-side world snapshot served to the UI. · `apps/api/src/services/world.ts`
- [Provisioner](https://github.com/arttribute/common-os/blob/main/apps/api/src/services/provisioner.ts): fleet provisioning · Orchestrates fleet creation, agent deployment, and cloud runtime startup. · `apps/api/src/services/provisioner.ts`
- [Cloud Init](https://github.com/arttribute/common-os/blob/main/apps/api/src/services/cloud-init.ts): bootstrapping · Builds agent startup configuration and runtime bootstrap payloads. · `apps/api/src/services/cloud-init.ts`

### Operator UI

Next.js frontend and live world simulation.

- [World Page](https://github.com/arttribute/common-os/blob/main/apps/web/app/world/page.tsx): next.js page · Primary world surface combining HUD and isometric simulation. · `apps/web/app/world/page.tsx`
- [World Client](https://github.com/arttribute/common-os/blob/main/apps/web/components/WorldClient.tsx): client bridge · Connects the UI to the control plane and live world stream. · `apps/web/components/WorldClient.tsx`
- [World Scene](https://github.com/arttribute/common-os/blob/main/apps/web/game/scenes/WorldScene.ts): phaser scene · Renders agents, objects, movement, and task state in the spatial simulation. · `apps/web/game/scenes/WorldScene.ts`
- [World Sync](https://github.com/arttribute/common-os/blob/main/apps/web/hooks/useWorldConnection.ts): realtime hook · Subscribes to the API websocket and keeps local stores in sync. · `apps/web/hooks/useWorldConnection.ts`
- [World Store](https://github.com/arttribute/common-os/blob/main/apps/web/store/worldStore.ts): state store · Client-side state for agents, world entities, and live updates. · `apps/web/store/worldStore.ts`

### Runtime

Agent pod process, runner wrapper, and entrypoint.

- [Runner](https://github.com/arttribute/common-os/blob/main/apps/runner/src/index.ts): cloud run service · Cloud Run wrapper for agent-commons execution. · `apps/runner/src/index.ts`
- [Agent Image](https://github.com/arttribute/common-os/blob/main/apps/api/agent/entrypoint.sh): container entrypoint · Container image and entrypoint used to launch agent pods. · `apps/api/agent/entrypoint.sh`
- [Daemon](https://github.com/arttribute/common-os/blob/main/packages/daemon/src/daemon.ts): agent process · Runs inside each agent pod to poll tasks, send heartbeats, watch files, and emit events. · `packages/daemon/src/daemon.ts`

### Shared Packages

Reusable CLI, SDK, cloud, and schema libraries.

- [CLI](https://github.com/arttribute/common-os/blob/main/packages/cli/src/cli.ts): operator tool · Command-line surface for auth, fleet management, agent deployment, tasks, logs, and inspection. · `packages/cli/src/cli.ts`
- [SDK](https://github.com/arttribute/common-os/blob/main/packages/sdk/src/index.ts): typed client · Shared client library for operator and in-pod access to the control plane. · `packages/sdk/src/index.ts`
- [Cloud Abstraction](https://github.com/arttribute/common-os/blob/main/packages/cloud/src/factory.ts): provider library · AWS and GCP provider implementations behind fleet deployment. · `packages/cloud/src/factory.ts`
- [Event Schema](https://github.com/arttribute/common-os/blob/main/packages/event-schema/src/index.ts): contracts · Shared event definitions for the control plane and runtime. · `packages/event-schema/src/index.ts`

## Connections

- API Server → Auth: uses · All control-plane requests pass through auth boundary.
- API Server → Routes: mounts · Server wires the domain route modules.
- Routes → Mongo DB: reads/writes · Route handlers persist and query state.
- Mongo DB → Domain Models: uses · Mongo collections are defined through models.
- Routes → Event Ingest: ingests · Agent events enter the control plane here.
- Event Ingest → World Stream: rebroadcasts · Stored events are pushed to live subscribers.
- Event Ingest → World State: updates · Event ingestion reconciles the server-side world snapshot.
- Provisioner → Cloud Init: builds · Provisioning prepares runtime bootstrap data.
- Provisioner → Cloud Abstraction: delegates · Cloud-specific launch logic is abstracted behind provider implementations.
- Provisioner → Runner: starts · Agent workloads are launched through the runner path.
- Provisioner → Agent Image: boots · Agent pods use the packaged container entrypoint.
- Runner → Daemon: executes · Runner wraps agent-commons execution for the pod.
- Daemon → Event Ingest: emits · Daemon sends task, heartbeat, health, and file events upstream.
- Daemon → SDK: uses · Runtime relies on typed control-plane client behavior.
- CLI → SDK: wraps · CLI is a thin operator surface over the SDK.
- SDK → Routes: calls · SDK targets the control-plane HTTP API.
- World Page → World Client: contains · World page composes the live client bridge.
- World Client → World Sync: subscribes · Client bridge listens to live control-plane updates.
- World Sync → World Stream: connects · UI syncs through the websocket world stream.
- World Client → World Scene: drives · Incoming events update the Phaser world.
- World Scene → World Store: reads/writes · Scene state is mirrored in client stores.
- World Client → Routes: queries · UI also uses control-plane endpoints for current state and actions.
- SDK → Event Ingest: posts · Agent and operator clients can submit events through the shared API surface.
- Event Schema → Event Ingest: defines · Shared schema keeps event payloads aligned.
- Event Schema → Daemon: defines · Runtime event payloads follow shared contracts.