ADR — архитектурный комитет

Что это

• Формализованный процесс фиксации ключевых архитектурных решений
• Каждое решение описывается отдельным документом ADR
• Документ имеет единый шаблон: Контекст → Решение → Последствия

Зачем

• Прозрачность и единая точка истории архитектурных изменений
• Помогает всем членам команды понять мотивацию решений
• Позволяет участвовать (челленджить) решение всем участникам команды

Как работаем раз в 2 недели

Параметр	Значение
Частота	Раз в 2 недели или чаще по запросу
Артефакт	ADR-документ в Bookstack

1. Инициатор создаёт ADR в Bookstack по шаблону ниже
2. На встрече обсуждаем, фиксируем одобрение или доработки к следующей встрече
3. Для изменений, затрагивающих несколько команд, ADR обязателен

Правило

Любое архитектурное решение, затрагивающее более одной команды, должно пройти через ADR-процесс.

---

Шаблон ADR

ADR-XXX: <Краткое название архитектурного решения>

1. Задача

• Опишите текущую архитектуру и проблему

  Пример: Сервис cost-service хранит ставки за почасовую оплату. Появилась необходимость поддерживать сдельную оплату.

• Какие сервисы затронуты
• Какая текущая схема БД

2. Решение

• Что именно должно измениться
• Новая функциональность
• Нефункциональные требования (производительность, масштабируемость, отказоустойчивость)

3. Микросервисы

Сервис	Изменение
cost-service	Новая логика расчёта
dap-payments	Новый отдельный сервис обработки платежей
api-gateway	Проброс новых эндпоинтов

4. Изменения сервисов

Существующие сервисы — какие изменения вносятся:

Пример: cost-service — добавлена логика расчёта сдельной оплаты в класс PaymentCalculator

Новые сервисы — зачем создаются, их ответственность:

Пример: payment-service — отвечает за обработку платёжных транзакций и интеграцию с платёжными системами

5. API

Метод	Эндпоинт	Описание
POST	/payments	Добавлен эндпоинт для списка платежей
GET	/orders/{id}	Добавлено поле paymentStatus

6. Базы данных

Новые таблицы:

• Описание новых таблиц и их назначение

Изменения существующих таблиц:

• Какие колонки добавляются / изменяются

Логическая структура данных:

• Диаграмма связей (ERD) или описание отношений между сущностями
• Ключевые поля, внешние ключи, индексы

Пример: payments (таблица платежей) связана с orders через order_id (FK), индекс на (user_id, created_at)

Схема БД (ссылка на DDL или миграции):

CREATE TABLE payments (
    id         BIGSERIAL PRIMARY KEY,
    order_id   BIGINT NOT NULL REFERENCES orders(id),
    amount     DECIMAL NOT NULL,
    status     VARCHAR NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

Стратегия миграции данных (если применимо):

• Как переносятся существующие данные
• План отката

7. Производительность

• Ожидаемая нагрузка (RPS, количество пользователей, объём данных)
• Требования по времени отклика (p50, p95, p99)
• Результаты нагрузочного тестирования или оценка на основе бенчмарков
• Узкие места и стратегия масштабирования (горизонтальное / вертикальное, кэширование, шардирование)
• Влияние на существующие сервисы (рост нагрузки, потребление ресурсов)

8. Мониторинг

Тип	Что отслеживаем
Метрики	Latency, error rate, throughput новых эндпоинтов
Алерты	Пороговые значения для ключевых метрик
Бизнес-метрики	Конверсия, объём транзакций, среднее время обработки