Skip to Content
Cloud Engineering Academy
14. Advanced Banking Architecture

How to read and write a banking architecture

Use the 15-section architecture template, measurable non-functional requirements and architecture decision records to produce a design a bank's design authority can approve, and check your own documents with a small C# linter.

advanced⏱ 2 h 🟢 FreeSAP-C03SAA-C03SCS-C03

Assumes: .NET 10 LTS (file-based apps) · AWS Well-Architected Framework · Mermaid diagrams · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Explain what a design authority (architecture board) checks, and why a design that "works" can still be rejected.
  • Write each of the 15 sections of the module's architecture template, and say what separates a strong section from a weak one.
  • Turn a vague business wish into measurable non-functional requirements (latency, availability, RPO/RTO, throughput, retention).
  • Record a decision as an architecture decision record (ADR) that names the alternatives you rejected and the consequences you accept.
  • Read someone else's architecture critically using a short question list, and run a C# linter that flags missing sections.
  • Mark every compliance statement as "needs specialist review" instead of claiming a design is compliant.

Prerequisites

Why this matters in banking

You have probably already built something a bank depends on. Now picture the meeting where it is judged. A payments service is proposed. The developer demonstrates it working. Then the design authority, a panel of senior architects plus representatives from security, risk, compliance and operations, asks questions the demo cannot answer:

  • "What happens to a payment in flight when the sanctions provider times out?"
  • "Which AWS accounts hold the ledger, and who can read it?"
  • "How long can this service be down before it breaks our stated impact tolerance?"
  • "Where is the evidence that the control you describe actually runs?"
  • "Why this service and not the one the platform team already operates?"

Teams that cannot answer in writing get sent away for another cycle, often weeks. Teams that answer well get approval with conditions. The difference is rarely cleverness. It is structure: a document that puts the same questions in the same order every time, so the reviewers can find the answer, or see at once that it is missing.

This lesson gives you that structure. It is the foundation for every other lesson in Module 14: each later lesson applies the template to one banking domain.

Educational content, not legal or regulatory advice

Everything here uses the fictional Harbourline Bank. Where a design touches KYC/AML, sanctions, PSD2-style open banking, PCI DSS, UK GDPR or operational resilience, this module tells you which team must review and what to ask them. It never states that a design "is compliant". Statements about specific regulations carry a ⚠ VERIFY marker until your own legal or compliance function confirms them.

The idea in plain language

An architecture document is an argument, not a diagram. The diagram is one piece of evidence. The argument runs like this:

  1. Here is the problem and its measurable targets (sections 1 to 3).
  2. Here is the shape of the solution (sections 4 to 10).
  3. Here is how it fails, grows and costs (sections 11 to 13).
  4. Here is how we will build it, and who must still approve parts of it (sections 14 and 15).

A reader who disagrees with a design should be able to point at a specific section and say "I disagree with this choice because...". If they cannot, the document is too vague to review.

Analogy: a building's architectural drawings. The floor plan (diagram) matters, but the planning office also wants the fire-escape routes (failure scenarios), the load calculations (scalability), the materials list and cost (service selection, cost) and a list of the inspections still required (compliance touchpoints). A beautiful floor plan with none of those is not a submission.

The 15-section template

