← All blogs

FullStack Engineering CourseLesson 11 of 20 19 min

Architecture Practice: C4, ADRs, NFRs, Threat Modelling and FinOps

Architecture is a team activity

Good architecture is not only a good design. It is a design that people understand, agree with, can find the reasons for later, and can build safely within their budget. This lesson covers the practices that make that happen:

  • Describing architecture clearly: the C4 model and diagrams as code.
  • Recording decisions: architecture decision records (ADRs) and RFCs.
  • Making quality requirements concrete: non-functional requirements (NFRs) and design reviews.
  • Finding security risks early: threat modelling with STRIDE.
  • Controlling cost: FinOps.
  • Choosing technology, guiding many teams, and managing technical debt.

Describing architecture: the C4 model

Many architecture diagrams fail because they mix levels of detail: a box for "Azure" next to a box for one class, with unlabelled arrows. The C4 model fixes this with four levels, like zooming in on a map:

LevelShowsAudience
1. System contextYour system as one box, the people who use it, and the other systems it talks toEveryone, including non-technical people
2. ContainerThe deployable or runnable parts: web app, APIs, databases, queues, functions, and how they communicateDevelopers, architects, operations
3. ComponentThe main parts inside one container: modules, controllers, servicesDevelopers working on that container
4. CodeClasses and interfacesRarely drawn by hand; generate it from the code if needed

Most teams need only the first two levels, kept up to date. Rules that make any diagram readable:

  • Give every diagram a title and a key that explains the shapes, colours and line styles.
  • Label every arrow with what it carries and how: "Submits claims (HTTPS/JSON)", "Publishes ClaimSubmitted (Service Bus)".
  • Say what each box is: its type and technology, such as "Claims API (ASP.NET Core)".
  • Keep one level of detail per diagram.

Diagrams drawn by hand go out of date quickly. Diagrams as code (Structurizr DSL, Mermaid, PlantUML) live in the repository, are reviewed in pull requests, and change together with the code:

workspace "Claims Platform" {
    model {
        biller   = person "Hospital biller" "Prepares and submits claims"
        payer    = softwareSystem "Payer system" "Adjudicates and pays claims" "External"
        platform = softwareSystem "Claims Platform" {
            web      = container "Claims Web" "Biller UI" "React"
            api      = container "Claims API" "Validates and stores claims" "ASP.NET Core"
            db       = container "Claims DB" "Claims and audit history" "Azure SQL"
            bus      = container "Event bus" "Claim events" "Azure Service Bus"
            worker   = container "Submission worker" "Sends claims to payers" ".NET worker"
        }
        biller -> web "Uses" "HTTPS"
        web    -> api "Calls" "HTTPS/JSON"
        api    -> db  "Reads and writes" "EF Core"
        api    -> bus "Publishes ClaimSubmitted"
        worker -> bus "Consumes ClaimSubmitted"
        worker -> payer "Submits claims" "HTTPS"
    }
    views {
        systemContext platform { include * }
        container platform { include * }
    }
}

Recording decisions: ADRs

Two years from now, someone will ask why the system uses Service Bus instead of Event Hubs, or why claims are stored in a separate database. If the answer lives only in someone's memory, the team may undo a good decision or repeat a bad one. An architecture decision record (ADR) is a short document that captures one significant decision: its context, the options considered, the choice and its consequences.

# ADR 0012: Use Azure Service Bus for claim events

Status: Accepted (2026-03-14)          <- Proposed / Accepted / Superseded by ADR 0031

## Context
Claim submission must notify eligibility, pricing and notifications. Each event must be
processed exactly once per consumer, and events for one claim must stay in order.
Expected volume: about 200,000 claims per day, with peaks of 50 per second.

## Options considered
1. Azure Service Bus (topics and subscriptions, sessions)
2. Azure Event Hubs
3. Direct HTTP calls from the Claims API

## Decision
Use Azure Service Bus, Premium tier, one topic "claim-events", one subscription per consumer,
with sessions keyed by claim ID.

## Consequences
+ Dead-letter queues, duplicate detection and per-claim ordering are built in.
+ Consumers are decoupled; a consumer outage does not affect submission.
- Consumers must be idempotent (at-least-once delivery).
- Premium tier costs more; Event Hubs would be cheaper for raw throughput we do not need.

Practices that keep ADRs useful:

  • Keep them short (one or two pages) and in the repository, next to the code they affect, numbered in order.
  • Write them when the decision is made, not afterwards.
  • Never edit an accepted ADR's decision. If it changes, write a new ADR that supersedes the old one, so the history stays visible.
  • Record the options you rejected and why. That is the part people need most later.

Proposing changes: RFCs and design documents

