# vereskdev/demonstrationbot architecture

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

- Interactive diagram: https://gitdiagram.com/vereskdev/demonstrationbot
- Repository: https://github.com/vereskdev/demonstrationbot

## Overview

assistant-bot is a personal Telegram assistant for notes, tasks, reminders, memory, and media generation. A Telegram update is polled, normalized and routed; owner commands and menu actions render deterministic views, while ordinary messages go through an agent turn that loads chat history, invokes Gemini and tools, then sends text and any queued files. A separate scheduler delivers due reminders. The README documents repository diagrams and image/card generation as tool capabilities. Some subsystem links are based on SOURCE INDEX references or README descriptions; unsampled implementation details are not inferred.

Main entry points: [`src/db/index.ts`](https://github.com/vereskdev/demonstrationbot/blob/main/src/db/index.ts) (Assistant data), [`src/tools/registry.ts`](https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/registry.ts) (Tool registry), [`src/telegram/handlers.ts`](https://github.com/vereskdev/demonstrationbot/blob/main/src/telegram/handlers.ts) (Update routing), [`src/agent/agent.ts`](https://github.com/vereskdev/demonstrationbot/blob/main/src/agent/agent.ts) (Agent turn)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interface"]
  node_main["Application startup<br/>[main.ts]"]
  node_polling["Long polling<br/>[polling.ts]"]
  node_handlers["Update routing<br/>[handlers.ts]"]
  node_views["Menu views<br/>[views.ts]"]
  node_tgapi["Telegram API client<br/>[api.ts]"]
end

subgraph group_agent["Agent and models"]
  node_agentturn["Agent turn<br/>[agent.ts]"]
  node_loop["Tool-call loop<br/>[loop.ts]"]
  node_gemini["Gemini transport<br/>[gemini.ts]"]
  node_registry["Tool registry<br/>[registry.ts]"]
end

subgraph group_tools["Assistant capabilities"]
  node_notes["Notes<br/>[notes.ts]"]
  node_tasks["Tasks<br/>[tasks.ts]"]
  node_remindtools["Reminder tools<br/>[reminders.ts]"]
  node_memory["Memory and settings<br/>[memory.ts]"]
  node_media["Media tools<br/>[media.ts]"]
  node_scheduler["Reminder scheduler<br/>[reminders.ts]"]
end

subgraph group_state["Persistence and time"]
  node_db[("Assistant data<br/>[index.ts]")]
  node_time["Time utilities<br/>[time.ts]"]
  node_config["Configuration<br/>[config.ts]"]
end

subgraph group_integrations["External integrations"]
  node_http["HTTP runtime<br/>[http.ts]"]
  node_imagegen["Image generation<br/>[generate.ts]"]
  node_card["Card rendering<br/>[card.ts]"]
  node_graphviz["Graph rendering<br/>[graphviz.ts]"]
  node_gitdiagram["GitHub diagrams<br/>[gitdiagram.ts]"]
end

node_owner(("Telegram owner"))
node_geminisvc{{"Google Gemini"}}
node_telegramapi{{"Telegram Bot API"}}
node_imageproviders{{"Image providers"}}
node_gitdiagramservice{{"GitDiagram service"}}

node_owner -->|"sends updates"| node_polling
node_main -->|"starts"| node_polling
node_main -->|"configures"| node_handlers
node_main -->|"starts"| node_scheduler
node_polling -->|"dispatches updates"| node_handlers
node_handlers -->|"routes messages"| node_agentturn
node_handlers -->|"renders menu views"| node_views
node_handlers -->|"reads chat state"| node_db
node_handlers -.->|"sends responses"| node_tgapi
node_agentturn -->|"runs turn"| node_loop
node_agentturn -->|"loads and saves history"| node_db
node_agentturn -->|"supplies tools"| node_registry
node_agentturn -.->|"sends reply"| node_tgapi
node_loop -->|"requests model turn"| node_gemini
node_loop -->|"executes tool calls"| node_registry
node_gemini -->|"sends requests"| node_http
node_gemini -->|"calls API"| node_geminisvc
node_registry -->|"registers"| node_notes
node_registry -->|"registers"| node_tasks
node_registry -->|"registers"| node_remindtools
node_registry -->|"registers"| node_memory
node_registry -->|"registers"| node_media
node_notes -->|"reads and writes"| node_db
node_tasks -->|"reads and writes"| node_db
node_remindtools -->|"reads and writes"| node_db
node_memory -->|"reads and writes"| node_db
node_scheduler -->|"loads and updates due reminders"| node_db
node_scheduler -.->|"delivers reminders"| node_tgapi
node_scheduler -->|"calculates repeats"| node_time
node_scheduler -->|"records bot event"| node_agentturn
node_views -->|"reads data"| node_db
node_media -->|"generates images"| node_imagegen
node_media -->|"renders cards"| node_card
node_media -->|"renders diagrams"| node_graphviz
node_media -->|"requests repository diagrams"| node_gitdiagram
node_imagegen -->|"sends requests"| node_http
node_imagegen -->|"requests image generation"| node_imageproviders
node_gitdiagram -->|"checks generated diagrams"| node_gitdiagramservice
node_tgapi -->|"uses HTTP client"| node_http
node_config -->|"configures data directory"| node_db

click node_main "https://github.com/vereskdev/demonstrationbot/blob/main/src/main.ts"
click node_polling "https://github.com/vereskdev/demonstrationbot/blob/main/src/telegram/polling.ts"
click node_handlers "https://github.com/vereskdev/demonstrationbot/blob/main/src/telegram/handlers.ts"
click node_views "https://github.com/vereskdev/demonstrationbot/blob/main/src/views.ts"
click node_tgapi "https://github.com/vereskdev/demonstrationbot/blob/main/src/telegram/api.ts"
click node_agentturn "https://github.com/vereskdev/demonstrationbot/blob/main/src/agent/agent.ts"
click node_loop "https://github.com/vereskdev/demonstrationbot/blob/main/src/llm/loop.ts"
click node_gemini "https://github.com/vereskdev/demonstrationbot/blob/main/src/llm/gemini.ts"
click node_registry "https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/registry.ts"
click node_notes "https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/notes.ts"
click node_tasks "https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/tasks.ts"
click node_remindtools "https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/reminders.ts"
click node_memory "https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/memory.ts"
click node_media "https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/media.ts"
click node_scheduler "https://github.com/vereskdev/demonstrationbot/blob/main/src/scheduler/reminders.ts"
click node_db "https://github.com/vereskdev/demonstrationbot/blob/main/src/db/index.ts"
click node_time "https://github.com/vereskdev/demonstrationbot/blob/main/src/time.ts"
click node_config "https://github.com/vereskdev/demonstrationbot/blob/main/src/config.ts"
click node_http "https://github.com/vereskdev/demonstrationbot/blob/main/src/runtime/http.ts"
click node_imagegen "https://github.com/vereskdev/demonstrationbot/blob/main/src/images/generate.ts"
click node_card "https://github.com/vereskdev/demonstrationbot/blob/main/src/images/card.ts"
click node_graphviz "https://github.com/vereskdev/demonstrationbot/blob/main/src/diagrams/graphviz.ts"
click node_gitdiagram "https://github.com/vereskdev/demonstrationbot/blob/main/src/diagrams/gitdiagram.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_main,node_polling,node_handlers,node_views,node_tgapi toneBlue
class node_agentturn,node_loop,node_gemini,node_registry toneAmber
class node_notes,node_tasks,node_remindtools,node_memory,node_media,node_scheduler,node_telegramapi toneMint
class node_db,node_time,node_config toneRose
class node_http,node_imagegen,node_card,node_graphviz,node_gitdiagram,node_owner,node_geminisvc,node_imageproviders,node_gitdiagramservice toneIndigo
```

## Components

### Telegram interface

- [Application startup](https://github.com/vereskdev/demonstrationbot/blob/main/src/main.ts): `src/main.ts`
- [Long polling](https://github.com/vereskdev/demonstrationbot/blob/main/src/telegram/polling.ts): `src/telegram/polling.ts`
- [Update routing](https://github.com/vereskdev/demonstrationbot/blob/main/src/telegram/handlers.ts): `src/telegram/handlers.ts`
- [Menu views](https://github.com/vereskdev/demonstrationbot/blob/main/src/views.ts): `src/views.ts`
- [Telegram API client](https://github.com/vereskdev/demonstrationbot/blob/main/src/telegram/api.ts): `src/telegram/api.ts`

### Agent and models

- [Agent turn](https://github.com/vereskdev/demonstrationbot/blob/main/src/agent/agent.ts): `src/agent/agent.ts`
- [Tool-call loop](https://github.com/vereskdev/demonstrationbot/blob/main/src/llm/loop.ts): `src/llm/loop.ts`
- [Gemini transport](https://github.com/vereskdev/demonstrationbot/blob/main/src/llm/gemini.ts): `src/llm/gemini.ts`
- [Tool registry](https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/registry.ts): `src/tools/registry.ts`

### Assistant capabilities

- [Notes](https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/notes.ts): `src/tools/notes.ts`
- [Tasks](https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/tasks.ts): `src/tools/tasks.ts`
- [Reminder tools](https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/reminders.ts): `src/tools/reminders.ts`
- [Memory and settings](https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/memory.ts): `src/tools/memory.ts`
- [Media tools](https://github.com/vereskdev/demonstrationbot/blob/main/src/tools/media.ts): `src/tools/media.ts`
- [Reminder scheduler](https://github.com/vereskdev/demonstrationbot/blob/main/src/scheduler/reminders.ts): `src/scheduler/reminders.ts`

### Persistence and time

- [Assistant data](https://github.com/vereskdev/demonstrationbot/blob/main/src/db/index.ts): `src/db/index.ts`
- [Time utilities](https://github.com/vereskdev/demonstrationbot/blob/main/src/time.ts): `src/time.ts`
- [Configuration](https://github.com/vereskdev/demonstrationbot/blob/main/src/config.ts): `src/config.ts`

### External integrations

- [HTTP runtime](https://github.com/vereskdev/demonstrationbot/blob/main/src/runtime/http.ts): `src/runtime/http.ts`
- [Image generation](https://github.com/vereskdev/demonstrationbot/blob/main/src/images/generate.ts): `src/images/generate.ts`
- [Card rendering](https://github.com/vereskdev/demonstrationbot/blob/main/src/images/card.ts): `src/images/card.ts`
- [Graph rendering](https://github.com/vereskdev/demonstrationbot/blob/main/src/diagrams/graphviz.ts): `src/diagrams/graphviz.ts`
- [GitHub diagrams](https://github.com/vereskdev/demonstrationbot/blob/main/src/diagrams/gitdiagram.ts): `src/diagrams/gitdiagram.ts`

### Other components

- **Telegram owner**
- **Google Gemini**
- **Telegram Bot API**
- **Image providers**
- **GitDiagram service**

## Connections

- Telegram owner → Long polling: sends updates (evidence: `README.md`)
- Application startup → Long polling: starts (evidence: `src/main.ts`)
- Application startup → Update routing: configures (evidence: `src/main.ts`)
- Application startup → Reminder scheduler: starts (evidence: `src/main.ts`)
- Long polling → Update routing: dispatches updates (evidence: `src/telegram/polling.ts`)
- Update routing → Agent turn: routes messages (evidence: `src/telegram/handlers.ts`)
- Update routing → Menu views: renders menu views (evidence: `src/telegram/handlers.ts`)
- Update routing → Assistant data: reads chat state (evidence: `src/telegram/handlers.ts`)
- Update routing → Telegram API client: sends responses (evidence: `src/telegram/handlers.ts`)
- Agent turn → Tool-call loop: runs turn (evidence: `src/agent/agent.ts`)
- Agent turn → Assistant data: loads and saves history (evidence: `src/agent/agent.ts`)
- Agent turn → Tool registry: supplies tools (evidence: `src/agent/agent.ts`)
- Agent turn → Telegram API client: sends reply
- Tool-call loop → Gemini transport: requests model turn (evidence: `src/llm/loop.ts`)
- Tool-call loop → Tool registry: executes tool calls (evidence: `src/llm/loop.ts`)
- Gemini transport → HTTP runtime: sends requests (evidence: `src/llm/gemini.ts`)
- Gemini transport → Google Gemini: calls API (evidence: `README.md`)
- Tool registry → Notes: registers (evidence: `src/tools/registry.ts`)
- Tool registry → Tasks: registers (evidence: `src/tools/registry.ts`)
- Tool registry → Reminder tools: registers (evidence: `src/tools/registry.ts`)
- Tool registry → Memory and settings: registers (evidence: `src/tools/registry.ts`)
- Tool registry → Media tools: registers (evidence: `src/tools/registry.ts`)
- Notes → Assistant data: reads and writes (evidence: `src/tools/notes.ts`)
- Tasks → Assistant data: reads and writes (evidence: `src/tools/tasks.ts`)
- Reminder tools → Assistant data: reads and writes (evidence: `src/tools/reminders.ts`)
- Memory and settings → Assistant data: reads and writes (evidence: `src/tools/memory.ts`)
- Reminder scheduler → Assistant data: loads and updates due reminders (evidence: `src/scheduler/reminders.ts`)
- Reminder scheduler → Telegram API client: delivers reminders
- Reminder scheduler → Time utilities: calculates repeats (evidence: `src/scheduler/reminders.ts`)
- Reminder scheduler → Agent turn: records bot event (evidence: `src/scheduler/reminders.ts`)
- Menu views → Assistant data: reads data (evidence: `src/views.ts`)
- Media tools → Image generation: generates images (evidence: `src/tools/media.ts`)
- Media tools → Card rendering: renders cards (evidence: `src/tools/media.ts`)
- Media tools → Graph rendering: renders diagrams (evidence: `src/tools/media.ts`)
- Media tools → GitHub diagrams: requests repository diagrams (evidence: `src/tools/media.ts`)
- Image generation → HTTP runtime: sends requests (evidence: `src/images/generate.ts`)
- Image generation → Image providers: requests image generation (evidence: `README.md`)
- GitHub diagrams → GitDiagram service: checks generated diagrams (evidence: `README.md`)
- Telegram API client → HTTP runtime: uses HTTP client (evidence: `src/telegram/api.ts`)
- Configuration → Assistant data: configures data directory (evidence: `src/db/index.ts`)
