AGENTS.md — 20-architecture (технический контекст)

Назначение уровня

Архитектурные решения, схемы данных, контракты и технические паттерны. Описывает как мы реализуем бизнес-логику. Не содержит бизнес-правил (ссылается на ../10-business/) и не содержит кода сервисов (ссылается на ../30-services/).

Содержимое

20-architecture/
├── AGENTS.md                      # ← вы здесь
├── principles.md                  # архитектурные принципы
├── high-level-architecture.md     # диаграммы, потоки, компоненты
├── module-layout.md               # clean architecture + микроядро
├── event-sourcing.md              # ES для canonical: как, где, почему
├── data-storage-decisions.md      # обзор хранилищ и их ролей
├── integration-patterns.md        # паттерн подключения нового поставщика
├── adr/                           # Architecture Decision Records
│   ├── AGENTS.md
│   ├── TEMPLATE.md
│   └── 0001-..0008-... .md
└── schemas/
    ├── AGENTS.md
    ├── postgres/                  # DDL, миграции, ERD
    ├── clickhouse/                # DDL для аналитики
    ├── elasticsearch/             # JSON mapping, analyzers, synonyms
    ├── events/                    # схемы Kafka-событий
    └── api/                       # OpenAPI / AsyncAPI

Ключевые концепции уровня

Clean Architecture (domain / app / infra / api слои модулей).
Event Sourcing и outbox pattern.
CQRS (commands / queries разделение в app-слое).
Projections (read models в PG, ES, CH).
Blue-Green Index (паттерн реиндексации ES).
Rate Budget (policy per-supplier).

См. ../GLOSSARY.md.

Когда смотреть сюда

Нужна схема таблицы / индекса / топика.
Нужно понять, почему используется именно это хранилище / брокер.
Нужен шаблон подключения нового поставщика.
Принимаете архитектурное решение — заведите ADR.

Когда НЕ смотреть сюда

Формулировка бизнес-правила → ../10-business/
Код или запуск сервиса → ../30-services/<n>/
Runbook инцидента → ../40-operations/runbooks/

Правила

Любое изменение схемы — через PR с обновлением файлов в schemas/.
Архитектурное решение — через ADR (иммутабельный после accepted).
Схемы — источник истины. Код, расходящийся со схемой, — баг.

Связанные материалы

Родитель: ../AGENTS.md
Источник бизнес-смысла: ../10-business/AGENTS.md
Реализации: ../30-services/AGENTS.md

Tracium

Разделы