# Технологический стек

**Дата:** 2026-03-21
**Статус:** Согласовано

---

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

```
┌─────────────────────────────────────────────┐
│                   Nginx                     │
│  /         → React SPA (статика)            │
│  /api/     → FastAPI backend                │
└────────────────────┬────────────────────────┘
                     │ Docker network
          ┌──────────┴──────────┐
          │                     │
    ┌─────▼──────┐       ┌──────▼─────┐
    │  FastAPI   │       │  React SPA │
    │  (backend) │       │  (frontend)│
    └─────┬──────┘       └────────────┘
          │
    ┌─────▼──────┐
    │ PostgreSQL │
    └────────────┘
```

---

## Backend

| Компонент | Технология | Версия |
|-----------|-----------|--------|
| Язык | Python | 3.12+ |
| Фреймворк | FastAPI | 0.115+ |
| ORM | SQLAlchemy (async) | 2.0+ |
| Миграции | Alembic | latest |
| База данных | PostgreSQL | 16+ |
| Валидация | Pydantic v2 | 2.x |
| Аутентификация | JWT (python-jose) | latest |
| Хэширование паролей | passlib + bcrypt | latest |
| ASGI-сервер | Uvicorn | latest |

### Почему FastAPI
- Автоматическая генерация OpenAPI/Swagger документации — джуниор сразу видит API
- Async из коробки — правильные привычки с первого проекта
- Pydantic-схемы = валидация + сериализация в одном месте
- Активное сообщество, отличная документация на русском

---

## Frontend

| Компонент | Технология | Версия |
|-----------|-----------|--------|
| Фреймворк | React | 18+ |
| Язык | TypeScript | 5.x |
| Сборщик | Vite | 5.x |
| UI-библиотека | Ant Design (antd) | 5.x |
| Роутинг | React Router | v6 |
| Серверный стейт | TanStack Query (React Query) | v5 |
| HTTP-клиент | Axios | latest |

### Почему Ant Design
- Готовые компоненты: таблицы, формы, прогрессбары, таймеры — сэкономит спринты
- Хорошо подходит для административных интерфейсов
- Поддержка русской локализации

### Почему TanStack Query
- Учит джуниора правильной работе с серверным состоянием
- Кэширование, loading/error состояния, инвалидация — всё из коробки
- Убирает необходимость в Redux для большинства задач

---

## Инфраструктура

| Компонент | Технология |
|-----------|-----------|
| Контейнеризация | Docker + Docker Compose |
| Реверс-прокси | Nginx |
| ОС сервера | Linux (Ubuntu/Debian) |

### Структура Docker Compose

```yaml
services:
  db:        # PostgreSQL
  backend:   # FastAPI + Uvicorn
  frontend:  # React (build) / Vite dev server
  nginx:     # Reverse proxy
```

---

## Инструменты разработки

| Назначение | Инструмент |
|-----------|-----------|
| Линтер Python | Ruff |
| Форматтер Python | Black |
| Линтер/форматтер JS | ESLint + Prettier |
| API-тестирование | Swagger UI (встроен в FastAPI) |

---

## Уведомления (последний спринт)

- Канал: мессенджер **MAX**
- Реализация: отдельный сервис/модуль в backend
- Интеграция: MAX API (изучить документацию перед спринтом)

---

## Вне scope (не используем)

- Redis / очереди задач (Celery) — не нужны для данного масштаба
- GraphQL — REST достаточно
- Kubernetes — Docker Compose достаточно для 50–200 пользователей
- SSR (Next.js) — не нужен, SPA достаточно