# Architecture

Zirabet is organized around domain services instead of page-only logic.

## Runtime

- Next.js App Router hosts UI and API routes.
- PostgreSQL stores regulated records: users, sessions, wallet ledger, bets, KYC, provider logs and audit logs.
- Redis is prepared for rate limiting and queue workers.
- Prisma is the transactional boundary for wallet, betting and webhook processing.

## Provider Boundary

Each external dependency is behind a typed adapter:

- `SportsDataProvider` / `OddsProvider` / `LiveScoreProvider`
- `PaymentProvider`
- `KycProvider`

Factories enforce provider policy. `local` providers can run in `development`, `staging` and `test`; production startup fails if they are selected.

## Money Safety

Balances are never mutated directly by UI actions. All money movement goes through `LedgerEntry` and atomic `WalletAccount` updates. Debits use guarded `updateMany` with `balance >= amount`, which prevents double-spend under concurrent requests.

## Betting Safety

Bet placement re-reads selections inside a database transaction, checks event/market/selection status, verifies odds version and applies the selected odds-change policy before debiting the wallet and creating the ticket.

## Audit

Sensitive admin/user actions write `AuditLog`; provider calls and webhooks write provider/webhook records for operations review.