system-prompts-and-models-of-ai-tools/salesflow-saas/AGENTS.md

AGENTS.md — Dealix AI Revenue OS

Project Identity

• Name: Dealix (ديلكس)
• Type: AI-Powered CRM SaaS for Saudi Arabia
• Stack: FastAPI + Next.js 15 + PostgreSQL + Redis + Celery
• Market: Saudi SMBs (real estate, healthcare, retail, contracting, education)
• Language: Arabic-first, bilingual (AR/EN)

Architecture Boundaries

Backend (salesflow-saas/backend/)

• FastAPI 0.115.6 on Python 3.12
• SQLAlchemy 2.0 async with PostgreSQL 16
• Celery 5.x with Redis broker
• JWT authentication (PyJWT)
• Multi-tenant data isolation via tenant_id

Frontend (salesflow-saas/frontend/)

• Next.js 15 with App Router
• TypeScript 5.7, Tailwind CSS 3.4
• RTL-first layout (dir="rtl")
• Fonts: IBM Plex Sans Arabic (primary), Tajawal (secondary)

AI Layer (backend/app/services/ai/)

• LLM Provider: Groq (primary) → OpenAI (fallback)
• Arabic NLP with Saudi dialect support
• Model routing via services/model_router.py

Agent System (backend/app/services/agents/)

• Manus-style orchestrator with 8 specialized roles
• Event-to-agent routing via router.py
• Executor with retry logic and escalation

Coding Conventions

• Python: async/await, type hints, Pydantic models, 4-space indent
• TypeScript: strict mode, functional components, Tailwind classes
• Database: all queries through SQLAlchemy ORM, never raw SQL
• API: RESTful, versioned (/api/v1/), proper HTTP status codes
• Naming: snake_case (Python), camelCase (TypeScript)
• Arabic: all user-facing strings must have Arabic versions
• Currency: SAR default, Numeric type for money fields
• Timezone: Asia/Riyadh (UTC+3)

Forbidden Actions

• Never hardcode API keys or secrets
• Never bypass tenant isolation
• Never send messages without PDPL consent check
• Never delete data without soft-delete first
• Never push directly to main branch
• Never skip security review for auth/payment changes
• Never use synchronous DB calls in async endpoints
• Never store PII in logs

Policy Classes

Class A — Auto-allowed

• Code reading and inspection
• Test generation and execution
• Documentation updates
• Memory/knowledge base updates
• Linting and formatting
• Architecture analysis

Class B — Approval Required

• Database migrations
• Customer-facing message sends
• Payment/billing changes
• Permission model changes
• External API integrations
• Production deployments
• PDPL consent configuration changes

Class C — Forbidden

• Secret exfiltration
• Bypassing branch protections
• Silent destructive changes
• Disabling security gates
• Cross-tenant data access
• Ungoverned bulk messaging

How to Install

cd salesflow-saas
cp .env.example .env  # Configure your environment
docker-compose up -d
make migrate
make seed

How to Test

cd salesflow-saas/backend
pytest -v
# Or with coverage
pytest --cov=app --cov-report=html

How to Run

docker-compose up  # All services
# Or individually:
cd backend && uvicorn app.main:app --reload --port 8000
cd frontend && npm run dev

Provider Preferences

1. Fast classification: Groq (llama-3.1-70b)
2. Arabic NLP: Groq with Arabic context prompts
3. Sales copy/proposals: Claude (via model_router)
4. Research/analysis: Gemini (via model_router)
5. Coding tasks: DeepSeek (via model_router)
6. Fallback: OpenAI GPT-4o-mini

Release Process

1. Feature branch → PR → Code review
2. Run tests + security scan
3. Deploy to staging
4. Smoke test (Arabic + English)
5. Deploy to production with canary (10%)
6. Monitor 30 min → full rollout
7. Rollback plan documented per release

Repository constitution (monorepo root)

The institutional operating prompt and governance docs live at the repository root (parent of salesflow-saas/):

• ../MASTER_OPERATING_PROMPT.md — Master Operating Prompt (planes, trust fabric, events, GitHub, Arabic-first).
• ../AGENTS.md — short agents constitution (references master + A/R/S).
• ../CLAUDE.md — Claude/repo-native rules.
• ../docs/ai-operating-model.md — decision / execution / control / data / trust summary + pointers into this app.
• ../docs/governance/approval-policy.md — approval, reversibility, sensitivity, action classes.

This file (salesflow-saas/AGENTS.md) is app-specific (stack, conventions, Class A/B/C for shipping). Align both layers: app rules must not contradict root policy.