# veta-one/sych-bot architecture

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

- Interactive diagram: https://gitdiagram.com/veta-one/sych-bot
- Repository: https://github.com/veta-one/sych-bot

## Overview

Сыч — Telegram-бот для групповых и личных чатов: принимает сообщения и медиа, решает, когда отвечать, формирует ответ с контекстом и при необходимости поиском, затем отправляет его в Telegram. Основной маршрут проходит через обработчик Telegram и логику диалога; рядом расположены функции голосовой и документной обработки, YouTube-разборов, напоминаний, форматирования и хранения профилей. Граф опирается на README и показанные импорты/вызовы; детали невычитанных частей реализации представлены только там, где README прямо описывает возможность.

Main entry points: [`src/core/logic.js`](https://github.com/veta-one/sych-bot/blob/main/src/core/logic.js) (Маршрутизация диалога), [`src/services/ai.js`](https://github.com/veta-one/sych-bot/blob/main/src/services/ai.js) (AI-оркестрация), [`src/index.js`](https://github.com/veta-one/sych-bot/blob/main/src/index.js) (Обработка событий), [`src/utils/rich.js`](https://github.com/veta-one/sych-bot/blob/main/src/utils/rich.js) (Форматирование сообщений)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Чат и маршрутизация"]
  node_entry["Обработка событий<br/>[index.js]"]
  node_conversation["Маршрутизация диалога<br/>[logic.js]"]
  node_ephemeral["Временные сообщения<br/>[ephemeral.js]"]
end

subgraph group_intelligence["Диалог и поиск"]
  node_ai["AI-оркестрация<br/>[ai.js]"]
  node_prompts["Промпты и модели<br/>[prompts.js]"]
  node_research["Поиск и проверка<br/>[research.js]"]
end

subgraph group_media["Медиа-анализ"]
  node_documents["Разбор документов<br/>[documents.js]"]
  node_voice["Распознавание и сводка<br/>[voice.js]"]
  node_youtube["Субтитры YouTube<br/>[youtube.js]"]
  node_youtube_gemini["Видео через Gemini<br/>[youtube-gemini.js]"]
end

subgraph group_memory["Память и напоминания"]
  node_storage[("Профили и архивы<br/>[storage.js]")]
  node_private_context["Приватный контекст<br/>[private-context.js]"]
  node_reminder_rules["Разбор времени<br/>[reminders.js]"]
  node_reminder_delivery["Доставка напоминаний"]
end

subgraph group_delivery["Ответы в Telegram"]
  node_rich["Форматирование сообщений<br/>[rich.js]"]
end

node_telegram_user(("Участник чата"))
node_telegram["Telegram Bot API"]
node_search_provider["Tavily / Perplexity / Google"]
node_llm_provider["OpenAI-compatible / Gemini"]
node_telegram_output(("Получатель в Telegram"))

node_telegram_user -->|"отправляет сообщение"| node_entry
node_entry -->|"передаёт событие"| node_conversation
node_conversation -->|"запрашивает анализ"| node_ai
node_conversation -->|"обрабатывает временные"| node_ephemeral
node_conversation -->|"читает и обновляет"| node_storage
node_conversation -->|"разбирает документы"| node_documents
node_conversation -->|"разбирает напоминание"| node_reminder_rules
node_ai -->|"собирает запросы"| node_prompts
node_ai -->|"учитывает статистику"| node_storage
node_ai -->|"проводит исследование"| node_research
node_research -.->|"ищет и читает"| node_search_provider
node_ai -->|"запрашивает модели"| node_llm_provider
node_conversation -->|"обрабатывает речь"| node_voice
node_ai -->|"распознаёт аудио"| node_voice
node_ai -->|"разбирает ролики"| node_youtube
node_ai -->|"использует видеоанализ"| node_youtube_gemini
node_youtube_gemini -->|"получает данные ролика"| node_youtube
node_conversation -.->|"использует приватный режим"| node_private_context
node_entry -->|"создаёт доставку"| node_reminder_delivery
node_reminder_delivery -->|"оформляет уведомление"| node_rich
node_conversation -->|"оформляет ответ"| node_rich
node_rich -->|"отправляет форматированный текст"| node_telegram
node_telegram -.->|"доставляет ответ"| node_telegram_output

click node_entry "https://github.com/veta-one/sych-bot/blob/main/src/index.js"
click node_conversation "https://github.com/veta-one/sych-bot/blob/main/src/core/logic.js"
click node_ephemeral "https://github.com/veta-one/sych-bot/blob/main/src/core/ephemeral.js"
click node_ai "https://github.com/veta-one/sych-bot/blob/main/src/services/ai.js"
click node_prompts "https://github.com/veta-one/sych-bot/blob/main/src/core/prompts.js"
click node_research "https://github.com/veta-one/sych-bot/blob/main/src/services/research.js"
click node_documents "https://github.com/veta-one/sych-bot/blob/main/src/services/documents.js"
click node_voice "https://github.com/veta-one/sych-bot/blob/main/src/utils/voice.js"
click node_youtube "https://github.com/veta-one/sych-bot/blob/main/src/services/youtube.js"
click node_youtube_gemini "https://github.com/veta-one/sych-bot/blob/main/src/services/youtube-gemini.js"
click node_storage "https://github.com/veta-one/sych-bot/blob/main/src/services/storage.js"
click node_private_context "https://github.com/veta-one/sych-bot/blob/main/src/utils/private-context.js"
click node_reminder_rules "https://github.com/veta-one/sych-bot/blob/main/src/utils/reminders.js"
click node_reminder_delivery "https://github.com/veta-one/sych-bot/blob/main/src/services/reminder-delivery.js"
click node_rich "https://github.com/veta-one/sych-bot/blob/main/src/utils/rich.js"

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_entry,node_conversation,node_ephemeral toneBlue
class node_ai,node_prompts,node_research toneAmber
class node_documents,node_voice,node_youtube,node_youtube_gemini,node_telegram toneMint
class node_storage,node_private_context,node_reminder_rules,node_reminder_delivery toneRose
class node_rich,node_telegram_user,node_search_provider,node_llm_provider,node_telegram_output toneIndigo
```

## Components

### Чат и маршрутизация

- [Обработка событий](https://github.com/veta-one/sych-bot/blob/main/src/index.js): `src/index.js`
- [Маршрутизация диалога](https://github.com/veta-one/sych-bot/blob/main/src/core/logic.js): `src/core/logic.js`
- [Временные сообщения](https://github.com/veta-one/sych-bot/blob/main/src/core/ephemeral.js): `src/core/ephemeral.js`

### Диалог и поиск

- [AI-оркестрация](https://github.com/veta-one/sych-bot/blob/main/src/services/ai.js): `src/services/ai.js`
- [Промпты и модели](https://github.com/veta-one/sych-bot/blob/main/src/core/prompts.js): `src/core/prompts.js`
- [Поиск и проверка](https://github.com/veta-one/sych-bot/blob/main/src/services/research.js): `src/services/research.js`

### Медиа-анализ

- [Разбор документов](https://github.com/veta-one/sych-bot/blob/main/src/services/documents.js): `src/services/documents.js`
- [Распознавание и сводка](https://github.com/veta-one/sych-bot/blob/main/src/utils/voice.js): `src/utils/voice.js`
- [Субтитры YouTube](https://github.com/veta-one/sych-bot/blob/main/src/services/youtube.js): `src/services/youtube.js`
- [Видео через Gemini](https://github.com/veta-one/sych-bot/blob/main/src/services/youtube-gemini.js): `src/services/youtube-gemini.js`

### Память и напоминания

- [Профили и архивы](https://github.com/veta-one/sych-bot/blob/main/src/services/storage.js): `src/services/storage.js`
- [Приватный контекст](https://github.com/veta-one/sych-bot/blob/main/src/utils/private-context.js): `src/utils/private-context.js`
- [Разбор времени](https://github.com/veta-one/sych-bot/blob/main/src/utils/reminders.js): `src/utils/reminders.js`
- [Доставка напоминаний](https://github.com/veta-one/sych-bot/blob/main/src/services/reminder-delivery.js): `src/services/reminder-delivery.js`

### Ответы в Telegram

- [Форматирование сообщений](https://github.com/veta-one/sych-bot/blob/main/src/utils/rich.js): `src/utils/rich.js`

### Other components

- **Участник чата**
- **Telegram Bot API**
- **Tavily / Perplexity / Google**
- **OpenAI-compatible / Gemini**
- **Получатель в Telegram**

## Connections

- Участник чата → Обработка событий: отправляет сообщение (evidence: `src/index.js`)
- Обработка событий → Маршрутизация диалога: передаёт событие (evidence: `src/index.js`)
- Маршрутизация диалога → AI-оркестрация: запрашивает анализ (evidence: `src/core/logic.js`)
- Маршрутизация диалога → Временные сообщения: обрабатывает временные (evidence: `src/core/logic.js`)
- Маршрутизация диалога → Профили и архивы: читает и обновляет (evidence: `src/core/logic.js`)
- Маршрутизация диалога → Разбор документов: разбирает документы (evidence: `src/core/logic.js`)
- Маршрутизация диалога → Разбор времени: разбирает напоминание (evidence: `src/core/logic.js`)
- AI-оркестрация → Промпты и модели: собирает запросы (evidence: `src/services/ai.js`)
- AI-оркестрация → Профили и архивы: учитывает статистику (evidence: `src/services/ai.js`)
- AI-оркестрация → Поиск и проверка: проводит исследование (evidence: `src/services/ai.js`)
- Поиск и проверка → Tavily / Perplexity / Google: ищет и читает (evidence: `README.md`)
- AI-оркестрация → OpenAI-compatible / Gemini: запрашивает модели (evidence: `src/services/ai.js`)
- Маршрутизация диалога → Распознавание и сводка: обрабатывает речь (evidence: `src/core/logic.js`)
- AI-оркестрация → Распознавание и сводка: распознаёт аудио (evidence: `src/services/ai.js`)
- AI-оркестрация → Субтитры YouTube: разбирает ролики (evidence: `src/services/ai.js`)
- AI-оркестрация → Видео через Gemini: использует видеоанализ (evidence: `src/services/ai.js`)
- Видео через Gemini → Субтитры YouTube: получает данные ролика (evidence: `src/services/youtube-gemini.js`)
- Маршрутизация диалога → Приватный контекст: использует приватный режим
- Обработка событий → Доставка напоминаний: создаёт доставку (evidence: `src/index.js`)
- Доставка напоминаний → Форматирование сообщений: оформляет уведомление (evidence: `src/services/reminder-delivery.js`)
- Маршрутизация диалога → Форматирование сообщений: оформляет ответ (evidence: `src/core/logic.js`)
- Форматирование сообщений → Telegram Bot API: отправляет форматированный текст (evidence: `src/utils/rich.js`)
- Telegram Bot API → Получатель в Telegram: доставляет ответ (evidence: `README.md`)
