Architecture: Decouple tax engine & payment tender domain boundaries

[khaira777]

Domain Decoupling & Refactoring Proposal

Extracted from fork codewithsharma/FloCafe (branch: modular-verticles):

Overview

Refactor monolithic routes into standalone domain boundaries for Tax calculations and Payment tender processing.

Proposed Changes

1. Tax Engine & Route Boundary:
   • Consolidate tax HTTP routes into main/routes/tax.ts.
   • Freeze tax snapshot contract and decouple tax calculation logic into main/services/tax-engine.ts and main/services/tax.ts.
   • Add snapshot contract test suite (tests/tax-snapshot-contract.test.ts, tests/tax-boundary.test.ts).
2. Payment Tender Boundary:
   • Extract payment process, tender validation, and split payment logic into main/services/payment-tender.ts.
   • Isolate payment domain logic from restaurant-specific dining order assumptions.
   • Reference: tests/payment-boundary.test.ts, tests/payment-without-restaurant.test.ts.

[khaira777]

Verdict: VALID BUT NEEDS RESCOPING — tax part largely done; payment part is the real work

Findings:

• Tax decoupling mostly exists: main/services/tax-engine.ts, main/services/tax.ts, main/services/tax-components.ts; tax routes are POST /api/tax/preview + GET /api/tax/categories in main/routes/index.ts plus main/routes/tax-packs.ts. A further "consolidate into routes/tax.ts" is mostly a file move with little behavioral value.
• Payment tender is NOT a separate service: payments, splits, and rounding live inline in main/routes/bills.ts (split_group_id, minor-unit math at :96-99, :175, :548-556). Extracting tender validation + split logic into a service is the valuable part, and it is testable today without restaurant/dining assumptions.

Suggested scope: (1) extract payment-tender validation/split into main/services/ with boundary tests; (2) add a tax-snapshot contract test suite (snapshots already exist — tax_snapshot columns, hasSnapshotLines() in bills.ts); (3) skip the route-consolidation move unless it reduces duplication. Related: #285 (minor-unit math in the extracted service).