An ADR records a decision. An RFC (request for comments) or design document is how a larger change is proposed and discussed before the decision. A typical outline:

  1. Problem and goals: what is wrong today, what success looks like, with numbers.
  2. Non-goals: what this change deliberately does not cover.
  3. Proposed design: diagrams (C4 levels 1 and 2), data flows, APIs, data model changes.
  4. Alternatives considered, and why they were not chosen.
  5. Non-functional impact: performance, security, cost, operations, migration and rollback.
  6. Risks and open questions.
  7. Rollout plan: phases, feature flags, how success is measured.

Share it early, with a deadline for comments, and invite the people who will build, run, secure and pay for the system. Writing the design down forces clear thinking, lets people in other time zones contribute, and turns the review into a record. The decisions that come out of it become ADRs.

Non-functional requirements

Functional requirements say what the system does ("a biller can submit a claim"). Non-functional requirements (NFRs), also called quality attributes, say how well it must do it. They often decide the architecture more than the features do:

Quality attributeExample question
PerformanceHow fast must a claim submission respond, at what load?
ScalabilityWhat volume must it handle next year, and at peaks?
AvailabilityHow much downtime per month is acceptable?
Reliability and recoverabilityHow much data may be lost in a disaster (RPO), and how fast must service return (RTO)?
Security and complianceWhich data is sensitive, and which regulations apply (for example HIPAA for US patient data)?
ObservabilityHow will we know it is broken before users tell us?
MaintainabilityHow quickly can a new developer make a safe change?
CostWhat may it cost per month, or per claim processed?

An NFR is only useful if it can be measured. "The system must be fast" cannot be tested. Write each one as a scenario with a number:

  • Vague: "Claim submission should be fast and scalable."
  • Measurable: "With 50 submissions per second, 95% of submissions respond within 300 ms and 99% within 1 second."
  • Vague: "The system must be highly available."
  • Measurable: "Claim submission is available 99.9% of each month (about 43 minutes of downtime). A regional outage loses at most 5 minutes of data (RPO) and service returns within 1 hour (RTO)."

Measurable NFRs become service level objectives (SLOs) in production, covered in the observability lesson, and load tests check them before release (the testing lesson).

Design reviews and NFR reviews

A design review checks a proposal before it is built, when changes are still cheap. It works best as a conversation guided by a checklist, not as an approval gate where one person says yes or no. A useful checklist:

  • Does the design meet each measurable NFR? How do we know: calculation, prototype or load test?
  • What happens when each dependency is slow or down (lesson 7)?
  • Where are the data boundaries, and who owns each piece of data?
  • How is it secured: authentication, authorisation, secrets, data protection? Has it been threat modelled?
  • How will we observe it: logs, metrics, traces, alerts?
  • How is it deployed and rolled back? Does it need a data migration?
  • What will it cost to run, and how does that grow with load?
  • Is there a simpler option that meets the requirements?

Record the outcome as ADRs and action items, and review again when something important changes.

Threat modelling with STRIDE

Threat modelling means looking at a design from an attacker's point of view before it is built, when fixing problems is cheap. A simple process:

  1. Draw a data flow diagram: users, processes, data stores, external systems, and the trust boundaries between them (for example, between the internet and your API, or between your service and a payer).
  2. For each element and each flow, ask what could go wrong, using STRIDE as a prompt.
  3. Decide how to handle each threat: fix it, reduce it, accept it with a reason, or transfer it.
  4. Track the actions like any other work, and revisit the model when the design changes.
ThreatMeaningExample in a claims APITypical defence
SpoofingPretending to be someone elseUsing a stolen token to submit claims as a hospitalStrong authentication (OAuth/OIDC, MFA, managed identities)
TamperingChanging data without permissionAltering a claim amount in transit or in a queueTLS, signatures (webhooks), integrity checks, authorisation on writes
RepudiationDenying an action, with no proof either wayA user claims they never approved a paymentAudit logs that cannot be changed, with user, time and action
Information disclosureExposing data to the wrong peopleAnother tenant's patient data in an API response or a logAuthorisation checks, tenant isolation, encryption, no sensitive data in logs
Denial of serviceMaking the system unavailableFloods of requests, or huge file uploadsRate limits, size limits, autoscaling, timeouts
Elevation of privilegeGaining rights you should not haveA biller calling an admin-only endpointLeast privilege, server-side role checks, input validation

Tools such as the Microsoft Threat Modeling Tool or OWASP Threat Dragon help draw the diagrams and suggest threats, but a whiteboard and an hour with the right people catch most problems. The security lesson covers the defences in detail.

FinOps: managing cloud cost

