# koshikraj/birdie architecture

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

- Interactive diagram: https://gitdiagram.com/koshikraj/birdie
- Repository: https://github.com/koshikraj/birdie

## Overview

Birdie is a local agent-to-agent messaging service: agents submit messages through MCP or HTTP, the bus tracks threads and delivery, and messages reach pull sessions or external webhook/ACP agents. The CLI supports installation, onboarding, setup, health checks and session management; the web UI provides agent, message and activity views. Backend excerpts were not supplied, so backend links below rely on explicit README statements; frontend links use the sampled source.

Main entry points: [`internal/bus/bus.go`](https://github.com/koshikraj/birdie/blob/main/internal/bus/bus.go) (Message bus), [`web/src/App.tsx`](https://github.com/koshikraj/birdie/blob/main/web/src/App.tsx) (UI application), [`web/src/api/client.ts`](https://github.com/koshikraj/birdie/blob/main/web/src/api/client.ts) (API client), [`web/src/api/hooks.ts`](https://github.com/koshikraj/birdie/blob/main/web/src/api/hooks.ts) (Query hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and setup"]
  node_cli_setup["Setup and onboarding<br/>[setup.go]"]
  node_cli_onboard["Guided onboarding<br/>[onboard.go]"]
  node_cli_service["Service management<br/>[service.go]"]
  node_cli_sessions["Session commands<br/>[thread.go]"]
end

subgraph group_interfaces["Agent interfaces"]
  node_mcp["MCP tools<br/>[tools.go]"]
  node_mcp_host["MCP host<br/>[host.go]"]
  node_http["HTTP API<br/>[server.go]"]
end

subgraph group_messaging["Messaging core"]
  node_bus["Message bus<br/>[bus.go]"]
  node_address["Address routing<br/>[address.go]"]
  node_events["Message events<br/>[events.go]"]
  node_sqlite[("SQLite state<br/>[sqlite.go]")]
end

subgraph group_delivery["Delivery adapters"]
  node_acp["ACP adapter<br/>[acp.go]"]
  node_webhook["Webhook adapter<br/>[webhook.go]"]
  node_hermes["Hermes integration<br/>[__init__.py]"]
end

subgraph group_webui["Web interface"]
  node_webui_api["Web UI API<br/>[api.go]"]
  node_webui_auth["Web UI auth<br/>[auth.go]"]
  node_webui_host["Web UI server<br/>[webui.go]"]
  node_app["UI application<br/>[App.tsx]"]
  node_pages["Agent and message pages<br/>[Agents.tsx]"]
  node_dashboard["Activity dashboard<br/>[Dashboard.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_api_events["Event stream client<br/>[events.ts]"]
  node_api_hooks["Query hooks<br/>[hooks.ts]"]
  node_scene["Message visualization<br/>[Scene.tsx]"]
  node_router["UI routing<br/>[router.ts]"]
end

node_operator(("Operator"))
node_agents(("Local agents"))
node_remote(("Remote agents"))

node_operator -->|"runs setup"| node_cli_onboard
node_cli_onboard -->|"configures agents"| node_cli_setup
node_cli_setup -->|"connects agents"| node_mcp
node_cli_service -->|"starts service"| node_bus
node_agents -->|"sends via MCP"| node_mcp
node_mcp -->|"submits messages"| node_bus
node_remote -->|"sends HTTP"| node_http
node_http -->|"submits messages"| node_bus
node_bus -.->|"resolves recipient"| node_address
node_bus -->|"stores state"| node_sqlite
node_bus -->|"delivers headlessly"| node_acp
node_bus -->|"posts messages"| node_webhook
node_webhook -->|"sends webhook"| node_remote
node_acp -->|"reaches agent"| node_remote
node_agents -.->|"connects through"| node_hermes
node_bus -.->|"publishes changes"| node_events
node_operator -->|"opens UI"| node_app
node_app -->|"selects view"| node_router
node_app -->|"signs in"| node_api_client
node_app -->|"starts stream"| node_api_events
node_app -->|"loads overview"| node_api_hooks
node_pages -->|"queries data"| node_api_hooks
node_dashboard -->|"queries data"| node_api_hooks
node_api_hooks -->|"calls endpoints"| node_api_client
node_api_events -->|"checks session"| node_api_client
node_api_events -->|"invalidates queries"| node_app
node_dashboard -->|"renders activity"| node_scene
node_api_client -->|"requests UI API"| node_webui_api
node_webui_host -.->|"serves UI API"| node_webui_api
node_webui_host -.->|"uses authentication"| node_webui_auth
node_cli_sessions -.->|"manages sessions"| node_bus

click node_cli_setup "https://github.com/koshikraj/birdie/blob/main/cmd/birdie/setup.go"
click node_cli_onboard "https://github.com/koshikraj/birdie/blob/main/cmd/birdie/onboard.go"
click node_cli_service "https://github.com/koshikraj/birdie/blob/main/cmd/birdie/service.go"
click node_cli_sessions "https://github.com/koshikraj/birdie/blob/main/cmd/birdie/thread.go"
click node_mcp "https://github.com/koshikraj/birdie/blob/main/internal/mcpserver/tools.go"
click node_mcp_host "https://github.com/koshikraj/birdie/blob/main/internal/mcpserver/host.go"
click node_http "https://github.com/koshikraj/birdie/blob/main/internal/httpapi/server.go"
click node_bus "https://github.com/koshikraj/birdie/blob/main/internal/bus/bus.go"
click node_address "https://github.com/koshikraj/birdie/blob/main/internal/bus/address.go"
click node_events "https://github.com/koshikraj/birdie/blob/main/internal/bus/events.go"
click node_sqlite "https://github.com/koshikraj/birdie/blob/main/internal/store/sqlite.go"
click node_acp "https://github.com/koshikraj/birdie/blob/main/internal/adapter/acp.go"
click node_webhook "https://github.com/koshikraj/birdie/blob/main/internal/adapter/webhook.go"
click node_hermes "https://github.com/koshikraj/birdie/blob/main/integrations/hermes/__init__.py"
click node_webui_api "https://github.com/koshikraj/birdie/blob/main/internal/webui/api.go"
click node_webui_auth "https://github.com/koshikraj/birdie/blob/main/internal/webui/auth.go"
click node_webui_host "https://github.com/koshikraj/birdie/blob/main/internal/webui/webui.go"
click node_app "https://github.com/koshikraj/birdie/blob/main/web/src/App.tsx"
click node_pages "https://github.com/koshikraj/birdie/blob/main/web/src/pages/Agents.tsx"
click node_dashboard "https://github.com/koshikraj/birdie/blob/main/web/src/pages/Dashboard.tsx"
click node_api_client "https://github.com/koshikraj/birdie/blob/main/web/src/api/client.ts"
click node_api_events "https://github.com/koshikraj/birdie/blob/main/web/src/api/events.ts"
click node_api_hooks "https://github.com/koshikraj/birdie/blob/main/web/src/api/hooks.ts"
click node_scene "https://github.com/koshikraj/birdie/blob/main/web/src/scene/Scene.tsx"
click node_router "https://github.com/koshikraj/birdie/blob/main/web/src/lib/router.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_cli_setup,node_cli_onboard,node_cli_service,node_cli_sessions toneBlue
class node_mcp,node_mcp_host,node_http toneAmber
class node_bus,node_address,node_events,node_sqlite toneMint
class node_acp,node_webhook,node_hermes toneRose
class node_webui_api,node_webui_auth,node_webui_host,node_app,node_pages,node_dashboard,node_api_client,node_api_events,node_api_hooks,node_scene,node_router,node_operator,node_agents,node_remote toneIndigo
```

## Components

### CLI and setup

- [Setup and onboarding](https://github.com/koshikraj/birdie/blob/main/cmd/birdie/setup.go): `cmd/birdie/setup.go`
- [Guided onboarding](https://github.com/koshikraj/birdie/blob/main/cmd/birdie/onboard.go): `cmd/birdie/onboard.go`
- [Service management](https://github.com/koshikraj/birdie/blob/main/cmd/birdie/service.go): `cmd/birdie/service.go`
- [Session commands](https://github.com/koshikraj/birdie/blob/main/cmd/birdie/thread.go): `cmd/birdie/thread.go`

### Agent interfaces

- [MCP tools](https://github.com/koshikraj/birdie/blob/main/internal/mcpserver/tools.go): `internal/mcpserver/tools.go`
- [MCP host](https://github.com/koshikraj/birdie/blob/main/internal/mcpserver/host.go): `internal/mcpserver/host.go`
- [HTTP API](https://github.com/koshikraj/birdie/blob/main/internal/httpapi/server.go): `internal/httpapi/server.go`

### Messaging core

- [Message bus](https://github.com/koshikraj/birdie/blob/main/internal/bus/bus.go): `internal/bus/bus.go`
- [Address routing](https://github.com/koshikraj/birdie/blob/main/internal/bus/address.go): `internal/bus/address.go`
- [Message events](https://github.com/koshikraj/birdie/blob/main/internal/bus/events.go): `internal/bus/events.go`
- [SQLite state](https://github.com/koshikraj/birdie/blob/main/internal/store/sqlite.go): `internal/store/sqlite.go`

### Delivery adapters

- [ACP adapter](https://github.com/koshikraj/birdie/blob/main/internal/adapter/acp.go): `internal/adapter/acp.go`
- [Webhook adapter](https://github.com/koshikraj/birdie/blob/main/internal/adapter/webhook.go): `internal/adapter/webhook.go`
- [Hermes integration](https://github.com/koshikraj/birdie/blob/main/integrations/hermes/__init__.py): `integrations/hermes/__init__.py`

### Web interface

- [Web UI API](https://github.com/koshikraj/birdie/blob/main/internal/webui/api.go): `internal/webui/api.go`
- [Web UI auth](https://github.com/koshikraj/birdie/blob/main/internal/webui/auth.go): `internal/webui/auth.go`
- [Web UI server](https://github.com/koshikraj/birdie/blob/main/internal/webui/webui.go): `internal/webui/webui.go`
- [UI application](https://github.com/koshikraj/birdie/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Agent and message pages](https://github.com/koshikraj/birdie/blob/main/web/src/pages/Agents.tsx): `web/src/pages/Agents.tsx`
- [Activity dashboard](https://github.com/koshikraj/birdie/blob/main/web/src/pages/Dashboard.tsx): `web/src/pages/Dashboard.tsx`
- [API client](https://github.com/koshikraj/birdie/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Event stream client](https://github.com/koshikraj/birdie/blob/main/web/src/api/events.ts): `web/src/api/events.ts`
- [Query hooks](https://github.com/koshikraj/birdie/blob/main/web/src/api/hooks.ts): `web/src/api/hooks.ts`
- [Message visualization](https://github.com/koshikraj/birdie/blob/main/web/src/scene/Scene.tsx): `web/src/scene/Scene.tsx`
- [UI routing](https://github.com/koshikraj/birdie/blob/main/web/src/lib/router.ts): `web/src/lib/router.ts`

### Other components

- **Operator**
- **Local agents**
- **Remote agents**

## Connections

- Operator → Guided onboarding: runs setup
- Guided onboarding → Setup and onboarding: configures agents
- Setup and onboarding → MCP tools: connects agents
- Service management → Message bus: starts service
- Local agents → MCP tools: sends via MCP
- MCP tools → Message bus: submits messages
- Remote agents → HTTP API: sends HTTP
- HTTP API → Message bus: submits messages
- Message bus → Address routing: resolves recipient
- Message bus → SQLite state: stores state
- Message bus → ACP adapter: delivers headlessly
- Message bus → Webhook adapter: posts messages
- Webhook adapter → Remote agents: sends webhook
- ACP adapter → Remote agents: reaches agent
- Local agents → Hermes integration: connects through
- Message bus → Message events: publishes changes
- Operator → UI application: opens UI
- UI application → UI routing: selects view (evidence: `web/src/App.tsx`)
- UI application → API client: signs in (evidence: `web/src/App.tsx`)
- UI application → Event stream client: starts stream (evidence: `web/src/App.tsx`)
- UI application → Query hooks: loads overview (evidence: `web/src/App.tsx`)
- Agent and message pages → Query hooks: queries data (evidence: `web/src/pages/Agents.tsx`)
- Activity dashboard → Query hooks: queries data (evidence: `web/src/pages/Dashboard.tsx`)
- Query hooks → API client: calls endpoints (evidence: `web/src/api/hooks.ts`)
- Event stream client → API client: checks session (evidence: `web/src/api/events.ts`)
- Event stream client → UI application: invalidates queries (evidence: `web/src/App.tsx`)
- Activity dashboard → Message visualization: renders activity (evidence: `web/src/pages/Dashboard.tsx`)
- API client → Web UI API: requests UI API
- Web UI server → Web UI API: serves UI API
- Web UI server → Web UI auth: uses authentication
- Session commands → Message bus: manages sessions