Blog
Mert Özen's blog posts on software development, backend, frontend, and DevOps.
What Is an Architecture Decision? Recognizing Architecturally Significant Choices
A decision is architectural, and deserves a record, when it is expensive to reverse, reaches several modules or the system boundary, or moves a prioritized quality attribute scenario. We classify ten decisions from Bookstore's first months with these three criteria in C#, and discuss which deserve an ADR, a design doc or a PR description, who owns the decision, and what unrecorded decisions cost.
Writing ADRs: Decision Records with the Nygard Template, MADR 4.0 and Y-Statements
A good ADR records not just the decision but the question it answers, the options it was made against, the accepted cost and when to reopen it, and it is never edited once decided. Nygard's five-section template, the sections and front matter of MADR 4.0.0, a rejected decision record, Y-statements, the status lifecycle and a real script that enforces immutability in PRs.
Trade-off Analysis: Comparing Options Against Scenarios, Sensitivity and Trade-off Points
You compare options not with each other but against prioritized quality attribute scenarios, ideally with measurements from a spike; ATAM's sensitivity point, trade-off point and risk concepts show where the decision is fragile. We weigh no cache, HybridCache and Redis for the Bookstore catalog with a real spike: why p95 did not move, why an L2 did not fix stale prices and why a weighted decision matrix misleads.
RFCs and Design Docs: Debating Big Decisions in Writing
A decision whose solution is unclear and that affects several teams is first debated in a design doc, with an RFC process with written rules when needed, and its outcome is recorded as a separate, immutable ADR. Using a two-page design doc for adding an outbox to Bookstore's order service: Context and Scope, measurable Goals, real Non-Goals, Alternatives Considered, cross-cutting concerns, the lifecycle and the RFC comment period.
Documenting Architecture: arc42, Docs as Code and Keeping C4 Diagrams Next to ADRs
To keep architecture documentation alive, arc42 provides the structure, C4 views the diagrams and ADRs the decisions, all in one repository, and CI checks on every PR that the diagrams match the model. In Bookstore's docs folder: mapping arc42 sections to ADRs and C4 views, Structurizr's !docs and !adrs directives, inspect and a staleness check, and which diagram to show to which reader.
From ADR to Automated Check: Verifying Decisions with Fitness Functions and CI
The Confirmation section of every ADR is the specification of a fitness function: a decision is checked on every PR, on a schedule, continuously in production, or lands on a short manual list. At Bookstore we verify the public API decision with oasdiff, the bundle size decision with Angular budgets, migration reversibility with an xUnit test and the .NET support window with a weekly check, all with real output.
Keeping Decisions Alive: Decision Logs, Architecture Reviews and the Advice Process
A decision log only works while it stays discoverable and is reviewed regularly: a generated index, a supersede chain checked in CI, calendar and condition triggers and a 30-minute monthly review. A C# tool that audits Bookstore's 15-ADR log, the advice process and the architecture advisory forum, the maintenance status of ADR tools at the time of writing, and a minimum process for a team of six.