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 current active ExecPlan is defined in PLANS.md. Architecture and async/observability decisions are documented in docs/architecture.md.