Salon/docs/architecture.md

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