ADR-004 — Dev bench: separate municipal emulator with three panels
- Status: accepted (2026-11-16)
Context
The municipal sandbox simulator can only mark a charge as paid; it cannot produce insufficient
balance, latency, 5xx responses or the cancel-vs-pay race. The team needs a visual bench to tune
the gateway and its use cases before connecting the real CYRE POS. GatewayPrismaQR already has
an emulator module (prisma-emulator) with scenarios and a fault injector.
Alternatives
- Separate emulator module with its own bench UI. Chosen.
- Bench inside the gateway cockpit. Rejected: test code would ship in the product installed on the CYRE server.
- Municipal sandbox only. Rejected: it cannot reproduce failure modes.
Decision
A muni-emulator module (runnable jar) implements the full municipal API (create, query,
cancel, /pagar, movements, balance) with in-memory state. It serves a React bench UI with
three panels:
- Simulated POS: speaks the PAGOQR contract to the real gateway, renders the QR, shows statuses as the cashier would see them.
- Payer app: "scans" a QR from the POS panel and chooses an outcome: pay, insufficient balance, pay at second X, or do nothing.
- Municipal backend: charges and their statuses, plus fault knobs (latency, 5xx, timeouts, 409 on the cancel-vs-pay race).
The gateway runs exactly as in production with its own cockpit; only its municipal base URL changes (emulator, sandbox or production). Phase 2: the real CYRE POS points at the gateway, and panel 1 stays for regression.
Consequences
- The emulator must track the municipal contract; corpus captured from the sandbox (RISKS R-01) is used to check the emulator's responses against reality.
- The emulator is never deployed to CYRE servers.
Implementation Plan
- Copy the
prisma-emulatormodule layout (scenarios,FaultInjector, runnable jar) fromC:/Work/AI/GatewayPrismaQR. - Bench UI: React 19 + Vite 8, served by the emulator jar.
Verification
- [ ] An end-to-end payment runs from panel 1 → gateway → emulator → panel 2 → back to panel 1.
- [ ] Each fault knob produces the expected gateway behavior (ADR-003 scenarios).
- [ ] The gateway artifact contains no emulator classes.