telepost/architecture.md

# Архитектура приложения TelePost Clone

## 1. Общая архитектура системы

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │◄──►│    Backend       │◄──►│  External APIs  │
│ (SvelteKit)    │    │   (FastAPI)      │    │ (Telegram, MAX) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                       ┌──────────────────┐
                       │   PostgreSQL     │
                       │                  │
                       │   Redis (queue) │
                       └──────────────────┘
```

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

```
telepost-clone/
├── backend/                 # FastAPI приложение
│   ├── app/
│   │   ├── api/            # API маршруты
│   │   ├── models/         # ORM модели
│   │   ├── schemas/        # Pydantic схемы
│   │   ├── services/       # Бизнес-логика
│   │   ├── database/       # Настройки базы данных
│   │   ├── auth/           # Аутентификация
│   │   ├── integrations/   # Интеграции с внешними сервисами
│   │   └── utils/          # Утилиты
│   ├── migrations/         # Миграции базы данных
│   ├── tests/              # Тесты
│   └── requirements.txt    # Зависимости
├── frontend/               # SvelteKit приложение
│   ├── src/
│   │   ├── routes/         # Страницы
│   │   ├── components/     # Компоненты
│   │   ├── lib/            # Библиотеки
│   │   ├── stores/         # Svelte stores
│   │   └── app.html        # Базовый шаблон
│   ├── static/             # Статические файлы
│   └── package.json        # Зависимости
├── docs/                   # Документация
└── docker-compose.yml      # Оркестрация
```

## 3. Подробное описание компонентов

### 3.1. Бэкенд (FastAPI)

**Основные модули:**

- **Auth module**: Telegram Login Widget с проверкой аутентичности
- **Posts module**: CRUD операции для постов, работа с черновиками
- **Channels module**: Управление Telegram-каналами
- **Integrations module**: Подключение и управление внешними платформами
- **Publications module**: Планирование и выполнение публикаций
- **Media module**: Загрузка и обработка медиафайлов

### 3.2. Фронтенд (SvelteKit)

**Основные страницы:**

- `/login` - Страница входа через Telegram
- `/dashboard` - Главная панель управления
- `/posts` - Список постов
- `/posts/new` - Создание нового поста
- `/posts/[id]/edit` - Редактирование поста
- `/channels` - Управление каналами
- `/integrations` - Подключение интеграций
- `/history` - История публикаций

### 3.3. База данных (PostgreSQL)

**Основные таблицы:**

- `users`: Информация о пользователях
- `channels`: Привязанные Telegram-каналы
- `posts`: Созданные посты
- `integrations`: Настроенные интеграции
- `publications`: История публикаций
- `media_files`: Загруженные медиафайлы

## 4. Потоки работы
### 4.1. Аутентификация

```
1. Пользователь переходит на /login
2. Нажимает кнопку "Войти через Telegram"
3. Telegram возвращает данные пользователя
4. Приложение проверяет подлинность данных
5. Создается/обновляется запись пользователя
6. Генерируется JWT-токен
7. Пользователь перенаправляется в панель управления
```

### 4.2. Создание и публикация поста
```text
1. Пользователь создает новый пост
2. Пользователь выбирает каналы для публикации
3. Пользователь может назначить время публикации
4. Пост сохраняется в базе данных
5. Если время публикации в будущем - задача помещается в очередь
6. При наступлении времени публикации:
   - Формируется сообщение под формат каждого канала
   - Отправляется в соответствующие интеграции
   - Результат сохраняется в истории публикаций
```

## 5. Технические особенности

### 5.1. Безопасность
- Проверка аутентичности данных от Telegram
- Валидация всех входных данных
- Защита от XSS и CSRF атак
- Хранение чувствительных данных в зашифрованном виде

### 5.2. Масштабируемость
- Использование очередей задач для фоновых операций
- Кэширование частых запросов
- Оптимизация SQL-запросов

### 5.3. Надежность
- Обработка ошибок и повторные попытки отправки
- Логирование всех действий
- Мониторинг статуса публикаций

## 6. Особенности реализации

### 6.1. Визуальный редактор
Для редактирования постов будет использован современный WYSIWYG редактор, поддерживающий:
- Форматирование текста
- Вставку изображений и видео
- Добавление опросов
- Работу с альбомами

### 6.2. Поддержка различных типов контента
- Текстовые посты
- Медиафайлы (фото, видео, документы)
- Альбомы
- Опросы
- Видеосообщения
- Специальные элементы (реакции, закрепление)

### 6.3. Интеграции
- Telegram (основная платформа)
- MAX (как пример внешней интеграции)
- Возможность легко добавлять новые интеграции

## 7. План реализации MVP

1. **Этап 1**: Базовая аутентификация и структура приложения
2. **Этап 2**: Создание и редактирование постов
3. **Этап 3**: Публикация в Telegram
4. **Этап 4**: Добавление интеграции с внешней платформой
5. **Этап 5**: Расширенные функции (планирование, история, черновики)