Five levels of immersion in a complex system

When all levels of context are mixed together

What prevents you from seeing the overall picture when every detail is available at once?

An ordinary repository does not separate information by scale: business areas, operations, data models, call order, infrastructure, and individual lines of code are all presented at once. Working memory has to hold facts from different levels and reconstruct the relationships between them on its own. Attention keeps switching between the structure of the system and local details, so understanding falls apart quickly after a break.

First, a map of responsibility

Where does responsibility live?

The first pillar is a map of responsibility. It gathers controllers, services, data models, infrastructure adapters, and call chains around the system's major areas — a frame to which operations, data, and code can then be attached.

Domains divide the system by durable areas of responsibility rather than by technical layers: orders, payments, communication, and analytics. Hundreds of equal-looking files give way to the first observable topology.

The map becomes a catalog of capabilities

What can the system do?

The domain map shows where responsibility lives, but it does not yet say what the system can do. To answer that, each domain opens into a catalog of Actions — named capabilities it provides to the rest of the system.

An Action is a named public capability of a domain. The catalog shows not internal functions but the operations a domain provides to the rest of the system, along with the directed relationships between them. Each Action becomes a single point of invocation: the caller picks the capability it needs by meaning, instead of assembling the operation from separate methods.

Fix the operation boundary

What does the operation require and promise?

The capability already has a name and a place in the system. To use it as a black box, we need to know exactly which data it accepts and which result it promises to return.

A Contract makes the Action boundary typed and unambiguous. Params describe everything the operation accepts; Result describes everything it must return. Calling code depends on that promise, not on the internal shape of the Action. The implementation can change as long as input, output, and observable behavior remain compatible.

Unfold the operation into a scenario

How does the scenario unfold?

The contract fixes the beginning and end of an operation, but it does not show how one becomes the other. To see that, we unfold the internal flow of the business scenario.

A Pipeline makes the main business scenario linear and visible: validate the input, reserve inventory, charge payment, and assemble the result. That does not mean errors, branches, and compensations do not exist; they receive an explicit place relative to the main line. Every step also has a local contract: it declares what it reads from Params, State, and Context, and what it adds to State for later stages.

Only now, the concrete behavior

Where does the concrete behavior live?

The Pipeline locates the required behavior precisely and sharply narrows the search area. We can now open not the entire repository or even the entire Action, but one step whose purpose, input, and output are already known.

Code is the fifth level not because details are unimportant, but because they are now surrounded by meaning. We know which domain owns the behavior, which capability the Action implements, what the Contract promises, and where reserve_inventory sits in the Pipeline. The implementation reads as a local answer to a concrete task rather than an entrance to an endless investigation of the repository.

@regular_aspect("Reserve inventory")@result_string("reservation_id", required=True)@context_requires("user.tenant_id", "env.inventory_region")async def reserve_inventory_aspect(    self, params, state, box, connections, ctx):    inventory = box.resolve(InventoryResource)    reservation_id = await inventory.reserve(        tenant_id=ctx.get("user.tenant_id"),        region=ctx.get("env.inventory_region"),        items=state["validated_items"],    )    return {"reservation_id": reservation_id}

The five levels do not hide code or reduce the system to a diagram. They preserve the path from the overall model to a concrete detail. A newcomer builds context progressively, an architect manages grammar and boundaries instead of every file, and an AI agent performs local work within declared rules: people design the language of the system, and the machine acts in that language.