telegram-tui/PROJECT_STRUCTURE.md

# Структура проекта

## Обзор директорий

```
tele-tui/
├── .github/                    # GitHub конфигурация
│   ├── ISSUE_TEMPLATE/         # Шаблоны для issue
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   ├── workflows/              # GitHub Actions CI/CD
│   │   └── ci.yml
│   └── pull_request_template.md
│
├── docs/                       # Дополнительная документация
│   └── TDLIB_INTEGRATION.md
│
├── src/                        # Исходный код
│   ├── app/                    # Состояние приложения
│   │   ├── mod.rs
│   │   └── state.rs
│   ├── input/                  # Обработка пользовательского ввода
│   │   ├── mod.rs
│   │   ├── auth.rs
│   │   └── main_input.rs
│   ├── media/                  # Работа с изображениями (PLANNED)
│   │   ├── mod.rs              # Экспорт публичных типов
│   │   ├── image_cache.rs      # LRU кэш для загруженных изображений
│   │   ├── image_loader.rs     # Асинхронная загрузка через TDLib
│   │   └── image_renderer.rs   # Рендеринг изображений в ratatui
│   ├── notifications.rs        # Desktop уведомления
│   ├── tdlib/                  # TDLib интеграция
│   │   ├── mod.rs
│   │   └── client.rs
│   ├── ui/                     # Рендеринг интерфейса
│   │   ├── mod.rs
│   │   ├── auth.rs
│   │   ├── chat_list.rs
│   │   ├── footer.rs
│   │   ├── loading.rs
│   │   ├── main_screen.rs
│   │   └── messages.rs
│   ├── config.rs               # Конфигурация приложения
│   ├── main.rs                 # Точка входа
│   └── utils.rs                # Утилиты
│
├── tdlib_data/                 # TDLib сессия (НЕ коммитится)
├── target/                     # Артефакты сборки (НЕ коммитится)
│
├── .editorconfig               # EditorConfig для IDE
├── .gitignore                  # Git ignore правила
├── Cargo.lock                  # Зависимости (точные версии)
├── Cargo.toml                  # Манифест проекта
├── rustfmt.toml                # Конфигурация форматирования
│
├── config.toml.example         # Пример конфигурации
├── credentials.example         # Пример credentials
│
├── CHANGELOG.md                # История изменений
├── CLAUDE.md                   # Инструкции для Claude AI
├── CONTRIBUTING.md             # Гайд по контрибуции
├── CONTEXT.md                  # Текущий статус разработки
├── DEVELOPMENT.md              # Правила разработки
├── FAQ.md                      # Часто задаваемые вопросы
├── HOTKEYS.md                  # Список горячих клавиш
├── INSTALL.md                  # Инструкция по установке
├── LICENSE                     # MIT лицензия
├── PROJECT_STRUCTURE.md        # Этот файл
├── README.md                   # Главная документация
├── REQUIREMENTS.md             # Функциональные требования
├── ROADMAP.md                  # План развития
└── SECURITY.md                 # Политика безопасности
```

## Исходный код (src/)

### main.rs
**Точка входа приложения**
- Инициализация TDLib клиента
- Event loop (60 FPS)
- Обработка Ctrl+C (graceful shutdown)
- Координация между UI, input и TDLib

### config.rs
**Конфигурация приложения**
- Загрузка/сохранение TOML конфига
- Парсинг timezone и цветов
- Загрузка credentials (приоритетная система)
- XDG directory support

### utils.rs
**Утилитарные функции**
- `disable_tdlib_logs()` — отключение TDLib логов через FFI
- `format_timestamp_with_tz()` — форматирование времени с учётом timezone
- `format_date()` — форматирование дат для разделителей
- `format_datetime()` — полное форматирование даты и времени
- `format_was_online()` — "был(а) X мин. назад"

### app/ — Состояние приложения

#### mod.rs
- `App` struct — главная структура состояния
- `needs_redraw` — флаг для оптимизации рендеринга
- Состояние модалок (delete confirm, reaction picker, profile)
- Состояние поиска и черновиков
- Методы для работы с UI state

#### state.rs
- `AppScreen` enum — текущий экран (Loading, Auth, Main)

### media/ — Работа с изображениями (PLANNED - Фаза 11)

#### image_cache.rs
- `ImageCache` — LRU кэш для загруженных изображений
- Лимит по размеру (MB) с автоматической очисткой
- Хранение как в памяти (DynamicImage), так и на диске (PathBuf)
- MAX_IMAGE_CACHE_SIZE = 100 MB (настраивается в config)

