system-prompts-and-models-o.../salesflow-saas/docs/DATA-MODEL.md
Claude 84762f08ab
Add complete launch infrastructure: models, APIs, agents, compliance, docs, knowledge base
Phase 1 - Repo Hardening:
- README.md, LICENSE, SECURITY.md, CONTRIBUTING.md
- GitHub Actions repo-hygiene workflow
- docs/: ARCHITECTURE, DATA-MODEL, API-MAP, AGENT-MAP, DEPLOYMENT-NOTES

Phase 2 - Database Models (7 new):
- Company, Contact, Call, Commission, Payout, Dispute, GuaranteeClaim
- Consent, Complaint, Policy, KnowledgeArticle, SectorAsset
- Updated models/__init__.py with all 32+ models

Phase 3 - API Surfaces (16 new route files):
- companies, contacts, calls, meetings, commissions, payouts
- disputes, guarantees, consents, complaints, knowledge
- sectors, presentations, supervisor, admin, health
- Updated router.py with all 24 route groups

Phase 4 - AI Prompt Registry (18 agent contracts):
- Lead Qualification, Affiliate Recruitment Evaluator, Onboarding Coach
- Outreach Writer, Arabic WhatsApp, English Conversation, Voice Call
- Meeting Booking, Sector Strategist, Objection Handler
- Proposal Drafter, QA Reviewer, Compliance Reviewer
- Knowledge Retrieval, Revenue Attribution, Fraud Reviewer
- Guarantee Claim Reviewer, Management Summary

Phase 5 - Communication Templates:
- 15 production templates (WhatsApp, email, voice, internal)
- Arabic + English variants with variable interpolation

Phase 6 - Compliance Center (7 legal docs):
- Privacy policy, Terms of service, Refund policy
- Commission policy, Affiliate rules, Consent policy, Data protection
- All PDPL-compliant, Arabic

Phase 7 - Celery Workers (fully implemented):
- follow_up_tasks: automated lead follow-ups with workflow execution
- message_tasks: WhatsApp/email/SMS with retry logic
- notification_tasks: daily reports, meeting reminders, in-app notifications
- affiliate_tasks: target checking, commission calculation, weekly reports, AI outreach

Phase 8 - Knowledge Base OS (8 files):
- Services overview, Pricing policy, Channel policy, Meeting policy
- Identity rules, Escalation rules, Hiring path, Internal SOPs

https://claude.ai/code/session_01KnJgK7RwyeCvRZTRThHtfU
2026-03-31 07:57:48 +00:00

541 lines
14 KiB
Markdown

