Glossary
Short definitions of terms that appear repeatedly across the handbook. Listed alphabetically.
The hierarchy
Tenant — The top-level isolation boundary; a firm. Every record belongs to exactly one tenant, enforced at the database. Tenant 0 is Spade itself. See the platform model.
Group — A client relationship: a family of companies under one account manager. A group-scoped login sees the whole portfolio.
Entity — A legal company. Carries incorporation date, financial year end, GST status, officers, shareholdings, addresses, and product subscriptions. Module artifacts (cycle, batch, engagement, filing) attach here.
Branch — A branch or representative office of an entity.
RLS (row-level security) — The database mechanism that makes tenant isolation absolute: queries only return rows for the current tenant context; with no context, zero rows. Not an application-level filter.
Product subscription — The record on an entity that enables a product (Secretarial, Bookkeeping, Payroll, Tax, FS, XBRL, …). Drives which nav and intake appear for that entity.
Cross-cutting
Action — A fine-grained permission verb (e.g. MANAGE_CYCLE, APPROVE_JOURNAL). Every API route and sidebar nav entry is gated by an Action. See packages/auth/src/rbac.ts for the full enum.
Agentic harness — The platform substrate that runs agent-prepared work: durable, resumable runs made of steps (LLM, tool, form, rule, human-in-the-loop), producing proposed actions that are routed for a human decision. See The review inbox and the human gate.
Run / step — A run is one execution of an agent workflow for an entity; a step is one unit within it. Steps record the model, prompt version, tokens, cost, and latency.
Proposed action — A change an agent has prepared (a filing, a dispatch, a posting) that does not take effect until routed and, where regulated or external, approved by a human.
Review task — An item in the review inbox asking an operator to approve, edit, or reject a proposed action. The concrete form of the human gate.
Human gate — The rule that no regulated or external action happens without a human operator's approval.
Audit event — An immutable log row recording a state change with actor, timestamp, and payload. Append-only. Surfaced under the Audit tab of any cycle / batch / client.
Client contact — A natural person at the client side (HR rep, FC, director). Receives magic-link invitations to act on the client surface. See Magic link.
Magic link — A short-lived JWT token (48h) sent over email, hashed in the database. The [token] page route exchanges it for a session scoped to the chosen product (intake / approval / unreconciled-items portal).
Outbox — The append-only event log driving outbound effects (emails, integrations). The outbox-poller worker job dispatches it. The Outbox UI page surfaces what's been sent.
Product — A module the platform ships: Payroll, Bookkeeping, Financial Statements, XBRL Filing, Correspondence (live), with more on the roadmap. Many artifacts (Cycle, Batch, FsEngagement, XbrlFiling) are scoped to one product; the hierarchy, files, audit, and notifications are shared.
Staff user — An internal BreezyCorp ops user. Eleven staff roles (plus two client-contact roles) — see Roles & permissions.
Payroll-specific
Cycle — A monthly artifact for one client (e.g. ACME's April-2026 cycle). Moves through 16 states. See Payroll cycle status machine.
Submission — The client's intake for a cycle. Versioned (version_no); a revision creates a new submission rather than overwriting.
Issue — A validation finding on a submission. May be BLOCKING (must be resolved or overridden) or WARNING.
Export — The Infotech import workbook generated from a validated submission. Versioned per cycle.
Output — The Infotech-produced workbook (payroll register), uploaded back into BreezyCorp after Infotech runs payroll.
Approval round — One iteration of client approval. Cycles can have multiple rounds if revisions are requested.
POL approval — Proof-of-Life approval: a Payroll Lead's override authority for a blocking issue, recorded in the audit log.
Bookkeeping-specific
Batch (Journal batch) — A grouping of journal entries for one client and processing period (typically monthly). Has its own 5-state lifecycle. See Journal batch states.
Journal entry — A single double-entry posting (debit + credit) drafted from a document. Has its own 5-state lifecycle including FLAGGED and ESCALATED.
Classification — Mapping an extracted document to a chart-of-accounts code. Three-tier confidence: HIGH (vendor-master match), MEDIUM (CoA keyword match), LOW (keyword + vendor missing) → UNCLASSIFIED if all fail.
Chart of Accounts (CoA) — Per-client list of account codes and their keyword triggers. The classification engine matches against this.
Vendor master — Per-client list of vendors with default account codes. A vendor-master match auto-confirms HIGH confidence.
Financial-statements-specific
Engagement — A per-financial-year project for one client (e.g. ACME's FY2024 statements). Carries reporting standard, year-end date, functional currency. Moves through 7 states from DRAFT to ARCHIVED. See FS engagement status machine.
Trial balance — The accounts and balances at year end, ingested from a CSV/XLSX. Each row is normalized to debit-positive and (after mapping) carries a SFRS taxonomy key.
SFRS taxonomy key — A stable identifier (e.g. cash, ppe, revenue) drawn from the constitution sfrs_taxonomy.json. Maps a TB account to a financial-statement section + sign + presentation order + note trigger.
Disclosure interrogation — A rules-engine pass over the constitution disclosure_rules.json. For each rule whose trigger_condition fires (e.g. tb_contains_any(['ppe'])), the system asks the preparer the rule's prompts. The answers feed the corresponding note.
Mandatory policy — Verbatim accounting-policy text (Income Tax, Employee Benefits, Provisions) that must appear in every set of statements regardless of TB content. Stored as markdown under packages/financial-statements/constitution/mandatory_policies/. Never paraphrased.
SOCE — Statement of Changes in Equity. One row per equity movement (opening, profit, share issue, closing); columns auto-omitted when the underlying TB component is zero in both years.
XBRL-specific
Filing — One ACRA XBRL submission for a client + period. Has its own 8-state lifecycle and pins a taxonomy_version (e.g. acra_2026_v1) at creation. See XBRL filing status machine.
Entry point — The ACRA filing template applicable to the entity: FULL_XBRL, SIMPLIFIED_XBRL, FSH_BANKS, FSH_INSURANCE. Drives which subset of the 1871 taxonomy elements is in scope.
Element — One taxonomy item. Identified by an element_id like sg-as_TotalAssets. Carries data_type, period_type (duration for flow statements, instant for balance sheet), balance (debit / credit), entry-point applicability, and minimum-requirement flag.
Tag mapping — The link from a parsed line item to one element. Always created with confirmedById = NULL by the suggestion engine; must be confirmed by a staff user before any export is allowed.
Mapping library — A writable seed file of (label → element_id) synonyms. Shared across all clients. New entries are restricted to XBRL Reviewer / Senior Accountant / Platform Admin and every write is audited.
Validation rule — One of 144 ACRA business rules (categories: arithmetical, totalling, cross-statement, mandatory-disclosure, sign-convention, format, custom). Severity is error / warning / info; only error + passed=false blocks export.
Export gate — The hard guard on EXPORT_BIZFINX and EXPORT_XBRL_XML. Returns HTTP 422 unless: validation has been run, no error-severity rule failed, and every tag mapping is confirmed. Implemented as assertExportAllowed in @breezycorp/xbrl/src/export-gate.ts — no override path exists.
The five non-negotiable rules — Architectural invariants ported verbatim from the source xbrl-saas/cursorrules: (1) no taxonomy element literal outside the loader, (2) no XBRL output without passing validation, (3) every mapping human-confirmed, (4) taxonomy version is first-class and pinned per filing, (5) regression suite gates every push.
Upload file — The CSV / IIF / XML artifact ready for manual upload into Xero / QBO / Zoho / Tally. The accountant downloads it and posts it themselves.
Reconciliation run — One pass at matching a bank statement to journal entries. Has six states. See Reconciliation run states.
Match types — EXACT (date + amount + reference auto-confirmed), PROPOSED (amount + date within tolerance, needs reviewer confirmation), or no match (creates an unreconciled item).
Unreconciled item — A bank transaction that didn't match a journal entry. Has 3 states (PENDING → CLIENT_RESPONDED → RESOLVED). Sent to the client via the magic-link portal.
Materiality threshold — Per-client SGD threshold below which variances are treated as non-material in reports. Configured on the Client record.
Ingestion channel — A source for inbound documents: WhatsApp inbound, Google Drive folder sync, email drop, manual upload. Configured per client.
Correspondence-specific
Correspondence document — One piece of incoming mail pulled from the firm's mailbox, stored as a PDF and tracked through OCR, classification, client matching, review, and dispatch.
Client match — Resolving a correspondence document (or a split item within it) to the right client, optionally via Odoo res.partner. A confident match auto-fills; an ambiguous one waits for an operator.
Dispatch mode — How clean items leave the queue: item_ready (send each clean item as soon as it's ready) or document_complete (send only once the whole document is done). Configured by a Correspondence Reviewer.
Grace window — A delay before dispatch, giving an operator time to intervene before mail goes out.
Status machine shorthands
When you see EXPORTED in a cycle list and EXPORTED in a batch list, those are different states from different enums. Use the status machine pages when in doubt.