Architectural principles¶
Why architectural principles?¶
Because without them, every decision gets made twice. Once when someone designs something, and again when someone else reviews it and disagrees. Principles are the shared language that cuts that argument short — not by suppressing debate, but by giving it a foundation.
They also protect you from yourself. The temptation to over-engineer is real. So is the temptation to cut corners. Principles create a standard you can hold a design against before it becomes a problem you have to live with.
These nine principles apply to every design decision, technology choice, and implementation in this bank. They are ordered by precedence. When principles conflict — and they will — the higher one wins.
How to use this: Before finalising any significant design, run it through these principles in order. A decision that violates a higher principle cannot be rescued by satisfying a lower one.
Understand your business first¶
Principles without business context are just philosophy. Before applying any of these, be clear on what this bank is:
- A digital-first bank operating in two jurisdictions with different regulators, different consumer protection laws, and overlapping AML obligations
- A technology company that holds a banking licence — not a bank that uses technology
- A small team building something that must work at scale, which means every engineering decision has a long tail
- A regulated entity where the audit trail is the evidence and the system is the compliance programme
That context shapes everything. It is why KISS is the top principle — we cannot afford complexity. It is why compliance-by-design exists — manual processes do not scale and do not satisfy regulators. It is why evolution-by-design matters — regulation changes, products change, and our ability to respond quickly is a commercial advantage.
Principles for principles¶
Before the list, three meta-rules:
Principles are not a menu. You do not get to pick the ones you like and ignore the rest. A solution that satisfies six principles but violates one is a problem, not a partial success.
Principles require judgment, not just compliance. The question is not "does this technically satisfy the principle?" It is "does this genuinely embody the intent?" Rules can be gamed. Principles should not be.
Validate your designs against them. When you present an architecture or a module design, walk through the principles explicitly. Which ones does it satisfy? Which ones are in tension? How did you resolve the tension? That conversation is the point.
The nine principles¶
| # | Principle | One-line version |
|---|---|---|
| AP-001 | Keep it simple, stupid | The simplest correct solution is the right solution |
| AP-002 | Data governance by design | Own, classify, and trace every data element from the start |
| AP-003 | Compliance by design | Every obligation satisfied by a module, not a process |
| AP-004 | Security by design | Secure by default — reducing a control requires justification |
| AP-005 | Customer driven | Customer experience metrics are engineering metrics |
| AP-006 | Cost effective | Right-sized for now; cost curve tested for scale |
| AP-007 | Evolution by design | Build to be regenerated, not just maintained |
| AP-008 | Real time where it matters | Default batch; earn real-time with a specific use case |
| AP-009 | Robust and serviceable | Operable by a small team at 2am without escalation |
| AP-010 | Modular by design | Everything has an owner, a boundary, and a contract |
Anti-principles¶
These are the patterns KISS protects you from. Watch for them.
Speculative complexity. "We might need this later" is not a justification for building it today.
Compliance theatre. Controls that generate paperwork without reducing risk. Reports nobody reads. Audit trails for decisions that are not material. Real compliance changes what the system does. Theatre is additive — it adds process without changing outcomes.
Security theatre. Access control matrices so complex that everyone ends up with too much access anyway. Security by box-ticking rather than by design.
Real-time for its own sake. Streaming pipelines for data that changes once a day. Kafka for messages that could be a database query.
Abstraction addiction. Every layer of abstraction is a layer of indirection that new engineers must understand. Some abstractions genuinely reduce complexity. Many are added because they feel architecturally clean rather than because they solve a real problem.
Resume-driven development. Choosing a technology because it is new and interesting rather than because it is the right tool. This is a KISS violation wearing a different hat.
Validating a solution against the principles¶
Use this before presenting any significant architectural decision.
| Principle | Question |
|---|---|
| AP-001 KISS | Is this the simplest correct solution? Can a new engineer understand it in thirty minutes? |
| AP-002 Data governance | Is every data element owned, classified, and lineage-tracked? |
| AP-003 Compliance | Does every policy obligation have a documented satisfaction mode? |
| AP-004 Security | Secure by default? What specific threat does each control address? |
| AP-005 Customer driven | Does this make the customer experience simpler or harder? |
| AP-006 Cost effective | Cost per thousand transactions at launch and at scale? |
| AP-007 Evolution | Could Claude Code rebuild this module from its wiki spec? |
| AP-008 Real time | Is real-time justified by a specific use case? Cost of 60 seconds of staleness? |
| AP-009 Robust and serviceable | Can one engineer resolve the most common failures at 2am without escalation? |
If you cannot answer all nine, the design is not ready.
Relationship to ADRs¶
Architecture Decision Records document how these principles were applied to specific decisions. When an ADR involves a trade-off between principles, it must name the principles in tension and justify the resolution. A decision that violates a principle without acknowledging it is not an ADR — it is a gap.
See decisions/ for all current ADRs.
Relationship to perspectives and viewpoints¶
Perspectives are evaluation lenses used to assess whether a solution meets these principles. Viewpoints are communication frameworks used to convey the architecture to different stakeholders.