# cgoinglove/thursday architecture

> Architecture diagram of the GitHub repository cgoinglove/thursday, 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/cgoinglove/thursday
- Repository: https://github.com/cgoinglove/thursday

## Overview

Thursday is a local-first voice assistant: the user talks or writes, a live call handles the conversation and invokes tools, and longer jobs are handed to background bots whose work is saved and reported back. Bots can coordinate through threads, use browser, shell, files, skills and MCP tools, and produce artifacts in the workspace. Routines and messaging integrations provide additional ways to start jobs. The graph follows README-described capabilities and sampled route, query and manager behavior; unsampled internals are represented only at supported directory paths.

Main entry points: [`features/bot/bot.run.ts`](https://github.com/cgoinglove/thursday/blob/main/features/bot/bot.run.ts) (Bot runner), [`lib/live/live.session.ts`](https://github.com/cgoinglove/thursday/blob/main/lib/live/live.session.ts) (Live session), [`app/page.tsx`](https://github.com/cgoinglove/thursday/blob/main/app/page.tsx) (Assistant app), [`features/ai/load-tools.ts`](https://github.com/cgoinglove/thursday/blob/main/features/ai/load-tools.ts) (Tool loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Live conversation"]
  node_app["Assistant app<br/>[page.tsx]"]
  node_live["Live session<br/>[live.session.ts]"]
  node_liveapi["Live API routes"]
  node_toolroute["Tool-call route<br/>[route.ts]"]
  node_toolregistry["Tool loader<br/>[load-tools.ts]"]
end

subgraph group_agents["Bots and jobs"]
  node_botapi["Bot API routes"]
  node_botrun["Bot runner<br/>[bot.run.ts]"]
  node_botcoord["Thread coordination<br/>[room.query.ts]"]
  node_routines["Scheduled routines"]
end

subgraph group_capabilities["Agent capabilities"]
  node_memory[("Readable memory<br/>[memory.query.ts]")]
  node_workspace["Workspace files<br/>[workspace.ts]"]
  node_fileapi["File serving<br/>[route.ts]"]
  node_artifacts["Artifact tools"]
  node_skills["Agent skills"]
  node_mcp["MCP connections<br/>[mcp.manager.ts]"]
  node_signin["Browser sign-ins<br/>[signins.query.ts]"]
end

subgraph group_persistence["Local data"]
  node_threads[("Thread history<br/>[thread.query.ts]")]
  node_database[("App database<br/>[db.ts]")]
end

subgraph group_integrations["External channels"]
  node_model["Model providers<br/>[model.ts]"]
  node_reach["Messaging channels"]
end

node_user(("User"))
node_browser["Browser and shell"]
node_mcpservers["MCP servers"]
node_chatgpt["OpenAI live service"]
node_othermodels["Text model services"]
node_messaging["Telegram Discord Slack"]

node_user -->|"speaks or writes"| node_app
node_app -->|"opens call"| node_live
node_live -->|"streams audio"| node_chatgpt
node_live -->|"uses call routes"| node_liveapi
node_liveapi -->|"posts tool calls"| node_toolroute
node_toolroute -->|"loads tools"| node_toolregistry
node_toolregistry -->|"builds model tools"| node_model
node_model -->|"calls text models"| node_othermodels
node_toolregistry -->|"delegates jobs"| node_botrun
node_botapi -->|"starts or resumes"| node_botrun
node_botrun -->|"coordinates work"| node_botcoord
node_botcoord -->|"reads and writes"| node_threads
node_botcoord -->|"persists room state"| node_database
node_botrun -->|"recalls or updates"| node_memory
node_botrun -->|"reads and writes files"| node_workspace
node_botrun -->|"runs browser and shell"| node_browser
node_botrun -->|"loads skills"| node_skills
node_botrun -->|"invokes MCP tools"| node_mcp
node_mcp -.->|"connects tools"| node_mcpservers
node_botrun -->|"uses sign-in state"| node_signin
node_signin -->|"reads browser state"| node_browser
node_botrun -->|"creates results"| node_artifacts
node_artifacts -->|"saves files"| node_workspace
node_app -->|"requests workspace files"| node_fileapi
node_fileapi -->|"serves confined files"| node_workspace
node_routines -->|"starts scheduled jobs"| node_botrun
node_messaging -.->|"sends messages"| node_reach
node_reach -->|"starts or continues jobs"| node_botrun
node_reach -->|"supports text calls"| node_live
node_user -.->|"writes remotely"| node_messaging

click node_app "https://github.com/cgoinglove/thursday/blob/main/app/page.tsx"
click node_live "https://github.com/cgoinglove/thursday/blob/main/lib/live/live.session.ts"
click node_liveapi "https://github.com/cgoinglove/thursday/tree/main/app/api/thursday"
click node_toolroute "https://github.com/cgoinglove/thursday/blob/main/app/api/thursday/tool-call/route.ts"
click node_toolregistry "https://github.com/cgoinglove/thursday/blob/main/features/ai/load-tools.ts"
click node_model "https://github.com/cgoinglove/thursday/blob/main/features/ai/model.ts"
click node_botapi "https://github.com/cgoinglove/thursday/tree/main/app/api/bot"
click node_botrun "https://github.com/cgoinglove/thursday/blob/main/features/bot/bot.run.ts"
click node_botcoord "https://github.com/cgoinglove/thursday/blob/main/features/bot/room.query.ts"
click node_threads "https://github.com/cgoinglove/thursday/blob/main/features/bot/thread.query.ts"
click node_routines "https://github.com/cgoinglove/thursday/tree/main/features/routine"
click node_memory "https://github.com/cgoinglove/thursday/blob/main/features/memory/memory.query.ts"
click node_workspace "https://github.com/cgoinglove/thursday/blob/main/features/workspace/workspace.ts"
click node_fileapi "https://github.com/cgoinglove/thursday/blob/main/app/api/file/%5B...path%5D/route.ts"
click node_artifacts "https://github.com/cgoinglove/thursday/tree/main/features/artifact"
click node_skills "https://github.com/cgoinglove/thursday/tree/main/features/skills"
click node_mcp "https://github.com/cgoinglove/thursday/blob/main/features/connectors/mcp.manager.ts"
click node_signin "https://github.com/cgoinglove/thursday/blob/main/features/signins/signins.query.ts"
click node_reach "https://github.com/cgoinglove/thursday/tree/main/features/reach"
click node_database "https://github.com/cgoinglove/thursday/blob/main/database/db.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_live,node_liveapi,node_toolroute,node_toolregistry,node_user,node_browser toneBlue
class node_botapi,node_botrun,node_botcoord,node_routines toneAmber
class node_memory,node_workspace,node_fileapi,node_artifacts,node_skills,node_mcp,node_signin,node_mcpservers toneMint
class node_threads,node_database toneRose
class node_model,node_reach,node_chatgpt,node_othermodels,node_messaging toneIndigo
```

## Components

### Live conversation

- [Assistant app](https://github.com/cgoinglove/thursday/blob/main/app/page.tsx): `app/page.tsx`
- [Live session](https://github.com/cgoinglove/thursday/blob/main/lib/live/live.session.ts): `lib/live/live.session.ts`
- [Live API routes](https://github.com/cgoinglove/thursday/tree/main/app/api/thursday): `app/api/thursday`
- [Tool-call route](https://github.com/cgoinglove/thursday/blob/main/app/api/thursday/tool-call/route.ts): `app/api/thursday/tool-call/route.ts`
- [Tool loader](https://github.com/cgoinglove/thursday/blob/main/features/ai/load-tools.ts): `features/ai/load-tools.ts`

### Bots and jobs

- [Bot API routes](https://github.com/cgoinglove/thursday/tree/main/app/api/bot): `app/api/bot`
- [Bot runner](https://github.com/cgoinglove/thursday/blob/main/features/bot/bot.run.ts): `features/bot/bot.run.ts`
- [Thread coordination](https://github.com/cgoinglove/thursday/blob/main/features/bot/room.query.ts): `features/bot/room.query.ts`
- [Scheduled routines](https://github.com/cgoinglove/thursday/tree/main/features/routine): `features/routine`

### Agent capabilities

- [Readable memory](https://github.com/cgoinglove/thursday/blob/main/features/memory/memory.query.ts): `features/memory/memory.query.ts`
- [Workspace files](https://github.com/cgoinglove/thursday/blob/main/features/workspace/workspace.ts): `features/workspace/workspace.ts`
- [File serving](https://github.com/cgoinglove/thursday/blob/main/app/api/file/%5B...path%5D/route.ts): `app/api/file/[...path]/route.ts`
- [Artifact tools](https://github.com/cgoinglove/thursday/tree/main/features/artifact): `features/artifact`
- [Agent skills](https://github.com/cgoinglove/thursday/tree/main/features/skills): `features/skills`
- [MCP connections](https://github.com/cgoinglove/thursday/blob/main/features/connectors/mcp.manager.ts): `features/connectors/mcp.manager.ts`
- [Browser sign-ins](https://github.com/cgoinglove/thursday/blob/main/features/signins/signins.query.ts): `features/signins/signins.query.ts`

### Local data

- [Thread history](https://github.com/cgoinglove/thursday/blob/main/features/bot/thread.query.ts): `features/bot/thread.query.ts`
- [App database](https://github.com/cgoinglove/thursday/blob/main/database/db.ts): `database/db.ts`

### External channels

- [Model providers](https://github.com/cgoinglove/thursday/blob/main/features/ai/model.ts): `features/ai/model.ts`
- [Messaging channels](https://github.com/cgoinglove/thursday/tree/main/features/reach): `features/reach`

### Other components

- **User**
- **Browser and shell**
- **MCP servers**
- **OpenAI live service**
- **Text model services**
- **Telegram Discord Slack**

## Connections

- User → Assistant app: speaks or writes
- Assistant app → Live session: opens call
- Live session → OpenAI live service: streams audio
- Live session → Live API routes: uses call routes
- Live API routes → Tool-call route: posts tool calls
- Tool-call route → Tool loader: loads tools
- Tool loader → Model providers: builds model tools
- Model providers → Text model services: calls text models
- Tool loader → Bot runner: delegates jobs
- Bot API routes → Bot runner: starts or resumes
- Bot runner → Thread coordination: coordinates work
- Thread coordination → Thread history: reads and writes
- Thread coordination → App database: persists room state
- Bot runner → Readable memory: recalls or updates
- Bot runner → Workspace files: reads and writes files
- Bot runner → Browser and shell: runs browser and shell
- Bot runner → Agent skills: loads skills
- Bot runner → MCP connections: invokes MCP tools
- MCP connections → MCP servers: connects tools
- Bot runner → Browser sign-ins: uses sign-in state
- Browser sign-ins → Browser and shell: reads browser state
- Bot runner → Artifact tools: creates results
- Artifact tools → Workspace files: saves files
- Assistant app → File serving: requests workspace files
- File serving → Workspace files: serves confined files
- Scheduled routines → Bot runner: starts scheduled jobs
- Telegram Discord Slack → Messaging channels: sends messages
- Messaging channels → Bot runner: starts or continues jobs
- Messaging channels → Live session: supports text calls
- User → Telegram Discord Slack: writes remotely