Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
Business Logic Patterns — Where Every Rule Goes
Every business rule has one correct home in the primitive stack. This page is the placement guide: the decision procedure, the map, and four worked examples (sales tax, payment aging, dunning, refunds) that most systems get wrong. The placement decisions and their reasons accumulate in logic-decisions.md, the way UI behavior accumulates in ui-decisions.md.
The method behind all of it (see logic-decisions #4): build each module's rules concretely in the cheapest correct primitive — a hook is three lines of real code — and only promote a pattern to a declarative schema key after it has repeated in two or three real modules. Concrete → pattern → primitive, never primitive-first. Systems that build the workflow/rules engine first die when reality doesn't fit it; ours extracts engines from reality.
Where does this rule go?
flowchart TD
Q["a business rule"] --> D1{"Derivable from<br/>stored data?"}
D1 -->|same record| F["formula field"]
D1 -->|child records| R["rollup field"]
D1 -->|no| D2{"Does it GATE<br/>a write?"}
D2 -->|shape / bounds / FK| V["schema validation"]
D2 -->|legal state moves + who| T["transitions + when guards"]
D2 -->|cross-record or computed gate| H["pre-write hook<br/>(reject or stamp)"]
D2 -->|no| D3{"Does TIME<br/>cause it?"}
D3 -->|yes| DM["daemon: scheduled pass /<br/>auto-transition"]
D3 -->|no| D4{"Is it a REACTION<br/>to a change?"}
D4 -->|notify / email| N["notify_rules (after write)"]
D4 -->|run code| TR["trigger → target object"]
D4 -->|external system| C["connector<br/>(desired state + reconcile)"]
D4 -->|no| O["plain object<br/>(page / API / worker)"]
The placement map
| Kind of rule | Primitive | Lives in | Example |
|---|---|---|---|
| Shape, type, bounds, enum, FK-exists | schema validation | object_records write path | amount is integer cents; project must exist |
| Same-record derivation | formula (materialized) | object_computed via object_records | tax_cents = amount_cents * tax_rate |
| Aggregation over children | rollup (materialized, live) | same | invoice.paid_cents = sum(payments) |
| Legal state moves, and who may move | transitions + when | object_records | draft → posted, owner only |
| Cross-record gate, computed gate, point-in-time stamp | pre-write hook | hooks.before_write → object_server write path | journal must balance; stamp tax_rate |
| Time-driven state | daemon scheduled pass / after_hours auto-transition | object_daemon | sent → overdue when past due |
| Reaction: notify, email | notify_rules | daemon, after the write | dunning email on overdue |
| Reaction: run code | trigger → target object | daemon | recompute, follow-on records |
| External side effect | connector | desired-state records + reconcile | payment-provider refund call |
| Correction to money / inventory | append-only compensating record | storage: append collections | refunds, stock moves, journal reversals |
| Everything else | a plain object | anywhere | bespoke report, integration, one-off page |
Two hard boundaries hold the map together:
- Gates before the write; reactions after. A hook may reject or stamp but
never send email or call out — a gate with side effects leaks that a write was attempted and couples saves to SMTP. A reaction may notify or spawn work but never block the write that already happened. (event-hooks-decisions.md)
- Derived values are non-authoritative; gates are authoritative. A broken
formula stores "" and the write succeeds; a broken hook fails closed and the write is rejected. Never let a gate read only a derived value it could recompute — the journal-balance hook sums the lines itself even though rollup totals exist.
Worked example 1: sales tax (the one everyone leaves out)
Why it's left out: it hides a doctrine most systems never articulate — stamp point-in-time facts; derive live facts (logic-decisions #1). The tax rate is a fact about the transaction moment: rates change, and the invoice must forever carry the rate it was issued under.
- Rates are data: a
tax_ratescollection —region,category,
rate, valid_from. Editable like any records; history visible.
- Stamping is a hook:
hooks.before_writeon invoice lines looks up the
applicable rate and stamps tax_rate onto the line — same posture as the server stamping owner_id. The client never supplies it; later rate changes never rewrite history.
- Amounts are formulas/rollups: `line.tax_cents = amount_cents *
tax_rate (formula); invoice.tax_total_cents` (rollup). Materialized, so they appear on every list/detail/report and update live.
Worked example 2: payment aging (time makes the state)
The trap: an invoice becomes overdue with no write happening — time did it. Any system that computes "is it late?" ad hoc in the UI grows a dozen disagreeing copies of that check.
balance_centsis a rollup (total_centsminussum(payments)).sent → overdueis a daemon scheduled pass through the ordinary
transition machinery, when due_date < today and balance_cents > 0 — so the state is stored, permission-checked, realtime-pushed, and every surface agrees (logic-decisions #2: time-driven state belongs to the daemon, never to read-time checks).
- Aging buckets (30/60/90) are a rollup/report over stored state.
Worked example 3: dunning (reactions compose on state)
Dunning is nothing new — it is the composition of the two layers above:
- The daemon flips the state (
overdue, lateroverdue_30, …). notify_rulesreacts: state change → email template to the invoice's
contact. The rule is data; the daemon delivers after the write.
- Escalation ("again at 30 days unless paid") is more time-driven state,
not a special notification feature — each escalation step is a transition the daemon makes, each with its own notify rule.
Worked example 4: refunds (money moves, never mutates)
Money never mutates; it moves (logic-decisions #3). A refund is not an edit to a payment — it is a new, append-only compensating record, exactly like a stock move or a journal reversal.
refundsis anstorage: appendcollection pointing at the payment.- The invariant is a hook:
refund ≤ payment − prior refunds— a
cross-record gate, summed from the records themselves.
payment.refunded_cents/net_centsare rollup/formula — display
truth, derived.
- "Correctly credited" is the balanced journal entry the refund composes —
enforced by the journal-balance hook that already ships. The chain closes: append-only record → hook invariant → rollup display → balanced books.
Worked example 5: inventory shrinkage (the events nobody codes for)
Waste, breakage, theft, expiry, damage, disaster: systems are easy to build when quantities just flow buy → stock → sell; real usage is losses. Naming them is the point — "adjustment" is the euphemism that hides exactly what operators and auditors need to see.
- Losses are movements (logic-decisions #3): a loss is an append-only
stock move with a loss reason, out of a location, to nowhere — never an edit to an on-hand number (levels stay derived).
- The hook stamps and gates:
unit_cost_centsis stamped from the
product at the moment of movement (#1 — tomorrow's cost edit must not reprice yesterday's loss); a loss must leave a real location and can have no destination.
- The composer books the shadow: a loss move composes a posted journal —
DR shrinkage-expense / CR inventory-asset — with per-reason account overrides as settings (theft to its own account for the insurance claim).
- Count reconciliation is the same machinery: a physical count writes
one compensating adjustment move for the variance (out for shortage, in for overage) plus the mirror journal. The count is an event, not an edit.
This was also the composer pattern's third repeat, which triggered the doctrine-#4 extraction: every generated journal now goes through object_finance.compose_posted_journal (idempotent by generated_from, verify-then-post), and the payment/refund/recurring/reversal composers shrank onto it.
Worked example 6: bank reconciliation (evidence, not data entry)
Comparing the books to a bank statement is the strongest practical control a small business has, and the reason is not arithmetic — it is that the bank's copy was written by someone with no stake in our numbers. Every design choice follows from protecting that independence (logic-decisions #8).
- Imported lines are append-only and keep their original text in
raw;
parsed fields are a view of it. A pre-write hook makes the factual fields immutable on update — corrections come from re-importing a corrected statement, never from editing a line to agree with the books.
- The statement checks itself. Opening + lines = closing (tie-out), and
this opening = the last statement's closing (continuity). Both run at import and set the import's status; a truncated or edited file fails arithmetic. The flags record which checks ran, so a balance-less CSV never reads as trustworthy as a verified one.
- Reading a bank's format is data, not code: a saved column map,
authored once with AI help and executed deterministically thereafter. AI at configuration time, code at run time — a control cannot be nondeterministic.
- The matcher proposes; a person disposes. Suggestions are derived and
non-authoritative; confirming is an ordinary attributed update, so the change log names who reconciled what. Only a two-signal match (reference and amount) is auto-confirmable, and even that is configurable to off.
- The unmatched tail is where the business logic lives: fees, interest,
own-account transfers, NSF bounces — each a resolution verb composing a posted journal through the shared composer, stamped with the line's id so resolving twice books once. These are exactly the entries small books never record, which is why their cash balance drifts until they stop reconciling at all.
State-dependent behavior generally
transitions + when guards define the machine; the board's drag is its UI; hooks gate specific moves with computed conditions (the balance check gates draft → posted); the daemon makes time-based moves. The known missing declarative is "state freezes fields" (a posted invoice's amounts are immutable). Per the method: express it in each module's hook first; promote it to a schema key (locked_when) only after the shape repeats (logic-decisions #5).
What this implies we build next
The examples above want one substrate piece that doesn't exist yet: a payments collection (plain records — provider integration is a connector later). It unblocks aging, dunning, and refunds at once. Then: tax_rates + the stamping hook; then a delay/repeat notion for notify_rules if escalation schedules outgrow "each step is its own transition."
Related
validation-and-logic.md— the enforcement
reference for each primitive (validation table, hooks contract, formulas/rollups, the automation substrate).
logic-decisions.md— the living log of placement
decisions and doctrines.
storage-modes.md— append-only collections, the
substrate for money-moves.