# 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
```bash
cd salesflow-saas
cp .env.example .env  # Configure your environment
docker-compose up -d
make migrate
make seed
```

## How to Test
```bash
cd salesflow-saas/backend
pytest -v
# Or with coverage
pytest --cov=app --cov-report=html
```

## How to Run
```bash
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

## Governance Integration (Tier-1)

All agents operate under the governance framework defined in `MASTER_OPERATING_PROMPT.md`:

- **Trust Plane**: Every agent action is classified as A/B/C via `openclaw/policy.py`. Class B actions (messaging, payments, CRM sync) require approval tokens.
- **Evidence Packs**: Agent outputs logged to `ai_conversations` contribute to evidence pack assembly.
- **Contradiction Detection**: Agent-generated content is subject to contradiction checks against governance docs.
- **Structured Outputs**: All critical agent outputs use defined schemas (LeadScoreCard, QualificationMemo, ProposalPack, etc.).

### New Tier-1 API Surfaces
- `GET /api/v1/executive-room/snapshot` — Executive Room
- `GET /api/v1/contradictions/` — Contradiction Engine
- `GET /api/v1/evidence-packs/` — Evidence Pack Viewer
- `GET /api/v1/approval-center/` — Approval Center
- `GET /api/v1/connectors/governance` — Connector Governance
- `GET /api/v1/model-routing/dashboard` — Model Routing
- `GET /api/v1/compliance/matrix/` — Saudi Compliance Matrix
- `GET /api/v1/forecast-control/unified` — Actual vs Forecast

### Architecture Preflight
```bash
python scripts/architecture_brief.py   # Run from salesflow-saas/ root
```