The architecture overlay

Domain and application modeling describe how the system is built — the aggregates, the commands, the events. The architecture overlay describes what the system is, as a product: the capabilities it offers, the systems that supply them, the way those capabilities are packaged for each audience, and the flows a persona walks to reach a goal. It is a set of lenses laid over the same model you already authored — not a second model to maintain by hand.

There are three lenses, and they render from one set of constructs:

This manual covers the supply side — capabilities, systems, features, and UI surfaces. The companion Business Process & Journey Modeling manual covers the demand side — the actors and the flows that require these capabilities.

Capability and feature are two different things

The single most important distinction in the overlay — and the one to get right before anything else:

• A capability is an engineering construct. It is a durable, implementation-independent statement of what the system can do — "check out an order," "reserve stock," "browse the catalog." You build capabilities. They are the primitives.
• A feature is a business construct. It is a way to package capabilities for consumption — how a capability is presented to an audience, segmented by who it's for and how mature it is, and (when it's paid) gated behind a plan. You build capabilities first, then package them into features.

You will see this layering made concrete throughout: a system provides capabilities (the engineering supply), and carries features that package those capabilities for a consumer (the business surface). A paid feature points back at the capability it gates with requires_capability. Keeping the two straight is what keeps "what we built" separate from "what we sell."

The capability is the hub

Everything on the supply side connects through the capability:

flowchart LR
  J[business_process step] -->|requires| C((capability))
  SYS[system] -->|provides| C
  UI[ui surface] -->|exposes| C
  F[feature] -.->|requires_capability<br/>·when entitled·| C
  R[route / subscription] -->|implements| UI

• A business_process step states its demand: requires [Capability] (see Business Process & Journey Modeling).
• A system states its supply: provides { Capability … }.
• A UI surface states its access: exposes [Capability].
• A route or subscription realizes a surface: implements <UiSurface>.

Crucially, a business process never names a system or an operation. Which system realizes a step is derived from the capabilities the step requires — match requires against every system's provides, and the provider falls out. That derivation is what keeps the plan (the flows) free of implementation topology, and what makes the overlay reconcile rather than drift.

One running example: the Chowk marketplace

Every example in this manual is drawn from Chowk, a demonstration marketplace that is a real, compiling Vishwakarma project. Chowk's overlay lives — by convention — in a _precise/ directory per sub-domain:

sub-domains/ordering/_precise/
├── capabilities.vishwakarma        # the engineering primitives (DEMAND vocabulary)
├── systems.vishwakarma             # what provides them         (SUPPLY)
├── ui.vishwakarma                  # how they're reached        (ACCESS)
├── business_processes.vishwakarma  # the flows that require them (FLOW — see Business Process & Journey Modeling)
└── journeys.vishwakarma            # the arcs that compose them  (FLOW)

Keeping the overlay in its own _precise/ folder separates what the product is from how it's built (the entities and commands in the sibling folders), while both compile into one model. The pages that follow build the supply side up from the bottom: Capabilities, then Systems and Composition & roll-ups, then Features, then UI surfaces.