#SectionThe question it answersA weak answer looks likeA strong answer looks like
1Business requirementsWhy are we doing this, and what is out of scope?"Modernise payments""Cut average card-to-account posting time from 4 hours to under 60 seconds for retail current accounts; corporate payments out of scope"
2Functional requirementsWhat must the system do?A feature list with no actorsNumbered requirements per actor, each testable ("Customer can cancel a payment until it is submitted")
3Non-functional requirementsHow well, how fast, how safe?"Highly available, secure""99.95% monthly availability for initiation; p99 under 800 ms; RPO 0 for ledger, RTO 15 min"
4Architecture diagramWhat are the parts and how do they connect?One box labelled "AWS"Context and container diagrams, numbered flows, trust zones drawn
5Service selectionWhy these services, and why not the others?A list of servicesA table: service, role, reason, rejected alternative, trade-off accepted
6Network architectureWhat can reach what?"Runs in a VPC"Subnet tiers, endpoints, egress path, how on-premises is reached, which flows are blocked
7Security architectureWho can do what, and what is encrypted?"Uses IAM and KMS"Identity flows, key hierarchy, data classification, logging, STRIDE threats mapped to controls
8API designWhat is the contract?A list of endpointsResources, idempotency, error model, versioning, auth scopes, rate limits
9Database designWhere does each fact live, and who owns it?"DynamoDB"Tables or schemas, keys, access patterns, consistency needs, retention
10Data flowWhat path does a piece of data take, and what is stored along the way?Arrows with no data namesOne numbered flow per use case, naming payload, store and classification at each hop
11Failure scenariosWhat breaks, and what happens next?"Retries on failure"A table: failure, detection, automatic response, customer impact, manual step
12ScalabilityWhat happens at 10 times the load?"Auto Scaling"Peak model, first bottleneck, scaling trigger, quotas that must be raised
13CostWhat does it cost to run and to build?"Pay as you go"Monthly estimate with assumptions, top three cost drivers, cost per transaction
14Implementation stepsIn what order do we build it, and how do we know each step worked?A to-do listPhased plan, each phase with an exit test and a rollback
15Compliance touchpointsWhich obligations touch this design, and who must review?"Compliant with GDPR" (a claim you cannot make)Table: obligation area, where it touches the design, reviewing team, evidence needed

Two rules make the template work:

  • Every section is mandatory. Writing "not applicable, because..." is allowed. Silence is not.
  • Sections cross-reference. A failure scenario in section 11 should name the component from section 4 and the control from section 7.

What problem the AWS services solve

This lesson is about documents more than services, but AWS publishes guidance that you should use instead of inventing your own criteria.

ResourceWhat it gives youLimits and sharp edges
AWS Well-Architected FrameworkSix pillars (operational excellence, security, reliability, performance efficiency, cost optimisation, sustainability) with question setsGeneric. It tells you what to consider, not what to build
Financial Services Industry LensWell-Architected guidance specific to regulated financial workloadsGuidance, not a certification. Check the current lens text; it is updated over time ⚠ VERIFY current structure
AWS Well-Architected ToolA console service for running a structured review and tracking improvementsRecords answers and risks; does not validate your design
AWS Architecture Center and Solutions LibraryReference architectures and deployable guidance, sometimes with infrastructure-as-codeA reference is a starting point. You still own every decision in it
AWS Prescriptive GuidancePatterns and process guides, including guidance on decision records ⚠ VERIFY exact titleWritten for a general audience; add your bank's standards

Honest limitation: none of these produces an approved design. The approval comes from your own organisation's reviewers, who apply the bank's policies.

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Azure Architecture Center, Cloud Adoption FrameworkAWS Architecture Center, Well-Architected, Cloud Adoption FrameworkBoth are guidance libraries. AWS ties its review to six pillars and a console tool
Azure Well-Architected ReviewAWS Well-Architected ToolSame idea: workload-level questions, results become an improvement plan
Azure Landing Zone design areasAWS multi-account landing zone (Control Tower, Organizations)The account is the main isolation boundary in AWS, so "which account?" belongs in every design
Architecture decision records in a repo (Markdown)Same practice, tool-neutralNo AWS product replaces a Git-reviewed ADR folder
Visio, draw.io, Structurizrdraw.io with AWS icons, Mermaid in Markdown, StructurizrText-based diagrams diff in pull requests; this course uses Mermaid
Azure Policy / Defender for Cloud recommendations as "architecture evidence"AWS Config, Security Hub, Audit ManagerSection 15 evidence often comes from these services

Architecture

The review pipeline

How the 15 sections connect

Notice that non-functional requirements (section 3) feed three later sections. If you leave them vague, failure, scalability and cost all become guesswork.

Security-boundary view of the documents themselves

Architecture documents describe sensitive things: network layouts, control gaps, partner connectivity. Treat them as internal-confidential artefacts.

AssetWhere it livesWho can change itControl
ADR folderGit repository, protected main branchAuthors via pull request, reviewers approveBranch protection, signed commits where the bank requires them
Diagrams as codeSame repositorySameReviewed like code
Approved baselineTagged release or wiki exportDesign authority secretaryRead-only after approval; changes need a new ADR

