Runtime
- TanStack Start (React 19, Vite 7) served from Cloudflare Workers (edge)
- Server functions for app logic, server routes under /api/public/* for webhooks and cron
- Static assets, images and video distributed through Cloudflare's global CDN
Documentation
System architecture.
A reference for engineers, partners and auditors. ZERAKET runs as an edge-first application with a hardened Postgres core and a strict separation between client, server functions and admin paths.
Data layer
- PostgreSQL (Supabase) with Row Level Security enabled on every public table
- Security-definer helper functions (has_role, has_organizer_role) avoid RLS recursion
- Realtime channels are policy-gated by ticket status and organizer membership
- Storage in private buckets by default; public buckets serve only marketing media
Ticketing pipeline
- Encrypted ticket payloads with rotating QR (15s window) and offline fallback
- Optional NFC binding for high-value tiers; identity-bound tickets for VIP
- Idempotent payment to ledger flow via Postgres triggers, no double-credit
- Scanner sessions with deployment-scoped tokens and stale-session revocation
- Every ticket code carries two signatures: a server HMAC and an Ed25519 proof signed with a key unique to that event
- Scanners hold only the event's public key, so a lost or stolen scanner can check tickets but never create them
- Before doors open each scanner downloads a block list of cancelled, refunded and transferred tickets, refreshed every two minutes
- Seat and tier capacity is reserved inside one locked database step, for paid and complimentary tickets alike
Offline scanning and the conflict rule
- With no signal, the scanner checks the signature, the event, the block list and its own scan history on the device
- Accepted offline scans are queued on the device and sent the moment the connection returns
- Rule: the first admission the server verifies is the official entry. Any other admission of the same ticket becomes a scan incident for the gate lead
- The same device never admits the same ticket twice while offline, unless re-entry is switched on
High-demand on-sales
- Organizers can switch on a waiting room per event; buyers enter checkout in arrival order at a set rate per minute
- The queue fails open: a queue fault never blocks a sale outright
- Capacity stays authoritative in the database, so the queue controls load, not inventory
Payments and money movement
- All mobile money through one pawaPay connection; cards through Pesapal
- A ticket is issued only after the payment provider confirms the money, never on the buyer's word
- Cross-border mobile money is charged in the network currency; the order and organizer earnings stay in the event currency
- Double-entry ledger (finance_txns, payout_ledger_entries) reconciled daily
- Platform fees, taxes and provider fees resolved per organizer / per event
- Payout disbursement attempts logged with provider response codes
Identity and access
- Email/password and Google auth via the managed auth service
- Roles stored in a dedicated user_roles table (never on profiles)
- Organizer membership uses a separate organizer_members table with capability checks
- Admin actions logged in admin_action_log and access_audit_log
Observability
- Structured server-function logs, Cloudflare access logs, Postgres slow-query log
- Heartbeat workers monitor critical user journeys end-to-end
- Real-time gate alerts on sales spikes, scan anomalies and session revokes
This document is maintained by ZERAKET engineering. Implementation details may change; the public contract is described in the API documentation.