# Architecture Snapshot

Compact snapshot for current MVP reliability work.

## System
- Backend: Django + DRF (`backend/`)
- Frontend: React + Vite (`frontend/`)
- Primary market defaults: KSA (locale + phone patterns)

## Backend Domains
- `apps/accounts`: phone-first users, OTP flows, auth APIs.
- `apps/salons`: salons/services/staff/availability/reviews.
- `apps/bookings`: booking creation + status transitions + overlap/availability validation.
- `apps/payments`: Moyasar payment creation + webhook reconciliation + idempotency.
- `apps/notifications`: booking lifecycle notifications (customer/staff).

## Key Flows
1. Phone auth: `/api/auth/phone/request/` -> OTP issue, `/api/auth/phone/verify/` -> JWT.
2. Booking: `POST /api/bookings/` enforces staff, duration, availability, overlap.
3. Payment: `POST /api/payments/` creates Moyasar payment with idempotency key.
4. Webhook: `/api/payments/webhook/` maps provider events to internal payment status.
5. Notification: booking create/confirm/cancel dispatches SMS/WhatsApp records.

## Current Design Decisions
- External calls are synchronous for MVP (ADR 0001).
- Moyasar is payment provider (ADR 0002).
- Authentica is primary OTP provider (ADR 0003).

## Reliability State
- Implemented: booking integrity, payment idempotency+webhooks, lifecycle notifications, locale foundations.
- Open: full OAuth linking policy, broader i18n coverage, stronger observability/audit/compliance.

## Where To Extend Safely
- Add business rules in services modules, not views.
- Preserve idempotency keys/state transitions for booking/payment changes.
- Update runbooks + risks with every production-impacting behavior change.

## Reference Docs
- Plan policy + active plan: `docs/PLANS.md`
- Known gaps: `docs/risks.md`
- Runbooks: `docs/runbooks/README.md`
- ADRs: `docs/adr/README.md`