yaru.nixg.ru/docs/backend

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, или оба варианта?
• Нужна ли модерация контента (админ-панель)?