Life Business Logic Registry

The single source of truth for Life Interiors' back-end business logic — written as three readings of the same rules: business logic for the business, developer logic for engineers, and a diagram anyone can follow.

It is a documentation-only repository. It describes how the systems behave; it does not run them and does not hold their source code.

What this registry is (and isn't)

It is:

• A canonical, dated record of the business logic behind each integration (courier approval, order sync, pricing, etc.).
• Written for every reader at once — a plain-language explanation the fulfilment/ops team can follow, the precise developer logic (rules, edge cases, reason codes, failure modes) engineers rely on, and a diagram for training and hand-over. Each is a tab; nothing is duplicated between them.
• Published as a static docs site on Cloudflare Pages so anyone can read it in a browser.

It is not:

• ❌ A place where source code lives. No integration code is stored, copied, or vendored here — entries link to the source files by path, they never contain them.
• ❌ A place that changes how any system behaves. Documenting logic here never edits the systems it describes.

How it works

1. Claude reads the integration repositories directly, read-only. To document or update an integration, Claude clones/reads that repo's code for reference only — nothing is written back to it, and no code is brought into this registry.
2. The logic is captured here as Markdown — business reading, developer reading, then the diagram — with links back to the exact source files so every entry stays traceable.
3. Only this repository is ever edited. Every other Life Interiors repository is strictly read-only. See ACCESS_POLICY.md for the full read/write rules, CONVENTIONS.md for how entries are identified, written and kept honest, and WORKING_AGREEMENT.md for asking before building anything new and who is recorded against each entry, and GLOSSARY.md for what the business's own words mean. CLAUDE.md is the short version an AI agent reads first.
4. Push → publish. Cloudflare Pages rebuilds the site on every push. See DEPLOYMENT.md.

Contents

Integrations

Seeing how it fits together

ORGANISATION-MAP.md — start here. Every documented automation laid out in the order the business moves through it — Buying · Supply · Order · Pre-Delivery · Delivery · Post-Delivery — so you can find where in an order's life something happens without knowing which integration owns it. Each row reads source of truth → the automation → where its work lands, with an arrow where one automation starts another and a Needs first line where one merely has to have run before another. Generated from the entries every build.

MAP.md — the integration map, nested beneath it. Which systems and chains each rule touches, and which rule reads or writes every field. The field view flags any field written from more than one entry, which is where integrations actually collide. It also carries a hand-maintained list of what is not documented yet, so absence from the map never implies absence in the business. See CONVENTIONS.md §11.

What every entry carries

• A business reading that answers six questions, in order — what it does · why it exists · who it affects · when it runs · how it decides · outcomes. How it decides is the whole logic at a high level, so a reader can predict a normal case without opening a single rule.
• A developer reading that both describes and proves — inputs, processing, outputs, edge cases and failure modes, plus worked examples, test cases, UAT, known limitations and known defects. A limitation is a decision; a defect is a mistake, and they are kept apart deliberately.
• A field registry split into Inputs and Outputs, rendered twice from one source: by name and meaning for the business, by id and record for developers.
• Deep links into the systems — the NetSuite saved searches and Celigo flows it runs on, one click away, in a Where this runs block above the reading switcher.
• Two clocks. Documented is when this page was written and last edited. Script created / updated is when the thing it describes last changed, read from GitHub or Celigo. A gap between them is the signal that the automation moved and the page did not. There is no version number — see CONVENTIONS.md §6.

Adding a new integration? Copy integrations/_TEMPLATE.md so every entry reads the same way. The three headings — ## Business logic, ## Developer logic, ## Diagram — are what the build splits on, so keep them exactly as written. And ask for the project owner, the developers and the department before you write — none of them is in the code (WORKING_AGREEMENT.md §2).

Layout

README.md                     What this registry is and how it works
ACCESS_POLICY.md              Read/write policy across repositories
WORKING_AGREEMENT.md          Ask before building; who is recorded on an entry
CONVENTIONS.md                How entries are identified, written & kept honest
CLAUDE.md                     Agent instructions — read first, every session
GLOSSARY.md                   Business vocabulary, one definition per term, stable IDs
ORGANISATION-MAP.md           Organisation map — the estate in order-journey order (generated)
MAP.md                        Integration map — systems, chains and field ownership (generated)
DEPLOYMENT.md                 Cloudflare Pages hosting & build
404.md                        The not-found page, built like every other page
integrations/
  _TEMPLATE.md                Starting point for a new integration entry
  shipping-automation/        Courier approval & ship-date automation
  transfer-order-automation/  Daily Overflow → Sydney backorder replenishment
  lead-time/                  NetSuite → Shopify lead-time chain (one entry per Celigo flow)
build.mjs                     Renders every .md into the public/ site (three readings per entry)
scripts/check-registry.mjs    Validates front-matter, rule IDs, anchors, terms and the three sections
DEFECTS.md                    Generated — every defect in every entry, open first
OPEN-QUESTIONS.md             Generated — everything the registry knows it does not know
TEST-CASES.md                 Generated — every documented case, in test-pack shape
registry-index.json           Generated on build — every entry, every rule, every glossary term,
                              every defect, every open question and every test case, queryable. Also served
                              from public/ for the sidebar search

Website

Published as a static docs site on Cloudflare Pages, connected to this GitHub repo — every push to main auto-deploys, and feature branches get preview URLs. See DEPLOYMENT.md.

• Build: npm run build renders every .md into public/ (the Pages output directory).
• Deploy: automatic on push — main → production, a feature branch → preview.