# maithili31/ai_os architecture

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

- Interactive diagram: https://gitdiagram.com/maithili31/ai_os
- Repository: https://github.com/maithili31/ai_os

## Overview

AI_OS is a TypeScript monorepo centered on a local, event-driven workflow runtime. The main architectural split is between the orchestration core in `packages/`, the API layer in `packages/server`, and two UI clients in `apps/dashboard` and `apps/desktop`.

1. **Core runtime: event → workflow → tool execution**
   The system’s primary flow is:
   external trigger, such as a Gmail event, becomes an internal event; the workflow engine matches that event to a workflow; the workflow executes one or more tools; results and failures are recorded. This is the main path to draw on the architecture diagram.

2. **Workflow engine is the central brain**
   `packages/workflow-engine` contains the orchestration layer: workflow definitions, workflow lookup, execution handling, action execution, and DLQ handling. The presence of `workflow.repository.ts`, `workflow.service.ts`, `execution.service.ts`, and `dlq.service.ts` suggests a clean separation between persistence, orchestration, and failure management.

3. **Tools are the execution boundary**
   `packages/tools` is the plugin-style capability layer. It includes Gmail, filesystem, notification, email send/save, and AI summary tools, plus a registry and executor. The workflow engine delegates concrete side effects to this layer rather than implementing them directly.

4. **Agent/planner layer for AI-driven action planning**
   `packages/agent/planner.ts` indicates an AI/planning boundary that can turn higher-level instructions into structured workflow actions. In the diagram, this sits between human intent or event interpretation and the workflow/tool runtime.

5. **Server API exposes the orchestration system**
   `packages/server` provides controllers and routes for agent, workflow, execution, and DLQ resources. This is the operational interface for configuring workflows, inspecting executions, and reviewing failed messages.

6. **Shared runtime primitives**
   `packages/shared` contains cross-cutting types and infrastructure: execution context, common error classes, logger, and tool abstractions. This is the contract layer that keeps the engine, tools, and server aligned.

7. **State and persistence are local-first**
   The repo description and filenames imply a single-process, SQLite-backed setup with in-memory queueing. `packages/memory` likely holds transient state/caches, while `packages/workflow-engine/workflow.repository.ts` anchors durable workflow/execution persistence. The architecture is currently local and monolithic rather than distributed.

8. **Failure handling is first-class**
   Retryable vs permanent error types exist in `packages/shared/errors`, and the workflow engine has a DLQ service. That means the runtime distinguishes temporary failures from unrecoverable ones, retries where appropriate, and preserves failed work for inspection instead of dropping it.

9. **Monitoring and automation input comes from Gmail**
   The repo includes `gmail-auth.ts`, `gmail-poller.ts`, `gmail-test.ts`, and many saved email fixtures under `emails/`. This strongly suggests Gmail is a primary external system being polled or authenticated against, then converted into workflow events.

10. **User-facing surfaces**
   `apps/dashboard` is a Vite/React web dashboard for observing or managing the runtime. `apps/desktop` wraps a similar frontend in Tauri, with a Rust backend under `apps/desktop/src-tauri`, indicating a desktop client for local operation or administration.

11. **Operational scripts and test harnesses**
   Top-level scripts such as `seed-workflows.ts`, `test-agent.ts`, `test-workflow-service.ts`, `db-test.ts`, and `filesystem-test.ts` are not core runtime components but are important for understanding the repo: they exercise the workflow engine, tools, storage, and agent behavior in isolation.

12. **How to draw the main boundaries**
   A good diagram would show:
   external systems like Gmail feeding events into the workflow engine;
   the engine calling the tool registry/executor for side effects;
   the server exposing control and observability APIs;
   shared types/errors/logger supporting every layer;
   and the dashboard/desktop clients consuming the server API. The DLQ and execution history should be shown as durable failure and audit paths alongside the main execution flow.

