# alookai/alook architecture

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

- Interactive diagram: https://gitdiagram.com/alookai/alook
- Repository: https://github.com/alookai/alook

## Overview

#### Purpose and entry points
Alook is a self-hosted orchestration platform for running local AI coding agents as persistent, collaborative workers with tasks, email, calendars, files, traces, and community messaging. Primary user entry point is `npx @alook/app onboard`, implemented by `src/app/src/index.ts` and onboarding commands in `src/app/src/commands/onboard.ts`. Runtime-facing CLI entry is `src/cli/src/index.ts`; the local daemon is separately packaged in `src/daemon/src/index.ts`.

#### Control plane: Web application and API
The Next.js application provides workspace dashboards, agent chat/canvas, task and runtime views, plus a large HTTP API used by browser clients, CLI/daemons, and workers. Workspace UI begins under `src/web/src/app/(app)/w/[slug]/`, while API handlers live in `src/web/src/app/api/`. Task lifecycle endpoints—poll, start, progress, complete, fail—form the central remote execution contract: `src/web/src/app/api/daemon/tasks/` and `src/web/src/lib/services/task.ts`.

#### Persistent domain model
`src/shared` is the cross-package domain boundary: API contracts, validation schemas, runtime configuration, and database query layer are shared by web and workers. Core entities include workspaces, agents, machines, runtimes, conversations, task queues, email, calendar events, artifacts, and community entities. Schema/query definitions are in `src/shared/src/db/schema.ts`, `src/shared/src/db/queries/`, and deployed SQL migrations in `src/web/migrations/`.

#### Local execution daemon
The daemon discovers installed agent runtimes, registers/heartbeats with the control plane, receives work, and launches isolated local agent sessions against local workdirs. Daemon composition starts at `src/daemon/src/daemon/createDaemon.ts`; routing and policy sit in `src/daemon/src/manager/managerRuntime.ts` and `src/daemon/src/manager/agentRouter.ts`. Session state, progress, notification, and process control are managed in `src/daemon/src/runtime/`.

#### Agent-provider adapters and isolation
Provider-specific drivers normalize heterogeneous local tools into a common runtime interface. Supported implementations include Claude, Codex, OpenCode, Gemini, Copilot, Cursor, Kimi, Pi, and Antigravity, centered on `src/daemon/src/drivers/index.ts`, `src/daemon/src/drivers/claude.ts`, and `src/daemon/src/drivers/codex.ts`. This is the key boundary between Alook orchestration and external AI CLIs/SDKs; drivers handle launch environments, event normalization, capability probing, prompts, and provider isolation.

#### Eventing, realtime, and community
WebSocket Durable Objects provide realtime control/event delivery and rate limiting: `src/ws-do/src/ws-durable.ts` and `src/ws-do/src/rate-limit-do.ts`. The web API issues WS tokens and produces events; browser community hooks consume them via `src/web/src/hooks/community/use-community-ws.ts`. Community servers/channels/DMs, agent/bot wake dispatch, membership, presence, and inbox projections are modeled in `src/shared/src/community/` and `src/shared/src/db/queries/community/`.

#### External integrations and deployment runtimes
Cloudflare Workers host the web control plane and specialized workers. `src/email-worker/src/imap-poller-do.ts` polls IMAP and forwards inbound email; `src/wake-worker/src/index.ts` dispatches agent wake requests. The system uses Cloudflare Durable Objects (`src/ws-do` and email poller), persistent SQL storage via web migrations/shared queries, and object/media storage implied by artifact and community upload APIs. Desktop/mobile delivery is a Tauri Rust shell bridging to the web experience and push plugin: `src/desktop/src-tauri/src/main.rs`, `src/desktop/src-tauri/src/lib.rs`, and `src/desktop/src-tauri/plugins/tauri-plugin-push/src/lib.rs`.

