Salon/AGENTS.md

AGENTS.md

Project Goal

Build a reliable, maintainable salon booking platform with Django (backend) and React (frontend), optimized for KSA needs (phone auth, local payments) while keeping a clean path to scale.

Coding

• Comment concisely and often, especially where intent, edge cases, or business rules are not obvious.

Current Plan (Roadmap)

Phase 1: Core MVP Reliability

• Phone-first auth with OTP (SMS/WhatsApp), rate limits, and social login.
• Booking integrity (availability, staff schedules, overlap prevention).
• Payments via Moyasar (payment creation, webhooks, reconciliation).
• Notifications for booking lifecycle.
• Localization foundations (i18n plumbing, RTL readiness, locale preferences).
• Tests for critical flows.

Phase 2: Manager Ops

• Salon/staff/service management.
• Calendar view + rescheduling/cancellation rules.
• Reviews/ratings with moderation and recompute.
• Reports (revenue, popular services, customer trends).
• Full translation coverage and Arabic UX polish.

Phase 3: Scale & Compliance

• Audit logs and data export.
• PDPL/GDPR retention policy.
• Observability and performance baselines.

Reliability Standards (Non‑Negotiable)

• Every new feature ships with tests.
• Avoid introducing regressions without covering a fix or guardrail.
• Payment and booking flows must be idempotent and auditable.
• Phone auth must be rate‑limited and safe from abuse.
• Every change should be tested before completion; no exceptions.

Testing Expectations

Backend

• Use pytest + pytest-django.
• Tests live beside apps (apps/<app>/tests/).
• Minimum coverage: auth, booking validation, payment state transitions.

Frontend

• Use vitest + Testing Library.
• Critical flows covered: search, booking form, auth state.

Code Style & Practices

• Keep business logic in services (avoid fat views).
• Use explicit, readable model fields and serializers.
• Small, well‑named functions > monolithic handlers.
• Prefer predictable error responses (HTTP status + detail).
• Prefer short, intent-focused comments over silent complexity.

Known Gaps (Tracked)

• See docs/risks.md for current gaps/risks to address.

Environment Notes

• Python is invoked as python3.
• A virtualenv is in use.
• DB: PostgreSQL in production, SQLite allowed for local dev.
• Backend tests must run with the venv active and pytest-django installed; run from backend/ so backend/pytest.ini is picked up and DJANGO_SETTINGS_MODULE resolves.

Collaboration Rules for Agents

• Don’t delete or rewrite unrelated work.
• Avoid destructive git commands unless explicitly asked.
• Update docs/risks.md when adding or closing a significant gap.
• Keep README instructions current when tooling changes.
• Prefer feature branches for significant work; commit early with clear summary messages.

ExecPlans

When writing complex features or significant refactors, use an ExecPlan (as described in PLANS.md) from design to implementation. The active ExecPlan is docs/execplans/payments-moyasar.md.