Main entry points: [`packages/workflow-engine/workflow.service.ts`](https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/workflow.service.ts) (Workflow engine), [`packages/server/index.ts`](https://github.com/maithili31/ai_os/blob/main/packages/server/index.ts) (Server API), [`packages/workflow-engine/execution.service.ts`](https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/execution.service.ts) (Execution service), [`packages/tools/executor.ts`](https://github.com/maithili31/ai_os/blob/main/packages/tools/executor.ts) (Tool layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core runtime"]
  node_node_planner["Planner<br/>[planner.ts]"]
  node_node_runtime["Workflow engine<br/>orchestrator"]
  node_node_repo[("Workflow store<br/>persistence")]
  node_node_exec["Execution service<br/>run handler"]
  node_node_dlq["DLQ service<br/>failure path<br/>[dlq.service.ts]"]
  node_node_actions["Actions<br/>[actions.ts]"]
  node_node_tools["Tool layer<br/>plugin boundary<br/>[executor.ts]"]
  node_node_registry["Tool registry<br/>capability registry<br/>[registry.ts]"]
  node_node_memory[("Memory<br/>local state<br/>[index.ts]")]
end

subgraph group_group_api["API layer"]
  node_node_server["Server API<br/>http api<br/>[index.ts]"]
  node_node_workflow_ctrl["Workflow API<br/>controller"]
  node_node_exec_ctrl["Execution API<br/>controller"]
  node_node_dlq_ctrl["DLQ API<br/>controller<br/>[dlq.controller.ts]"]
  node_node_agent_ctrl["Agent API<br/>controller"]
end

subgraph group_group_clients["Clients"]
  node_node_dashboard["Dashboard<br/>web client<br/>[App.tsx]"]
  node_node_desktop["Desktop app<br/>tauri client<br/>[App.tsx]"]
end

subgraph group_group_shared["Shared runtime"]
  node_node_shared["Shared contracts<br/>runtime common<br/>[index.ts]"]
end

subgraph group_group_external["External inputs"]
  node_node_gmail(("Gmail input<br/>external source<br/>[gmail-poller.ts]"))
end

node_node_gmail -->|"events"| node_node_runtime
node_node_planner -->|"plans"| node_node_runtime
node_node_runtime -->|"loads/saves"| node_node_repo
node_node_runtime -->|"drives"| node_node_exec
node_node_exec -->|"executes"| node_node_actions
node_node_actions -->|"invokes"| node_node_tools
node_node_tools -->|"resolves"| node_node_registry
node_node_runtime -->|"fails to"| node_node_dlq
node_node_runtime -->|"uses"| node_node_shared
node_node_tools -->|"uses"| node_node_shared
node_node_exec -->|"uses"| node_node_shared
node_node_server -->|"routes"| node_node_workflow_ctrl
node_node_server -->|"routes"| node_node_exec_ctrl
node_node_server -->|"routes"| node_node_dlq_ctrl
node_node_server -->|"routes"| node_node_agent_ctrl
node_node_workflow_ctrl -->|"orchestrates"| node_node_runtime
node_node_exec_ctrl -->|"inspects"| node_node_exec
node_node_dlq_ctrl -->|"inspects"| node_node_dlq
node_node_agent_ctrl -->|"plans"| node_node_planner
node_node_dashboard -->|"consumes"| node_node_server
node_node_desktop -->|"consumes"| node_node_server
node_node_runtime -->|"caches"| node_node_memory

click node_node_gmail "https://github.com/maithili31/ai_os/blob/main/gmail-poller.ts"
click node_node_planner "https://github.com/maithili31/ai_os/blob/main/packages/agent/planner.ts"
click node_node_runtime "https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/workflow.service.ts"
click node_node_repo "https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/workflow.repository.ts"
click node_node_exec "https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/execution.service.ts"
click node_node_dlq "https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/dlq.service.ts"
click node_node_actions "https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/actions.ts"
click node_node_tools "https://github.com/maithili31/ai_os/blob/main/packages/tools/executor.ts"
click node_node_registry "https://github.com/maithili31/ai_os/blob/main/packages/tools/registry.ts"
click node_node_server "https://github.com/maithili31/ai_os/blob/main/packages/server/index.ts"
click node_node_workflow_ctrl "https://github.com/maithili31/ai_os/blob/main/packages/server/controllers/workflow.controller.ts"
click node_node_exec_ctrl "https://github.com/maithili31/ai_os/blob/main/packages/server/controllers/execution.controller.ts"
click node_node_dlq_ctrl "https://github.com/maithili31/ai_os/blob/main/packages/server/controllers/dlq.controller.ts"
click node_node_agent_ctrl "https://github.com/maithili31/ai_os/blob/main/packages/server/controllers/agent.controller.ts"
click node_node_dashboard "https://github.com/maithili31/ai_os/blob/main/apps/dashboard/src/App.tsx"
click node_node_desktop "https://github.com/maithili31/ai_os/blob/main/apps/desktop/src/App.tsx"
click node_node_shared "https://github.com/maithili31/ai_os/blob/main/packages/shared/index.ts"
click node_node_memory "https://github.com/maithili31/ai_os/blob/main/packages/memory/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_node_planner,node_node_runtime,node_node_repo,node_node_exec,node_node_dlq,node_node_actions,node_node_tools,node_node_registry,node_node_memory toneBlue
class node_node_server,node_node_workflow_ctrl,node_node_exec_ctrl,node_node_dlq_ctrl,node_node_agent_ctrl toneAmber
class node_node_dashboard,node_node_desktop toneMint
class node_node_shared toneRose
class node_node_gmail toneIndigo
```

## Components

### Core runtime

Event-driven workflow orchestration, tools, persistence, and agent planning.

- [Planner](https://github.com/maithili31/ai_os/blob/main/packages/agent/planner.ts): AI planner · Turns higher-level intent into structured workflow actions. · `packages/agent/planner.ts`
- [Workflow engine](https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/workflow.service.ts): orchestrator · Central brain for workflow lookup, execution, action dispatch, and failure handling. · `packages/workflow-engine/workflow.service.ts`
- [Workflow store](https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/workflow.repository.ts): persistence · Durable repository for workflow and execution state. · `packages/workflow-engine/workflow.repository.ts`
- [Execution service](https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/execution.service.ts): run handler · Coordinates workflow runs and records outcomes. · `packages/workflow-engine/execution.service.ts`
- [DLQ service](https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/dlq.service.ts): failure path · Captures failed work for review and retry management. · `packages/workflow-engine/dlq.service.ts`
- [Actions](https://github.com/maithili31/ai_os/blob/main/packages/workflow-engine/actions.ts): workflow actions · Workflow action definitions and execution primitives used by the engine. · `packages/workflow-engine/actions.ts`
- [Tool layer](https://github.com/maithili31/ai_os/blob/main/packages/tools/executor.ts): plugin boundary · Registry and executor for concrete side effects such as Gmail, filesystem, email, and notifications. · `packages/tools/executor.ts`
- [Tool registry](https://github.com/maithili31/ai_os/blob/main/packages/tools/registry.ts): capability registry · Maps named tools to implementations and enforces the plugin boundary. · `packages/tools/registry.ts`
- [Memory](https://github.com/maithili31/ai_os/blob/main/packages/memory/index.ts): local state · Transient in-memory state and caches for the local runtime. · `packages/memory/index.ts`

### API layer

Server controllers and routes exposing runtime operations.

- [Server API](https://github.com/maithili31/ai_os/blob/main/packages/server/index.ts): http api · Operational API surface for workflows, executions, DLQ, and agent resources. · `packages/server/index.ts`
- [Workflow API](https://github.com/maithili31/ai_os/blob/main/packages/server/controllers/workflow.controller.ts): controller · Workflow management endpoints. · `packages/server/controllers/workflow.controller.ts`
- [Execution API](https://github.com/maithili31/ai_os/blob/main/packages/server/controllers/execution.controller.ts): controller · Execution inspection endpoints. · `packages/server/controllers/execution.controller.ts`
- [DLQ API](https://github.com/maithili31/ai_os/blob/main/packages/server/controllers/dlq.controller.ts): controller · Failed-message review and recovery endpoints. · `packages/server/controllers/dlq.controller.ts`
- [Agent API](https://github.com/maithili31/ai_os/blob/main/packages/server/controllers/agent.controller.ts): controller · Agent and planning endpoints. · `packages/server/controllers/agent.controller.ts`

### Clients

Dashboard and desktop user-facing surfaces.

- [Dashboard](https://github.com/maithili31/ai_os/blob/main/apps/dashboard/src/App.tsx): web client · React/Vite web UI for observing and managing the runtime. · `apps/dashboard/src/App.tsx`
- [Desktop app](https://github.com/maithili31/ai_os/blob/main/apps/desktop/src/App.tsx): tauri client · Tauri-wrapped desktop client for local operation and administration. · `apps/desktop/src/App.tsx`

### Shared runtime

Cross-cutting contracts, errors, logger, and execution context.

- [Shared contracts](https://github.com/maithili31/ai_os/blob/main/packages/shared/index.ts): runtime common · Cross-cutting execution context, tool abstraction, errors, and logger. · `packages/shared/index.ts`

### External inputs

Gmail and local fixtures that feed the runtime.

- [Gmail input](https://github.com/maithili31/ai_os/blob/main/gmail-poller.ts): external source · Primary external event source, likely polled or authenticated against before becoming workflow input. · `gmail-poller.ts`

## Connections

- Gmail input → Workflow engine: events · External Gmail input becomes internal workflow events.
- Planner → Workflow engine: plans · AI planning output is translated into workflow actions.
- Workflow engine → Workflow store: loads/saves · Engine reads workflow definitions and persists run state.
- Workflow engine → Execution service: drives · Orchestrator delegates run coordination to execution handling.
- Execution service → Actions: executes · Execution service steps through workflow actions.
- Actions → Tool layer: invokes · Actions are materialized through the tool boundary.
- Tool layer → Tool registry: resolves · Executor looks up concrete tool implementations via registry.
- Workflow engine → DLQ service: fails to · Unrecoverable work is routed to dead-letter handling.
- Workflow engine → Shared contracts: uses · Engine depends on shared context, errors, and logging.
- Tool layer → Shared contracts: uses · Tool implementations share common contracts and error types.
- Execution service → Shared contracts: uses · Execution logic relies on shared runtime primitives.
- Server API → Workflow API: routes · Server mounts workflow management endpoints.
- Server API → Execution API: routes · Server mounts execution endpoints.
- Server API → DLQ API: routes · Server mounts DLQ endpoints.
- Server API → Agent API: routes · Server mounts agent/planning endpoints.
- Workflow API → Workflow engine: orchestrates · Workflow API delegates to the workflow engine.
- Execution API → Execution service: inspects · Execution API exposes execution service state.
- DLQ API → DLQ service: inspects · DLQ API exposes failed work management.
- Agent API → Planner: plans · Agent API surfaces planner behavior.
- Dashboard → Server API: consumes · Web dashboard talks to the server API.
- Desktop app → Server API: consumes · Desktop client talks to the server API.
- Workflow engine → Memory: caches · Local runtime uses transient in-memory state.
