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 provider classes as an MVP shortcut; sends on booking created/confirmed/cancelled. See note below.

Data Model Overview

The core data model centers on users, salons, and time-bound bookings. A booking ties a customer to a service, a staff member, and a scheduled time. Payments are recorded per booking and reconcile to the external gateway. Notifications are stored for every booking lifecycle message for auditability.

• accounts.User owns phone, locale, and auth preferences.
• salons.Salon, salons.Service, and salons.Staff define the catalog and scheduling surface.
• bookings.Booking links customer, staff, service, and scheduled time, with status transitions.
• payments.Payment tracks gateway state and idempotency per booking.
• notifications.Notification records each SMS/WhatsApp send attempt tied to a booking event.

Data Flow

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

Notification / OTP Provider Coupling (MVP Shortcut)

notifications/services.py imports PROVIDERS from apps.accounts.services.otp and uses OTP provider instances (e.g. AuthenticaOtpProvider) to send booking SMSes. This works today because Authentica handles both authentication OTPs and general SMS delivery.

Consequences of this coupling:

• Notifications and OTP delivery cannot independently use different providers (e.g. Twilio for OTP, Unifonic for notifications).
• The notifications app is conceptually coupled to the accounts app's auth infrastructure.

This is an acceptable MVP shortcut. Before Phase 2, introduce a dedicated NotificationProvider abstraction in notifications/ (mirroring OtpProvider) so the two systems can be configured and tested independently.

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. This is captured in ADR 0001 (docs/adr/0001-synchronous-external-calls-mvp.md).

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.