chore: condense all docs and markdown files
This commit is contained in:
@@ -1,33 +1,25 @@
|
||||
# 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.
|
||||
OTP sends, booking notifications, and payment provider calls were needed quickly for MVP reliability. Running queue infrastructure early would add operational overhead.
|
||||
|
||||
## 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.
|
||||
Keep external calls synchronous in request/response paths for MVP, with explicit timeouts and failure handling.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Faster initial delivery with fewer moving parts.
|
||||
- Increased latency risk on endpoints that call external providers.
|
||||
- Payment and OTP failures are surfaced to clients immediately (correct behaviour — clients need to know).
|
||||
- Notification failures are absorbed: `notifications/services.py` catches provider errors, stores them as `FAILED` status, and never surfaces them to the client. A failed booking SMS does not cause the booking request to fail. This means notification failures require active monitoring rather than appearing in client-facing error rates.
|
||||
- Faster delivery, fewer moving pieces.
|
||||
- Higher latency risk when providers are slow.
|
||||
- Payment/OTP failures surface to clients immediately.
|
||||
- Notification failures are recorded (`FAILED`) and monitored, not returned to client requests.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Celery + Redis for all external calls: rejected for MVP due to infra overhead.
|
||||
- Hybrid async for notifications only: not wrong in principle, deferred for operational simplicity. The three call types have genuinely different semantics:
|
||||
- **Payment creation**: synchronous by design — the client needs the Moyasar redirect URL before the response returns.
|
||||
- **OTP sends**: synchronous by design — users expect immediate confirmation that the code was sent.
|
||||
- **Booking notifications**: fire-and-forget by nature — the booking is already committed and the client does not wait for delivery confirmation.
|
||||
When notification latency becomes a problem (e.g. under load or with slow SMS providers), only notifications need to move off the request path. Payments and OTP sends should remain synchronous regardless.
|
||||
- Full queue (Celery/Redis): deferred.
|
||||
- Hybrid queue for notifications only: valid future step when latency/throughput needs it.
|
||||
|
||||
## Related
|
||||
|
||||
- `docs/architecture.md`
|
||||
- `docs/runbooks/auth_otp_failures.md`
|
||||
- `docs/runbooks/payments_sanity_check.md`
|
||||
|
||||
@@ -1,30 +1,23 @@
|
||||
# ADR 0002: Moyasar As The Payment Gateway
|
||||
# ADR 0002: Moyasar As 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.
|
||||
MVP requires KSA-focused payment support (SAR + local methods).
|
||||
|
||||
## 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`.
|
||||
Use Moyasar as the primary gateway for payment creation and webhook reconciliation.
|
||||
|
||||
## 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.
|
||||
- Strong KSA fit for MVP.
|
||||
- External dependency on Moyasar uptime/API stability.
|
||||
- Gateway abstraction can be expanded later for multi-provider support.
|
||||
|
||||
## 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.
|
||||
- Other regional gateways: deferred.
|
||||
- Global-first provider: not selected for MVP priorities.
|
||||
|
||||
## Related
|
||||
|
||||
- `backend/apps/payments/services/gateway.py`
|
||||
- `docs/runbooks/payments_sanity_check.md`
|
||||
- `docs/architecture.md`
|
||||
|
||||
@@ -1,28 +1,24 @@
|
||||
# ADR 0003: Authentica As Primary OTP Provider
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Context
|
||||
|
||||
The platform requires phone-first authentication with OTP delivery for KSA. The codebase includes provider adapters (`console`, `authentica`) and Authentica is implemented for provider-managed OTP delivery (send/verify) and direct SMS messaging. A console provider exists for local development.
|
||||
MVP auth is phone-first; production OTP delivery needed for KSA.
|
||||
|
||||
## 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.
|
||||
Use Authentica as production OTP provider. Keep `console` provider for local development/tests.
|
||||
|
||||
## 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.
|
||||
- Production auth depends on Authentica credentials + uptime.
|
||||
- Local development remains simple.
|
||||
- Adding backup provider needs new adapter + runbook updates.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- Console-only: not viable for production.
|
||||
- Multi-provider from day one: deferred for scope control.
|
||||
|
||||
## Related
|
||||
|
||||
- `backend/apps/accounts/services/otp.py`
|
||||
- `backend/salon_api/settings.py`
|
||||
- `docs/architecture.md`
|
||||
- `docs/runbooks/auth_otp_failures.md`
|
||||
|
||||
+11
-3
@@ -1,5 +1,13 @@
|
||||
# Architecture Decision Records
|
||||
# ADR Index
|
||||
|
||||
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 ADRs for cross-cutting, hard-to-reverse decisions.
|
||||
|
||||
Use the template in `docs/templates/adr.md` and increment the numeric prefix (`0002`, `0003`, ...).
|
||||
## Existing ADRs
|
||||
- `0001-synchronous-external-calls-mvp.md`
|
||||
- `0002-moyasar-payment-gateway.md`
|
||||
- `0003-authentica-otp-provider.md`
|
||||
|
||||
## Add New ADR
|
||||
- Copy `docs/templates/adr.md`
|
||||
- Use next numeric prefix (`0004`, `0005`, ...)
|
||||
- Keep status updated (`Proposed`, `Accepted`, `Deprecated`, `Superseded`)
|
||||
|
||||
Reference in New Issue
Block a user