second-mind-aep/Telegram бот для Obsidian.md

1. Обзор системы

1.1 Назначение

Система представляет собой Telegram бота для автоматизации создания и управления заметками в Obsidian с интеграцией в существующий Git + Quartz workflow.

1.2 Ключевые функции

• Создание заметок из текстовых и голосовых сообщений
• Семантический поиск по базе знаний
• Дополнение существующих заметок
• Автоматическое форматирование через GPT
• Интеграция с Git для версионирования
• Автоматическая публикация через Quartz

1.3 Ограничения и допущения

• Один пользователь (личное использование)
• Развертывание на VPS с ограниченными ресурсами
• Интеграция с существующей инфраструктурой Git + Quartz
• Приоритет простоты разработки над масштабируемостью

2. Архитектурные решения

2.1 Выбор архитектурного стиля: Модульный монолит

Обоснование:

• Простота разработки и развертывания
• Оптимальное использование ресурсов VPS
• Быстрая итерация для единственного пользователя
• Легкость отладки и мониторинга

Альтернативы рассмотренные:

• Микросервисная архитектура (отклонена из-за избыточной сложности)
• Serverless функции (отклонена из-за холодного старта и ограничений по времени)

2.2 Технологический стек

Основной язык: Go 1.21+

• Высокая производительность
• Простое развертывание (единый бинарник)
• Отличная поддержка конкурентности
• Богатая экосистема для Telegram ботов

Ключевые зависимости:

• telegram-bot-api/v5 - Telegram Bot API
• go-openai - OpenAI API интеграция
• go-git/v5 - Git операции
• viper - конфигурация
• logrus - структурированное логирование

Внешние сервисы:

• OpenAI API (GPT-4, Whisper)
• Telegram Bot API
• Векторная база данных (Qdrant/Chroma)

3. Архитектура системы

3.1 Общая диаграмма системы

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Telegram      │    │                 │    │   External      │
│   User          │◄──►│   Monolithic    │◄──►│   Services      │
│                 │    │   Bot App       │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                        │
                              ▼                        ├─ OpenAI API
                    ┌─────────────────┐                ├─ Vector DB
                    │   File System   │                └─ Telegram API
                    │                 │
                    ├─ Obsidian Vault │
                    ├─ Git Repository │
                    └─ Vector Index   │
                              │
                              ▼
                    ┌─────────────────┐
                    │   Git Hooks     │
                    │                 │
                    └─ Quartz Rebuild │

3.2 Компонентная диаграмма

┌─────────────────────────────────────────────────────────┐
│                    Monolithic Application                │
│                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Bot       │  │   HTTP      │  │   CLI       │     │
│  │   Handler   │  │   Server    │  │   Tools     │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│         │                 │                 │           │
│         └─────────────────┼─────────────────┘           │
│                           │                             │
│  ┌─────────────────────────┼─────────────────────────┐   │
│  │              Business Logic Layer                │   │
│  │                         │                       │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────┐ │   │
│  │  │   Note      │  │   Search    │  │   Voice   │ │   │
│  │  │   Service   │  │   Service   │  │   Service │ │   │
│  │  └─────────────┘  └─────────────┘  └───────────┘ │   │
│  │         │                 │                │     │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────┐ │   │
│  │  │   LLM       │  │   File      │  │   Git     │ │   │
│  │  │   Service   │  │   Service   │  │   Service │ │   │
│  │  └─────────────┘  └─────────────┘  └───────────┘ │   │
│  └─────────────────────┼─────────────────────────────┘   │
│                        │                                 │
│  ┌─────────────────────┼─────────────────────────────┐   │
│  │              Infrastructure Layer              │   │
│  │                     │                         │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────┐ │   │
│  │  │   Config    │  │   Logger    │  │   Cache   │ │   │
│  │  │   Manager   │  │             │  │           │ │   │
│  │  └─────────────┘  └─────────────┘  └───────────┘ │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

3.3 Диаграмма потоков данных

User Message Flow:
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Telegram   │───►│   Bot       │───►│   Router    │
│  Message    │    │  Handler    │    │             │
└─────────────┘    └─────────────┘    └─────────────┘
                                             │
                   ┌─────────────────────────┼─────────────────────────┐
                   ▼                         ▼                         ▼
           ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
           │   Create    │          │   Search    │          │   Append    │
           │   Note      │          │   Notes     │          │   Note      │
           └─────────────┘          └─────────────┘          └─────────────┘
                   │                         │                         │
                   ▼                         │                         ▼
           ┌─────────────┐                   │                ┌─────────────┐
           │   Format    │                   │                │   Find &    │
           │   with GPT  │                   │                │   Update    │
           └─────────────┘                   │                └─────────────┘
                   │                         │                         │
                   ▼                         │                         ▼
           ┌─────────────┐          ┌─────────────┐          ┌─────────────┐
           │   Save      │          │   Vector    │          │   Save      │
           │   File      │          │   Search    │          │   File      │
           └─────────────┘          └─────────────┘          └─────────────┘
                   │                         │                         │
                   └─────────────────────────┼─────────────────────────┘
                                             ▼
                                   ┌─────────────┐
                                   │   Git       │
                                   │   Commit    │
                                   └─────────────┘
                                             │
                                             ▼
                                   ┌─────────────┐
                                   │   Quartz    │
                                   │   Rebuild   │
                                   └─────────────┘

4. Детальное описание компонентов

4.1 Presentation Layer

Bot Handler

• Ответственность: Обработка Telegram API, маршрутизация команд
• Интерфейсы: Telegram Bot API
• Зависимости: Router, Context Manager

HTTP Server (опциональный)

