# cloudnutzer/tybo architecture

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

- Interactive diagram: https://gitdiagram.com/cloudnutzer/tybo
- Repository: https://github.com/cloudnutzer/tybo

## Overview

tybo is an always-on AI assistant whose main workflow accepts messages through Telegram or the browser, runs them through Claude Code with a topic-specific agent and available context, then returns replies through the chat interfaces. Persistent memory, fallback models, long-running jobs, and ongoing goals are major product capabilities. The graph uses README statements and the supplied excerpts; several subsystem connections are therefore intentionally left unspecified.

Main entry points: [`src/bot.ts`](https://github.com/cloudnutzer/tybo/blob/master/src/bot.ts) (Bot runtime), [`src/lib/telegram.ts`](https://github.com/cloudnutzer/tybo/blob/master/src/lib/telegram.ts) (Telegram gateway), [`src/web/bot-turn.ts`](https://github.com/cloudnutzer/tybo/blob/master/src/web/bot-turn.ts) (Web chat handler), [`src/lib/memory.ts`](https://github.com/cloudnutzer/tybo/blob/master/src/lib/memory.ts) (Memory and context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Chat interfaces"]
  node_telegram["Telegram gateway<br/>[telegram.ts]"]
  node_web_server["Web server<br/>[server.ts]"]
  node_web_chat["Web chat<br/>[chat.ts]"]
  node_web_turn["Web chat handler<br/>[bot-turn.ts]"]
end

subgraph group_runtime["Assistant runtime"]
  node_bot["Bot runtime<br/>[bot.ts]"]
end

subgraph group_capabilities["Assistant capabilities"]
  node_agents["Agent catalog<br/>[index.ts]"]
  node_fallback["Fallback models<br/>[fallback-llm.ts]"]
  node_memory["Memory and context<br/>[memory.ts]"]
  node_knowledge["Knowledge base<br/>[knowledge-base.ts]"]
end

subgraph group_persistence["Persistence"]
  node_supabase[("Supabase backend<br/>[supabase.ts]")]
  node_convex_client["Convex client<br/>[convex.ts]"]
  node_convex_data[("Convex data<br/>[schema.ts]")]
  node_local_session[("Session continuity<br/>[session-manager.ts]")]
end

subgraph group_background["Background work"]
  node_goals["Goal engine<br/>[goal-engine.ts]"]
  node_jobs["Background jobs<br/>[runner.ts]"]
end

node_telegram_user(("Telegram user"))
node_browser_user(("Browser user"))
node_claude["Claude Code CLI"]

node_telegram_user -->|"sends messages"| node_telegram
node_telegram -->|"delivers messages"| node_bot
node_browser_user -->|"sends messages"| node_web_chat
node_web_chat -->|"requests chat"| node_web_server
node_web_server -->|"routes turns"| node_web_turn
node_bot -->|"selects agent"| node_agents
node_bot -->|"runs turns"| node_claude
node_bot -.->|"uses on failure"| node_fallback
node_bot -->|"loads context"| node_memory
node_bot -->|"uses knowledge"| node_knowledge
node_bot -->|"sends replies"| node_telegram
node_web_turn -->|"runs turns"| node_claude
node_web_turn -->|"loads context"| node_memory
node_web_turn -->|"mirrors messages"| node_telegram
node_memory -.->|"persists memory"| node_supabase
node_memory -.->|"persists memory"| node_convex_client
node_convex_client -->|"reads and writes"| node_convex_data
node_bot -->|"checks goals"| node_goals
node_goals -->|"runs goal turns"| node_claude
node_bot -->|"starts jobs"| node_jobs
node_jobs -->|"reports results"| node_telegram
node_bot -.->|"tracks sessions"| node_local_session

click node_telegram "https://github.com/cloudnutzer/tybo/blob/master/src/lib/telegram.ts"
click node_bot "https://github.com/cloudnutzer/tybo/blob/master/src/bot.ts"
click node_web_server "https://github.com/cloudnutzer/tybo/blob/master/src/web/server.ts"
click node_web_chat "https://github.com/cloudnutzer/tybo/blob/master/src/web/chat.ts"
click node_web_turn "https://github.com/cloudnutzer/tybo/blob/master/src/web/bot-turn.ts"
click node_agents "https://github.com/cloudnutzer/tybo/blob/master/src/agents/index.ts"
click node_fallback "https://github.com/cloudnutzer/tybo/blob/master/src/lib/fallback-llm.ts"
click node_memory "https://github.com/cloudnutzer/tybo/blob/master/src/lib/memory.ts"
click node_knowledge "https://github.com/cloudnutzer/tybo/blob/master/src/lib/knowledge-base.ts"
click node_goals "https://github.com/cloudnutzer/tybo/blob/master/src/lib/goal-engine.ts"
click node_jobs "https://github.com/cloudnutzer/tybo/blob/master/src/lib/jobs/runner.ts"
click node_supabase "https://github.com/cloudnutzer/tybo/blob/master/src/lib/supabase.ts"
click node_convex_client "https://github.com/cloudnutzer/tybo/blob/master/src/lib/convex.ts"
click node_convex_data "https://github.com/cloudnutzer/tybo/blob/master/convex/schema.ts"
click node_local_session "https://github.com/cloudnutzer/tybo/blob/master/src/lib/session-manager.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_telegram,node_web_server,node_web_chat,node_web_turn,node_telegram_user,node_browser_user toneBlue
class node_bot toneAmber
class node_agents,node_fallback,node_memory,node_knowledge toneMint
class node_supabase,node_convex_client,node_convex_data,node_local_session toneRose
class node_goals,node_jobs,node_claude toneIndigo
```

## Components

### Chat interfaces

- [Telegram gateway](https://github.com/cloudnutzer/tybo/blob/master/src/lib/telegram.ts): `src/lib/telegram.ts`
- [Web server](https://github.com/cloudnutzer/tybo/blob/master/src/web/server.ts): `src/web/server.ts`
- [Web chat](https://github.com/cloudnutzer/tybo/blob/master/src/web/chat.ts): `src/web/chat.ts`
- [Web chat handler](https://github.com/cloudnutzer/tybo/blob/master/src/web/bot-turn.ts): `src/web/bot-turn.ts`

### Assistant runtime

- [Bot runtime](https://github.com/cloudnutzer/tybo/blob/master/src/bot.ts): `src/bot.ts`

### Assistant capabilities

- [Agent catalog](https://github.com/cloudnutzer/tybo/blob/master/src/agents/index.ts): `src/agents/index.ts`
- [Fallback models](https://github.com/cloudnutzer/tybo/blob/master/src/lib/fallback-llm.ts): `src/lib/fallback-llm.ts`
- [Memory and context](https://github.com/cloudnutzer/tybo/blob/master/src/lib/memory.ts): `src/lib/memory.ts`
- [Knowledge base](https://github.com/cloudnutzer/tybo/blob/master/src/lib/knowledge-base.ts): `src/lib/knowledge-base.ts`

### Persistence

- [Supabase backend](https://github.com/cloudnutzer/tybo/blob/master/src/lib/supabase.ts): `src/lib/supabase.ts`
- [Convex client](https://github.com/cloudnutzer/tybo/blob/master/src/lib/convex.ts): `src/lib/convex.ts`
- [Convex data](https://github.com/cloudnutzer/tybo/blob/master/convex/schema.ts): `convex/schema.ts`
- [Session continuity](https://github.com/cloudnutzer/tybo/blob/master/src/lib/session-manager.ts): `src/lib/session-manager.ts`

### Background work

- [Goal engine](https://github.com/cloudnutzer/tybo/blob/master/src/lib/goal-engine.ts): `src/lib/goal-engine.ts`
- [Background jobs](https://github.com/cloudnutzer/tybo/blob/master/src/lib/jobs/runner.ts): `src/lib/jobs/runner.ts`

### Other components

- **Telegram user**
- **Browser user**
- **Claude Code CLI**

## Connections

- Telegram user → Telegram gateway: sends messages
- Telegram gateway → Bot runtime: delivers messages
- Browser user → Web chat: sends messages
- Web chat → Web server: requests chat
- Web server → Web chat handler: routes turns
- Bot runtime → Agent catalog: selects agent
- Bot runtime → Claude Code CLI: runs turns
- Bot runtime → Fallback models: uses on failure
- Bot runtime → Memory and context: loads context
- Bot runtime → Knowledge base: uses knowledge
- Bot runtime → Telegram gateway: sends replies
- Web chat handler → Claude Code CLI: runs turns
- Web chat handler → Memory and context: loads context
- Web chat handler → Telegram gateway: mirrors messages
- Memory and context → Supabase backend: persists memory
- Memory and context → Convex client: persists memory
- Convex client → Convex data: reads and writes
- Bot runtime → Goal engine: checks goals
- Goal engine → Claude Code CLI: runs goal turns
- Bot runtime → Background jobs: starts jobs
- Background jobs → Telegram gateway: reports results
- Bot runtime → Session continuity: tracks sessions