Step-by-step implementation

Start with the NFR table, not the diagram

Write section 3 first. Use this format and refuse to proceed while any cell says "high", "fast" or "secure":

QualityTargetHow measuredSource of the target
Availability (payment initiation)99.95% per calendar monthSynthetic probe plus success ratio of POST /paymentsBusiness service owner
Latencyp99 under 800 ms for POST /payments, excluding scheme settlementAPI Gateway and application metricsProduct requirement
Durability of ledgerNo acknowledged posting is ever lost (RPO 0)Multi-AZ commit plus reconciliationRisk appetite statement
Recovery timeRTO 15 minutes for initiation, 4 hours for reportingDR game-day timingImpact tolerance for the important business service ⚠ VERIFY your firm's tolerance
Throughput200 payments per second sustained, 800 at peakLoad testVolume forecast
RetentionPayment records 7 years ⚠ VERIFY with complianceLifecycle rules, Object LockRecords-retention policy

Why: every later choice is justified against these numbers. "99.95%" allows about 22 minutes of downtime in a 30-day month. If a design cannot meet that arithmetic, you find out in section 11, not in production.

Draw context first, then containers

Use the C4 model levels. Level 1 (context): your system, its users and the external systems it talks to. Level 2 (containers): the deployable parts (service, database, queue). Stop there for the authority pack. Component-level diagrams belong with the team that builds it. Number every arrow and refer to the numbers in section 10.

Fill section 5 as a decision table

For each service write a row with: role, why chosen, the alternative you rejected, and the trade-off you accept. The rejected-alternative column is the one reviewers read first, because it shows you considered more than one option.

Write the failure table before the happy path is polished

List at least eight failures. Include one each from: dependency timeout, duplicate request, poison message, data-store throttling, Availability Zone loss, credential or key problem, bad deployment, and a malicious or erroneous input. For each: how it is detected, what the system does by itself, what the customer sees, and what a human must do.

Record each significant decision as an ADR

Use a short, stable template (below). One decision per record. Never edit an accepted ADR to change history; write a new one that supersedes it.

Finish with section 15, and keep it honest

List each obligation area that touches the design, the place in the design where it touches, the team that must review, and the evidence you will collect. Do not write "satisfies" or "complies". Write "requires review by".

Lint the document, then ask a colleague to attack it

Run the linter below to catch missing sections, then give the document to a colleague with the question list in "Reading someone else's architecture".

AWS Console instructions

The AWS Well-Architected Tool is the one console service that supports this lesson. It is free to use (you pay only for the resources you review, not for the tool ⚠ VERIFY current pricing).

  1. Console → Well-Architected Tool → Define workload.
  2. Enter a name such as harbourline-payments-design, environment type Pre-production, and select the Regions and accounts that apply.
  3. Apply the Financial Services Industry Lens if it is offered for your workload ⚠ VERIFY availability, then answer the questions for the pillars you are reviewing.
  4. Open Improvement plan to see the high-risk issues and copy them into section 11 or 14 of your document.

Use fictional workload names in the sandbox. Do not paste real account IDs or customer information into any review tool.

AWS CLI

# List the Well-Architected lenses available to your account (read-only call).
aws wellarchitected list-lenses --profile learn-sandbox --region us-east-1

# Create a workload record for the design review. Fictional names only.
aws wellarchitected create-workload \
  --workload-name harbourline-payments-design \
  --description "Learning design review for the Harbourline payments architecture" \
  --environment PREPRODUCTION \
  --review-owner "learner@example.com" \
  --lenses wellarchitected \
  --aws-regions us-east-1 \
  --tags Project=cea-lab,Lab=m14-l1,Environment=learn,Owner=learner \
  --profile learn-sandbox --region us-east-1

The second command creates a small metadata record with no running resources. The --review-owner value is an email-style string; use a reserved example.com address. If the CLI rejects a flag, check aws wellarchitected create-workload help for the current shape ⚠ VERIFY.

Infrastructure as Code