In the cloud, every design decision is also a spending decision, and costs can grow quietly. FinOps is the practice of making engineering teams aware of and responsible for what their systems cost. Key practices:

  • Visibility: tag every resource with its owner, environment and product, so costs can be traced to teams. Review the costs regularly.
  • Budgets and alerts: set budgets per team and environment in Azure Cost Management, with alerts before they are exceeded.
  • Right-sizing: match instance sizes to measured use. Many services run on far larger machines than they need.
  • Elasticity: scale out for peaks and back in afterwards (autoscaling), and stop non-production environments at night and at weekends.
  • Commitments: for steady workloads, Azure reservations and savings plans cost much less than pay-as-you-go prices.
  • Unit economics: track cost per business unit, such as cost per claim processed. Total cost going up is fine if volume grows faster; cost per claim going up is a warning.

Architecture choices drive cost too: chatty services that move data across regions, logs kept at full detail for ever, a Premium tier chosen "just in case", an always-on cluster for a job that runs once a day. Include cost in design reviews and ADRs, next to performance and security.

Technology evaluations and proofs of concept

When choosing between technologies (two message brokers, two front-end frameworks), avoid deciding on enthusiasm. A structured evaluation:

  1. Write down the requirements and constraints first, including the NFRs, the team's skills, licensing and support.
  2. Pick two or three realistic candidates.
  3. Score them against weighted criteria, agreed before anyone scores.
  4. Build a time-boxed proof of concept (POC) for the riskiest question only, such as "can it handle our peak load", rather than a mini product.
  5. Record the result in an ADR, including what would make you revisit it.
Criterion (weight)Option AOption B
Meets ordering and delivery needs (30%)53
Operational effort (25%)42
Team experience (20%)43
Cost at expected volume (15%)34
Community and support (10%)45
Weighted score4.203.10

Guardrails, reference architectures and technical debt

When many teams build on one platform, consistency matters. Instead of reviewing every decision centrally, give teams a paved road: an easy, approved way to do common things.

  • Reference architectures: worked examples of approved designs, such as "an event-driven worker on Azure", with diagrams, ADRs and a template repository.
  • Guardrails: rules enforced automatically rather than by review, such as Azure Policy denying public storage accounts, required tags, or CI checks for vulnerable packages.
  • Shared libraries and templates for logging, resilience, authentication and health checks, so every service gets good defaults for free.

Teams can leave the paved road when they have a good reason, recorded in an ADR, but staying on it should be the easiest choice.

Technical debt is the extra cost of change caused by past shortcuts or outdated designs. Some debt is a sensible trade-off, as long as it is visible and managed:

  • Keep a tech debt register: each item with its impact (what it slows down or risks), the estimated effort, and an owner.
  • Prioritise by impact on delivery and risk, not by how much it annoys developers.
  • Reserve regular capacity for it (many teams use around 15–20% of each sprint), and fix debt in the areas you are changing anyway.
  • Explain debt to the business in business terms: "releases take two days longer because of manual deployments", not "the pipeline is ugly".

Architecture work across teams relies on influence more than authority: writing clearly, explaining the reasons behind decisions, listening to the teams who will live with them, and helping others grow through reviews, pairing and mentoring.

Check your understanding

QuestionShort answer
What are the C4 levels?System context, container, component and code, from the widest view to the most detailed.
What makes a diagram readable?A title, a key, labelled arrows with protocol and purpose, typed boxes, and one level of detail.
What goes in an ADR?Context, options considered, the decision and its consequences, with a status and date.
How do you change an accepted ADR?Write a new ADR that supersedes it; the old one stays as history.
ADR or RFC?An RFC proposes and discusses a change before it is decided; an ADR records the decision.
What makes an NFR useful?A measurable scenario: a load, a target number and a percentile.
What does STRIDE stand for?Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege.
What is a trust boundary?A line in a data flow where the level of trust changes, such as between the internet and your API.
What is unit economics in FinOps?Cost per business unit, such as cost per claim processed.
What is a paved road?An easy, approved way to build common things, with reference architectures, templates and automated guardrails.
How should technical debt be managed?Keep it visible in a register, prioritise by impact, reserve regular capacity, and explain it in business terms.

Summary

  • Draw architecture with C4 levels 1 and 2, as code, with labelled arrows and a key.
  • Record every significant decision in a short ADR, with the options you rejected.
  • Propose larger changes in RFCs and invite comments early.
  • Write NFRs as measurable scenarios, and check designs against them in reviews.
  • Threat model designs with STRIDE across trust boundaries before building them.
  • Make cost visible and owned: tags, budgets, right-sizing, elasticity and cost per unit of business.
  • Evaluate technology with weighted criteria and a focused POC; guide teams with paved roads and automated guardrails; keep technical debt visible and funded.

The next lesson covers identity and security: OAuth 2.0 and OpenID Connect, JWTs, Microsoft Entra ID and managed identities, role-, attribute- and relationship-based access control, the OWASP Top 10, mTLS and zero trust.

Found this useful? Share it: LinkedIn X

Comments