# Architecture

## Laravel — system of record
Laravel owns:
- Users / authentication / roles
- Wallets and ledger
- Purchases
- Provider routing
- Payment webhooks
- Admin dashboard
- Pricing
- Commissions
- Notifications
- Audit logs
- Reconciliation state
- API access

## Python — optional sidecar
Python may handle:
- Analytics
- report generation
- anomaly scoring
- non-financial batch processing
- provider latency telemetry
- data science / forecasting

Python must call authenticated Laravel internal APIs for any action that could affect money.

## Transaction lifecycle

1. Client submits purchase with idempotency key.
2. Laravel validates product, amount, user, PIN/risk rules.
3. Laravel locks wallet row.
4. Laravel reserves/deducts amount and writes ledger entry.
5. Laravel creates transaction record.
6. Provider adapter sends request.
7. Provider response updates VTU transaction state.
8. On definitive failure, Laravel reverses through a compensating ledger entry.
9. Pending results enter reconciliation queue.
10. Notifications are generated from transaction state changes.

Never edit or delete historical ledger entries.