# Data Model
Complete schema reference for the Dealix platform. All tenant-scoped tables include a `tenant_id` foreign key. Timestamps (`created_at`, `updated_at`) are present on every table unless noted.
---
## Core Tables
### users
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| email | VARCHAR(255) | unique per tenant |
| phone | VARCHAR(20) | |
| hashed_password | TEXT | |
| full_name | VARCHAR(255) | |
| role | ENUM | owner, admin, manager, agent, affiliate, viewer |
| language | VARCHAR(5) | ar, en |
| is_active | BOOLEAN | |
| last_login_at | TIMESTAMP | |
### tenants
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| name | VARCHAR(255) | |
| slug | VARCHAR(100) | unique |
| plan | ENUM | free, starter, pro, enterprise |
| domain | VARCHAR(255) | custom domain |
| settings | JSONB | tenant-level config |
| is_active | BOOLEAN | |
### leads
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| assigned_to | UUID | FK -> users |
| source | VARCHAR(50) | whatsapp, web, referral, import, affiliate |
| status | ENUM | new, contacted, qualified, converted, lost |
| score | INTEGER | AI-computed 0-100 |
| full_name | VARCHAR(255) | |
| phone | VARCHAR(20) | |
| email | VARCHAR(255) | |
| company_name | VARCHAR(255) | |
| sector | VARCHAR(100) | |
| city | VARCHAR(100) | |
| notes | TEXT | |
| qualified_at | TIMESTAMP | |
| converted_at | TIMESTAMP | |
### deals
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| lead_id | UUID | FK -> leads |
| assigned_to | UUID | FK -> users |
| title | VARCHAR(255) | |
| stage | ENUM | discovery, proposal, negotiation, closed_won, closed_lost |
| value | DECIMAL(12,2) | SAR |
| currency | VARCHAR(3) | default SAR |
| probability | INTEGER | 0-100 |
| expected_close | DATE | |
| closed_at | TIMESTAMP | |
| lost_reason | TEXT | |
### customers
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| lead_id | UUID | FK -> leads |
| deal_id | UUID | FK -> deals |
| full_name | VARCHAR(255) | |
| email | VARCHAR(255) | |
| phone | VARCHAR(20) | |
| company_name | VARCHAR(255) | |
| lifetime_value | DECIMAL(12,2) | |
### activities
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| user_id | UUID | FK -> users |
| lead_id | UUID | FK -> leads, nullable |
| deal_id | UUID | FK -> deals, nullable |
| type | ENUM | call, email, whatsapp, meeting, note, task |
| subject | VARCHAR(255) | |
| body | TEXT | |
| scheduled_at | TIMESTAMP | |
| completed_at | TIMESTAMP | |
### messages
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| lead_id | UUID | FK -> leads, nullable |
| contact_id | UUID | FK -> contacts, nullable |
| channel | ENUM | whatsapp, email, sms, in_app |
| direction | ENUM | inbound, outbound |
| content | TEXT | |
| status | ENUM | queued, sent, delivered, read, failed |
| sent_at | TIMESTAMP | |
### proposals
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| deal_id | UUID | FK -> deals |
| version | INTEGER | |
| title | VARCHAR(255) | |
| content | JSONB | structured proposal data |
| status | ENUM | draft, sent, viewed, accepted, rejected |
| sent_at | TIMESTAMP | |
| viewed_at | TIMESTAMP | |
### notifications
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| user_id | UUID | FK -> users |
| type | VARCHAR(50) | |
| title | VARCHAR(255) | |
| body | TEXT | |
| channel | ENUM | in_app, email, whatsapp, sms |
| is_read | BOOLEAN | |
| read_at | TIMESTAMP | |
### subscriptions
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| plan | ENUM | free, starter, pro, enterprise |
| status | ENUM | active, past_due, cancelled, trialing |
| current_period_start | TIMESTAMP | |
| current_period_end | TIMESTAMP | |
| payment_provider | VARCHAR(50) | |
| external_id | VARCHAR(255) | provider subscription ID |
### templates
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants, nullable (global templates) |
| type | ENUM | whatsapp, email, sms, proposal |
| name | VARCHAR(255) | |
| language | VARCHAR(5) | ar, en |
| subject | VARCHAR(255) | |
| body | TEXT | supports variables |
| is_active | BOOLEAN | |
### properties
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| entity_type | VARCHAR(50) | lead, deal, contact, company |
| entity_id | UUID | |
| key | VARCHAR(100) | |
| value | TEXT | |
### audit_logs
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| user_id | UUID | FK -> users |
| action | VARCHAR(50) | create, update, delete, login, export |
| entity_type | VARCHAR(50) | |
| entity_id | UUID | |
| changes | JSONB | before/after diff |
| ip_address | VARCHAR(45) | |
---
## Affiliate Tables
### affiliates
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| user_id | UUID | FK -> users |
| status | ENUM | applied, approved, active, suspended, terminated |
| tier | ENUM | bronze, silver, gold, platinum |
| referral_code | VARCHAR(20) | unique |
| commission_rate | DECIMAL(5,2) | percentage |
| approved_at | TIMESTAMP | |
### affiliate_performances
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| affiliate_id | UUID | FK -> affiliates |
| period | DATE | month start |
| leads_generated | INTEGER | |
| deals_closed | INTEGER | |
| revenue_attributed | DECIMAL(12,2) | |
| commission_earned | DECIMAL(12,2) | |
| conversion_rate | DECIMAL(5,2) | |
### affiliate_deals
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| affiliate_id | UUID | FK -> affiliates |
| deal_id | UUID | FK -> deals |
| lead_id | UUID | FK -> leads |
| attributed_revenue | DECIMAL(12,2) | |
| commission_amount | DECIMAL(12,2) | |
| status | ENUM | pending, confirmed, paid, disputed |
---
## AI Tables
### ai_conversations
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| agent_type | VARCHAR(50) | agent identifier |
| lead_id | UUID | FK -> leads, nullable |
| contact_id | UUID | FK -> contacts, nullable |
| input_payload | JSONB | |
| output_payload | JSONB | |
| tokens_used | INTEGER | |
| latency_ms | INTEGER | |
| status | ENUM | success, error, escalated |
### auto_bookings
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| lead_id | UUID | FK -> leads |
| agent_id | UUID | FK -> users (assigned agent) |
| proposed_time | TIMESTAMP | |
| confirmed_time | TIMESTAMP | |
| status | ENUM | proposed, confirmed, rescheduled, cancelled, completed |
| channel | VARCHAR(20) | whatsapp, email |
| calendar_event_id | VARCHAR(255) | external calendar ref |
---
## New Tables
### companies
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| name | VARCHAR(255) | |
| name_ar | VARCHAR(255) | Arabic name |
| sector | VARCHAR(100) | |
| size | ENUM | micro, small, medium, large, enterprise |
| city | VARCHAR(100) | |
| region | VARCHAR(100) | |
| cr_number | VARCHAR(20) | commercial registration |
| website | VARCHAR(255) | |
| is_active | BOOLEAN | |
### contacts
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| company_id | UUID | FK -> companies, nullable |
| lead_id | UUID | FK -> leads, nullable |
| full_name | VARCHAR(255) | |
| job_title | VARCHAR(100) | |
| email | VARCHAR(255) | |
| phone | VARCHAR(20) | |
| whatsapp | VARCHAR(20) | |
| language | VARCHAR(5) | ar, en |
| consent_status | ENUM | granted, revoked, pending |
### prospects
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| company_id | UUID | FK -> companies, nullable |
| contact_id | UUID | FK -> contacts, nullable |
| source | VARCHAR(50) | |
| status | ENUM | identified, researching, approaching, engaged, disqualified |
| priority | ENUM | low, medium, high, critical |
| sector | VARCHAR(100) | |
| estimated_value | DECIMAL(12,2) | |
| notes | TEXT | |
### calls
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| lead_id | UUID | FK -> leads, nullable |
| contact_id | UUID | FK -> contacts, nullable |
| user_id | UUID | FK -> users |
| direction | ENUM | inbound, outbound |
| status | ENUM | ringing, answered, missed, voicemail, failed |
| duration_seconds | INTEGER | |
| recording_url | TEXT | |
| transcript | TEXT | AI-generated |
| sentiment | VARCHAR(20) | positive, neutral, negative |
| outcome | VARCHAR(50) | |
### commissions
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| affiliate_id | UUID | FK -> affiliates |
| deal_id | UUID | FK -> deals |
| amount | DECIMAL(12,2) | |
| currency | VARCHAR(3) | SAR |
| rate | DECIMAL(5,2) | percentage applied |
| status | ENUM | pending, approved, paid, disputed, cancelled |
| approved_by | UUID | FK -> users, nullable |
| approved_at | TIMESTAMP | |
| period | DATE | commission period |
### payouts
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| affiliate_id | UUID | FK -> affiliates |
| amount | DECIMAL(12,2) | |
| currency | VARCHAR(3) | |
| method | ENUM | bank_transfer, wallet, check |
| status | ENUM | pending, processing, completed, failed |
| reference | VARCHAR(100) | payment reference |
| bank_name | VARCHAR(100) | |
| iban | VARCHAR(34) | |
| processed_at | TIMESTAMP | |
### disputes
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| commission_id | UUID | FK -> commissions, nullable |
| affiliate_id | UUID | FK -> affiliates |
| type | ENUM | commission, attribution, payout, guarantee |
| status | ENUM | open, under_review, resolved, escalated, closed |
| description | TEXT | |
| resolution | TEXT | |
| resolved_by | UUID | FK -> users, nullable |
| resolved_at | TIMESTAMP | |
### guarantee_claims
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| deal_id | UUID | FK -> deals |
| customer_id | UUID | FK -> customers |
| claim_type | ENUM | performance, quality, delivery, other |
| status | ENUM | submitted, reviewing, approved, denied, refunded |
| description | TEXT | |
| evidence | JSONB | uploaded proof references |
| amount_claimed | DECIMAL(12,2) | |
| amount_approved | DECIMAL(12,2) | |
| reviewed_by | UUID | FK -> users, nullable |
| reviewed_at | TIMESTAMP | |
### refunds
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| guarantee_claim_id | UUID | FK -> guarantee_claims |
| deal_id | UUID | FK -> deals |
| amount | DECIMAL(12,2) | |
| currency | VARCHAR(3) | |
| status | ENUM | pending, processing, completed, failed |
| method | ENUM | bank_transfer, original_method, wallet |
| processed_at | TIMESTAMP | |
| reference | VARCHAR(100) | |
### consents
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| contact_id | UUID | FK -> contacts |
| channel | ENUM | whatsapp, email, sms, phone |
| status | ENUM | granted, revoked |
| granted_at | TIMESTAMP | |
| revoked_at | TIMESTAMP | |
| ip_address | VARCHAR(45) | |
| source | VARCHAR(50) | how consent was collected |
### complaints
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| contact_id | UUID | FK -> contacts, nullable |
| customer_id | UUID | FK -> customers, nullable |
| category | ENUM | service, billing, communication, privacy, other |
| status | ENUM | open, investigating, resolved, closed |
| severity | ENUM | low, medium, high, critical |
| description | TEXT | |
| resolution | TEXT | |
| assigned_to | UUID | FK -> users, nullable |
| resolved_at | TIMESTAMP | |
### policies
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants, nullable (platform-wide) |
| type | ENUM | commission, guarantee, refund, compliance, privacy |
| name | VARCHAR(255) | |
| content | TEXT | |
| version | INTEGER | |
| is_active | BOOLEAN | |
| effective_from | DATE | |
### knowledge_articles
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants, nullable (shared) |
| category | VARCHAR(100) | |
| title | VARCHAR(255) | |
| title_ar | VARCHAR(255) | |
| body | TEXT | |
| body_ar | TEXT | |
| embedding | VECTOR(1536) | for RAG retrieval |
| sector | VARCHAR(100) | nullable |
| is_published | BOOLEAN | |
### sector_assets
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants, nullable |
| sector | VARCHAR(100) | |
| asset_type | ENUM | pitch_deck, case_study, objection_map, pricing_guide, competitor_matrix |
| title | VARCHAR(255) | |
| content | JSONB | structured asset data |
| language | VARCHAR(5) | ar, en |
| is_active | BOOLEAN | |
### scorecards
| Field | Type | Notes |
|-------|------|-------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants |
| user_id | UUID | FK -> users |
| period | DATE | scoring period |
| leads_handled | INTEGER | |
| deals_closed | INTEGER | |
| revenue_generated | DECIMAL(12,2) | |
| avg_response_time | INTEGER | seconds |
| customer_satisfaction | DECIMAL(3,2) | 0.00-5.00 |
| ai_assist_rate | DECIMAL(5,2) | percentage of AI-assisted interactions |
| composite_score | DECIMAL(5,2) | weighted aggregate |
---
## Entity Relationships
```
tenants 1--* users
tenants 1--* leads
tenants 1--* deals
tenants 1--* companies
tenants 1--* contacts
leads *--1 users (assigned_to)
leads 1--* deals
leads 1--* activities
leads 1--* messages
leads 1--* ai_conversations
leads 1--* auto_bookings
leads 1--* calls
deals 1--* proposals
deals 1--* commissions
deals 1--* guarantee_claims
companies 1--* contacts
contacts 1--* messages
contacts 1--* calls
contacts 1--* consents
affiliates 1--1 users
affiliates 1--* affiliate_deals
affiliates 1--* affiliate_performances
affiliates 1--* commissions
affiliates 1--* payouts
affiliates 1--* disputes
guarantee_claims 1--* refunds
commissions 1--* disputes
```