• Ответственность: Health checks, метрики, webhook endpoint
• Интерфейсы: HTTP REST API
• Зависимости: Monitoring tools

4.2 Business Logic Layer

Note Service

• Ответственность: Создание, обновление заметок, управление жизненным циклом
• Интерфейсы: Note CRUD операции
• Зависимости: LLM Service, File Service, Git Service

Search Service

• Ответственность: Векторный поиск, индексация, семантический анализ
• Интерфейсы: Search API, Indexing API
• Зависимости: Vector Database, Embedding Service

Voice Service

• Ответственность: Обработка голосовых сообщений, транскрипция
• Интерфейсы: Audio processing API
• Зависимости: Whisper API, File Service

LLM Service

• Ответственность: Интеграция с GPT, форматирование, генерация контента
• Интерфейсы: Text processing API
• Зависимости: OpenAI API

4.3 Infrastructure Layer

File Service

• Ответственность: Файловые операции, управление Obsidian vault
• Интерфейсы: File system operations
• Зависимости: OS file system

Git Service

• Ответственность: Version control, автоматические коммиты
• Интерфейсы: Git operations API
• Зависимости: Git repository

5. Интеграционная архитектура

5.1 Внешние интеграции

OpenAI API

• Назначение: GPT-4 для форматирования, Whisper для транскрипции
• Протокол: HTTPS REST API
• Аутентификация: API Key
• Обработка ошибок: Retry with exponential backoff

Telegram Bot API

• Назначение: Получение сообщений, отправка ответов
• Протокол: HTTPS REST API / WebHooks
• Аутентификация: Bot Token
• Режим работы: Long polling (рекомендуется для VPS)

Vector Database

• Назначение: Семантический поиск по заметкам
• Варианты: Qdrant (HTTP API) или Chroma (HTTP API)
• Протокол: HTTPS REST API
• Данные: Embeddings + метаданные заметок

5.2 Файловая система

Obsidian Vault Structure

vault/
├── notes/              # Основные заметки
├── daily/              # Ежедневные заметки
├── templates/          # Шаблоны
├── attachments/        # Медиа файлы
└── .obsidian/          # Конфигурация Obsidian

Git Integration

• Автоматические коммиты после каждого изменения
• Meaningful commit messages
• Direct push в main branch
• Git hooks для триггера Quartz rebuild

6. Данные и хранение

6.1 Модель данных

Note Entity

Note {
    ID: UUID
    Title: string
    Content: string (Markdown)
    Filename: string
    Created: timestamp
    Updated: timestamp
    Tags: []string
    Links: []string
    Embedding: []float32
}

User Context

UserContext {
    UserID: int64
    State: enum (idle, creating_note, appending, searching)
    Data: map[string]interface{}
    LastActivity: timestamp
}

6.2 Хранение данных

Файловая система

• Obsidian заметки: Markdown файлы в vault directory
• Конфигурация: .env файл или environment variables
• Логи: Rotated log files или stdout для containerized deployment

Временное хранение

• User contexts: In-memory map (single user)
• Cache: In-memory или embedded BoltDB
• Vector embeddings: External vector database

7. Развертывание и операционные аспекты

7.1 Архитектура развертывания

VPS Server
├── Application Binary
├── Configuration Files
├── Obsidian Vault (Git Repository)
├── Vector Database (если локальная)
└── Monitoring & Logs

7.2 Масштабирование

Текущие ограничения:

• Один пользователь
• Один экземпляр приложения
• Локальные файловые операции

Возможности роста:

• Horizontal scaling: добавление Redis для shared state
• Vertical scaling: увеличение ресурсов VPS
• Service extraction: выделение vector search в отдельный сервис

7.3 Мониторинг и наблюдаемость

Логирование:

• Structured logging (JSON format)
• Log levels: ERROR, WARN, INFO, DEBUG
• Log rotation для экономии места

Метрики:

• Application health status
• Message processing time
• OpenAI API response times
• Git operation success/failure rates

Алерты:

• Application down
• High error rate
• OpenAI API quota exceeded
• Git push failures

8. Безопасность

8.1 Аутентификация и авторизация

• Telegram User ID whitelist (только владелец)
• API keys в environment variables
• No public endpoints кроме Telegram webhook

8.2 Защита данных

• API keys не в коде
• Логи не содержат sensitive данные
• HTTPS для всех внешних API calls
• Git repository может быть private

9. Качественные атрибуты

9.1 Производительность

• Время отклика бота: < 2 секунды для текстовых сообщений
• Время создания заметки: < 5 секунд включая GPT обработку
• Голосовые сообщения: < 10 секунд для транскрипции и создания заметки

9.2 Надежность

• Graceful degradation при недоступности OpenAI API
• Retry mechanisms для внешних API
• Data consistency через atomic git operations

9.3 Maintainability

• Четкое разделение ответственности между слоями
• Интерфейсы для всех основных компонентов
• Comprehensive logging для отладки
• Configuration management через environment variables

10. Риски и ограничения

10.1 Технические риски

• OpenAI API limits: Rate limiting может замедлить обработку
• Vector DB performance: Поиск может замедляться с ростом количества заметок
• VPS resources: Ограниченная память и CPU для vector operations

10.2 Операционные риски

• Single point of failure: Монолитная архитектура
• Manual deployment: Отсутствие автоматизированного CI/CD
• Backup dependency: Зависимость от Git для backup заметок

10.3 Митигация рисков

• Monitoring и alerting для раннего обнаружения проблем
• Регулярные backups Git repository
• Graceful fallbacks при недоступности внешних сервисов
• Resource monitoring для предотвращения исчерпания ресурсов VPS