Glossary

Short definitions of terms that appear repeatedly across the handbook. Listed alphabetically.

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.

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 — One legal entity. Carries enabledProducts (Payroll, Bookkeeping, or both), bookkeepingConfig, materiality threshold, and a list of contacts.

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 — Either PAYROLL or BOOKKEEPING. Many entities (Cycle, Batch) are scoped to one product; some (Client, File, AuditEvent) are shared.

Staff user — An internal Spade ops user (Payroll Executive, Lead, Bookkeeper, Senior Accountant, Platform Admin).

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 Spade 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.

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.

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.