Architecture documents & governance

12.1 Where each document fits

Documents get more detailed as an initiative moves from idea to operations. ADRs are written throughout.

12.2 ACD: Architecture Concept / Context Document

The earliest architecture artefact. It frames the problem, the business context and the target concept before detailed design begins.

12.3 AIA: Architecture Impact Assessment

Assesses how a change affects existing systems, data, integrations, security, operations and cost, and decides how much governance it needs.

12.4 SO: Solution Outline / Solution Overview

A high-level description of the proposed solution: its components, integrations, key decisions and how it meets requirements. The bridge between concept and detailed design.

12.5 HLD: High-Level Design Added

The system-level design: major components, interactions, technology choices and deployment topology. In many organisations, the SO and HLD are one document.

• Architecture diagrams (logical + physical), component interactions, sequence diagrams for key flows
• Technology stack, hosting, networking, environments
• Cross-cutting concerns: logging, monitoring, security, resilience

// AppHost: the container view (C4 level 2) in code
var builder = DistributedApplication.CreateBuilder(args);
var redis = builder.AddRedis("cache");
var sql   = builder.AddSqlServer("sql").AddDatabase("payments");
var bus   = builder.AddAzureServiceBus("bus");

builder.AddProject<Projects.Payments_Api>("payments-api")
       .WithReference(sql).WithReference(redis).WithReference(bus);

builder.Build().Run();

12.6 LLD: Low-Level Design

The developer-ready blueprint. It describes each component in enough detail to build and test without guessing.

// Program.cs
builder.Services.AddOpenApi();
app.MapOpenApi();                          // /openapi/v1.json

// Event schema for the LLD / schema registry
JsonNode schema = JsonSerializerOptions.Default.GetJsonSchemaAsNode(typeof(PaymentCompleted));

12.7 ADR: Architecture Decision Record

A short, immutable note recording one significant decision: its context, the options, the choice and the consequences. Your future self will thank you.

ADR-017: Use Azure Service Bus for payment event integration
Status:   Accepted (2026-03-04)   [Proposed | Accepted | Deprecated | Superseded by ADR-0xx]
Context:  Payment service must notify 4 downstream systems; needs ordering per account,
          DLQ, at-least-once delivery, enterprise support; volumes ~200 msg/s peak.
Options:  1) Service Bus topics  2) Event Hubs/Kafka  3) Direct REST calls
Decision: Service Bus topics with sessions (session = account ID) + transactional outbox.
Consequences:
   + ordering per account, DLQ, managed service, fits volumes
   − not built for replaying history (use Event Hubs later if analytics streaming needed)
   − consumers must be idempotent

12.8 SOP: Standard Operating Procedure

Step-by-step instructions for a routine operational task, so it's done the same way every time, by anyone trained.

12.9 Non-Functional Requirements (NFRs) Added

Functional requirements say what the system does. NFRs say how well it does it. Make them measurable.

12.10 C4 model for diagrams Added

Four zoom levels of architecture diagrams, like Google Maps for software.

12.11 Threat model (STRIDE) Added

Systematically ask "what could go wrong?" on your data-flow diagram, before attackers do.

12.12 Runbook vs SOP vs Playbook Added

12.13 TOGAF & Well-Architected frameworks Added

Two widely used frameworks: TOGAF for running enterprise architecture, and Well-Architected for reviewing cloud workloads.

12.14 Architect soft skills: trade-offs & stakeholders Added

Architecture is decisions plus persuasion. Make the trade-offs explicit, speak to each audience in its own language, and drive to a decision people will actually back.

Communicating trade-offs

• "It depends → on what." Never stop at "it depends". Name the 3–4 drivers (cost, latency, risk, time, skills) and say which way each one pushes.
• Options table, not a single answer. 2–3 genuine options, including "do nothing". The same criteria for every option, with costs shown honestly.
• Lead with the recommendation. Then the reason, then the trade-off you're accepting: "We recommend A. It meets the 99.95% target at half the cost. We accept no message replay."
• Say what would change your mind. It shows the decision is reasoned, and it tells people when to revisit it.

Tailor to the audience

The one-page decision memo

12.15 Build vs buy, technical debt & governance Added

Build only what differentiates you. Manage technical debt like financial debt, deliberately and visibly. Govern with guardrails and paved roads, not just approval gates.

Build vs buy vs SaaS vs open source

Technical debt: Fowler's quadrant

Architecture governance

using static ArchUnitNET.Fluent.ArchRuleDefinition;

public class ArchitectureTests
{
    static readonly Architecture Arch = new ArchLoader()
        .LoadAssemblies(typeof(Payment).Assembly, typeof(PaymentsDbContext).Assembly)
        .Build();

    [Fact]
    public void Domain_does_not_depend_on_infrastructure() =>
        Types().That().ResideInNamespace("Payments.Domain")
            .Should().NotDependOnAny(Types().That().ResideInNamespace("Payments.Infrastructure"))
            .Check(Arch);
}