#### image_loader.rs
- `ImageLoader` — асинхронная загрузка изображений через TDLib
- Метод `load_photo(file_id)` — получить изображение из кэша или загрузить
- Метод `download_and_cache(file)` — загрузка через TDLib downloadFile API
- Обработка состояний загрузки (pending/downloading/ready)
- Приоритизация видимых изображений

#### image_renderer.rs
- `ImageRenderer` — рендеринг изображений в ratatui
- Auto-detection протокола терминала (Sixel/Kitty/iTerm2/Halfblocks)
- Автоматическое масштабирование под размер области
- Сохранение aspect ratio
- Fast resize для превью
- Fallback на текстовую заглушку

#### mod.rs
- Экспорт публичных типов
- `PhotoInfo` struct — метаданные изображения (file_id, width, height)
- `TerminalProtocol` enum — поддерживаемые протоколы отображения

### notifications.rs — Desktop уведомления

- `NotificationManager` — управление desktop уведомлениями
- Интеграция с notify-rust для кроссплатформенных уведомлений
- Фильтрация по muted чатам и mentions
- Beautification медиа-типов с emoji
- Настраиваемый timeout и urgency (Linux)

### tdlib/ — Telegram интеграция

#### client.rs
- `TdClient` — обёртка над TDLib
- Авторизация (телефон, код, 2FA)
- Загрузка чатов и сообщений
- Отправка/редактирование/удаление сообщений
- Reply, Forward
- Реакции (`ReactionInfo`)
- LRU кеши (users, statuses)
- `NetworkState` enum

#### mod.rs
- Экспорт публичных типов

### ui/ — Рендеринг интерфейса

#### mod.rs
- `render()` — роутинг по экранам
- Проверка минимального размера терминала (80x20)

#### loading.rs
- Экран "Loading..."

#### auth.rs
- Экран авторизации (ввод телефона, кода, пароля)

#### main_screen.rs
- Главный экран
- Отображение папок сверху

#### chat_list.rs
- Список чатов
- Индикаторы: 📌, 🔇, @, (N)
- Онлайн-статус (●)
- Поиск по чатам

#### messages.rs
- Область сообщений
- Группировка по дате и отправителю
- Markdown форматирование
- Реакции под сообщениями
- Emoji picker modal
- Profile modal
- Delete confirmation modal
- Pinned message
- Динамический инпут
- Блочный курсор

#### footer.rs
- Футер с командами
- Индикатор состояния сети

### input/ — Обработка ввода

#### mod.rs
- Роутинг ввода по экранам

#### auth.rs
- Обработка ввода на экране авторизации

#### main_input.rs
- Обработка ввода на главном экране
- **Важно**: порядок обработчиков имеет значение!
  1. Reaction picker (Enter/Esc)
  2. Delete confirmation
  3. Profile modal
  4. Search в чате
  5. Forward mode
  6. Edit/Reply mode
  7. Message selection
  8. Chat list
- Поддержка русской раскладки

## Конфигурационные файлы

### Cargo.toml
Манифест проекта:
- Metadata (name, version, authors, license)
- Dependencies
- Build dependencies (tdlib-rs)

### rustfmt.toml
Конфигурация `cargo fmt`:
- max_width = 100
- imports_granularity = "Crate"
- Стиль комментариев

### .editorconfig
Универсальные настройки для IDE:
- Unix line endings (LF)
- UTF-8 encoding
- Отступы (4 spaces для Rust)

## Рантайм файлы

### tdlib_data/
Создаётся автоматически TDLib:
- Токены авторизации
- Кеш сообщений и файлов
- **НЕ коммитится** (в .gitignore)
- **НЕ делиться** (содержит чувствительные данные)

### ~/.config/tele-tui/
XDG config directory:
- `config.toml` — пользовательская конфигурация
- `credentials` — API_ID и API_HASH

## Документация

### Пользовательская
- **README.md** — главная страница, overview
- **INSTALL.md** — установка и настройка
- **HOTKEYS.md** — все горячие клавиши
- **FAQ.md** — часто задаваемые вопросы

### Разработчика
- **CONTRIBUTING.md** — как внести вклад
- **DEVELOPMENT.md** — правила разработки
- **PROJECT_STRUCTURE.md** — этот файл
- **ROADMAP.md** — план развития
- **REFACTORING_ROADMAP.md** — план рефакторинга
- **TESTING_ROADMAP.md** — план покрытия тестами
- **CONTEXT.md** — текущий статус, архитектурные решения

