# ericbss05/openbot-lite architecture

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

- Interactive diagram: https://gitdiagram.com/ericbss05/openbot-lite
- Repository: https://github.com/ericbss05/openbot-lite

## Overview

OpenBot Lite is a browser-based console and Hono API for managing AI agent profiles, channels, routines, plugins and governance. Users authenticate, create or manage agents, and can submit channel messages; the API records the message and queues a turn. Administrative flows configure policy and inspect audit events, while plugin calls are checked and audited before execution. The README describes a simplified product, but the supplied tree contains additional runtime subsystems. Several of their internal links are omitted because their callers were not shown.

Main entry points: [`server-lite/src/app.ts`](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/app.ts) (HTTP routes), [`server-lite/src/db/index.ts`](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/db/index.ts) (PostgreSQL), [`server-lite/src/gateway/store.ts`](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/gateway/store.ts) (Policy gateway), [`server-lite/src/agent/runtime/loop.ts`](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/agent/runtime/loop.ts) (Agent runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web console"]
  node_web_auth["Sign-in page<br/>[page.tsx]"]
  node_web_agents["Agent pages<br/>[page.tsx]"]
  node_web_create["Agent creation"]
  node_web_agent_hook["Agent data hook<br/>[useAgents.ts]"]
  node_web_api["Agent API client<br/>[agents.ts]"]
end

subgraph group_api["API and identity"]
  node_app["HTTP routes<br/>[app.ts]"]
  node_auth["Session auth<br/>[auth.ts]"]
end

subgraph group_agents["Agent operations"]
  node_profiles["Agent profiles<br/>[store.ts]"]
  node_agent_runtime["Agent runtime<br/>[loop.ts]"]
  node_agent_tools["Tool registry<br/>[tools.ts]"]
  node_channels["Channels<br/>[store.ts]"]
  node_work_queue["Work queue<br/>[queue.ts]"]
  node_routines["Routines<br/>[store.ts]"]
end

subgraph group_governance["Governance and extensions"]
  node_gateway["Policy gateway<br/>[store.ts]"]
  node_audit["Audit events<br/>[audit.ts]"]
  node_plugins["Plugin registry<br/>[store.ts]"]
  node_mcp["MCP tools<br/>[mcp.ts]"]
end

subgraph group_persistence["Persistence"]
  node_database[("PostgreSQL<br/>[index.ts]")]
end

node_user(("User"))

node_user -->|"signs in"| node_web_auth
node_user -->|"manages agents"| node_web_agents
node_web_agents -->|"loads agents"| node_web_agent_hook
node_web_create -.->|"creates agent"| node_web_api
node_web_api -.->|"requests API"| node_app
node_web_auth -.->|"authenticates"| node_auth
node_app -->|"handles auth routes"| node_auth
node_app -->|"manages profiles"| node_profiles
node_app -->|"manages channels"| node_channels
node_app -->|"queues turns"| node_work_queue
node_app -->|"checks policy"| node_gateway
node_app -->|"records events"| node_audit
node_app -->|"manages routines"| node_routines
node_app -->|"manages plugins"| node_plugins
node_app -->|"lists or calls tools"| node_mcp
node_profiles -->|"reads and writes"| node_database
node_channels -->|"reads and writes"| node_database
node_work_queue -->|"stores work"| node_database
node_routines -->|"reads and writes"| node_database
node_plugins -->|"reads and writes"| node_database
node_audit -->|"persists events"| node_database
node_gateway -->|"persists policy"| node_database
node_agent_runtime -.->|"uses tools"| node_agent_tools
node_agent_runtime -.->|"authorizes actions"| node_gateway

click node_web_auth "https://github.com/ericbss05/openbot-lite/blob/main/web/app/page.tsx"
click node_web_agents "https://github.com/ericbss05/openbot-lite/blob/main/web/app/(protected)/agents/page.tsx"
click node_web_create "https://github.com/ericbss05/openbot-lite/blob/main/web/app/(protected)/agents/new/_components/createAgentForm.tsx"
click node_web_agent_hook "https://github.com/ericbss05/openbot-lite/blob/main/web/hooks/useAgents.ts"
click node_web_api "https://github.com/ericbss05/openbot-lite/blob/main/web/lib/api/agents.ts"
click node_app "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/app.ts"
click node_auth "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/auth/auth.ts"
click node_profiles "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/agent-profiles/store.ts"
click node_agent_runtime "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/agent/runtime/loop.ts"
click node_agent_tools "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/agent/tools/tools.ts"
click node_channels "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/channels/store.ts"
click node_work_queue "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/work/queue.ts"
click node_routines "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/routines/store.ts"
click node_gateway "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/gateway/store.ts"
click node_audit "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/gateway/audit.ts"
click node_plugins "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/plugins/store.ts"
click node_mcp "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/plugins/mcp.ts"
click node_database "https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/db/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_web_auth,node_web_agents,node_web_create,node_web_agent_hook,node_web_api,node_user toneBlue
class node_app,node_auth toneAmber
class node_profiles,node_agent_runtime,node_agent_tools,node_channels,node_work_queue,node_routines toneMint
class node_gateway,node_audit,node_plugins,node_mcp toneRose
class node_database toneIndigo
```

## Components

### Web console

- [Sign-in page](https://github.com/ericbss05/openbot-lite/blob/main/web/app/page.tsx): `web/app/page.tsx`
- [Agent pages](https://github.com/ericbss05/openbot-lite/blob/main/web/app/(protected)/agents/page.tsx): `web/app/(protected)/agents/page.tsx`
- [Agent creation](https://github.com/ericbss05/openbot-lite/blob/main/web/app/(protected)/agents/new/_components/createAgentForm.tsx): `web/app/(protected)/agents/new/_components/createAgentForm.tsx`
- [Agent data hook](https://github.com/ericbss05/openbot-lite/blob/main/web/hooks/useAgents.ts): `web/hooks/useAgents.ts`
- [Agent API client](https://github.com/ericbss05/openbot-lite/blob/main/web/lib/api/agents.ts): `web/lib/api/agents.ts`

### API and identity

- [HTTP routes](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/app.ts): `server-lite/src/app.ts`
- [Session auth](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/auth/auth.ts): `server-lite/src/auth/auth.ts`

### Agent operations

- [Agent profiles](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/agent-profiles/store.ts): `server-lite/src/agent-profiles/store.ts`
- [Agent runtime](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/agent/runtime/loop.ts): `server-lite/src/agent/runtime/loop.ts`
- [Tool registry](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/agent/tools/tools.ts): `server-lite/src/agent/tools/tools.ts`
- [Channels](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/channels/store.ts): `server-lite/src/channels/store.ts`
- [Work queue](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/work/queue.ts): `server-lite/src/work/queue.ts`
- [Routines](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/routines/store.ts): `server-lite/src/routines/store.ts`

### Governance and extensions

- [Policy gateway](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/gateway/store.ts): `server-lite/src/gateway/store.ts`
- [Audit events](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/gateway/audit.ts): `server-lite/src/gateway/audit.ts`
- [Plugin registry](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/plugins/store.ts): `server-lite/src/plugins/store.ts`
- [MCP tools](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/plugins/mcp.ts): `server-lite/src/plugins/mcp.ts`

### Persistence

- [PostgreSQL](https://github.com/ericbss05/openbot-lite/blob/main/server-lite/src/db/index.ts): `server-lite/src/db/index.ts`

### Other components

- **User**

## Connections

- User → Sign-in page: signs in (evidence: `web/app/page.tsx`)
- User → Agent pages: manages agents (evidence: `web/app/(protected)/agents/page.tsx`)
- Agent pages → Agent data hook: loads agents (evidence: `web/app/(protected)/agents/page.tsx`)
- Agent creation → Agent API client: creates agent
- Agent API client → HTTP routes: requests API
- Sign-in page → Session auth: authenticates
- HTTP routes → Session auth: handles auth routes (evidence: `server-lite/src/app.ts`)
- HTTP routes → Agent profiles: manages profiles (evidence: `server-lite/src/app.ts`)
- HTTP routes → Channels: manages channels (evidence: `server-lite/src/app.ts`)
- HTTP routes → Work queue: queues turns (evidence: `server-lite/src/app.ts`)
- HTTP routes → Policy gateway: checks policy (evidence: `server-lite/src/app.ts`)
- HTTP routes → Audit events: records events (evidence: `server-lite/src/app.ts`)
- HTTP routes → Routines: manages routines (evidence: `server-lite/src/app.ts`)
- HTTP routes → Plugin registry: manages plugins (evidence: `server-lite/src/app.ts`)
- HTTP routes → MCP tools: lists or calls tools (evidence: `server-lite/src/app.ts`)
- Agent profiles → PostgreSQL: reads and writes (evidence: `server-lite/src/agent-profiles/store.ts`)
- Channels → PostgreSQL: reads and writes (evidence: `server-lite/src/channels/store.ts`)
- Work queue → PostgreSQL: stores work (evidence: `server-lite/src/work/queue.ts`)
- Routines → PostgreSQL: reads and writes (evidence: `server-lite/src/routines/store.ts`)
- Plugin registry → PostgreSQL: reads and writes (evidence: `server-lite/src/plugins/store.ts`)
- Audit events → PostgreSQL: persists events (evidence: `server-lite/src/gateway/audit.ts`)
- Policy gateway → PostgreSQL: persists policy (evidence: `server-lite/src/gateway/store.ts`)
- Agent runtime → Tool registry: uses tools
- Agent runtime → Policy gateway: authorizes actions