Main entry points: [`src/daemon/src/daemon/createDaemon.ts`](https://github.com/alookai/alook/blob/main/src/daemon/src/daemon/createDaemon.ts) (Daemon composition), [`src/shared`](https://github.com/alookai/alook/tree/main/src/shared) (Shared domain), [`src/daemon/src/drivers/index.ts`](https://github.com/alookai/alook/blob/main/src/daemon/src/drivers/index.ts) (Provider drivers), [`src/ws-do/src/ws-durable.ts`](https://github.com/alookai/alook/blob/main/src/ws-do/src/ws-durable.ts) (WebSocket Durable Object)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_onboard["Onboarding CLI<br/>CLI entry<br/>[index.ts]"]
  node_onboard_commands["Onboarding commands<br/>CLI commands<br/>[onboard.ts]"]
  node_runtime_cli["Runtime CLI<br/>CLI entry<br/>[index.ts]"]
  node_desktop_shell["Desktop shell<br/>Tauri application<br/>[main.rs]"]
  node_push_plugin["Push plugin<br/>Tauri plugin<br/>[lib.rs]"]
end

subgraph group_control["Control plane"]
  node_workspace_ui["Workspace UI<br/>Next.js UI"]
  node_web_api{{"Web API<br/>HTTP control plane"}}
  node_task_api["Task lifecycle API<br/>Execution contract"]
  node_task_service["Task service<br/>Task domain service<br/>[task.ts]"]
  node_shared_domain["Shared domain<br/>Contracts &amp; validation"]
  node_db_schema["Database schema<br/>Domain schema<br/>[schema.ts]"]
  node_db_queries["Database queries<br/>Query layer"]
  node_sql_migrations[("SQL migrations<br/>Persistent storage")]
end

subgraph group_execution["Local execution"]
  node_daemon_entry["Daemon entry<br/>[index.ts]"]
  node_daemon_composition["Daemon composition<br/>Daemon bootstrap<br/>[createDaemon.ts]"]
  node_runtime_manager["Runtime manager<br/>Routing &amp; policy<br/>[managerRuntime.ts]"]
  node_agent_router["Agent router<br/>Execution routing<br/>[agentRouter.ts]"]
  node_session_runtime["Session runtime<br/>Local session control"]
  node_provider_drivers{{"Provider drivers<br/>Runtime adapter boundary<br/>[index.ts]"}}
  node_claude_driver["Claude driver<br/>Provider adapter<br/>[claude.ts]"]
  node_codex_driver["Codex driver<br/>Provider adapter<br/>[codex.ts]"]
end

subgraph group_realtime["Realtime &amp; workers"]
  node_ws_durable["WebSocket Durable Object<br/>Realtime delivery<br/>[ws-durable.ts]"]
  node_rate_limit["Rate-limit Durable Object<br/>Realtime policy<br/>[rate-limit-do.ts]"]
  node_community_ws["Community WS client<br/>Browser realtime hook"]
  node_community_domain["Community domain<br/>Community model"]
  node_email_worker["IMAP email worker<br/>Inbound email worker<br/>[imap-poller-do.ts]"]
  node_wake_worker["Wake worker<br/>Agent wake dispatcher<br/>[index.ts]"]
end

node_onboard -->|"runs"| node_onboard_commands
node_onboard_commands -->|"configures"| node_runtime_cli
node_workspace_ui -->|"HTTP requests"| node_web_api
node_desktop_shell -->|"hosts"| node_workspace_ui
node_desktop_shell -->|"uses"| node_push_plugin
node_web_api -->|"exposes"| node_task_api
node_task_api -->|"drives"| node_task_service
node_task_service -->|"uses"| node_shared_domain
node_shared_domain -->|"defines"| node_db_schema
node_shared_domain -->|"provides"| node_db_queries
node_db_queries -->|"persists through"| node_sql_migrations
node_runtime_cli -->|"connects to"| node_daemon_entry
node_daemon_entry -->|"boots"| node_daemon_composition
node_daemon_composition -->|"registers &amp; heartbeats"| node_web_api
node_daemon_composition -->|"creates"| node_runtime_manager
node_runtime_manager -->|"routes work"| node_agent_router
node_agent_router -->|"launches session"| node_session_runtime
node_session_runtime -->|"executes through"| node_provider_drivers
node_provider_drivers -->|"implements"| node_claude_driver
node_provider_drivers -->|"implements"| node_codex_driver
node_task_api -->|"task lifecycle"| node_daemon_composition
node_web_api -->|"issues tokens &amp; events"| node_ws_durable
node_ws_durable -->|"enforces limits"| node_rate_limit
node_community_ws -->|"consumes events"| node_ws_durable
node_workspace_ui -->|"uses"| node_community_ws
node_community_domain -->|"extends"| node_shared_domain
node_email_worker -->|"forwards email"| node_web_api
node_wake_worker -->|"dispatches wake"| node_daemon_composition

click node_onboard "https://github.com/alookai/alook/blob/main/src/app/src/index.ts"
click node_onboard_commands "https://github.com/alookai/alook/blob/main/src/app/src/commands/onboard.ts"
click node_runtime_cli "https://github.com/alookai/alook/blob/main/src/cli/src/index.ts"
click node_task_service "https://github.com/alookai/alook/blob/main/src/web/src/lib/services/task.ts"
click node_shared_domain "https://github.com/alookai/alook/tree/main/src/shared"
click node_db_schema "https://github.com/alookai/alook/blob/main/src/shared/src/db/schema.ts"
click node_daemon_entry "https://github.com/alookai/alook/blob/main/src/daemon/src/index.ts"
click node_daemon_composition "https://github.com/alookai/alook/blob/main/src/daemon/src/daemon/createDaemon.ts"
click node_runtime_manager "https://github.com/alookai/alook/blob/main/src/daemon/src/manager/managerRuntime.ts"
click node_agent_router "https://github.com/alookai/alook/blob/main/src/daemon/src/manager/agentRouter.ts"
click node_provider_drivers "https://github.com/alookai/alook/blob/main/src/daemon/src/drivers/index.ts"
click node_claude_driver "https://github.com/alookai/alook/blob/main/src/daemon/src/drivers/claude.ts"
click node_codex_driver "https://github.com/alookai/alook/blob/main/src/daemon/src/drivers/codex.ts"
click node_ws_durable "https://github.com/alookai/alook/blob/main/src/ws-do/src/ws-durable.ts"
click node_rate_limit "https://github.com/alookai/alook/blob/main/src/ws-do/src/rate-limit-do.ts"
click node_community_ws "https://github.com/alookai/alook/blob/main/src/web/src/hooks/community/use-community-ws.ts"
click node_email_worker "https://github.com/alookai/alook/blob/main/src/email-worker/src/imap-poller-do.ts"
click node_wake_worker "https://github.com/alookai/alook/blob/main/src/wake-worker/src/index.ts"
click node_desktop_shell "https://github.com/alookai/alook/blob/main/src/desktop/src-tauri/src/main.rs"
click node_push_plugin "https://github.com/alookai/alook/blob/main/src/desktop/src-tauri/plugins/tauri-plugin-push/src/lib.rs"

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_onboard,node_onboard_commands,node_runtime_cli,node_desktop_shell,node_push_plugin toneBlue
class node_workspace_ui,node_web_api,node_task_api,node_task_service,node_shared_domain,node_db_schema,node_db_queries,node_sql_migrations toneAmber
class node_daemon_entry,node_daemon_composition,node_runtime_manager,node_agent_router,node_session_runtime,node_provider_drivers,node_claude_driver,node_codex_driver toneMint
class node_ws_durable,node_rate_limit,node_community_ws,node_community_domain,node_email_worker,node_wake_worker toneRose
```

## Components

### Clients

- [Onboarding CLI](https://github.com/alookai/alook/blob/main/src/app/src/index.ts): CLI entry · Primary setup entry point. · `src/app/src/index.ts`
- [Onboarding commands](https://github.com/alookai/alook/blob/main/src/app/src/commands/onboard.ts): CLI commands · `src/app/src/commands/onboard.ts`
- [Runtime CLI](https://github.com/alookai/alook/blob/main/src/cli/src/index.ts): CLI entry · `src/cli/src/index.ts`
- [Desktop shell](https://github.com/alookai/alook/blob/main/src/desktop/src-tauri/src/main.rs): Tauri application · Bridges the web experience and native push delivery. · `src/desktop/src-tauri/src/main.rs`
- [Push plugin](https://github.com/alookai/alook/blob/main/src/desktop/src-tauri/plugins/tauri-plugin-push/src/lib.rs): Tauri plugin · `src/desktop/src-tauri/plugins/tauri-plugin-push/src/lib.rs`

### Control plane

- **Workspace UI**: Next.js UI · Dashboards, chat, canvas, tasks, and runtime views.
- **Web API**: HTTP control plane · Serves browsers, daemons, CLI clients, and workers.
- **Task lifecycle API**: Execution contract · Poll, start, progress, complete, and fail endpoints.
- [Task service](https://github.com/alookai/alook/blob/main/src/web/src/lib/services/task.ts): Task domain service · `src/web/src/lib/services/task.ts`
- [Shared domain](https://github.com/alookai/alook/tree/main/src/shared): Contracts & validation · Cross-package contracts, schemas, configuration, and queries. · `src/shared`
- [Database schema](https://github.com/alookai/alook/blob/main/src/shared/src/db/schema.ts): Domain schema · Defines workspaces, agents, machines, runtimes, and collaboration entities. · `src/shared/src/db/schema.ts`
- **Database queries**: Query layer
- **SQL migrations**: Persistent storage

### Local execution

- [Daemon entry](https://github.com/alookai/alook/blob/main/src/daemon/src/index.ts): Daemon entry · `src/daemon/src/index.ts`
- [Daemon composition](https://github.com/alookai/alook/blob/main/src/daemon/src/daemon/createDaemon.ts): Daemon bootstrap · Discovers runtimes, registers, heartbeats, and receives work. · `src/daemon/src/daemon/createDaemon.ts`
- [Runtime manager](https://github.com/alookai/alook/blob/main/src/daemon/src/manager/managerRuntime.ts): Routing & policy · `src/daemon/src/manager/managerRuntime.ts`
- [Agent router](https://github.com/alookai/alook/blob/main/src/daemon/src/manager/agentRouter.ts): Execution routing · `src/daemon/src/manager/agentRouter.ts`
- **Session runtime**: Local session control · Manages state, progress, notifications, and processes.
- [Provider drivers](https://github.com/alookai/alook/blob/main/src/daemon/src/drivers/index.ts): Runtime adapter boundary · Normalizes local AI CLI and SDK providers. · `src/daemon/src/drivers/index.ts`
- [Claude driver](https://github.com/alookai/alook/blob/main/src/daemon/src/drivers/claude.ts): Provider adapter · `src/daemon/src/drivers/claude.ts`
- [Codex driver](https://github.com/alookai/alook/blob/main/src/daemon/src/drivers/codex.ts): Provider adapter · `src/daemon/src/drivers/codex.ts`

### Realtime & workers

- [WebSocket Durable Object](https://github.com/alookai/alook/blob/main/src/ws-do/src/ws-durable.ts): Realtime delivery · Delivers control and community events. · `src/ws-do/src/ws-durable.ts`
- [Rate-limit Durable Object](https://github.com/alookai/alook/blob/main/src/ws-do/src/rate-limit-do.ts): Realtime policy · `src/ws-do/src/rate-limit-do.ts`
- [Community WS client](https://github.com/alookai/alook/blob/main/src/web/src/hooks/community/use-community-ws.ts): Browser realtime hook · `src/web/src/hooks/community/use-community-ws.ts`
- **Community domain**: Community model · Channels, DMs, presence, inboxes, and wake dispatch.
- [IMAP email worker](https://github.com/alookai/alook/blob/main/src/email-worker/src/imap-poller-do.ts): Inbound email worker · Polls IMAP and forwards inbound email. · `src/email-worker/src/imap-poller-do.ts`
- [Wake worker](https://github.com/alookai/alook/blob/main/src/wake-worker/src/index.ts): Agent wake dispatcher · `src/wake-worker/src/index.ts`

## Connections

- Onboarding CLI → Onboarding commands: runs
- Onboarding commands → Runtime CLI: configures
- Workspace UI → Web API: HTTP requests
- Desktop shell → Workspace UI: hosts
- Desktop shell → Push plugin: uses
- Web API → Task lifecycle API: exposes
- Task lifecycle API → Task service: drives
- Task service → Shared domain: uses
- Shared domain → Database schema: defines
- Shared domain → Database queries: provides
- Database queries → SQL migrations: persists through
- Runtime CLI → Daemon entry: connects to
- Daemon entry → Daemon composition: boots
- Daemon composition → Web API: registers & heartbeats
- Daemon composition → Runtime manager: creates
- Runtime manager → Agent router: routes work
- Agent router → Session runtime: launches session
- Session runtime → Provider drivers: executes through
- Provider drivers → Claude driver: implements
- Provider drivers → Codex driver: implements
- Task lifecycle API → Daemon composition: task lifecycle
- Web API → WebSocket Durable Object: issues tokens & events
- WebSocket Durable Object → Rate-limit Durable Object: enforces limits
- Community WS client → WebSocket Durable Object: consumes events
- Workspace UI → Community WS client: uses
- Community domain → Shared domain: extends
- IMAP email worker → Web API: forwards email
- Wake worker → Daemon composition: dispatches wake