Канонический набор архитектурных документов проекта. Описывает границы системы, интеграции, контракты API, инфраструктуру, настройки и процесс разработки.

Детальная схема таблиц App DB, правила проверки файлов (file_rules и др.) и OpenAPI-файлы — зона ответственности соответствующих модулей; архитектура задаёт только границы, контракты и общие правила.

Состав документов

Документ	Содержание
`arch-00-glossary.md`	Канонические имена и семантика enum/lifecycle: сущности, поля, id, enum, бакеты S3, env
`arch-01-system-architecture.md`	Общая архитектура: компоненты, сценарии, потоки данных, безопасность
`arch-02-api-contracts.md`	Реестр API-контрактов, realtime, гостевая сессия, OpenAPI, аудит
`arch-03-docker-compose-blueprint.md`	Требования к Docker Compose, сетям и published ports. Детальный контракт nginx — arch-08
`arch-04-settings-and-content.md`	`.env` (infra), таблица `app_settings`, значения service-token переменных, типы файлов
`arch-05-agent-development-process.md`	Правила разработки модулей отдельными агентами
`arch-06-service-hosting-security.md`	Безопасность VM и деплоя: OS-роли, SSH, sudo/systemd, секреты, контейнеры, сеть и lockdown
`arch-07-observability.md`	Контракт наблюдаемости: Collector, JSON-логи, корреляция, redaction, sampling, SLO, SigNoz. Реализация VM — `module-09-observability-vm1.md` / `module-09-observability-vm2.md`
`arch-08-nginx.md`	Контракт корневого nginx: TLS/ACME, request id, internal 404, access log, reload. Реализация VM — `module-03-nginx-vm1.md` / `module-03-nginx-vm2.md`. Сети и ports — arch-03
`arch-09-redis.md`	Контракт Redis: не source of truth, формат ключей, TTL, Lua, AOF/ACL. Реализация VM — `module-04-redis-vm1.md` / `module-04-redis-vm2.md`
`arch-10-deployment.md`	Контракт развёртывания: VPC/SG, PG/S3, роли `deploy`, TLS процедура, cutover. Runbook VM — `module-10-deployment-vm1.md` / `module-10-deployment-vm2.md`. OS-роли — arch-06

Ownership-матрица архитектурных требований

Область	Канонический владелец	Что остаётся в связанных документах
Термины, поля, enum и базовый lifecycle	`arch-00-glossary.md`	Сценарии переходов ссылаются на arch-00 и не переопределяют значения
Границы сервисов и пользовательские сценарии	`arch-01-system-architecture.md`	API, Compose и deployment описывают реализацию этих границ
HTTP/API/realtime контракты	`arch-02-api-contracts.md`	Routing и rollout только ссылаются на endpoint/auth contract
Compose, Docker networks, mounts и published ports	`arch-03-docker-compose-blueprint.md`	arch-06 задаёт security baseline; arch-08 — поведение nginx
Non-secret env, secret references и business settings	`arch-04-settings-and-content.md`	Модули задают schema/validation конкретного потребителя
OS-роли, secret delivery и host/container hardening	`arch-06-service-hosting-security.md`	arch-03 применяет требования в Compose; arch-10 ставит rollout gates
Observability contract	`arch-07-observability.md`	VM module-09 задаёт конкретные pipelines/alerts
Nginx, TLS/ACME, единый `308`, request id и reload	`arch-08-nginx.md`	arch-03 задаёт mounts/ports и сохраняет исключение HTTP webhook ВМ2; VM module-03 — routing matrix
Redis contract	`arch-09-redis.md`	VM module-04 задаёт конкретную карту instances/keys
Provisioning, rollout/cutover, backup/rollback/DR	`arch-10-deployment.md`	Профильный module-10 содержит исполняемые команды и VM-specific gates

Как читать

