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:
| Level | Shows | Audience |
|---|---|---|
| 1. System context | Your system as one box, the people who use it, and the other systems it talks to | Everyone, including non-technical people |
| 2. Container | The deployable or runnable parts: web app, APIs, databases, queues, functions, and how they communicate | Developers, architects, operations |
| 3. Component | The main parts inside one container: modules, controllers, services | Developers working on that container |
| 4. Code | Classes and interfaces | Rarely 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:
- Problem and goals: what is wrong today, what success looks like, with numbers.
- Non-goals: what this change deliberately does not cover.
- Proposed design: diagrams (C4 levels 1 and 2), data flows, APIs, data model changes.
- Alternatives considered, and why they were not chosen.
- Non-functional impact: performance, security, cost, operations, migration and rollback.
- Risks and open questions.
- 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 attribute | Example question |
|---|---|
| Performance | How fast must a claim submission respond, at what load? |
| Scalability | What volume must it handle next year, and at peaks? |
| Availability | How much downtime per month is acceptable? |
| Reliability and recoverability | How much data may be lost in a disaster (RPO), and how fast must service return (RTO)? |
| Security and compliance | Which data is sensitive, and which regulations apply (for example HIPAA for US patient data)? |
| Observability | How will we know it is broken before users tell us? |
| Maintainability | How quickly can a new developer make a safe change? |
| Cost | What 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:
- 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).
- For each element and each flow, ask what could go wrong, using STRIDE as a prompt.
- Decide how to handle each threat: fix it, reduce it, accept it with a reason, or transfer it.
- Track the actions like any other work, and revisit the model when the design changes.
| Threat | Meaning | Example in a claims API | Typical defence |
|---|---|---|---|
| Spoofing | Pretending to be someone else | Using a stolen token to submit claims as a hospital | Strong authentication (OAuth/OIDC, MFA, managed identities) |
| Tampering | Changing data without permission | Altering a claim amount in transit or in a queue | TLS, signatures (webhooks), integrity checks, authorisation on writes |
| Repudiation | Denying an action, with no proof either way | A user claims they never approved a payment | Audit logs that cannot be changed, with user, time and action |
| Information disclosure | Exposing data to the wrong people | Another tenant's patient data in an API response or a log | Authorisation checks, tenant isolation, encryption, no sensitive data in logs |
| Denial of service | Making the system unavailable | Floods of requests, or huge file uploads | Rate limits, size limits, autoscaling, timeouts |
| Elevation of privilege | Gaining rights you should not have | A biller calling an admin-only endpoint | Least 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:
- Write down the requirements and constraints first, including the NFRs, the team's skills, licensing and support.
- Pick two or three realistic candidates.
- Score them against weighted criteria, agreed before anyone scores.
- 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.
- Record the result in an ADR, including what would make you revisit it.
| Criterion (weight) | Option A | Option B |
|---|---|---|
| Meets ordering and delivery needs (30%) | 5 | 3 |
| Operational effort (25%) | 4 | 2 |
| Team experience (20%) | 4 | 3 |
| Cost at expected volume (15%) | 3 | 4 |
| Community and support (10%) | 4 | 5 |
| Weighted score | 4.20 | 3.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
| Question | Short 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.
Comments