# aleksbuss/orchestra architecture

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

- Interactive diagram: https://gitdiagram.com/aleksbuss/orchestra
- Repository: https://github.com/aleksbuss/orchestra

## Overview

Orchestra is a local-first AI workspace. Its primary workflow is a user chat request routed through the chat API to an agent, which can run a Mixture-of-Agents ensemble and return a response while chat state and usage are persisted. Major supporting capabilities include project and knowledge management, scheduled jobs, Telegram integration, live UI events, and cost visibility. Edges are limited to relationships shown by excerpts, the SOURCE INDEX, or README; unsampled feature wiring is not asserted.

Main entry points: [`src/lib/agent/agent.ts`](https://github.com/aleksbuss/orchestra/blob/main/src/lib/agent/agent.ts) (Agent runtime), [`src/app/api/chat/route.ts`](https://github.com/aleksbuss/orchestra/blob/main/src/app/api/chat/route.ts) (Chat API), [`src/lib/storage/chat-store.ts`](https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/chat-store.ts) (Chat storage), [`src/components/chat/chat-panel.tsx`](https://github.com/aleksbuss/orchestra/blob/main/src/components/chat/chat-panel.tsx) (Chat interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_chat_ui["Chat interface<br/>[chat-panel.tsx]"]
  node_chat_api["Chat API<br/>[route.ts]"]
  node_event_stream["UI event stream<br/>[route.ts]"]
end

subgraph group_orchestration["Agent orchestration"]
  node_agent["Agent runtime<br/>[agent.ts]"]
  node_moa["MoA ensemble<br/>[moa.ts]"]
  node_providers["Model providers<br/>[llm-provider.ts]"]
  node_tools["Agent tools<br/>[agent-tools.ts]"]
end

subgraph group_workspace["Workspace services"]
  node_memory["Memory service<br/>[memory.ts]"]
  node_knowledge["Knowledge service<br/>[knowledge.ts]"]
  node_projects[("Project storage<br/>[project-store.ts]")]
  node_chat_store[("Chat storage<br/>[chat-store.ts]")]
  node_settings_api["Settings API<br/>[route.ts]"]
  node_settings_store[("Settings storage<br/>[settings-store.ts]")]
  node_cron["Scheduled jobs<br/>[service.ts]"]
  node_telegram["Telegram integration<br/>[route.ts]"]
  node_telegram_settings[("Telegram configuration")]
end

subgraph group_platform["Runtime platform"]
  node_event_bus["Event bus<br/>[event-bus.ts]"]
  node_cost["Usage and cost<br/>[accumulator.ts]"]
  node_logging["Observability<br/>[logger.ts]"]
  node_data_root["Data directory<br/>[data-dir.ts]"]
  node_file_safety["Safe file access<br/>[fs-utils.ts]"]
end

node_user(("Workspace user"))
node_external_models(("Model services"))
node_telegram_service(("Telegram service"))

node_user -->|"asks"| node_chat_ui
node_chat_ui -.->|"submits chat"| node_chat_api
node_chat_api -->|"runs turn"| node_agent
node_chat_api -->|"creates and reads"| node_chat_store
node_chat_api -->|"starts scheduler"| node_cron
node_chat_api -->|"adds log context"| node_logging
node_agent -->|"runs ensemble"| node_moa
node_agent -->|"loads and updates"| node_chat_store
node_agent -->|"folds usage"| node_cost
node_agent -.->|"calls models"| node_providers
node_agent -->|"assembles tools"| node_tools
node_agent -.->|"recalls context"| node_memory
node_moa -.->|"consults experts"| node_external_models
node_providers -.->|"requests inference"| node_external_models
node_chat_store -->|"publishes changes"| node_event_bus
node_event_stream -->|"subscribes events"| node_event_bus
node_chat_ui -.->|"receives updates"| node_event_stream
node_knowledge -->|"uses memory"| node_memory
node_settings_api -->|"reads and saves"| node_settings_store
node_telegram -->|"loads configuration"| node_telegram_settings
node_telegram -.->|"handles messages"| node_telegram_service
node_cron -->|"runs scheduled turns"| node_agent
node_cron -->|"loads project data"| node_projects
node_chat_store -->|"locks and writes"| node_file_safety
node_projects -->|"validates and writes"| node_file_safety
node_settings_store -->|"locks settings file"| node_file_safety
node_chat_store -->|"locates data"| node_data_root
node_projects -->|"locates data"| node_data_root
node_settings_store -->|"locates settings"| node_data_root

click node_chat_ui "https://github.com/aleksbuss/orchestra/blob/main/src/components/chat/chat-panel.tsx"
click node_chat_api "https://github.com/aleksbuss/orchestra/blob/main/src/app/api/chat/route.ts"
click node_event_stream "https://github.com/aleksbuss/orchestra/blob/main/src/app/api/events/route.ts"
click node_event_bus "https://github.com/aleksbuss/orchestra/blob/main/src/lib/realtime/event-bus.ts"
click node_agent "https://github.com/aleksbuss/orchestra/blob/main/src/lib/agent/agent.ts"
click node_moa "https://github.com/aleksbuss/orchestra/blob/main/src/lib/agent/moa.ts"
click node_providers "https://github.com/aleksbuss/orchestra/blob/main/src/lib/providers/llm-provider.ts"
click node_tools "https://github.com/aleksbuss/orchestra/blob/main/src/lib/agent/agent-tools.ts"
click node_memory "https://github.com/aleksbuss/orchestra/blob/main/src/lib/memory/memory.ts"
click node_knowledge "https://github.com/aleksbuss/orchestra/blob/main/src/lib/memory/knowledge.ts"
click node_projects "https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/project-store.ts"
click node_chat_store "https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/chat-store.ts"
click node_settings_api "https://github.com/aleksbuss/orchestra/blob/main/src/app/api/settings/route.ts"
click node_settings_store "https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/settings-store.ts"
click node_cron "https://github.com/aleksbuss/orchestra/blob/main/src/lib/cron/service.ts"
click node_telegram "https://github.com/aleksbuss/orchestra/blob/main/src/app/api/integrations/telegram/route.ts"
click node_telegram_settings "https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/telegram-integration-store.ts"
click node_cost "https://github.com/aleksbuss/orchestra/blob/main/src/lib/cost/accumulator.ts"
click node_logging "https://github.com/aleksbuss/orchestra/blob/main/src/lib/observability/logger.ts"
click node_data_root "https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/data-dir.ts"
click node_file_safety "https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/fs-utils.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_chat_ui,node_chat_api,node_event_stream,node_user toneBlue
class node_agent,node_moa,node_providers,node_tools toneAmber
class node_memory,node_knowledge,node_projects,node_chat_store,node_settings_api,node_settings_store,node_cron,node_telegram,node_telegram_settings toneMint
class node_event_bus,node_cost,node_logging,node_data_root,node_file_safety toneRose
class node_external_models,node_telegram_service toneIndigo
```

## Components

### User experience

- [Chat interface](https://github.com/aleksbuss/orchestra/blob/main/src/components/chat/chat-panel.tsx): `src/components/chat/chat-panel.tsx`
- [Chat API](https://github.com/aleksbuss/orchestra/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [UI event stream](https://github.com/aleksbuss/orchestra/blob/main/src/app/api/events/route.ts): `src/app/api/events/route.ts`

### Agent orchestration

- [Agent runtime](https://github.com/aleksbuss/orchestra/blob/main/src/lib/agent/agent.ts): `src/lib/agent/agent.ts`
- [MoA ensemble](https://github.com/aleksbuss/orchestra/blob/main/src/lib/agent/moa.ts): `src/lib/agent/moa.ts`
- [Model providers](https://github.com/aleksbuss/orchestra/blob/main/src/lib/providers/llm-provider.ts): `src/lib/providers/llm-provider.ts`
- [Agent tools](https://github.com/aleksbuss/orchestra/blob/main/src/lib/agent/agent-tools.ts): `src/lib/agent/agent-tools.ts`

### Workspace services

- [Memory service](https://github.com/aleksbuss/orchestra/blob/main/src/lib/memory/memory.ts): `src/lib/memory/memory.ts`
- [Knowledge service](https://github.com/aleksbuss/orchestra/blob/main/src/lib/memory/knowledge.ts): `src/lib/memory/knowledge.ts`
- [Project storage](https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/project-store.ts): `src/lib/storage/project-store.ts`
- [Chat storage](https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/chat-store.ts): `src/lib/storage/chat-store.ts`
- [Settings API](https://github.com/aleksbuss/orchestra/blob/main/src/app/api/settings/route.ts): `src/app/api/settings/route.ts`
- [Settings storage](https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/settings-store.ts): `src/lib/storage/settings-store.ts`
- [Scheduled jobs](https://github.com/aleksbuss/orchestra/blob/main/src/lib/cron/service.ts): `src/lib/cron/service.ts`
- [Telegram integration](https://github.com/aleksbuss/orchestra/blob/main/src/app/api/integrations/telegram/route.ts): `src/app/api/integrations/telegram/route.ts`
- [Telegram configuration](https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/telegram-integration-store.ts): `src/lib/storage/telegram-integration-store.ts`

### Runtime platform

- [Event bus](https://github.com/aleksbuss/orchestra/blob/main/src/lib/realtime/event-bus.ts): `src/lib/realtime/event-bus.ts`
- [Usage and cost](https://github.com/aleksbuss/orchestra/blob/main/src/lib/cost/accumulator.ts): `src/lib/cost/accumulator.ts`
- [Observability](https://github.com/aleksbuss/orchestra/blob/main/src/lib/observability/logger.ts): `src/lib/observability/logger.ts`
- [Data directory](https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/data-dir.ts): `src/lib/storage/data-dir.ts`
- [Safe file access](https://github.com/aleksbuss/orchestra/blob/main/src/lib/storage/fs-utils.ts): `src/lib/storage/fs-utils.ts`

### Other components

- **Workspace user**
- **Model services**
- **Telegram service**

## Connections

- Workspace user → Chat interface: asks (evidence: `README.md`)
- Chat interface → Chat API: submits chat
- Chat API → Agent runtime: runs turn (evidence: `src/app/api/chat/route.ts`)
- Chat API → Chat storage: creates and reads (evidence: `src/app/api/chat/route.ts`)
- Chat API → Scheduled jobs: starts scheduler (evidence: `src/app/api/chat/route.ts`)
- Chat API → Observability: adds log context (evidence: `src/app/api/chat/route.ts`)
- Agent runtime → MoA ensemble: runs ensemble (evidence: `src/lib/agent/agent.ts`)
- Agent runtime → Chat storage: loads and updates (evidence: `src/lib/agent/agent.ts`)
- Agent runtime → Usage and cost: folds usage (evidence: `src/lib/agent/agent.ts`)
- Agent runtime → Model providers: calls models (evidence: `src/lib/agent/agent.ts`)
- Agent runtime → Agent tools: assembles tools (evidence: `src/lib/agent/agent.ts`)
- Agent runtime → Memory service: recalls context (evidence: `src/lib/agent/agent.ts`)
- MoA ensemble → Model services: consults experts (evidence: `README.md`)
- Model providers → Model services: requests inference
- Chat storage → Event bus: publishes changes (evidence: `src/lib/storage/chat-store.ts`)
- UI event stream → Event bus: subscribes events (evidence: `src/app/api/events/route.ts`)
- Chat interface → UI event stream: receives updates
- Knowledge service → Memory service: uses memory (evidence: `src/lib/memory/knowledge.ts`)
- Settings API → Settings storage: reads and saves (evidence: `src/app/api/settings/route.ts`)
- Telegram integration → Telegram configuration: loads configuration (evidence: `src/app/api/integrations/telegram/route.ts`)
- Telegram integration → Telegram service: handles messages
- Scheduled jobs → Agent runtime: runs scheduled turns (evidence: `src/lib/cron/service.ts`)
- Scheduled jobs → Project storage: loads project data (evidence: `src/lib/cron/service.ts`)
- Chat storage → Safe file access: locks and writes (evidence: `src/lib/storage/chat-store.ts`)
- Project storage → Safe file access: validates and writes (evidence: `src/lib/storage/project-store.ts`)
- Settings storage → Safe file access: locks settings file (evidence: `src/lib/storage/settings-store.ts`)
- Chat storage → Data directory: locates data (evidence: `src/lib/storage/chat-store.ts`)
- Project storage → Data directory: locates data (evidence: `src/lib/storage/project-store.ts`)
- Settings storage → Data directory: locates settings (evidence: `src/lib/storage/settings-store.ts`)