An architecture's IaC is evidence for section 14. For this lesson, the useful IaC is the repository structure for your documents. Tools like CDK and Terraform come in the later lessons.

architecture/
  payments/
    README.md                 # the 15-section document
    diagrams/
      context.mmd             # Mermaid source, reviewed in pull requests
      containers.mmd
    adr/
      0001-use-step-functions-for-payment-saga.md
      0002-fail-closed-when-screening-unavailable.md
      0003-dynamodb-for-idempotency-aurora-for-ledger.md
    evidence/
      nfr-test-results.md
      failure-game-day-2026-11.md

Complete code

The linter below is a single-file .NET 10 program. It reads a Markdown architecture document and reports which of the 15 sections are missing, which are suspiciously short, and whether banned compliance phrases appear.

ArchLint.cs
// Run with: dotnet run ArchLint.cs -- path/to/README.md
// (.NET 10 file-based app: no project file needed.)
using System.Text.RegularExpressions;

string[] required =
[
    "business requirements", "functional requirements", "non-functional requirements",
    "architecture diagram", "service selection", "network architecture",
    "security architecture", "api design", "database design", "data flow",
    "failure scenarios", "scalability", "cost", "implementation steps",
    "compliance touchpoints",
];

string[] bannedPhrases = ["is compliant", "fully compliant", "guarantees compliance", "meets all requirements"];
const int minWords = 40;

if (args.Length != 1 || !File.Exists(args[0]))
{
    Console.Error.WriteLine("Usage: dotnet run ArchLint.cs -- <architecture.md>");
    return 2;
}

var text = File.ReadAllText(args[0]);

// Split into sections at level-2 headings: "## 3. Non-functional requirements"
var headingPattern = new Regex(@"^##\s+(?:\d+[.)]?\s*)?(?<title>.+?)\s*$", RegexOptions.Multiline);
var matches = headingPattern.Matches(text);

var sections = new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase);
for (var i = 0; i < matches.Count; i++)
{
    var start = matches[i].Index + matches[i].Length;
    var end = i + 1 < matches.Count ? matches[i + 1].Index : text.Length;
    var body = text[start..end];
    var words = Regex.Matches(body, @"\b[\w'-]+\b").Count;
    sections[matches[i].Groups["title"].Value.Trim()] = words;
}

var problems = 0;
foreach (var name in required)
{
    var found = sections.Keys.FirstOrDefault(k => k.Contains(name, StringComparison.OrdinalIgnoreCase));
    if (found is null)
    {
        Console.WriteLine($"MISSING  {name}");
        problems++;
    }
    else if (sections[found] < minWords)
    {
        Console.WriteLine($"THIN     {name} ({sections[found]} words; write 'not applicable because...' or add detail)");
        problems++;
    }
}

foreach (var phrase in bannedPhrases)
{
    if (text.Contains(phrase, StringComparison.OrdinalIgnoreCase))
    {
        Console.WriteLine($"CLAIM    contains '{phrase}': say 'requires review by <team>' instead");
        problems++;
    }
}

if (!text.Contains("rejected", StringComparison.OrdinalIgnoreCase))
{
    Console.WriteLine("HINT     no 'rejected' alternatives mentioned: section 5 should name at least one per service");
}

Console.WriteLine(problems == 0 ? "OK: all 15 sections present." : $"{problems} problem(s) found.");
return problems == 0 ? 0 : 1;