### Спецификации
- **REQUIREMENTS.md** — функциональные требования
- **CHANGELOG.md** — история изменений
- **SECURITY.md** — политика безопасности

### Внутренняя
- **CLAUDE.md** — инструкции для AI ассистента
- **docs/TDLIB_INTEGRATION.md** — детали интеграции TDLib

## Ключевые концепции

### Архитектура
- **Event-driven**: TDLib updates → mpsc channel → main loop
- **Unidirectional data flow**: TDLib → App state → UI rendering
- **Modal stacking**: приоритет обработки ввода для модалок

### Оптимизации
- **needs_redraw**: рендеринг только при изменениях
- **LRU caches**: user_names, user_statuses (500 записей)
- **Limits**: 500 messages/chat, 200 chats
- **Lazy loading**: users загружаются батчами (5 за цикл)

### Состояние
```
App {
  screen: AppScreen,
  config: Config,
  needs_redraw: bool,

  // TDLib state
  chats: Vec<Chat>,
  folders: Vec<Folder>,

  // UI state
  selected_chat_id: Option<i64>,
  input_text: String,
  cursor_position: usize,

  // Modals
  is_delete_confirmation: bool,
  is_reaction_picker_mode: bool,
  profile_info: Option<ProfileInfo>,
  view_image_mode: Option<ViewImageState>,  // PLANNED - Фаза 11

  // Search
  search_query: String,
  search_results: Vec<i64>,

  // Drafts
  drafts: HashMap<i64, String>,

  // Media (PLANNED - Фаза 11)
  image_loader: ImageLoader,
  image_protocol: StatefulProtocol,  // Terminal capabilities
}
```

## Потоки выполнения

### Main thread
- Event loop (16ms tick для 60 FPS)
- UI rendering
- Input handling
- App state updates

### TDLib thread
- `td_client.receive()` в отдельном Tokio task
- Updates отправляются через `mpsc::channel`
- Неблокирующий для main thread

### Blocking operations
- Загрузка конфига (при запуске)
- Авторизация (блокирует до ввода кода)
- Graceful shutdown (2 sec timeout)

## Зависимости

### UI
- `ratatui` 0.29 — TUI framework
- `crossterm` 0.28 — terminal control
- `ratatui-image` 1.0 — отображение изображений в TUI (PLANNED)

### Media (PLANNED)
- `image` — загрузка и обработка изображений
- `ratatui-image` — рендеринг в ratatui с поддержкой Sixel/Kitty/iTerm2

### Notifications
- `notify-rust` 4.11 — desktop уведомления (feature flag)

### Telegram
- `tdlib-rs` 1.1 — TDLib bindings
- `tokio` 1.x — async runtime

### Data
- `serde` + `serde_json` 1.0 — serialization
- `toml` 0.8 — config parsing
- `chrono` 0.4 — date/time

### System
- `dirs` 5.0 — XDG directories
- `arboard` 3.4 — clipboard
- `open` 5.0 — открытие URL/файлов
- `dotenvy` 0.15 — .env файлы

## Workflow разработки

1. Изучить [ROADMAP.md](ROADMAP.md) — понять текущую фазу
2. Прочитать [DEVELOPMENT.md](DEVELOPMENT.md) — правила работы
3. Изучить [CONTEXT.md](CONTEXT.md) — архитектурные решения
4. Найти issue или создать новую фичу
5. Создать feature branch
6. Внести изменения
7. `cargo fmt` + `cargo clippy`
8. Протестировать вручную
9. Создать PR с описанием

## CI/CD

### GitHub Actions (.github/workflows/ci.yml)
- **Check**: `cargo check`
- **Format**: `cargo fmt --check`
- **Clippy**: `cargo clippy`
- **Build**: для Ubuntu, macOS, Windows

Запускается на:
- Push в `main` или `develop`
- Pull requests

## Безопасность

### Чувствительные файлы (в .gitignore)
- `.env`
- `credentials`
- `config.toml` (если в корне проекта)
- `tdlib_data/`
- `target/`

### Рекомендации
- Credentials в `~/.config/tele-tui/credentials`
- Права доступа: `chmod 600 ~/.config/tele-tui/credentials`
- Никогда не коммитить `tdlib_data/`