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

## Стек технологий

| Компонент | Технология | Примечание |
|-----------|------------|------------|
| Язык | Python 3.11+ | |
| Фреймворк | FastAPI | Асинхронный, автодокументация |
| База данных | PostgreSQL 15+ | Основная БД |
| Кэш | PostgreSQL + pg_redis | Или Redis через extension |
| Очереди | PostgreSQL + pgqueue | Или Celery + Redis |
| ORM | SQLAlchemy 2.0 + Async | Асинхронная работа |

---

## Архитектура сервера

```
┌─────────────────────────────────────────────────────────┐
│                      FastAPI App                        │
├─────────────┬─────────────┬─────────────┬───────────────┤
│   REST API  │ ActivityPub │   Auth API  │  Export API   │
│  (лента,    │  (inbox,    │  (OAuth2,   │  (markdown,   │
│  профили)   │  outbox)    │   JWT)      │   медиа)      │
└─────────────┴─────────────┴─────────────┴───────────────┘
                              │
                    ┌─────────▼──────────┐
                    │   PostgreSQL       │
                    │  ───────────────── │
                    │  • pg_redis (кэш)  │
                    │  • pgqueue (очереди)│
                    │  • pg_trgm (поиск)  │
                    └────────────────────┘
```

---

## Требования к бэкенду

### 1. ActivityPub реализация

- [ ] **Inbox** — приём активностей от других серверов
- [ ] **Outbox** — отправка активностей подписчикам
- [ ] **WebFinger** — обнаружение пользователей по @username@domain
- [ ] **Actor** — профиль пользователя в формате ActivityPub
- [ ] **Follow/Unfollow** — подписки между серверами
- [ ] **Create/Update/Delete** — посты и их редактирование
- [ ] **Like/Announce** — лайки и репосты
- [ ] **Mastodon совместимость** — тестирование с mastodon.social

### 2. REST API

- [ ] `/api/v1/accounts` — управление профилем
- [ ] `/api/v1/statuses` — создание/чтение постов
- [ ] `/api/v1/timelines/home` — домашняя лента
- [ ] `/api/v1/timelines/public` — публичная лента
- [ ] `/api/v1/follows` — подписки
- [ ] `/api/v1/karma` — карма пользователя

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

#### Основные таблицы:
- `users` — пользователи (id, username, domain, display_name, bio, karma)
- `posts` — посты (id, user_id, content, content_type, created_at)
- `follows` — подписки (follower_id, following_id, created_at)
- `likes` — лайки (user_id, post_id, created_at)
- `media` — медиафайлы (id, user_id, filename, mime_type, size)
- `activities` — ActivityPub активности (id, type, actor, object, timestamp)

#### PostgreSQL расширения:
- `pg_trgm` — полнотекстовый поиск по постам
- `pg_redis` — кэширование лент
- `pgqueue` — фоновые задачи (отправка активностей)

### 4. Экспорт контента

**Требование**: Пользователь может экспортировать весь свой контент в виде:

```
export_username_2026-03-01/
├── profile.md              # Информация о профиле
├── posts/
│   ├── 2026-03-01_post-123.md
│   ├── 2026-03-02_post-124.md
│   └── ...
├── media/
│   ├── image-001.png
│   ├── image-002.jpg
│   └── ...
└── manifest.json           # Структура экспорта
```

- [ ] Формат постов — Markdown с frontmatter (дата, теги, карма)
- [ ] Медиа — оригинальные файлы с переименованием
- [ ] Manifest — JSON со списком всех файлов и метаданными
- [ ] API endpoint: `GET /api/v1/export/@username`

### 5. Аутентификация

- [ ] OAuth2 + JWT токены
- [ ] Поддержка Application Passwords для клиентов
- [ ] Сессии с возможностью отзыва

### 6. Карма

- [ ] Механизм начисления/списания кармы
- [ ] Защита от накрутки (лимиты, анти-спам)
- [ ] История изменений кармы

---

## План разработки бэкенда

1. [ ] Настройка проекта FastAPI + SQLAlchemy
2. [ ] Модели базы данных (users, posts, follows, likes)
3. [ ] REST API (CRUD для постов, профили)
4. [ ] ActivityPub базовая реализация (Actor, Outbox)
5. [ ] ActivityPub полная реализация (Inbox, Federation)
6. [ ] Экспорт контента (Markdown + медиа)
7. [ ] Система кармы
8. [ ] Тестирование совместимости с Mastodon

---

## Вопросы для обсуждения

- [ ] Нужно ли поддерживать совместимость с другими Fediverse-серверами (Pleroma, Pixelfed)?
- [ ] Требуется ли rate limiting на API? Какие лимиты?
- [ ] Как хранить медиа: локально, S3, или оба варианта?
- [ ] Нужна ли модерация контента (админ-панель)?