first commit

docs/architecture/adr/000-template.md

@@ -0,0 +1,54 @@
+# Шаблон ADR
+
+## Заголовок
+[Краткое название архитектурного решения]
+
+## Статус
+[PROPOSED | ACCEPTED | DEPRECATED | SUPERSEDED]
+
+## Контекст
+Опишите проблему, которая мотивирует это решение. Укажите значимые факты:
+- Почему это решение нужно?
+- Какие ограничения или требования применимы?
+- Какие альтернативы рассматривались?
+
+## Решение
+Сформулируйте принятое решение чётко и кратко.
+
+## Последствия
+Опишите результаты и следствия этого решения:
+- **Плюсы:** выгоды, улучшения
+- **Минусы:** компромиссы, риски
+- **Нейтрально:** изменения, которые не хороши и не плохи
+
+## Ссылки
+- Связанные ADR (если есть)
+- Внешняя документация или стандарты
+- Файлы кода, реализующие это решение
+
+---
+
+## Пример: ADR-001 Использование UUID как первичного ключа
+
+### Статус
+ACCEPTED
+
+### Контекст
+VidConf требует глобально уникальных идентификаторов для распределённых операций и будущего шардирования.
+- Генерация UUID в PostgreSQL быстрая (через `gen_random_uuid()`)
+- Не требует центральной нумерации
+- Поддерживает репликацию без координации
+
+### Решение
+Все таблицы используют `UUID` (версия 4) как первичный ключ, генерируемый на сервере через `gen_random_uuid()`.
+Исключения: `phrases` и `chat_messages` используют `BIGINT IDENTITY` для высокочастотных вставок.
+
+### Последствия
+- **Плюс:** уникальность на всех инстансах; не требует глобальной координации
+- **Плюс:** поддерживает будущие распределённые архитектуры
+- **Минус:** больший размер индекса (16 байт против 8 у BIGINT)
+- **Нейтрально:** требует явной поддержки типа UUID в ORM
+
+### Ссылки
+- `backend/models/*.py` — все модели используют `Mapped[uuid.UUID]`
+- `backend/alembic/versions/1e2e34a0cb06_initial_schema.py` — миграция