# yetone/cumora architecture

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

- Interactive diagram: https://gitdiagram.com/yetone/cumora
- Repository: https://github.com/yetone/cumora

## Overview

Cumora is a cross-platform team chat and work-coordination product where humans and AI agents share conversations, boards, calendars, documents, and email. Users enter through the authenticated React app, which loads team state and sends commands to the server; the server persists changes and delivers realtime updates. Agent work is coordinated and executed either in managed pods or through paired BYOA computers, with runtime actions using the shared CLI protocol. The README documents the main capabilities and infrastructure; sampled source supports selected API, agent-runtime, and storage links, so uncertain internal wiring is omitted.

Main entry points: [`server/src/api/router.ts`](https://github.com/yetone/cumora/blob/main/server/src/api/router.ts) (HTTP API), [`src/api/client.ts`](https://github.com/yetone/cumora/blob/main/src/api/client.ts) (API client), [`server/src/agents/runtime/server.ts`](https://github.com/yetone/cumora/blob/main/server/src/agents/runtime/server.ts) (Runtime API), [`src/App.tsx`](https://github.com/yetone/cumora/blob/main/src/App.tsx) (App bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client apps"]
  node_app["App bootstrap<br/>[App.tsx]"]
  node_desktop["Desktop UI<br/>[DesktopApp.tsx]"]
  node_mobile["Mobile UI<br/>[MobileApp.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_backend["Application backend"]
  node_api["HTTP API<br/>[router.ts]"]
  node_ws["Realtime gateway<br/>[ws.ts]"]
end

subgraph group_work["Team workspace"]
  node_boards["Boards and tasks<br/>[router.ts]"]
  node_calendar["Team calendar<br/>[calendar.ts]"]
  node_documents["Shared documents<br/>[rooms.ts]"]
  node_shipping["Shipping workflow<br/>[shipping-router.ts]"]
  node_conversations["Chat and email<br/>[router.ts]"]
end

subgraph group_agents["Agent platform"]
  node_coordination["Agent coordination<br/>[routing.ts]"]
  node_scheduler["Agent scheduler<br/>[scheduler.ts]"]
  node_turn["Agent turns<br/>[turn.ts]"]
  node_runtime_api["Runtime API<br/>[server.ts]"]
  node_cloud_pods["Managed agent pods<br/>[orchestrator.ts]"]
  node_byoa["BYOA daemon<br/>[cli.ts]"]
  node_fuse["Workspace mount<br/>[main.go]"]
end

subgraph group_infra["Persistence and integrations"]
  node_postgres[("PostgreSQL<br/>[pool.ts]")]
  node_redis[("Redis<br/>[redis.ts]")]
  node_outbox[("Realtime outbox<br/>[realtime-outbox.ts]")]
  node_storage[("File storage<br/>[storage.ts]")]
  node_workers["Email and CDN gates<br/>[index.ts]"]
end

node_people(("People"))
node_llm["OpenAI service"]
node_email_service["Email service"]
node_push_service["Push services"]

node_people -->|"use app"| node_app
node_app -->|"select shell"| node_desktop
node_app -->|"select shell"| node_mobile
node_desktop -->|"issue requests"| node_api_client
node_mobile -->|"issue requests"| node_api_client
node_api_client -->|"HTTP requests"| node_api
node_api -->|"return responses"| node_api_client
node_api_client -->|"open realtime"| node_ws
node_ws -->|"deliver events"| node_api_client
node_api -->|"handle chat"| node_conversations
node_api -->|"handle board work"| node_boards
node_api -->|"handle calendar"| node_calendar
node_api -->|"handle documents"| node_documents
node_api -->|"dispatch shipping"| node_shipping
node_api -->|"start convene"| node_coordination
node_api -->|"query and persist"| node_postgres
node_api -->|"enqueue invalidations"| node_outbox
node_outbox -->|"fan out events"| node_redis
node_ws -->|"subscribe events"| node_redis
node_scheduler -->|"coordinate work"| node_coordination
node_scheduler -->|"activate turns"| node_turn
node_turn -->|"request completions"| node_llm
node_turn -->|"invoke tools"| node_runtime_api
node_runtime_api -->|"read and write state"| node_postgres
node_cloud_pods -->|"use runtime API"| node_runtime_api
node_byoa -->|"use runtime API"| node_runtime_api
node_cloud_pods -->|"mount workspace"| node_fuse
node_fuse -->|"access workspace files"| node_runtime_api
node_api -->|"store attachments"| node_storage
node_api -.->|"send email"| node_email_service
node_workers -.->|"forward inbound mail"| node_api
node_api -.->|"send notifications"| node_push_service

click node_app "https://github.com/yetone/cumora/blob/main/src/App.tsx"
click node_desktop "https://github.com/yetone/cumora/blob/main/src/desktop/DesktopApp.tsx"
click node_mobile "https://github.com/yetone/cumora/blob/main/src/mobile/MobileApp.tsx"
click node_api_client "https://github.com/yetone/cumora/blob/main/src/api/client.ts"
click node_api "https://github.com/yetone/cumora/blob/main/server/src/api/router.ts"
click node_ws "https://github.com/yetone/cumora/blob/main/server/src/ws.ts"
click node_boards "https://github.com/yetone/cumora/blob/main/server/src/api/router.ts"
click node_calendar "https://github.com/yetone/cumora/blob/main/server/src/calendar.ts"
click node_documents "https://github.com/yetone/cumora/blob/main/server/src/documents/rooms.ts"
click node_shipping "https://github.com/yetone/cumora/blob/main/server/src/api/shipping-router.ts"
click node_conversations "https://github.com/yetone/cumora/blob/main/server/src/api/router.ts"
click node_coordination "https://github.com/yetone/cumora/blob/main/server/src/agents/routing.ts"
click node_scheduler "https://github.com/yetone/cumora/blob/main/server/src/agents/scheduler.ts"
click node_turn "https://github.com/yetone/cumora/blob/main/server/src/agents/turn.ts"
click node_runtime_api "https://github.com/yetone/cumora/blob/main/server/src/agents/runtime/server.ts"
click node_cloud_pods "https://github.com/yetone/cumora/blob/main/server/src/agents/runtime/orchestrator.ts"
click node_byoa "https://github.com/yetone/cumora/blob/main/agent-cli/src/cli.ts"
click node_fuse "https://github.com/yetone/cumora/blob/main/agent-fuse/main.go"
click node_postgres "https://github.com/yetone/cumora/blob/main/server/src/db/pool.ts"
click node_redis "https://github.com/yetone/cumora/blob/main/server/src/redis.ts"
click node_outbox "https://github.com/yetone/cumora/blob/main/server/src/realtime-outbox.ts"
click node_storage "https://github.com/yetone/cumora/blob/main/server/src/storage.ts"
click node_workers "https://github.com/yetone/cumora/blob/main/workers/email-gate/src/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_app,node_desktop,node_mobile,node_api_client toneBlue
class node_api,node_ws toneAmber
class node_boards,node_calendar,node_documents,node_shipping,node_conversations toneMint
class node_coordination,node_scheduler,node_turn,node_runtime_api,node_cloud_pods,node_byoa,node_fuse toneRose
class node_postgres,node_redis,node_outbox,node_storage,node_workers,node_people,node_llm,node_email_service,node_push_service toneIndigo
```

## Components

### Client apps

- [App bootstrap](https://github.com/yetone/cumora/blob/main/src/App.tsx): `src/App.tsx`
- [Desktop UI](https://github.com/yetone/cumora/blob/main/src/desktop/DesktopApp.tsx): `src/desktop/DesktopApp.tsx`
- [Mobile UI](https://github.com/yetone/cumora/blob/main/src/mobile/MobileApp.tsx): `src/mobile/MobileApp.tsx`
- [API client](https://github.com/yetone/cumora/blob/main/src/api/client.ts): `src/api/client.ts`

### Application backend

- [HTTP API](https://github.com/yetone/cumora/blob/main/server/src/api/router.ts): `server/src/api/router.ts`
- [Realtime gateway](https://github.com/yetone/cumora/blob/main/server/src/ws.ts): `server/src/ws.ts`

### Team workspace

- [Boards and tasks](https://github.com/yetone/cumora/blob/main/server/src/api/router.ts): `server/src/api/router.ts`
- [Team calendar](https://github.com/yetone/cumora/blob/main/server/src/calendar.ts): `server/src/calendar.ts`
- [Shared documents](https://github.com/yetone/cumora/blob/main/server/src/documents/rooms.ts): `server/src/documents/rooms.ts`
- [Shipping workflow](https://github.com/yetone/cumora/blob/main/server/src/api/shipping-router.ts): `server/src/api/shipping-router.ts`
- [Chat and email](https://github.com/yetone/cumora/blob/main/server/src/api/router.ts): `server/src/api/router.ts`

### Agent platform

- [Agent coordination](https://github.com/yetone/cumora/blob/main/server/src/agents/routing.ts): `server/src/agents/routing.ts`
- [Agent scheduler](https://github.com/yetone/cumora/blob/main/server/src/agents/scheduler.ts): `server/src/agents/scheduler.ts`
- [Agent turns](https://github.com/yetone/cumora/blob/main/server/src/agents/turn.ts): `server/src/agents/turn.ts`
- [Runtime API](https://github.com/yetone/cumora/blob/main/server/src/agents/runtime/server.ts): `server/src/agents/runtime/server.ts`
- [Managed agent pods](https://github.com/yetone/cumora/blob/main/server/src/agents/runtime/orchestrator.ts): `server/src/agents/runtime/orchestrator.ts`
- [BYOA daemon](https://github.com/yetone/cumora/blob/main/agent-cli/src/cli.ts): `agent-cli/src/cli.ts`
- [Workspace mount](https://github.com/yetone/cumora/blob/main/agent-fuse/main.go): `agent-fuse/main.go`

### Persistence and integrations

- [PostgreSQL](https://github.com/yetone/cumora/blob/main/server/src/db/pool.ts): `server/src/db/pool.ts`
- [Redis](https://github.com/yetone/cumora/blob/main/server/src/redis.ts): `server/src/redis.ts`
- [Realtime outbox](https://github.com/yetone/cumora/blob/main/server/src/realtime-outbox.ts): `server/src/realtime-outbox.ts`
- [File storage](https://github.com/yetone/cumora/blob/main/server/src/storage.ts): `server/src/storage.ts`
- [Email and CDN gates](https://github.com/yetone/cumora/blob/main/workers/email-gate/src/index.ts): `workers/email-gate/src/index.ts`

### Other components

- **People**
- **OpenAI service**
- **Email service**
- **Push services**

## Connections

- People → App bootstrap: use app
- App bootstrap → Desktop UI: select shell
- App bootstrap → Mobile UI: select shell
- Desktop UI → API client: issue requests
- Mobile UI → API client: issue requests
- API client → HTTP API: HTTP requests
- HTTP API → API client: return responses
- API client → Realtime gateway: open realtime
- Realtime gateway → API client: deliver events
- HTTP API → Chat and email: handle chat
- HTTP API → Boards and tasks: handle board work
- HTTP API → Team calendar: handle calendar
- HTTP API → Shared documents: handle documents
- HTTP API → Shipping workflow: dispatch shipping
- HTTP API → Agent coordination: start convene
- HTTP API → PostgreSQL: query and persist
- HTTP API → Realtime outbox: enqueue invalidations
- Realtime outbox → Redis: fan out events
- Realtime gateway → Redis: subscribe events
- Agent scheduler → Agent coordination: coordinate work
- Agent scheduler → Agent turns: activate turns
- Agent turns → OpenAI service: request completions
- Agent turns → Runtime API: invoke tools
- Runtime API → PostgreSQL: read and write state
- Managed agent pods → Runtime API: use runtime API
- BYOA daemon → Runtime API: use runtime API
- Managed agent pods → Workspace mount: mount workspace
- Workspace mount → Runtime API: access workspace files
- HTTP API → File storage: store attachments
- HTTP API → Email service: send email
- Email and CDN gates → HTTP API: forward inbound mail
- HTTP API → Push services: send notifications