Fleshed out documentation

docs/adr/0001-synchronous-external-calls-mvp.md

@@ -0,0 +1,28 @@
+# ADR 0001: Synchronous External Calls For MVP
+
+## Status
+
+Accepted
+
+## Context
+
+The MVP relies on OTP delivery, booking notifications, and payment gateway calls. Introducing a task queue (Celery/RQ) would add infrastructure (Redis, workers, retries) and operational complexity that is not required for the early launch.
+
+## Decision
+
+For the MVP, OTP sends, booking notifications, and payment gateway calls run synchronously in the request/response path with strict timeouts. A task queue will be revisited when traffic grows or operational needs change.
+
+## Consequences
+
+- Faster initial delivery with fewer moving parts.
+- Increased latency risk on endpoints that call external providers.
+- Failures are immediately visible to clients and logged for support.
+
+## Alternatives Considered
+
+- Celery + Redis for all external calls: rejected for MVP due to infra overhead.
+- Hybrid async for notifications only: rejected to keep the execution model consistent.
+
+## Related
+
+- `docs/architecture.md`

docs/adr/0002-moyasar-payment-gateway.md

@@ -0,0 +1,30 @@
+# ADR 0002: Moyasar As The Payment Gateway
+
+## Status
+
+Accepted
+
+## Context
+
+The platform needs a payment gateway that supports Saudi Arabia, SAR currency defaults, and local payment methods (e.g. STC Pay, Apple Pay, Samsung Pay). The backend already implements a `MoyasarGateway` integration and models `payments.Payment` with a `moyasar` provider option.
+
+## Decision
+
+Use Moyasar as the payment gateway for the MVP. Payment creation, capture, refund, and webhook reconciliation are implemented through `apps.payments.services.gateway.MoyasarGateway`.
+
+## Consequences
+
+- Supports KSA-focused payment methods and SAR by default.
+- Operational dependency on Moyasar uptime and API stability.
+- Payment flows and webhooks are tied to the Moyasar API surface until a gateway abstraction is expanded.
+
+## Alternatives Considered
+
+- Other regional gateways: deferred until the MVP is validated.
+- Stripe or similar global providers: not selected for MVP due to KSA-specific coverage priorities.
+
+## Related
+
+- `backend/apps/payments/services/gateway.py`
+- `docs/runbooks/payments_sanity_check.md`
+- `docs/architecture.md`

docs/adr/0003-authentica-otp-provider.md

@@ -0,0 +1,30 @@
+# ADR 0003: Authentica As Primary OTP Provider
+
+## Status
+
+Accepted
+
+## Context
+
+The platform requires phone-first authentication with OTP delivery for KSA. The codebase includes multiple provider adapters (`console`, `twilio`, `unifonic`, `authentica`) but only Authentica is implemented for provider-managed OTP delivery (send/verify) and direct SMS messaging. Twilio and Unifonic adapters are partial or unimplemented; a console provider exists for local development.
+
+## Decision
+
+Use Authentica as the primary OTP provider for the MVP, with `OTP_PROVIDER=authentica` in production environments. Keep `console` for local development and tests, and retain Twilio/Unifonic adapters as scaffolds for future expansion.
+
+## Consequences
+
+- OTP verification relies on Authentica APIs and credentials in production.
+- Local development remains simple with the console provider.
+- Adding a second production provider will require completing adapters and updating operational runbooks.
+
+## Alternatives Considered
+
+- Twilio as primary provider: not selected due to KSA-focused delivery needs and current adapter gaps.
+- Unifonic as primary provider: deferred until the adapter is fully implemented and validated.
+
+## Related
+
+- `backend/apps/accounts/services/otp.py`
+- `backend/salon_api/settings.py`
+- `docs/architecture.md`

docs/adr/README.md

@@ -0,0 +1,5 @@
+# Architecture Decision Records
+
+ADRs capture cross-cutting or hard-to-reverse decisions. Add a new ADR when changing providers, async strategy, data model boundaries, or other architectural choices.
+
+Use the template in `docs/templates/adr.md` and increment the numeric prefix (`0002`, `0003`, ...).