Userflows
End-to-end manual-test playbooks, one MD per flow, for all four BreezyCorp products. Each playbook is self-contained: it lists the actor, prerequisites (seed data references), step-by-step click path, the API contracts it exercises, and the DB / mailpit / S3 verifications you should expect at every step.
Use these whenever you are:
- onboarding to the codebase and want to walk a single feature without reading the whole testing guide
- writing or reviewing an integration test and need a canonical trace
- triaging a bug — match the failure to a flow and follow the verification points
- demoing a specific capability to a stakeholder
One-shot setup of every dependency the playbooks expect:
_shared/00-environment-setup.md. Run that once per machine; everything else assumes it.
Source-of-truth SOPs
The flows are derived directly from the SOPs and trace each numbered step back to a section anchor:
- Payroll —
docs/sop/Payroll_Processing.md - Bookkeeping —
docs/sop/SOP_AI_Bookkeeping_Automation.md - Financial Statements —
docs/sop/SOP_Financial_Statements.md - XBRL Filing —
docs/sop/SOP_XBRL_Filing.md - Immigration —
docs/sop/SOP_Immigration_Applications.md
If a playbook diverges from the SOP, the playbook is wrong — file a ticket against the playbook, not the SOP.
Payroll
Anchor client: ACME (clientCode: ACME) — already seeded with a closed 2026-03 prior cycle and an open 2026-04 INTAKE_IN_PROGRESS cycle. GLOBEX is used for the approval-side flow because it is seeded mid-CLIENT_REVIEW.
| # | Flow | SOP step | File |
|---|---|---|---|
| P-01 | Initiate cycle (request data) | §6 / Step 1.0 (S0 → S1) | payroll/01-initiate-cycle.md |
| P-02 | Client intake — Yes-changes path | §6 / Step 2.0 (S1 → S4) | payroll/02-client-intake-changes.md |
| P-03 | Client intake — Zero-change fast path | §6 / Step 2.0 (one-click) | payroll/03-zero-change-fast-path.md |
| P-04 | Validation & completeness | §6 / Step 3.0 (S4 → S7) | payroll/04-validation.md |
| P-05 | Request info from client (issue resolution loop) | §7 / Exception Handling | payroll/05-request-info-from-client.md |
| P-06 | Internal review & override approvals | §6 / Step 4.0 (S7 → S8) | payroll/06-internal-review.md |
| P-07 | Generate Infotech export | §6 / Step 5.0 (S8 → S10) | payroll/07-generate-export.md |
| P-08 | Upload payroll output (optional) | §6 / Step 6.0 | payroll/08-upload-output.md |
| P-09 | Request client approval | §6 / Step 6.0 | payroll/09-request-approval.md |
| P-10 | Client approval decision (approve / revision / query) | §6 / Step 6.0 (S10 → S14) | payroll/10-client-approval.md |
| P-11 | Finalize, close, archive | §6 / Step 7.0 (S14 → S16) | payroll/11-finalize-close.md |
| P-12 | Reminder escalation (day 2 / 5 / 7) | §6 / Step 2.0 (timeline) | payroll/12-reminder-escalation.md |
Walk down P-01 → P-11 in order for the end-to-end story.
Bookkeeping
Anchor client: ZENITH (clientCode: ZENITH) — bookkeeping-only, Xero platform, SGD base, materiality SGD 50. Seeded with a draft April 2026 batch (4 entries spanning every status × confidence combination) and a UOB statement with 1 EXACT + 2 PROPOSED + 3 UNRECONCILED matches.
| # | Flow | SOP step | File |
|---|---|---|---|
| B-01 | Onboard a new bookkeeping client (cold path) | §2 + §4 | bookkeeping/01-onboard-client.md |
| B-02 | Configure ingestion channels (WhatsApp / Google Drive) | §3 | bookkeeping/02-ingestion-channels.md |
| B-03 | Ingest a document — manual upload path | §3 + §4.1 | bookkeeping/03-ingest-document-manual.md |
| B-04 | Ingest a document — WhatsApp / folder paths | §3.2 + §3.3 | bookkeeping/04-ingest-document-channels.md |
| B-05 | Review a journal batch (approve / edit / reject / escalate) | §4.5 | bookkeeping/05-review-journal-batch.md |
| B-06 | Generate upload file (Xero / QBO / Zoho / Tally) | §4.4 | bookkeeping/06-generate-upload-file.md |
| B-07 | Upload bank statement & parse | §5.1 | bookkeeping/07-bank-statement.md |
| B-08 | Run reconciliation matcher | §5.2 | bookkeeping/08-reconciliation-run.md |
| B-09 | Confirm proposed matches | §5.2 | bookkeeping/09-confirm-matches.md |
| B-10 | Dispatch unreconciled items to client | §5.3.1 | bookkeeping/10-dispatch-unreconciled.md |
| B-11 | Client portal — respond to unreconciled items | §5.3.2 / §5.3.3 / §5.3.4 | bookkeeping/11-client-portal-unreconciled.md |
| B-12 | Reviewer exception queue (NO_SUPPORTING above materiality) | §5.3.4 + Exception Handling | bookkeeping/12-exception-queue.md |
| B-13 | Complete reconciliation & generate report | §5.4 | bookkeeping/13-complete-reconciliation.md |
| B-14 | Annual bookkeeping batch flow | §6 | bookkeeping/14-annual-bookkeeping.md |
| B-15 | Audit export (immutable trail) | §8 | bookkeeping/15-audit-export.md |
Walk down B-01 → B-15 in order for the end-to-end story.
Financial Statements
Anchor client: AURORA (clientCode: AURORA) — financial-statements-only, SFRS for Small Entities, SGD base. Seeded with one FY2024 engagement in TB_MAPPED: 13 trial-balance rows already mapped to SFRS taxonomy keys, one persisted FsGeneratedStatement (v1, balanced), and five mandatory disclosure responses pre-filled (DISC-001 / DISC-002 / DISC-003).
The Phase 0 cross-cutting state + the constitution / status machine / export gate foundations are in place; the operational surfaces (TB upload → mapping → statements → notes → DOCX) light up as the Phase 1 service layer ships. Until then, the 00-manual-testing.md playbook drives every layer through Prisma Studio / Node REPL.
| # | Flow | SOP step | File |
|---|---|---|---|
| FS-00 | Manual testing — Phase 0 / Phase 1 foundations | (cross-cutting) | financial-statements/00-manual-testing.md |
| FS-01 | Create FS engagement | §6 / Step 1.0 | financial-statements/01-create-engagement.md |
| FS-02 | Upload trial balance | §6 / Step 2.0 | financial-statements/02-upload-trial-balance.md |
| FS-03 | Auto-suggest and confirm SFRS taxonomy mappings | §6 / Step 3.0 | financial-statements/03-auto-suggest-mapping.md |
| FS-04 | Generate statements (BS / P&L / SOCE / Cash Flow) | §6 / Step 4.0 | financial-statements/04-generate-statements.md |
| FS-05 | Disclosure interrogation | §6 / Step 5.0 | financial-statements/05-disclosure-interrogation.md |
| FS-06 | Generate notes & Directors Report (Claude, single 16K call) | §6 / Step 6.0 | financial-statements/06-generate-notes.md |
| FS-07 | Export publication-ready DOCX | §6 / Step 7.0 | financial-statements/07-export-docx.md |
| FS-08 | Client portal sign-off (optional) | §6 / Step 8.0 | financial-statements/08-client-review.md |
| FS-09 | Archive engagement | §6 / Step 9.0 | financial-statements/09-archive.md |
Walk down FS-01 → FS-09 in order for the end-to-end story.
XBRL Filing
Anchor client: STELLAR (clientCode: STELLAR) — XBRL-only, FULL_XBRL entry point, NON_LISTED_COMPANY_FULL entity type, SFRS accounting standard, taxonomy acra_2026_v1. Seeded with two filings designed to exercise the export-gate failure paths:
- One filing in
MAPPING_IN_PROGRESS— 5 line items, 3 confirmed, 2 unconfirmed → gate raisesUNCONFIRMED_TAG_MAPPING. - One filing in
VALIDATION_FAILED— 5 line items all confirmed, validation run with 1 ERROR + 1 WARNING + 1 INFO → gate raisesVALIDATION_ERROR_PRESENT.
The Phase 0 cross-cutting state + the constitution (1871 elements, 144 rules, mapping library) / status machine / export gate / five non-negotiable cursorrules foundations are in place; the operational surfaces (document ingestion → mapping confirmation → validation → BizFinx export → mark filed) light up as the Phase 2 service layer ships. Until then, the 00-manual-testing.md playbook (shared with FS) drives every layer through Prisma Studio / Node REPL.
| # | Flow | SOP step | File |
|---|---|---|---|
| X-01 | Create XBRL filing | §6 / Step 1.0 | xbrl/01-create-filing.md |
| X-02 | Upload source document (DOCX / PDF) | §6 / Step 2.0 | xbrl/02-upload-source-document.md |
| X-02b | Pull line items from a Financial Statements engagement | §6 / Step 2.0 (cross-product, Phase 3) | xbrl/02b-pull-from-fs-engagement.md |
| X-03 | Confirm tag mappings (Rule 3 gate) | §6 / Step 3.0 | xbrl/03-confirm-mappings.md |
| X-04 | Run 144-rule validation (Rule 2 gate) | §6 / Step 4.0 | xbrl/04-run-validation.md |
| X-05 | Export BizFinx XLSX and XBRL XML (gated) | §6 / Step 5.0 | xbrl/05-export.md |
| X-06 | Client portal sign-off (optional, UEN-confirmed) | §6 / Step 6.0 | xbrl/06-client-signoff.md |
| X-07 | Mark filed with ACRA (XBRL_REVIEWER / PLATFORM_ADMIN only) | §6 / Step 7.0 | xbrl/07-mark-filed.md |
| X-08 | Archive filing | §6 / Step 8.0 | xbrl/08-archive.md |
Walk down X-01 → X-08 in order for the end-to-end story.
Immigration
Singapore MOM work / visit pass applications. One AgentRun of IMM.PREPARE_APPLICATION per application, on the tenant spine — there is no anchor seed client; provision a LIVE employer entity + applicant Party under any tenant, or use the SG smoke group entity. The workflow pauses at a client FORM step (AWAITING_CLIENT) and ends at a tier-4 human submission gate; the platform never auto-files with MOM.
| # | Flow | SOP step | File |
|---|---|---|---|
| IMM-01 | Operator intake (start a pass application) | §8 / Step 1 | immigration/01-operator-intake.md |
| IMM-02 | Client form and documents (portal) | §4 / Step 3 | immigration/02-client-form-and-documents.md |
| IMM-03 | Eligibility and operator review | §5 / Steps 4–5 | immigration/03-eligibility-and-review.md |
| IMM-04 | Tier-4 submission and acknowledgement | §6 / Step 6 | immigration/04-tier4-submission-and-acknowledgement.md |
| IMM-05 | Renewal tracking | §7 / Step 7 | immigration/05-renewal-tracking.md |
Walk down IMM-01 → IMM-05 in order for the end-to-end story.
Conventions used in every playbook
Each file follows the same shape so you can scan one and skim the rest:
# <flow id> · <flow title>
> SOP: <link + section>
> Actors: <Staff / Client roles>
> Pre-state: <required cycle / batch state>
> Post-state: <expected outcome>
## 0. Prerequisites
- Seed data references (which client, which IDs)
- Other flows that must have run first
## 1. Steps
- Numbered click path with API endpoint, request body shape, expected response
## 2. Verification
- DB rows / state transitions
- Mailpit subjects + recipients
- S3 / MinIO objects
- Audit log entries
## 3. Negative & edge cases
- Bad-state attempts, validation failures, idempotency checksWhen a flow has multiple branches (e.g. happy path vs. revision-requested), each branch lives under its own H2 in the same file.
Naming
- Roles use SOP terminology (CR / PE / POL for payroll, Reviewer / Senior Accountant for bookkeeping) but cross-reference the codebase role enum (
PAYROLL_EXECUTIVE,BOOKKEEPER, etc.) when calling out RBAC checks. - "Staff user" / "Ops user" for internal actors. "Client user" / "Client contact" for external actors. Never "internal user".
- All dates are absolute (
2026-04-25), never relative.