Начните с arch-01 — общая картина и зафиксированные решения MVP.
При работе с API — arch-02; с Compose/сетями — arch-03; с контрактом nginx — arch-08 и профильная спецификация VM; с Redis — arch-09 и профильная спецификация VM; с настройками — arch-04; с VM, SSH, правами деплоя, секретами и host/container hardening — arch-06; с rollout stages/gates — arch-10 и профильный runbook VM; с telemetry/логами/traces — arch-07 и профильная спецификация VM.
Спорные имена полей, id, enum, бакетов и базовая семантика enum/lifecycle — arch-00. Лимиты и правила реализации остаются в профильных arch-*.
Перед разработкой модуля — arch-05, релевантные разделы arch-01/arch-02 и arch-06, если меняются deployment, сети, volumes, capabilities или секреты. Наблюдаемость сервиса — arch-07 плюс module-09-observability-vm1.md или module-09-observability-vm2.md. Nginx — arch-08 плюс module-03-nginx-vm1.md или module-03-nginx-vm2.md. Redis — arch-09 плюс module-04-redis-vm1.md или module-04-redis-vm2.md. Раскатка VM — arch-10 плюс module-10-deployment-vm1.md или module-10-deployment-vm2.md.

Приоритет документов

При конфликте требований:

arch-00 — имена и базовая семантика (поля, id, enum, бакеты, env, смысл статусов); не бизнес-лимиты и не детальная реализация.
arch-01 — границы сервисов, сценарии, sync, безопасность.
arch-02 — HTTP-контракты и направление вызовов.
arch-06 — безопасность размещения на VM, OS-роли, SSH, secrets delivery, host/container hardening и production-деплой.
arch-03 — Compose, сети контейнеров и published ports.
arch-08 — контракт nginx: TLS/ACME, request id, internal 404, access log, reload. Routing matrix — профильный module-03 VM spec.
arch-04 — non-secret env, secret references, app_settings, публичные DTO.
arch-09 — контракт Redis: не source of truth, ключи, TTL, Lua, AOF/ACL. Карта ключей — профильный module-04 VM spec.
arch-07 — контракт telemetry: JSON-поля, resource attributes, redaction, sampling, Collector, SigNoz. Не бизнес-лимиты сервисов.
arch-10 — контракт развёртывания: VPC/SG, PG/S3, stages/gates, cutover. Не ослабляет arch-06. Процедуры VM — профильный module-10 runbook.
arch-05 — процесс разработки.

Профильные спецификации модулей уточняют реализацию внутри этих границ. Если границы не позволяют эффективно реализовать модуль, то агент, разрабатывающий модуль, может предложить внести изменения в архитектуру.

Разрешение конфликтов

Имена полей, бакетов, статусов → arch-00, затем синхронизация arch-*.
Endpoint или auth → arch-02, при необходимости arch-01/arch-03.
Новая интеграция → сначала arch-02.
Compose, сети контейнеров, published ports → arch-03.
TLS/ACME nginx, request id, internal 404, access log → arch-08, затем профильный module-03-nginx-vm1.md или module-03-nginx-vm2.md.
Redis ключи/TTL/ACL/AOF, запрет очереди и OTP store → arch-09, затем профильный module-04-redis-vm1.md или module-04-redis-vm2.md.
VM, SSH, sudo, systemd-деплой, secret delivery, container/host hardening → arch-06, затем синхронизация arch-03/arch-04 и runbook.
Rollout stages, SG/DNS, PG/S3 gates, Safety cutover порядок → arch-10, затем профильный module-10-deployment-vm1.md или module-10-deployment-vm2.md.
JSON-лог, request_id/trace_id, redaction, sampling, Collector, SigNoz → arch-07, затем профильный module-09-observability-vm1.md или module-09-observability-vm2.md.

В бэклоге (не MVP)

