# garysychan/ai-os architecture

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

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

## Overview

AI OS Control Plane is a governed framework for coordinating task state, agent roles, policy checks, workflow execution, and auditable runtime evidence. A user enters through the HTTP API or CLI; the API exposes control-plane and workflow operations, while the workflow engine can delegate lifecycle work to the controller, which dispatches requests through the agent runtime. Tasks and workflow definitions provide the domain state; execution adapters and persistence support controlled operations and recovery. The README documents broader governance, scheduling, monitoring, and collaboration capabilities; unsampled links are omitted where source evidence is unavailable.

Main entry points: [`src/ai_os/api/services.py`](https://github.com/garysychan/ai-os/blob/main/src/ai_os/api/services.py) (API Services), [`src/ai_os/workflows/engine.py`](https://github.com/garysychan/ai-os/blob/main/src/ai_os/workflows/engine.py) (Workflow Engine), [`src/ai_os/cli.py`](https://github.com/garysychan/ai-os/blob/main/src/ai_os/cli.py) (Control CLI), [`src/ai_os/controller/engine.py`](https://github.com/garysychan/ai-os/blob/main/src/ai_os/controller/engine.py) (Controller Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_api["HTTP API<br/>[app.py]"]
  node_api_services["API Services<br/>[services.py]"]
  node_cli["Control CLI<br/>[cli.py]"]
end

subgraph group_domain["Task and Governance"]
  node_tasks["Task Model<br/>[models.py]"]
  node_governance["Governance Checks<br/>[checker.py]"]
  node_workflow_defs["Workflow Definitions<br/>[definitions.py]"]
end

subgraph group_runtime["Orchestration Runtime"]
  node_workflow["Workflow Engine<br/>[engine.py]"]
  node_controller["Controller Engine<br/>[engine.py]"]
  node_agents["Agent Runtime<br/>[runtime.py]"]
  node_execution["Execution Engine<br/>[engine.py]"]
end

subgraph group_support["Policies and Integrations"]
  node_adapters["Adapter Services<br/>[service.py]"]
  node_tools["Tool Services<br/>[service.py]"]
  node_scheduler["Scheduler<br/>[service.py]"]
  node_monitoring["Monitoring<br/>[service.py]"]
end

subgraph group_evidence["Persistence and Audit"]
  node_observability["Observability<br/>[service.py]"]
  node_persistence[("SQLite Persistence<br/>[sqlite_store.py]")]
  node_workflow_store[("Workflow Store<br/>[store.py]")]
end

node_user(("Operator"))

node_user -->|"submits requests"| node_api
node_user -->|"runs commands"| node_cli
node_api -->|"routes operations"| node_api_services
node_api_services -->|"checks consistency"| node_governance
node_api_services -->|"validates workflows"| node_workflow_defs
node_api_services -->|"dry-runs workflows"| node_workflow
node_workflow -->|"delegates lifecycle"| node_controller
node_controller -->|"dispatches requests"| node_agents
node_workflow -->|"advances task state"| node_tasks
node_controller -->|"updates task status"| node_tasks
node_execution -->|"resolves adapters"| node_adapters
node_api_services -->|"validates plans"| node_execution
node_api_services -->|"lists agents"| node_agents
node_api_services -->|"uses repositories"| node_persistence
node_api_services -->|"reads metrics"| node_monitoring
node_api_services -->|"queries audit"| node_observability
node_workflow -.->|"stores sessions"| node_workflow_store
node_scheduler -->|"uses agent roles"| node_agents
node_observability -.->|"stores runtime events"| node_persistence
node_cli -.->|"exposes commands"| node_scheduler
node_cli -.->|"exposes commands"| node_execution
node_tools -->|"uses adapters"| node_adapters

click node_api "https://github.com/garysychan/ai-os/blob/main/src/ai_os/api/app.py"
click node_api_services "https://github.com/garysychan/ai-os/blob/main/src/ai_os/api/services.py"
click node_cli "https://github.com/garysychan/ai-os/blob/main/src/ai_os/cli.py"
click node_tasks "https://github.com/garysychan/ai-os/blob/main/src/ai_os/tasks/models.py"
click node_governance "https://github.com/garysychan/ai-os/blob/main/src/ai_os/governance/checker.py"
click node_workflow_defs "https://github.com/garysychan/ai-os/blob/main/src/ai_os/workflows/definitions.py"
click node_workflow "https://github.com/garysychan/ai-os/blob/main/src/ai_os/workflows/engine.py"
click node_controller "https://github.com/garysychan/ai-os/blob/main/src/ai_os/controller/engine.py"
click node_agents "https://github.com/garysychan/ai-os/blob/main/src/ai_os/agents/runtime.py"
click node_execution "https://github.com/garysychan/ai-os/blob/main/src/ai_os/execution/engine.py"
click node_adapters "https://github.com/garysychan/ai-os/blob/main/src/ai_os/adapters/service.py"
click node_tools "https://github.com/garysychan/ai-os/blob/main/src/ai_os/tools/service.py"
click node_scheduler "https://github.com/garysychan/ai-os/blob/main/src/ai_os/scheduler/service.py"
click node_monitoring "https://github.com/garysychan/ai-os/blob/main/src/ai_os/monitoring/service.py"
click node_observability "https://github.com/garysychan/ai-os/blob/main/src/ai_os/observability/service.py"
click node_persistence "https://github.com/garysychan/ai-os/blob/main/src/ai_os/persistence/sqlite_store.py"
click node_workflow_store "https://github.com/garysychan/ai-os/blob/main/src/ai_os/workflows/store.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_api,node_api_services,node_cli toneBlue
class node_tasks,node_governance,node_workflow_defs toneAmber
class node_workflow,node_controller,node_agents,node_execution toneMint
class node_adapters,node_tools,node_scheduler,node_monitoring toneRose
class node_observability,node_persistence,node_workflow_store,node_user toneIndigo
```

## Components

### User Interfaces

- [HTTP API](https://github.com/garysychan/ai-os/blob/main/src/ai_os/api/app.py): `src/ai_os/api/app.py`
- [API Services](https://github.com/garysychan/ai-os/blob/main/src/ai_os/api/services.py): `src/ai_os/api/services.py`
- [Control CLI](https://github.com/garysychan/ai-os/blob/main/src/ai_os/cli.py): `src/ai_os/cli.py`

### Task and Governance

- [Task Model](https://github.com/garysychan/ai-os/blob/main/src/ai_os/tasks/models.py): `src/ai_os/tasks/models.py`
- [Governance Checks](https://github.com/garysychan/ai-os/blob/main/src/ai_os/governance/checker.py): `src/ai_os/governance/checker.py`
- [Workflow Definitions](https://github.com/garysychan/ai-os/blob/main/src/ai_os/workflows/definitions.py): `src/ai_os/workflows/definitions.py`

### Orchestration Runtime

- [Workflow Engine](https://github.com/garysychan/ai-os/blob/main/src/ai_os/workflows/engine.py): `src/ai_os/workflows/engine.py`
- [Controller Engine](https://github.com/garysychan/ai-os/blob/main/src/ai_os/controller/engine.py): `src/ai_os/controller/engine.py`
- [Agent Runtime](https://github.com/garysychan/ai-os/blob/main/src/ai_os/agents/runtime.py): `src/ai_os/agents/runtime.py`
- [Execution Engine](https://github.com/garysychan/ai-os/blob/main/src/ai_os/execution/engine.py): `src/ai_os/execution/engine.py`

### Policies and Integrations

- [Adapter Services](https://github.com/garysychan/ai-os/blob/main/src/ai_os/adapters/service.py): `src/ai_os/adapters/service.py`
- [Tool Services](https://github.com/garysychan/ai-os/blob/main/src/ai_os/tools/service.py): `src/ai_os/tools/service.py`
- [Scheduler](https://github.com/garysychan/ai-os/blob/main/src/ai_os/scheduler/service.py): `src/ai_os/scheduler/service.py`
- [Monitoring](https://github.com/garysychan/ai-os/blob/main/src/ai_os/monitoring/service.py): `src/ai_os/monitoring/service.py`

### Persistence and Audit

- [Observability](https://github.com/garysychan/ai-os/blob/main/src/ai_os/observability/service.py): `src/ai_os/observability/service.py`
- [SQLite Persistence](https://github.com/garysychan/ai-os/blob/main/src/ai_os/persistence/sqlite_store.py): `src/ai_os/persistence/sqlite_store.py`
- [Workflow Store](https://github.com/garysychan/ai-os/blob/main/src/ai_os/workflows/store.py): `src/ai_os/workflows/store.py`

### Other components

- **Operator**

## Connections

- Operator → HTTP API: submits requests (evidence: `src/ai_os/api/app.py`)
- Operator → Control CLI: runs commands (evidence: `src/ai_os/cli.py`)
- HTTP API → API Services: routes operations (evidence: `src/ai_os/api/app.py`)
- API Services → Governance Checks: checks consistency (evidence: `src/ai_os/api/services.py`)
- API Services → Workflow Definitions: validates workflows (evidence: `src/ai_os/api/services.py`)
- API Services → Workflow Engine: dry-runs workflows (evidence: `src/ai_os/api/services.py`)
- Workflow Engine → Controller Engine: delegates lifecycle (evidence: `src/ai_os/workflows/engine.py`)
- Controller Engine → Agent Runtime: dispatches requests (evidence: `src/ai_os/controller/engine.py`)
- Workflow Engine → Task Model: advances task state (evidence: `src/ai_os/workflows/engine.py`)
- Controller Engine → Task Model: updates task status (evidence: `src/ai_os/controller/engine.py`)
- Execution Engine → Adapter Services: resolves adapters (evidence: `src/ai_os/execution/engine.py`)
- API Services → Execution Engine: validates plans (evidence: `src/ai_os/api/services.py`)
- API Services → Agent Runtime: lists agents (evidence: `src/ai_os/api/services.py`)
- API Services → SQLite Persistence: uses repositories (evidence: `src/ai_os/api/services.py`)
- API Services → Monitoring: reads metrics (evidence: `src/ai_os/api/services.py`)
- API Services → Observability: queries audit (evidence: `src/ai_os/api/services.py`)
- Workflow Engine → Workflow Store: stores sessions (evidence: `src/ai_os/workflows/engine.py`)
- Scheduler → Agent Runtime: uses agent roles (evidence: `src/ai_os/scheduler/service.py`)
- Observability → SQLite Persistence: stores runtime events
- Control CLI → Scheduler: exposes commands
- Control CLI → Execution Engine: exposes commands
- Tool Services → Adapter Services: uses adapters (evidence: `src/ai_os/tools/service.py`)
