Getting started

What goes where

ZestreaDB has five places to write things down, and they split into two kinds. Four are node knowledge — attached to an object — and they TRAVEL: write a gotcha on a table and it shows on that table in every flow that contains it. The fifth, a flow’s notes, STAYS: it’s about this flow at this moment, and wouldn’t be true anywhere else. Get the split right and you write each thing once, where it belongs.

1. Description (General tab) — what the object is and what it’s for.

   The one-line answer to "what is this?" a newcomer actually asks — not the column list, which they can already see.

2. Business logic (Logic tab) — the rules: how a calculation works, what a procedure does, the order things run in.

3. Gotchas (Logic tab, + Add gotchas) — what will bite you: misleading names, deliberate weirdness, the thing not to do.

   A gotcha read before someone trusts a field prevents the bug they’d otherwise ship.

4. Failure notes (Logic tab, + Add failure notes) — what to do when it breaks. Written for 2 a.m., read during an incident, not while browsing.

5. Team Notes (the flow’s inspector, Add note) — situational, about this flow right now: "moved the export to 02:30 in Q1 after it kept colliding with the warehouse sync".

   This is the one that does NOT travel — it’s true of this flow at this time, so it stays with the flow, not the object.

6. Worked example — a Payments table. Description: "one row per kiosk transaction". Business logic: "IsSuccessful is set from the partner’s confirmation". Gotcha: "IsSuccessful = 0 can be a confirmation timeout, not a real failure". Failure note: "if totals look low, check the confirmation job ran before the export". The flow’s Team Note: "the 02:00 export slot is deliberate".

   The first four ride with Payments into every flow that includes it; the Team Note stays with this one flow. That’s the whole model in one object.