# AGENTS.md

## General

Minimum tokens, skip grammar

## Tasks
- Consult `AGENTS.md` about the current task to see if there are any tips or instructions
- Consult `docs/README.md` for any relevant files or tips to consider  

## 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 `docs/PLANS.md`) from design to implementation. The current active ExecPlan is defined in `docs/PLANS.md`. Architecture documented in `docs/architecture.md`.