Enhance documentation, implement Twilio OTP delivery, and update payment gateway methods. Updated AGENTS.md and README.md for clarity on ExecPlans and architecture. Added Twilio as a dependency and implemented capture/refund methods in MoyasarGateway. Improved frontend routing with react-router-dom and added authentication context. Updated styles and localization files for better user experience.

2026-02-28 15:33:50 +03:00
parent 86fd07c778
commit a1da918f95
37 changed files with 1645 additions and 277 deletions
@@ -0,0 +1,39 @@
+# 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.
@@ -5,7 +5,7 @@ This file tracks known gaps and risks to address in future iterations.
 ## Security And Auth
 - Phone normalization is KSA-focused and minimal; broaden for multi-country use.
 - OTP protections are basic; add device fingerprinting and IP throttling if needed.
- OTP provider adapters (Twilio/Unifonic) are scaffolds only; no real SMS/WhatsApp delivery yet.
+- Twilio OTP provider is implemented (SMS + WhatsApp); Unifonic remains a scaffold.
 - Social login is a placeholder.
 - USERNAME_FIELD is still `email` while email can be null; verify admin/login flows.

@@ -16,12 +16,12 @@ This file tracks known gaps and risks to address in future iterations.

 ## Payments
 - Moyasar payment creation, webhook reconciliation, and idempotency are implemented.
- Refund/capture operations are not implemented yet if required.
+- Moyasar capture and refund are implemented in the gateway; API endpoints for admin-initiated capture/refund can be added when needed.

 ## Data And UX
 - Ratings are not recalculated from reviews.
 - No image upload or storage strategy for photos.
- Booking lifecycle notifications are implemented (SMS/WhatsApp via provider scaffolds); production delivery still needs real provider adapters.
+- Booking lifecycle notifications are implemented; Twilio delivers SMS/WhatsApp when OTP_PROVIDER=twilio.
 - Localization foundations are in progress; full Arabic translation coverage and RTL QA are still pending.

 ## Ops And Compliance