second-mind-aep/💡 Идеи/💡 Проекты/Obsidian телеграм бот/Telegram бот для Obsidian.md

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

1.1 Назначение

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

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

• Создание заметок из текстовых и голосовых сообщений
• Семантический поиск по базе знаний
• Дополнение существующих заметок
• Автоматическое форматирование через YandexGPT
• Интеграция с 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
• yandexcloud-sdk-go - YandexGPT API интеграция
• go-git/v5 - Git операции
• viper - конфигурация
• logrus - структурированное логирование

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

• YandexGPT API (YandexGPT Lite/Pro, SpeechKit для голоса)
• Telegram Bot API
• Векторная база данных (Qdrant/Chroma)

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

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

graph TB
    A[Telegram User] --> B[Monolithic Bot App]
    B --> A
    B --> C[External Services]
    C --> B
    
    subgraph "External Services"
        D[YandexGPT API]
        E[Vector DB]
        F[Telegram API]
    end
    
    B --> G[File System]
    
    subgraph "File System"
        H[Obsidian Vault]
        I[Git Repository]
        J[Vector Index]
    end
    
    G --> K[Git Hooks]
    K --> L[Quartz Rebuild]
    
    C --> D
    C --> E
    C --> F

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

graph TB
    subgraph "Monolithic Application"
        A[Bot Handler]
        B[HTTP Server]
        C[CLI Tools]
        
        subgraph "Business Logic Layer"
            D[Note Service]
            E[Search Service]
            F[Voice Service]
            G[LLM Service]
            H[File Service]
            I[Git Service]
        end
        
        subgraph "Infrastructure Layer"
            J[Config Manager]
            K[Logger]
            L[Cache]
        end
    end
    
    A --> D
    A --> E
    A --> F
    B --> D
    B --> E
    B --> F
    C --> D
    C --> E
    C --> F
    
    D --> G
    D --> H
    D --> I
    E --> G
    E --> H
    F --> G
    F --> H
    
    G --> J
    H --> J
    I --> J
    G --> K
    H --> K
    I --> K

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

graph TB
    A[Telegram Message] --> B[Bot Handler]
    B --> C[Router]
    
    C --> D[Create Note]
    C --> E[Search Notes]
    C --> F[Append Note]
    
    D --> G[Format with YandexGPT]
    F --> H[Find & Update]
    
    G --> I[Save File]
    E --> J[Vector Search]
    H --> I
    
    I --> K[Git Commit]
    J --> K
    
    K --> L[Quartz Rebuild]
    
    subgraph "Message Processing"
        A
        B
        C
    end
    
    subgraph "Note Operations"
        D
        E
        F
    end
    
    subgraph "Processing"
        G
        H
        J
    end
    
    subgraph "Storage"
        I
        K
        L
    end

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
• Зависимости: Yandex SpeechKit API, File Service

LLM Service

• Ответственность: Интеграция с YandexGPT, форматирование, генерация контента
• Интерфейсы: Text processing API
• Зависимости: YandexGPT 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 Внешние интеграции

YandexGPT API

• Назначение: YandexGPT Lite/Pro для форматирования, SpeechKit для транскрипции
• Протокол: HTTPS REST API
• Аутентификация: API Key (IAM токен)
• Обработка ошибок: Retry with exponential backoff
• Модели: yandexgpt-lite, yandexgpt-pro

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
• YandexGPT API response times
• Git operation success/failure rates

Алерты:

• Application down
• High error rate
• YandexGPT 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 секунд включая YandexGPT обработку
• Голосовые сообщения: < 10 секунд для транскрипции и создания заметки

9.2 Надежность

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

9.3 Maintainability

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

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

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

• YandexGPT 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

11. Конфигурация YandexGPT

11.1 API Ключи и аутентификация

• IAM Token: Основной способ аутентификации для YandexGPT API
• API Key: Альтернативный способ для некоторых сервисов
• Folder ID: Идентификатор каталога в Yandex Cloud

11.2 Модели YandexGPT

• yandexgpt-lite: Быстрая модель для базового форматирования
• yandexgpt-pro: Продвинутая модель для сложных задач
• speechkit: Для обработки голосовых сообщений

11.3 Переменные окружения

YANDEX_API_KEY=your_api_key
YANDEX_FOLDER_ID=your_folder_id
YANDEX_IAM_TOKEN=your_iam_token
TELEGRAM_BOT_TOKEN=your_bot_token
VAULT_PATH=/path/to/obsidian/vault