# Задача

Создай (или обнови, если уже существует) файл `docs/ARCHITECTURE.md`.

# Вводные

`ARCHITECTURE.md` — это живой архитектурный документ, описывающий текущее фактическое состояние системы. Это не vision-документ и не roadmap. Он фиксирует реальную архитектуру, отражённую в коде и инфраструктуре.

# Требования к содержанию `ARCHITECTURE.md`

Документ обязан содержать следующие разделы:

1. System Overview
– назначение системы
– ключевая бизнес-цель
– границы системы (что входит и что явно не входит)
– основные внешние акторы и интеграции

2. Architectural Context
– тип архитектуры (монолит, модульный монолит, микросервисы и т.д.)
– среда исполнения (runtime, инфраструктура, deployment-модель)
– основные технологические стеки

3. Subsystems and Responsibilities
Для каждой подсистемы:
– название
– ответственность
– публичные интерфейсы
– зависимости
– что она не должна делать

4. Interactions
– логическая схема взаимодействия подсистем
– направление зависимостей
– синхронные / асинхронные взаимодействия
– точки интеграции с внешними системами

Описание должно быть логическим и архитектурным, без BPMN и без избыточной детализации бизнес-процессов.

5. Data Architecture
– основные доменные сущности
– границы владения данными
– источники истины
– политика кэширования (если есть)

6. Key Technical Decisions
– принятые архитектурные решения
– их причины
– зафиксированные компромиссы
– допущения

7. Constraints
– технические ограничения
– инфраструктурные ограничения
– нормативные или внешние ограничения

8. Extension Points
– предусмотренные точки расширения
– места, где допустимо добавлять новые модули
– зоны, требующие осторожности

9. Architectural Invariants
Перечень принципов, которые запрещено нарушать.
Это должны быть чёткие, проверяемые правила.


# Правила описания

– Документ описывает текущее состояние кода, а не желаемое будущее.
– Если что-то не реализовано — не описывать это как существующее.
– Не использовать расплывчатые формулировки («гибкая», «масштабируемая» без пояснения).
– Не дублировать README.
– Не описывать бизнес-функциональность вне архитектурного контекста.
– Не фантазировать о механиках, которых нет в коде.

# Консистентность

Перед созданием/обновлением документа:
– проанализируй текущую структуру репозитория
– определи реальные модули и зависимости
– зафиксируй их как есть

Документ должен быть согласован с кодовой базой.

# Обновление AGENTS.md

Обнови файл `AGENTS.md`, добавив:

1. Правило, что `docs/ARCHITECTURE.md` является единственным источником истины по архитектуре системы.

2. Обязанность агента:
– при любом изменении, затрагивающем архитектуру (структура модулей, зависимости, интеграции, инфраструктура, доменные границы), обновлять `ARCHITECTURE.md` в том же коммите.

3. Запрет на архитектурные изменения без обновления документа.

4. Если архитектурное изменение невозможно корректно отразить в `ARCHITECTURE.md`, агент обязан:
– явно указать это в комментарии к изменению
– объяснить причину
– предложить способ корректного отражения

# Запрет дублирования

– Архитектурные описания запрещено дублировать в других документах.
– Все архитектурные разделы в других файлах должны ссылаться на `docs/ARCHITECTURE.md`.

# Дополнительно

Если файл уже существует:
– не переписывать его полностью без причины
– сохранить структуру, если она логична
– обновлять только несоответствующие или устаревшие разделы

# Результат

После выполнения:
– `docs/ARCHITECTURE.md` отражает реальную архитектуру
– `AGENTS.md` закрепляет дисциплину поддержки архитектурной документации