Overview

Functional decomposition of the system into Domains, Modules, Services, and Endpoints. The criteria for each level — what defines a Module versus a Service versus an Endpoint, the canonical naming rules, and the URL formula — are documented in Functional Decomposition. The top-level diagram below shows the present-day grouping; the per-Domain pages give the detail of what each Domain contains.

Note

The diagram above predates the module reorganization and still shows Stations, Loops, Operators and Dispatch as separate modules. Stations and loops are now the Processing Network; operators are covered by Staff. Take the domain grouping from the diagram and the module list from the sections below, which are current.

Domains

The functional Domains of the system. The Domain canonical names use kebab-case lowercase; the per-Domain pages below catalog the Modules in each Domain. The demand-to-supply domains appear in The Domain Map below; system and shop-access are platform concerns outside that map.

Domain canonical	Pages	Modules covered
receiving	Overview	Receiving
procurement	Overview	Orders
operations	Overview	Demand
resources	Overview	Kanban Cards, Inventory Items, Processing Network
reference (folder: reference-data)	Overview	Item, Business Affiliate, Staff
system	Overview	User Account, Tenant, AgentFor, Invitation (in the accounts-component); Batch (embedded inside operations)
shop-access	(see Modules below)	PDF Render (in-pod consumer only); Email (per-tenant transactional email)

The Domain Map

The domains of the demand-to-supply chain this documentation set covers run from the shop floor’s pull signal down to the reference data everything else points at. Each domain depends only on domains below it in the map — nothing calls into, or knows about, anything above it. A higher domain may call a lower one directly, along the dependency arrows (an order starts production on its demand items in Demand); what happens in a lower domain reaches the domains above it only as an observable notification that travels back against the arrows (see Everything is Observable below), never as a call upward. The module-level picture lives with each module: every module page opens with a Context section drawing its own clients and servers.

In map order, top-down:

• Receiving — the capture surface where material arrives: recording what showed up, birthing inventory at the dock, and attributing receipts back to the orders they satisfy.
• Procurement — agreement documents with outside parties: composing, committing, and closing out the orders that obtain materials from suppliers.
• Operations — the running work of manufacturing and logistics: collating shop-floor demand into demand items and tracking production against them.
• Resources — the operational assets the shop floor works with day to day: kanban cards and their laps, inventory custody, and the network of stations and loops.
• Reference data — the slowly-changing records everything else points at: items, business affiliates, and staff.

Consumers hold version pins on reference data, so committed documents permanently show the records they were agreed under — the shared discipline is the Reference-Data Module Pattern.

Everything is Observable

Most modules in this decomposition announce the actions recorded against their entities, and any other module can listen and react to them — including modules that aren’t allowed to call it directly, because a lower module in the map above never calls into a higher one. This is how, for example, a demand item in Demand can hear that a kanban card’s trip ended, or an order can hear that material was received against a demand item it depends on, without either module reaching upward into the one that knows about it. Each module’s own page lists only the notifications that carry business meaning for its neighbors: what it announces, and what it listens for. Participation is selective: Inventory Items has no notification wiring at all — Demand calls it directly, as an injected service (see its data model); Staff and Processing Network announce nothing and listen for nothing; and Item, Business Affiliate and Orders announce no business notifications of their own.

Scenarios

The domains above are exercised together, not one at a time. The Business Flows section walks end-to-end flows across several domains and the personas around them, ranked in descending order of business value — starting with FLOW-0001 — The Pull-Replenishment Round Trip, the round trip the product exists to run. Each scenario is a value-ordered tour through behavior the per-module pages specify.

Modules and Endpoints

The full per-Endpoint table — every Endpoint published today, with canonical URL, current URL, and collapse pattern — is the Endpoints at a glance appendix in the API Endpoint Catalog. The per-API operation listing in the catalog body shows the actual published routes.

Shop Access

shop-access does not have a dedicated index.md of its own — the per-Module pages link directly:

• PDF Render — In-pod printing capability consumed by Item and Kanban. No public REST surface today.
• Email — Per-tenant transactional email through Postmark. The Email Module is in flight on PR-#182; it ships with the canonical URL shape /v1/shop-access/email/... per Functional Decomposition. Three Endpoints: Configuration, Job, PostmarkEvents. See the API Endpoint Catalog for the operations exposed.

Authentication

Authentication is a cross-cutting concern rather than a functional Domain. See Authentication for the JWT, OAuth2, Cognito, and realm/permission infrastructure.

Frontend

Frontend patterns and conventions are documented in Frontend Patterns.

Everything is Observable

Modules depend on each other in one direction, and that direction is the architecture’s spine: a module may call the modules it depends on and must not call the ones that depend on it. Operations run along that direction. Notifications run against it.

An operation is invoked: a caller names a module and asks it to do something, so the caller knows the callee. A notification is announced: a module states that something happened, and the modules that care react without being called. The announcer does not know its listeners and does not wait for them. That is what keeps the dependency direction intact while still letting information travel back up it.

The consequence is the name. Any change a module considers meaningful is observable by any other module, without the announcer acquiring a dependency on the observer. A new consumer of an existing announcement costs the announcing module nothing — it does not change, and it does not learn that the consumer exists.

Two things follow that are easy to get wrong. A notification is not a request: nothing about it obliges a listener to act, and a module that needs an answer must call rather than announce. And a listener reacts to what the announcement carries, rather than calling back to ask what happened — a listener that re-reads the announcer has quietly reintroduced the dependency the notification exists to avoid.

In the sequence diagrams throughout these pages, a solid arrow is an operation and points along the dependency direction; a dashed arrow is a notification and points against it.

For how this is implemented — post-commit dispatch, transaction boundaries, and the traps around cascades — see Observer Patterns.

Related Pages

• Business Flows — End-to-end flows showing users obtaining value across the domains, ranked by business value.
• Module Status — Where each module stands between the design described here and the runtime today.
• Glossary — The model-defined vocabulary these pages use, one definition per term.
• Functional Decomposition — Criteria for each level of the hierarchy and the canonical naming rules.
• Module Concept — Module-level deep dive.
• Component Concept — How Modules are packaged into deployable Components.
• API Endpoint Catalog — Concrete URLs published today.
• Data Models — Reading guide for the per-module data-model pages: stored versus projected shape, and the record envelope they share.
• The Orders v2 Call Shape — The request/response convention nearly every call follows, and the one module that predates it.
• Legacy State — Divergences between the canonical naming and the live system’s URLs, plus the cardinality-transition and collapse-rule mechanics that govern Module evolution.