How maithili31/ai_os works
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: workflow.service.ts Workflow engine · index.ts Server API · execution.service.ts Execution service · executor.ts Tool layer
Components 18
Core runtime
Event-driven workflow orchestration, tools, persistence, and agent planning.
- Planner · Turns higher-level intent into structured workflow actions.
packages/agent/planner.ts - Workflow engine · Central brain for workflow lookup, execution, action dispatch, and failure handling.
packages/workflow-engine/workflow.service.ts - Workflow store · Durable repository for workflow and execution state.
packages/workflow-engine/workflow.repository.ts - Execution service · Coordinates workflow runs and records outcomes.
packages/workflow-engine/execution.service.ts - DLQ service · Captures failed work for review and retry management.
packages/workflow-engine/dlq.service.ts - Actions · Workflow action definitions and execution primitives used by the engine.
packages/workflow-engine/actions.ts - Tool layer · Registry and executor for concrete side effects such as Gmail, filesystem, email, and notifications.
packages/tools/executor.ts - Tool registry · Maps named tools to implementations and enforces the plugin boundary.
packages/tools/registry.ts - Memory · 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 · Operational API surface for workflows, executions, DLQ, and agent resources.
packages/server/index.ts - Workflow API · Workflow management endpoints.
packages/server/controllers/workflow.controller.ts - Execution API · Execution inspection endpoints.
packages/server/controllers/execution.controller.ts - DLQ API · Failed-message review and recovery endpoints.
packages/server/controllers/dlq.controller.ts - Agent API · Agent and planning endpoints.
packages/server/controllers/agent.controller.ts
Clients
Dashboard and desktop user-facing surfaces.
- Dashboard · React/Vite web UI for observing and managing the runtime.
apps/dashboard/src/App.tsx - Desktop app · 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 · 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 · Primary external event source, likely polled or authenticated against before becoming workflow input.
gmail-poller.ts
Connections 22
- 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.