Plan PayGate v4 unified architecture

[Phloraxx]

Purpose

Final PayGate v4 architecture and implementation plan. Documentation only; no production behavior changes.

Core semantics

• name = merchant-supplied person/payee identifier, not event title
• external_id = event ID and deliberately non-unique across payments
• PayGate payment ID + merchant Idempotency-Key provide payment/request identity
• notification-derived payer identity remains separate from merchant name

Architecture

• PayGate = one Go server + one Android APK
• payment-frontend remains a separate test/reference consumer
• merchant never selects Paytm/Kotak
• PayGate owns active collection profile for new payments and snapshots destination/profile on creation
• server returns canonical UPI URI; frontend renders QR
• v4.0 sources: Paytm Business + Kotak via Google Messages notification
• Android is a dumb signed notification sensor; server parses/matches
• server-side Google Messages/libgm retires after parity
• GPay and Slice deferred
• no UTR/RRN matching requirement

Amount/lifecycle design

• for a ₹N request, randomly choose among free ₹N.01…₹N.99
• only when that entire 99-value base bucket is unavailable may PayGate choose randomly from ₹(N+1).01…₹(N+1).99
• never randomize across both buckets at once and never overflow early
• default max adjustment ₹1.99
• 5m active + 5m grace + 5m hard quarantine
• soft recent-use avoidance after release lowers rapid reuse without creating another hard lock
• database-enforced active (profile, payable_amount) uniqueness
• historical reservation/timestamp reasoning; reused amount + ambiguous time fails closed

Storage

• direct SQLite only through Go database/sql + modernc.org/sqlite
• no PocketBase in final v4 runtime
• local WAL database, one PayGate process
• synchronous=FULL, foreign keys, bounded busy timeout
• STRICT/CHECK/UNIQUE/partial-index invariants where practical
• BEGIN IMMEDIATE for critical write transactions
• in-process SQLite Online Backup API; host only exports completed backups

UX

• Overview / Payments / Activity / Settings
• Razorpay-inspired dark navy/blue web + Android design
• password-only singleton operator login
• direct payment correction instead of Manual Review product
• one active relay phone in v4.0 with QR/App-Link Connect/Replace flow

Documentation

docs/v4/README.md plus product vision, target architecture, notification/pairing, payment lifecycle/matching, API/webhooks, Android, UI/design, direct SQLite/security/operations, migration plan, research notes, and a dedicated edge-case/invariant catalogue.

Safety

Implementation is split into focused PRs and introduced beside v3 with a verified rollback path.