Salon/docs/architecture.md

Architecture

Overview

The Salon platform is a Django REST API backend with a React/Vite frontend, optimized for KSA (phone auth, Riyadh timezone, Arabic locale).

Backend Apps and Responsibilities

App	Responsibility
accounts	User model, phone/OTP auth, JWT tokens, locale preferences. OTP providers (console, Twilio, Unifonic) send SMS/WhatsApp.
salons	Salon catalog, services, staff, availability windows, reviews. Read-only public APIs.
bookings	Booking model, validation (availability, overlap prevention), status transitions. Triggers notifications on create and status change.
payments	Payment model, Moyasar integration (create, capture, refund), webhook reconciliation, idempotency.
notifications	Booking lifecycle notifications (SMS/WhatsApp). Reuses OTP providers; sends on booking created/confirmed/cancelled.

Data Flow

User → React Frontend → Django API
         ↓
    accounts (auth) ──→ OTP providers (Twilio/Unifonic/console)
    salons (catalog)
    bookings ──→ notifications ──→ OTP providers
    payments ──→ Moyasar gateway

Async and Observability (MVP Decision)

Decision (MVP): All OTP sends, booking notifications, and payment gateway calls run synchronously in the request/response path. No Celery, RQ, or other task queue for the initial launch.

Rationale:

• Reduces deployment complexity (no Redis, no worker processes).
• MVP traffic is expected to be low; synchronous latency is acceptable.
• External calls already use timeouts (e.g. Moyasar: 10s, Twilio: SDK default).

Future: When scaling, introduce a task queue (e.g. Celery + Redis) for OTP and notification sends. Payment creation and webhooks should remain synchronous for immediate feedback and idempotency.

Observability: Errors are logged via Python logging and stored in model metadata (e.g. Payment.metadata["gateway_error"], Notification.error_message). Structured logging and metrics are Phase 3 work.