# Qadam Platform — архитектурные решения

## Паспорт документа

- Статус документа: working spec
- Актуально на: 28 марта 2026 года
- Владелец: backend/platform-команда
- Пересмотр: при изменении платформенной архитектуры, roadmap или статуса реализации
- Область применения: канонические платформенные spec-документы для текущего ядра Qadam
- Связанные документы:
  - [Текущее состояние](../../docs/project/current-state.md)
  - [Roadmap](../../docs/project/roadmap.md)
  - [Индекс документации](../../docs/README.md)

## ADR-001: Хранение JWT в `httpOnly` cookies

### Контекст

Токены в `localStorage` создают лишний XSS-риск и усложняют безопасную серверную работу в Next.js.

### Решение

Access token и refresh token хранятся в `httpOnly` cookies.

### Последствия

- Frontend не читает токены напрямую.
- Проверка авторизации идёт через `GET /auth/me`.
- Нужна корректная настройка cookies, CORS и SSR.

## ADR-002: Refresh token rotation с `jti`

### Контекст

Простой долгоживущий refresh token плохо защищает от повторного использования и кражи.

### Решение

Refresh token содержит `jti`. Активные `jti` хранятся в Redis. При refresh токен одноразово потребляется, а семейство токенов может быть отозвано при подозрении на reuse.

### Последствия

- Нужна инфраструктура хранения в Redis.
- Старые refresh token без `jti` должны считаться устаревшими после соответствующего деплоя.
- Unit-тесты auth-слоя должны учитывать новую модель.

## ADR-003: Next.js App Router и SSR как базовая модель для публичных страниц

### Контекст

Каталог, карточки айтемов и публичные страницы продавцов должны быть пригодны для SEO и быстро отдаваться из сервера.

### Решение

Использовать Next.js App Router, Server Components и SSR как основную модель для публичной части.

### Последствия

- Данные для публичных страниц грузятся на сервере.
- Client Components используются только там, где действительно нужна интерактивность.
- Нужно следить за корректной hydration-моделью и сериализацией.

## ADR-004: Общие схемы в `packages/shared`

### Контекст

Валидация не должна расходиться между frontend и backend.

### Решение

Общие DTO и Zod-схемы живут в `packages/shared`.

### Последствия

- Один источник истины для валидации.
- Backend и frontend используют одинаковые контракты.
- Изменение поля начинается с общей схемы, а не с локальных DTO.

## ADR-005: Канонический production deploy на текущем сервере — host runtime, а не Docker runtime

### Контекст

В репозитории есть Docker-контур, но фактический production на текущем сервере запущен через `systemd`, `nginx`, PostgreSQL и Redis на хосте.

### Решение

До отдельного пересмотра канонической считается именно host-level модель деплоя.

### Последствия

- Источником истины по эксплуатации становится `docs/operations/deployment-runbook.md`.
- Docker-скрипты считаются legacy и требуют ревизии перед любым использованием в production.
- Любые изменения инфраструктуры должны сначала отражаться в хостовом runbook.

## ADR-006: Отдельный защищённый портал документации на поддомене

### Контекст

Команде нужен быстрый доступ к roadmap, требованиям, текущему состоянию и markdown-документам прямо с сервера.

### Решение

Поднять `qadam-roadmap.2fab.app`, закрыть его `basic auth`, вынести runtime в отдельный standalone docs-service и читать канонические markdown-документы из `qadam-core/docs` с поддержкой переходов в связанные `specs` и `docs/Agents`.

### Последствия

- Команда работает с живыми файлами, а не с экспортами или копиями.
- Портал можно использовать как внутреннюю рабочую поверхность для документации.
- Требуется отдельное сопровождение basic auth, upload/delete/comment механики, отдельного runtime/unit и TLS.