System Design Cases
Architecture Decision Records
ADR (Architecture Decision Records) concept page. Markdown в репо, фиксирующий context + decision + consequences. Lifecycle Proposed -> Accepted -> Deprecated/Superseded. Tooling: adr-tools, log4brains. Scenarios: writing ADR for Postgres vs Mongo, superseding RabbitMQ -> Kafka, onboarding via log4brains, anti-pattern of decisions in Slack threads.
Architecture Decision Records: context, decision and consequences over time
ADR сохраняет мотивацию одной architecturally significant decision. Nygard’s original format uses Title, Context, Decision, Status и Consequences; proposed/accepted/deprecated/superseded are useful states. Markdown в Git и one-to-two pages — решения его проекта, а не обязательный стандарт для всех команд.
Что утверждает паттерн — и чего он не гарантирует
- Nygard’s ADR captures one architecturally significant decision and its forces, response and consequences.
- Original proposed/accepted/deprecated/superseded states preserve history; reversing a decision should reference its replacement.
- Markdown, repository path, sequential numbering and one-to-two-page length are Nygard’s project decisions/examples, not universal ADR conformance rules.
- An ADR records a decision; it does not prove the decision is correct, implemented or still valid.
Границы и компоненты
| Компонент | Ответственность |
|---|---|
| Decision Author and Stakeholders | Формулируют forces, scope, alternatives и decision owner. |
| ADR Record | Хранит title/status/context/decision/consequences и links. |
| Evidence and Alternatives | Содержит measurements, assumptions, rejected options и confidence. |
| Decision Review Gate | Проверяет scope, consequences, owner и acceptance criteria. |
| Implementation and Configuration | Реализует accepted decision с traceable link. |
| Architecture Fitness Check | Проверяет измеримые assumptions/constraints после принятия. |
| Superseding ADR | Ссылается на старое решение и объясняет изменившийся context. |
| Searchable Decision Index | Делает актуальный status и replacement discoverable. |
Сценарии
Propose a significant decision
Author records facts/forces neutrally, alternatives and measurable assumptions before a decision is accepted. The ADR can be written before, during or after discovery as long as status and evidence are honest.
Проверяемый исход: Readers can distinguish facts, assumptions, options and the proposed response.
Accept with all consequences
Review checks decision scope, positive/negative/neutral consequences, owner and verification plan. Acceptance means stakeholders chose it, not that technology guarantees the outcome.
Проверяемый исход: The accepted record names success/failure signals and known trade-offs.
Verify assumptions in operation
A queue/broker decision uses measured workload, latency, durability and recovery tests. No fixed RabbitMQ ceiling is copied into the ADR as a universal product fact.
Проверяемый исход: Fitness checks detect when assumptions or consequences diverge from reality.
Supersede without erasing history
Changed forces lead to a new ADR. It links the old record, marks it superseded and preserves why the old decision was reasonable then.
Проверяемый исход: Search resolves the current decision while historical context remains auditable.
Failure, concurrency и evolution checklist
- Link decision to implementation/configuration and observable verification.
- Record negative and neutral consequences, not only benefits.
- Time-stamp evidence and re-evaluate assumptions when workload/context changes.
- Never delete or rewrite accepted history to hide a reversal; supersede with links and access controls appropriate to the repository.
Метрики, units и допущения
- Capacity claims cite benchmark workload, payload, durability, concurrency, hardware and confidence range; no broker has a universal messages/s ceiling.
- Review age = current time − last evidence time; teams choose thresholds based on volatility/risk.
- ADR size/page count is an editing heuristic, not a correctness metric.
Числа здесь — размерностные формулы или явно помеченные учебные inputs. Паттерн архитектуры сам по себе не задаёт SLA, throughput, latency или fault tolerance.
Связанные темы
[CONCEPT]evolutionary-architecture
Первичные источники
Scope note
ADR discipline improves traceability. It does not guarantee consensus, implementation conformance, current evidence, good architecture or any vendor performance number.