mirror of
https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git
synced 2026-06-17 23:09:35 +00:00
afd37142fe
- wiki/README.md: Wiki system guide with page templates and conventions - wiki/architecture.md: Dealix architecture wiki page - deployment-checklist.md: Enhanced with full pre-deploy, deploy, post-deploy, rollback procedures https://claude.ai/code/session_01LsnvBa7HwF5hs99VZbgLGj
165 lines
8.3 KiB
Markdown
165 lines
8.3 KiB
Markdown
# Dealix System Architecture (بنية نظام ديلكس)
|
|
|
|
**Type**: architecture
|
|
**Summary**: Multi-tenant AI CRM built on FastAPI + Next.js + PostgreSQL + Redis + Celery with Arabic-first UX and PDPL compliance.
|
|
**Summary_AR**: نظام إدارة علاقات عملاء ذكي متعدد المستأجرين مبني على FastAPI و Next.js و PostgreSQL مع واجهة عربية أولاً والتوافق مع نظام حماية البيانات.
|
|
**Key Facts**:
|
|
- Backend: FastAPI 0.115.6 on Python 3.12, async everywhere (asyncpg, async SQLAlchemy)
|
|
- Frontend: Next.js 15 with App Router, TypeScript 5.7, RTL-first layout
|
|
- Database: PostgreSQL 16 with tenant_id isolation on every table; Alembic migrations
|
|
- Cache/Queue: Redis 7 for caching + Celery 5.x task broker with 4 workers + Celery Beat scheduler
|
|
- AI Engine: Groq (primary) with OpenAI fallback; Arabic NLP, lead scoring, conversation intelligence
|
|
- Compliance: PDPL-native — consent checked before every outbound message; SAR 5M penalty per violation
|
|
- Multi-agent system: Manus-style orchestrator with 8 specialized roles and event-to-agent routing
|
|
**Provenance**: AGENTS.md, CLAUDE.md, memory/architecture/system-overview.md, docker-compose.yml
|
|
**Confidence**: high
|
|
**Related Pages**: [glossary](./glossary.md), [system-overview](../architecture/system-overview.md)
|
|
**Last Updated**: 2026-04-11
|
|
**Stale**: false
|
|
|
|
---
|
|
|
|
## High-Level Architecture
|
|
|
|
```
|
|
┌──────────────────────────┐
|
|
│ Nginx Reverse Proxy │
|
|
└─────────┬────────┬─────────┘
|
|
│ │
|
|
┌─────────────┘ └──────────────┐
|
|
▼ ▼
|
|
┌──────────────────┐ ┌──────────────────┐
|
|
│ Next.js Frontend │ │ FastAPI Backend │
|
|
│ (Port 3000) │ │ (Port 8000) │
|
|
│ - Dashboard │ │ - API v1 │
|
|
│ - Landing Page │ │ - Services Layer │
|
|
│ - Auth Flows │ │ - AI Engine │
|
|
│ - Pipeline View │ │ - Agent System │
|
|
│ - RTL / Arabic │ │ - Integrations │
|
|
└──────────────────┘ └────────┬───────────┘
|
|
│
|
|
┌─────────────┼──────────────┐
|
|
▼ ▼ ▼
|
|
┌───────────┐ ┌───────────┐ ┌────────────┐
|
|
│ PostgreSQL │ │ Redis │ │ Celery │
|
|
│ 16 │ │ 7 │ │ Workers │
|
|
│ (asyncpg) │ │ (cache + │ │ (4) + │
|
|
│ │ │ broker) │ │ Beat │
|
|
└───────────┘ └───────────┘ └────────────┘
|
|
```
|
|
|
|
## Backend Layers
|
|
|
|
### API Layer (`backend/app/api/v1/`)
|
|
RESTful endpoints versioned under `/api/v1/`. JWT authentication via python-jose. All endpoints require tenant context.
|
|
|
|
Key route groups:
|
|
- **Auth**: registration, login, token refresh, password reset
|
|
- **Leads**: CRUD, scoring, bulk import, assignment
|
|
- **Deals**: pipeline management, stage transitions, forecasting
|
|
- **Inbox**: unified WhatsApp + Email + SMS conversation view
|
|
- **Sequences**: automated outreach cadences
|
|
- **Compliance**: PDPL consent management, data subject rights
|
|
- **Proposals / CPQ**: configure-price-quote with Arabic PDF generation
|
|
|
|
### Services Layer (`backend/app/services/`)
|
|
Business logic is isolated from API routes. Each service is a class with async methods.
|
|
|
|
Core services:
|
|
- `ai/` — Arabic NLP (intent, sentiment, entity extraction), lead scoring (0-100), conversation intelligence
|
|
- `pdpl/` — Consent manager, data rights handler, audit trail
|
|
- `cpq/` — Configure-Price-Quote with SAR currency handling
|
|
- `agents/` — Multi-agent orchestrator, 8 specialized roles, event routing, executor with retry
|
|
- `sequence_engine.py` — Automated multi-step outreach with channel rotation
|
|
- `model_router.py` — Task-specific LLM model selection across providers
|
|
- `security_gate.py` — Runtime security verification, PDPL enforcement
|
|
- `tool_verification.py` — Agent action audit trail (intent vs claim vs execution)
|
|
|
|
### Integration Layer (`backend/app/integrations/`)
|
|
Adapters for external services:
|
|
- **WhatsApp**: UltraMsg API (primary Saudi channel, 85% penetration)
|
|
- **Email**: SMTP with template rendering
|
|
- **SMS**: Twilio / local Saudi provider
|
|
- **Payments**: Stripe with SAR support
|
|
- **Tax**: ZATCA e-invoicing compliance
|
|
|
|
### Worker Layer (`backend/app/workers/`)
|
|
Celery tasks for async processing:
|
|
- Lead scoring recalculation
|
|
- Sequence step execution
|
|
- Email/WhatsApp delivery
|
|
- Analytics aggregation
|
|
- Scheduled reports
|
|
|
|
## Frontend Architecture
|
|
|
|
- **Framework**: Next.js 15 with App Router
|
|
- **Language**: TypeScript 5.7 in strict mode
|
|
- **Styling**: Tailwind CSS 3.4 with RTL-first layout (`dir="rtl"`)
|
|
- **Fonts**: IBM Plex Sans Arabic (primary), Tajawal (secondary)
|
|
- **Components**: Functional components with hooks
|
|
- **State**: Server components by default, client where interactivity needed
|
|
|
|
## Data Architecture
|
|
|
|
### Multi-Tenant Isolation
|
|
Every table includes a `tenant_id` column. All queries are scoped by tenant at the ORM level. Cross-tenant access is a Class C forbidden action.
|
|
|
|
### Key Models
|
|
- **Lead**: Contact with scoring, source tracking, assignment
|
|
- **Deal**: Pipeline stage, value (SAR), probability, close date
|
|
- **Company**: Organization with enrichment data
|
|
- **Sequence**: Multi-step outreach cadence
|
|
- **Consent**: PDPL consent record with purpose, channel, expiry (12 months)
|
|
- **Meeting**: Scheduled interactions with intelligence extraction
|
|
|
|
### Database Conventions
|
|
- All money fields use `Numeric` type (never Float)
|
|
- Soft-delete before hard-delete
|
|
- Alembic for all migrations
|
|
- Timezone: Asia/Riyadh (UTC+3)
|
|
- Currency: SAR default
|
|
|
|
## AI Architecture
|
|
|
|
### LLM Provider Chain
|
|
1. **Groq** (llama-3.1-70b): Fast classification, Arabic NLP
|
|
2. **Claude**: Sales copy, proposals, complex reasoning
|
|
3. **Gemini**: Research, analysis
|
|
4. **DeepSeek**: Code generation
|
|
5. **OpenAI GPT-4o-mini**: Fallback
|
|
|
|
### Agent System
|
|
Manus-style orchestrator with specialized agents:
|
|
- Lead Qualifier, Deal Advisor, Meeting Prep, Sequence Optimizer
|
|
- Content Generator, Analytics Reporter, Compliance Checker, Escalation Handler
|
|
|
|
Event-to-agent routing via `router.py`. Executor handles retry logic and escalation to human.
|
|
|
|
## Security & Compliance
|
|
|
|
### PDPL (نظام حماية البيانات الشخصية)
|
|
- Consent required before any outbound message
|
|
- Consent tracks: purpose, channel, timestamp, expiry
|
|
- Data subject rights: access, correction, deletion
|
|
- Full audit trail for consent changes
|
|
- Auto-expire after 12 months
|
|
- Penalty: up to SAR 5,000,000 per violation
|
|
|
|
### Authentication
|
|
- JWT tokens via python-jose
|
|
- Role-based access: owner, admin, manager, sales_rep, viewer
|
|
- Tenant-scoped permissions
|
|
|
|
### Policy Classes
|
|
- **Class A** (Auto-allowed): Reading, testing, documentation, analysis
|
|
- **Class B** (Approval required): Migrations, messaging, payments, deployments
|
|
- **Class C** (Forbidden): Secret exfiltration, cross-tenant access, ungoverned bulk messaging
|
|
|
|
## Deployment
|
|
|
|
- **Containerized**: Docker Compose for all services
|
|
- **Reverse proxy**: Nginx
|
|
- **CI/CD**: GitHub Actions (feature branch → PR → review → staging → canary 10% → production)
|
|
- **Monitoring**: Health checks, error tracking, performance metrics
|