A methodology for architecture
Capability-Driven Design decomposes a system not by team, technology, or service, but by capability — a mandate-backed business function that owns its data, exposes a curated API to the channels that call it, and speaks to its peers only through events. Everything else is derived from that one commitment.
A capability is not a service, a team, or a database. It is a business function the organisation is mandated to hold — and it is the primary unit around which the whole architecture is organised.
A capability is a mandate-backed business function — the primary unit of architectural decomposition.
A capability owns one or more databases or schemas, invisible to every other capability. No shared stores, no shared entities, no reaching into another capability's persistence.
It exposes a single curated REST API for channels to call, and publishes events on a shared bus for peers to consume. You share contracts, never implementations.
Capabilities change only when the mandate changes. Technology is derived from the capability's requirements — never the reverse.
A capability is sized to fit an AI agent's context window. This is the primary decomposition constraint — small enough for one agent to hold whole.
Every capability is researched against its competitive landscape and regulatory horizon before it is drafted. A list derived from the org chart produces a shallow architecture.
The method produces a headless system specification. Channel UIs sit outside the system boundary and consume capability APIs — a separate development concern.
A capability file is not a paragraph of description. It is a structured bundle that forces the questions of mandate, competition, regulation, and rationale to be answered before a line is built.
The statutes, regulations, policies, charters, or strategic decisions that explain why the organisation holds this capability. At least one source, always.
Where the organisation sits relative to others offering the same capability: table stakes, differentiators, disruptors, unbundling, rebundling, switching drivers.
What is currently in force, what is coming in the next two to three years, and which enforcement signals matter.
Which elements must be built in-house and which should be bought from vendors — an explicit position, not an accident of tooling.
The bounded areas of responsibility that compose the capability, each carrying its own promotion test.
Architectural choices with rationale, alternatives considered, and why those alternatives were rejected. No silent deviation.
Revenue model is intentionally not part of the bundle. The capability file describes what the capability is; commercial analysis is a separate concern.
Every sub-capability is evaluated against four boolean criteria. The count of trues decides whether it stands on its own — with a documented override the only escape hatch.
Does it involve actors absent from the parent's other sub-capabilities?
Is it governed by a materially distinct body of rules?
Does it have phases of operation that appear nowhere else?
Do its demand drivers vary independently of the parent?
The prima facie rule. Each criterion is a boolean; criteria_met is the count of trues. If three or more are true, promote the sub-capability to a standalone capability. If fewer, retain it.
Overrides are permitted — a 3-of-4 may be retained, a 2-of-4 may be promoted — but the parent capability's design decisions must record the reasoning. No silent deviation.
These are not style guidelines. They are structural invariants the model checks — the boundaries that keep capabilities independent and the system composable.
Every capability publishes an OpenAPI spec. Customer, partner, and external systems reach it only through that contract.
Every capability publishes an AsyncAPI spec of the events it emits on the shared bus. Peers subscribe; they do not call the REST API.
Each service inside a capability publishes its own OpenAPI spec for intra-capability calls and an AsyncAPI spec for the events it publishes and consumes.
Every sub-capability belongs to exactly one parent. If two capabilities seem to need the same one, either promote it or accept they solve different problems that merely sound alike.
If capability A needs data owned by B, A subscribes to B's events. Share contracts, not implementations.
Every DS-XXX belongs to one capability. Every entity lives in exactly one store, whose data classification equals or exceeds every entity it holds.
The data model lives with the capability that owns it. Journeys reference entities by ID; they do not define them.
End-to-end latency and regulatory SLAs are journey-scoped. Per-service SLAs live on the technical-service spec and compose into the journey target.
A journey initiates many sequences, each attached to a phase. There are no capability-level or service-level sequence diagrams.
Everything a capability can legitimately do to reach the outside world reduces to these.
Channels and external consumers call the capability's published OpenAPI contract.
Capabilities emit and subscribe to events on the shared bus — the only path between them.
Services within one capability call each other over their own OpenAPI specs.
Services publish and consume events via their own AsyncAPI specs on the bus.
The meta-model is a sector-neutral set of JSON Schemas. A sector pack supplies concrete content that validates against them. Everything below is a first-class, versioned artifact — grouped here by the scope that owns it.
| Prefix | Meaning | Format |
|---|---|---|
| CAP-XXX | Capability | 3 digits |
| SUB-XXX | Sub-capability | 3 digits |
| JRN-XXX | Journey | 3 digits |
| PH-XXX | Phase (within a journey) | 3 digits |
| PER-XXX | Persona | 3 digits |
| CHN-XXX | Channel | 3 digits |
| SVC-XXX | Service | 3 digits |
| ENT-XXX | Entity | 3 digits |
| DS-XXX | Data store | 3 digits |
| EVT-XXX | Event | 3 digits |
| GOV-XXX | Governance rule | 3 digits, optional sub-rule |
| DD-XXX | Design decision | 3 digits |
| SEQ-XXX | Sequence diagram | 3 digits |
Prefixes are conventions, not hard schema requirements. A pack may override them; the schema regex patterns move with it.
Artifacts are produced by a three-phase pipeline with quality gates between them. Each stable journey model is a single buildable vertical slice — handed to development, one at a time.
Sequential, done once. Research-led — the market and regulatory landscape is captured before any artifact is drafted.
Sequential, done once. The system is drawn at the context and container level, and the work is enumerated and prioritised.
Iterative, per journey in priority order. Each journey is scaffolded, modelled end-to-end, then reviewed against the invariants.
A stable journey model is one buildable vertical slice. It becomes a deliverable in the development project. Channel development is a separate concern consuming the capability APIs.