docs: add architecture and incident runbooks

2026-09-13 09:19:46 +07:00
parent c6ffded8d7
commit 6aaee107a9
4 changed files with 65 additions and 1 deletions
@@ -0,0 +1,17 @@
+# Архитектурные решения
+
+## ADR-001 · Astro + FastAPI + PostgreSQL
+
+Статус: принято. Astro отвечает за быстрый SSR-интерфейс и SEO, FastAPI — за типизированный API и фоновые операции, PostgreSQL — за канонические данные, блокировки и миграции. Next.js/Vinext не вводятся: второй web-runtime усложнит сборку, кэш и эксплуатацию без пользы для текущего продукта.
+
+## ADR-002 · Локальный cache API
+
+Статус: принято для одного API-процесса. Публичная активность хранится в ограниченном memory-cache 20 секунд и инвалидируется после изменений в том же процессе. Данные scheduler могут появиться с задержкой до TTL. Redis нужен только при нескольких API-процессах или измеренной проблеме; до этого он создаёт лишнюю stateful-зависимость.
+
+## ADR-003 · Отдельный scheduler и общий cooldown
+
+Статус: принято. Scheduler отделён от HTTP API, а попытка импорта резервируется в PostgreSQL до сетевого запроса. Endpoint одной площадки делят минимальный интервал 30 минут; ошибка также расходует окно, повторные ошибки увеличивают паузу до 24 часов. Ручной production-запуск проходит через тот же журнал, чтобы не обходить лимит.
+
+## ADR-004 · PostgreSQL и MinIO как разные контуры данных
+
+Статус: принято. Метаданные и moderation state хранятся в PostgreSQL; бинарные скриншоты — в MinIO под отдельными минимальными credentials. База не содержит большие изображения, а API не получает root-доступ к object storage. Backup считается полноценным только при согласованном сохранении обоих контуров и проверенном restore.