## 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