Code explained line by line

  1. The required array holds the lower-case section names. Matching is by "contains", so ## 5. AWS service selection and rejected alternatives still matches service selection.
  2. bannedPhrases encodes the course rule that an architecture document never asserts compliance. A regex or a code-review bot can enforce it in a pull request.
  3. File.ReadAllText(args[0]) loads the whole document. Documents are small, so there is no need to stream.
  4. The headingPattern regex matches level-2 Markdown headings and strips an optional leading number such as 3. or 3). RegexOptions.Multiline makes ^ match at each line start.
  5. The loop slices the text between one heading and the next (text[start..end] is a C# range on a string) and counts words with a second regex.
  6. A section under 40 words is reported as THIN. The point is not the number; it is forcing an explicit "not applicable, because..." instead of an empty heading.
  7. The exit code is 0 only when nothing is wrong, so you can run the tool in a CI step (see Module 9) and fail a pull request that touches the architecture folder.

Security considerations

⚠ Learning shortcut — not for production

The linter checks structure, not truth. A document can contain all 15 sections and still be wrong. In production, pair automated structure checks with a human review by the design authority, and generate evidence (IaC scans, test reports, Security Hub findings) rather than trusting the prose.

  • Do not put secrets or real identifiers in architecture documents. Use placeholders such as ACC-0000000001 and fictional account IDs.
  • Classify the document. A network diagram showing partner connectivity is useful to an attacker. Store it where access is limited to staff.
  • Threat model the design, not just the code. Section 7 should reference the STRIDE threats you found, and each should map to a control. See threat modelling.
  • Treat "approved" as a version. Pin the approved document to a Git tag so later edits cannot silently change what the board saw.

Banking use case

Harbourline Bank wants a new faster-payments initiation service. The product owner's request: "customers should be able to send money instantly, safely."

Run the template:

  • Section 1 turns "instantly" into a target: scheme acceptance within seconds for 99% of payments, with clear status for the other 1%.
  • Section 3 turns "safely" into: duplicate-free under client retry (idempotency), fail-closed when screening is unavailable, and tamper-evident audit records.
  • Section 5 forces a choice between Step Functions orchestration and in-service orchestration, recorded as an ADR with the alternative rejected.
  • Section 11 is where the sanctions provider outage is discussed in daylight, rather than discovered at 02:00.
  • Section 15 lists payments-scheme rules, sanctions obligations, data-protection impact assessment, operational resilience and third-party risk, each with a named reviewing team.

Later lessons do exactly this for payment processing, customer onboarding and others.

An ADR template and an example

adr/0002-fail-closed-when-screening-unavailable.md
# 0002. Fail closed when sanctions screening is unavailable

Status: Accepted (2026-11-18)
Deciders: Payments architect, Financial-crime compliance lead, Head of operations

## Context
Payments are screened by an external provider. The provider has had two
short outages in the past year (fictional figure). During an outage we must
either release payments unscreened or hold them.

## Decision
Hold the payment (status PendingReview) after three bounded retries.
Never release a payment because screening could not complete.

## Alternatives considered
1. Fail open (release if provider is down): rejected. Unacceptable risk of
   unscreened payments; regulator and sponsor-bank consequences need review.
2. Second provider as hot standby: deferred. Adds cost and a second
   third-party risk assessment. Revisit if PendingReview volume exceeds the
   agreed threshold.

## Consequences
+ No unscreened payment can leave the bank.
- During an outage customers see "pending" instead of "sent".
- Operations needs a review queue and an SLA to clear it.

## Compliance touchpoints
Financial-crime compliance must confirm the retry window and hold policy. ⚠ VERIFY

Reading someone else's architecture

When you review a design, ask these in order. They map to the sections.

  1. Section 3: which number would make this design wrong? If none, the targets are not measurable.
  2. Section 4: can I trace one payment from the customer to the ledger along numbered arrows?
  3. Section 5: for each service, what was rejected and why?
  4. Section 6 and 7: where are the trust boundaries, and what authenticates each crossing?
  5. Section 9: who owns each fact? Is any fact written by two services?
  6. Section 11: what does the system do when each dependency is slow, not just when it is down?
  7. Section 13: what is the cost per transaction, and what doubles it?
  8. Section 15: who has actually reviewed the regulatory points, or is it still an aspiration?

Common mistakes

  • Starting with the diagram. The picture then drives the requirements, instead of the other way round. Write sections 1 to 3 first.
  • Service lists with no alternatives. Reviewers cannot tell whether you chose or defaulted. Always record what you rejected.
  • "Highly available" without arithmetic. State the percentage and compute the allowed downtime. 99.9% is about 43 minutes in a 30-day month; 99.99% is about 4 minutes.
  • Happy-path-only documents. The failure section is where the real design lives.
  • Claiming compliance. Replace with "requires review by". The linter above flags the common phrases.
  • Editing accepted ADRs. History becomes untrustworthy. Supersede instead.
  • One giant diagram. Use context, containers, then flows. A diagram that needs a magnifying glass communicates nothing.

Troubleshooting

SymptomLikely causeFix
Linter reports MISSING for a section that existsHeading is level 3 (###) or the title lacks the expected wordsUse ## headings and include the section name, e.g. ## 7. Security architecture
Linter reports THIN for a short but valid sectionFewer than 40 wordsAdd "not applicable because..." with a reason, or expand
dotnet run ArchLint.cs says it needs a projectOlder SDK than .NET 10Use the .NET 10 SDK or run in the mcr.microsoft.com/dotnet/sdk:10.0 image
Mermaid diagram does not render in the repository viewerSyntax error or unsupported featureTest in the Mermaid live editor; keep diagrams simple
aws wellarchitected create-workload returns a validation errorA required parameter is missing or a flag name changedRun the command with help and compare ⚠ VERIFY
Reviewers keep asking the same questionSection is missing or buriedAdd it to the section list and cross-reference from related sections

Cost and cleanup

This lesson is free: it is a document exercise. The optional Well-Architected Tool workload is metadata only.

# Remove the optional workload record. First list to find the workload id.
aws wellarchitected list-workloads --profile learn-sandbox --region us-east-1

# Delete it (replace the id with the value from the list output).
aws wellarchitected delete-workload --workload-id <workload-id> --profile learn-sandbox --region us-east-1

# Check nothing tagged for the course remains (Resource Groups Tagging API).
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab \
  --profile learn-sandbox --region us-east-1

Exercises

  • 🟢 Guided: take the one-paragraph request "build a service that lets customers see their statements online" and write sections 1, 2 and 3 as three small tables. Every non-functional target must have a number.
  • 🟡 Challenge: write ADR 0003 deciding between DynamoDB and Aurora PostgreSQL for the idempotency store. Include two rejected alternatives and the consequences you accept. Run the linter on a document containing your ADR reference in section 5.
  • 🔴 Live problem: your design authority rejected a design with the note "failure handling not credible". You have two days. Read the design in the solution below, find at least five missing failure scenarios, and write the failure table for section 11.

Assignment

Create a folder architecture/statement-portal/ in your portfolio repository with a README that contains all 15 sections for a small statement-viewing service (fictional), two Mermaid diagrams (context and container), and two ADRs. The linter must pass. Add a short "Compliance touchpoints" table with no compliance claims.

Solutions

Knowledge check

Interview questions

  • What do you put in an architecture document beyond a diagram? Measurable requirements, service choices with rejected alternatives, failure scenarios, cost, and a list of compliance touchpoints with owners. The diagram is one piece of evidence.
  • How do you decide a design is ready for the design authority? Peers cannot find a missing section, every non-functional target has a number and a measurement method, the failure table covers dependency, duplicate, capacity and security failures, and specialist reviews are booked.
  • How do you keep decisions from being lost? Architecture decision records in Git, one per decision, immutable once accepted, superseded rather than edited.
  • A reviewer says "this will not scale". What do you do? Ask for the load number they believe is wrong, then show the peak model, the first bottleneck and the quota or scaling trigger from section 12. If those are missing, the criticism is fair.
  • Why does multi-account design belong in every architecture? The AWS account is the strongest isolation boundary for blast radius, permissions and billing. A design that does not say which account holds each component has not made a security decision.

Certification practice

Completion checklist

  • I can name the 15 sections and say what question each answers
  • I wrote section 3 with numbers for every target
  • I recorded at least one ADR with a rejected alternative
  • I ran the linter and fixed what it found
  • My compliance section says "requires review by", never "complies"
  • I ran the cleanup steps if I created a Well-Architected Tool workload

Key takeaways

  • An architecture document is an argument: measurable requirements first, then design, then failure, scale and cost.
  • Every section is mandatory; "not applicable, because..." is acceptable, silence is not.
  • Record decisions as immutable ADRs that name the alternatives you rejected.
  • Never claim compliance in a design: say where an obligation touches it and who must review.
  • Use the Well-Architected Framework and the Financial Services Industry Lens as question lists, not as approval.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page