## 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 Общая диаграмма системы

```mermaid
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 Компонентная диаграмма

```mermaid
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 Диаграмма потоков данных

```mermaid
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
```