Part 3 of 8 — the eleven (plus two) living documents that, kept together and current, are the definition of an internal app. Tuned for CPG.
The catalog is the set of documents that, taken together, answer "what is this system?" without anyone reading the source code. It is not a specification written once and frozen; it is a living wiki — in the Karpathy sense of a continuously, incrementally updated body of knowledge that tracks reality. Each entity is a small, focused document with a clear owner and a freshness date, maintained as code in GitHub (chapter 6) and kept honest by the Librarian (chapter 4).
The discipline that makes it work is decomposition. "The documentation" as one giant page rots invisibly — you can never tell which paragraph went stale. Split into the right entities, each one is small enough to verify, owns one concern, and can carry its own freshness signal. The question is which entities. Below is a canonical set for an enterprise internal app, tuned for CPG and grounded in PromoDesk.
---
entity: batch-processes
owner: data-platform-team
status: authoritative # draft | reviewed | authoritative
last_verified: 2026-06-20
source_of_truth: repo://jobs/accruals/ # where reality lives, if code
related_stories: [PROMO-481, PROMO-512]
---Eleven core entities cover an internal app of PromoDesk's shape. They are ordered from the most abstract (business language) to the most operational (jobs and constraints), because that is roughly the order in which a new requirement touches them.
The agreed meaning of every business term: promotion, accrual, deduction, claim, fund, lift, trade spend, settlement, key account. It is first because everything else references it — when the conceptual model says "accrual," it means exactly what the glossary says. A shared vocabulary is the cheapest defense against vague requirements: half of "we mean different things" is really "we use the same word for different things."
The business entities and how they relate, in plain language with a Mermaid ER diagram — a Promotion covers one or more Products at one or more Accounts; it accrues into a Fund; a Deduction Claim is matched to a Promotion. No tables, no types, no keys. This is the picture a key-account manager would nod along to, and the bridge between the glossary and the physical schema.
The schema of record: tables, columns, types, keys, constraints, indexes — in SQL, or the equivalent for a non-relational store. Its source_of_truth points at the migrations directory, so the Librarian can detect when the schema changed but the doc didn't. This is where "which table is settled spend in?" gets an authoritative answer.
The why behind the numbers: how accrual amounts are computed, the tolerance window for matching a claim to a promotion, how fund balances roll up, what makes a deduction "unmatched." These rules are where vague requirements hide most dangerously, because they are invisible in the schema and the screens. Documenting them explicitly is often the single highest-value entity in the whole catalog.
One entry per screen: purpose, the fields it shows, the actions it offers, which data it reads and writes, and a link to the wireframe or live route. PromoDesk's are the Promotion Planner, Fund Dashboard, Claims Workbench, and Approvals Inbox. This inventory is what lets the Analyst answer "is there already a screen for this?" before anyone proposes a new one.
The end-to-end flows and state machines: the promotion lifecycle — plan → approve → execute → settle — and the claim lifecycle from receipt to match to resolution. These are the verbs of the system, where the data model is the nouns. Most cross-cutting requirements are really changes to a process, and naming the states makes those changes precise.
One entry per job: schedule, inputs, outputs, upstream/downstream dependencies, idempotency guarantees, and failure/restart behavior. PromoDesk runs a nightly accrual-posting job and a claims-matcher. Batch logic is notoriously undocumented and notoriously load-bearing — "as-of the nightly batch" is the answer to half the freshness questions in chapter 1's table.
Every connection to the outside world: the external system, the direction of flow, the format and contract, the auth, and the failure mode. PromoDesk exports GL postings to the ERP and imports retailer deduction claims via EDI. Integration assumptions are a classic source of escaped requirements ("we didn't know the ERP rejected negative postings"); writing the contract down is cheap insurance.
Who can see and do what: identity source, roles, the permission matrix, and the approval thresholds — a promotion over $50k needs director approval; over $250k needs VP. Authorization is where "visible to whom?" requirements live, and getting it wrong is both a bug and a control failure. The Analyst consults this on nearly every request.
The qualities the system must hold regardless of feature: performance and volume targets, data retention, audit requirements, and compliance — for PromoDesk, SOX controls on financial postings loom large. NFRs are the requirements most often left implicit and most expensive to retrofit; making them an explicit entity means the Analyst can hold every new story against them.
Architecture Decision Records: why the significant choices were made — why accruals post nightly rather than in real time, why claims matching tolerates a $-and-date window. This is the institutional memory that stops teams from re-litigating settled questions, and it gives the Analyst the rationale behind a rule, not just the rule.
Two more entities are worth adding as the practice matures — they are where the requirements process leaves its own trail:
| Entity | What it holds | Why it earns a place |
|---|---|---|
Test & Acceptance Catalogdocs/acceptance/ | The acceptance criteria and test scenarios tied to each story and entity. | Closes the loop from requirement to verification; lets the Analyst reuse proven criteria. |
Open Questions / Ambiguity Backlogdocs/open-questions.md | The live list of unresolved "what" — known gaps the catalog can't yet answer. | Makes ignorance explicit and trackable instead of rediscovered every sprint; feeds the Analyst's grilling. |
That is the seven-to-twelve range from the brief: eleven core entities that define the system, plus two that document the process of defining it.
The catalog is not eleven islands — the entities reference each other, and those links are what let the Analyst trace impact across the system. A change to a domain rule touches a screen, a batch job, and an authorization threshold; the cross-links make that traceable.
The entities form a graph, not a list. The Analyst's impact-scan (chapter 5) walks these links to find everything a proposed change touches.
A decomposed, front-mattered, cross-linked catalog gives the rest of the system its leverage. The Analyst can pull exactly the entities a request touches instead of swallowing one giant document. The Librarian can verify and date-stamp entities independently, so freshness is measurable. Impact analysis becomes a graph walk. And every claim either agent makes is traceable to a specific, owned, dated document — which is what keeps the whole thing honest.
Next we make the hardest promise real: how the Librarian keeps all of this current, so the catalog is something you can actually trust.