Тема	Где зафиксировано
Доставка документов компании из Bitrix24 в приложение (`bitrix-sync` → `api-backend`, уведомление клиента)	Спецификация: `module-07-bitrix-sync.md`; API-контракты — `arch-02-api-contracts.md`
Интеграция с SMS-провайдерами (отправка OTP, отключение `KEYCLOAK_OTP_MOCK_*`)	Спецификация: `module-11-idgtl-sms.md` (доставка через Direct SMS API; проверка OTP — локально в Keycloak)

Каноническое размещение production-контуров

ВМ1 HAN Chat — самостоятельная публичная точка входа приложения: nginx, api-backend, Keycloak, bitrix-local-app, SMS-контур, Redis DB0/DB1 и локальный OTEL Collector.
ВМ2 Processing — самостоятельная service VM с отдельным public webhook host, private Message Safety ingress и постоянным ограниченным egress: message-safety, bitrix-sync, clamd/freshclam, отдельный Redis Safety, nginx и локальный OTEL Collector.
На каждой VM действует один root Compose project и отдельный root-owned systemd deployment unit. «Единый Compose» означает один проект на VM, а не один общий project через несколько хостов.
Bitrix24 вызывает CRM webhook напрямую на nginx ВМ2; ВМ1 в route не участвует. ВМ1 вызывает только Message Safety по private HTTPS.
При росте нагрузки bitrix-sync может быть перенесён на ВМ3 без изменения API и границ схем PostgreSQL.

Открытые пробелы

#	Пробел	Статус
G8	Явный список `is_public=true` для ключей `app_settings`	Отложить до оформления сервисов; seed в модуле `database`
G10	Полный DTO `GET /api/v1/public/app-config` и мэппинг `setting_key → response field`	Уточнить при оформлении OpenAPI `api-backend`
G11	Версионирование API/WS: deprecation policy, срок поддержки v1, `ws_protocol_version`	Уточнить перед публичным релизом API
G12	Масштабирование realtime: Redis Pub/Sub, sticky sessions, backpressure при нескольких репликах `api-backend`	Post-MVP / перед горизонтальным масштабированием
G13	Contract tests между `api-backend`, `message-safety`, `bitrix-local-app`, `bitrix-sync`	Контракт sync зафиксирован в module-07 §18; общий межсервисный gate остаётся до появления всех OpenAPI

Обновление документации

Изменение MVP → arch-01 + arch-02 (+ arch-03/arch-04 при необходимости).
Новый env или ключ app_settings → arch-04.
Новая VM, изменение сетевой доступности, прав deploy, sudo/systemd, capabilities, volumes или способа доставки секретов → arch-06 (+ arch-03/arch-04 и deployment runbook).
Изменение host bind owner/mode, named-volume ownership init, healthcheck command/image digest, published Docker port/DOCKER-USER, release file modes или renewal/systemd hook → arch-06 + arch-03 + профильный module + runbook.
Изменение service seed/schema/embedded artifact или feature flag, влияющего на edge route/allow-list → arch-04 + профильный module + rollout/rollback gates в arch-10 и профильном module-10-deployment-vm1.md / module-10-deployment-vm2.md.
Новый термин / enum → arch-00, затем поиск по arch-*.
Изменение JSON-лога, resource attributes, redaction, sampling, Collector pipeline или SigNoz endpoint → arch-07 (+ профильный module-09 VM spec, если меняется состав сервисов/алертов этой машины).
Изменение общего контракта nginx (TLS/ACME, request id, internal 404, reload) → arch-08 (+ профильный module-03 VM spec, если меняется routing/allow-list этой машины).
Изменение общего контракта Redis (формат ключей, TTL, Lua, AOF/ACL, запрет очереди) → arch-09 (+ профильный module-04 VM spec, если меняется карта ключей этой машины).
Изменение общего rollout (SG/DNS, PG/S3 gates, cutover порядок) → arch-10 (+ профильный module-10 VM runbook).
Закрытие пробела → убрать из «Открытые пробелы» и отразить решение в arch-*.

README.md Unescape Escape

Архитектура HAN Chat