system-prompts-and-models-o.../salesflow-saas/docs/API-MAP.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

9.3 KiB

API Route Map

All routes are prefixed with /api/v1. Authentication is required unless marked [public]. Tenant scoping is automatic via JWT.


Auth

Method Route Description
POST /auth/register Register new tenant + owner [public]
POST /auth/login Email/password login [public]
POST /auth/refresh Refresh access token
POST /auth/logout Invalidate session
GET /auth/me Current user profile
PUT /auth/me Update profile
POST /auth/forgot-password Request password reset [public]
POST /auth/reset-password Reset with token [public]
POST /auth/verify-otp OTP verification

Leads

Method Route Description
GET /leads List leads (filterable, paginated)
POST /leads Create lead
GET /leads/{id} Get lead details
PUT /leads/{id} Update lead
DELETE /leads/{id} Soft-delete lead
POST /leads/{id}/qualify Trigger AI qualification
POST /leads/{id}/assign Assign to agent
POST /leads/{id}/convert Convert to deal
GET /leads/{id}/activities Lead activity timeline
GET /leads/{id}/messages Lead message history
POST /leads/import Bulk import (CSV/Excel)
GET /leads/export Export leads

Deals

Method Route Description
GET /deals List deals (filterable, paginated)
POST /deals Create deal
GET /deals/{id} Get deal details
PUT /deals/{id} Update deal
DELETE /deals/{id} Soft-delete deal
PUT /deals/{id}/stage Move deal stage
GET /deals/{id}/proposals List proposals for deal
POST /deals/{id}/proposals Generate proposal
GET /deals/pipeline Pipeline summary by stage
GET /deals/forecast Revenue forecast

Dashboard

Method Route Description
GET /dashboard/summary KPI summary
GET /dashboard/pipeline Pipeline analytics
GET /dashboard/revenue Revenue metrics
GET /dashboard/agents Agent performance
GET /dashboard/affiliates Affiliate overview
GET /dashboard/activity Recent activity feed

Affiliates

Method Route Description
GET /affiliates List affiliates
POST /affiliates Create affiliate application
GET /affiliates/{id} Get affiliate details
PUT /affiliates/{id} Update affiliate
PUT /affiliates/{id}/approve Approve affiliate
PUT /affiliates/{id}/suspend Suspend affiliate
GET /affiliates/{id}/performance Performance metrics
GET /affiliates/{id}/deals Attributed deals
GET /affiliates/{id}/commissions Commission history
GET /affiliates/leaderboard Ranked leaderboard

AI Agents

Method Route Description
GET /agents List available agents
POST /agents/{agent_type}/invoke Invoke agent manually
GET /agents/{agent_type}/history Agent invocation history
GET /agents/conversations All AI conversations
GET /agents/conversations/{id} Conversation detail

New Routes

Companies

Method Route Description
GET /companies List companies
POST /companies Create company
GET /companies/{id} Get company details
PUT /companies/{id} Update company
DELETE /companies/{id} Soft-delete company
GET /companies/{id}/contacts List contacts at company
GET /companies/{id}/deals Deals linked to company

Contacts

Method Route Description
GET /contacts List contacts
POST /contacts Create contact
GET /contacts/{id} Get contact details
PUT /contacts/{id} Update contact
DELETE /contacts/{id} Soft-delete contact
GET /contacts/{id}/messages Message history
GET /contacts/{id}/calls Call history
GET /contacts/{id}/consents Consent records

Conversations

Method Route Description
GET /conversations List AI conversations
GET /conversations/{id} Get conversation detail
GET /conversations/{id}/messages Message thread
POST /conversations/{id}/escalate Escalate to human

Calls

Method Route Description
GET /calls List calls
POST /calls Log a call
GET /calls/{id} Call detail
GET /calls/{id}/transcript AI transcript
PUT /calls/{id}/outcome Set call outcome

Meetings

Method Route Description
GET /meetings List meetings
POST /meetings Create meeting
GET /meetings/{id} Meeting detail
PUT /meetings/{id} Update meeting
PUT /meetings/{id}/confirm Confirm meeting
PUT /meetings/{id}/cancel Cancel meeting
PUT /meetings/{id}/reschedule Reschedule meeting
GET /meetings/availability Check agent availability

Commissions

Method Route Description
GET /commissions List commissions
GET /commissions/{id} Commission detail
PUT /commissions/{id}/approve Approve commission
PUT /commissions/{id}/dispute Dispute commission
GET /commissions/summary Period summary

Payouts

Method Route Description
GET /payouts List payouts
POST /payouts Create payout batch
GET /payouts/{id} Payout detail
PUT /payouts/{id}/process Process payout
GET /payouts/pending Pending payouts

Disputes

Method Route Description
GET /disputes List disputes
POST /disputes Open dispute
GET /disputes/{id} Dispute detail
PUT /disputes/{id}/resolve Resolve dispute
PUT /disputes/{id}/escalate Escalate dispute

Guarantees

Method Route Description
GET /guarantees List guarantee claims
POST /guarantees Submit claim
GET /guarantees/{id} Claim detail
PUT /guarantees/{id}/review Review claim
PUT /guarantees/{id}/approve Approve claim
PUT /guarantees/{id}/deny Deny claim
POST /guarantees/{id}/refund Trigger refund

Consents

Method Route Description
GET /consents List consent records
POST /consents Record consent
PUT /consents/{id}/revoke Revoke consent
GET /consents/contact/{contact_id} Consents for contact

Complaints

Method Route Description
GET /complaints List complaints
POST /complaints File complaint
GET /complaints/{id} Complaint detail
PUT /complaints/{id}/assign Assign to agent
PUT /complaints/{id}/resolve Resolve complaint

Knowledge

Method Route Description
GET /knowledge List articles
POST /knowledge Create article
GET /knowledge/{id} Article detail
PUT /knowledge/{id} Update article
DELETE /knowledge/{id} Archive article
POST /knowledge/search Semantic search (RAG)

Sectors

Method Route Description
GET /sectors List sectors
GET /sectors/{sector} Sector detail
GET /sectors/{sector}/assets Sector assets
POST /sectors/{sector}/assets Upload asset
GET /sectors/{sector}/strategy AI sector strategy
GET /sectors/{sector}/scorecards Sector scorecards

Presentations

Method Route Description
GET /presentations List presentations
POST /presentations Generate presentation
GET /presentations/{id} Get presentation
PUT /presentations/{id} Update presentation
POST /presentations/{id}/send Send to contact

Supervisor

Method Route Description
GET /supervisor/agents Agent workload overview
GET /supervisor/queue Unassigned lead queue
POST /supervisor/reassign Bulk reassign leads
GET /supervisor/scorecards Team scorecards
GET /supervisor/alerts Escalation alerts

Admin

Method Route Description
GET /admin/tenants List tenants (superadmin)
GET /admin/tenants/{id} Tenant detail
PUT /admin/tenants/{id} Update tenant
GET /admin/users List all users
GET /admin/audit-logs Audit log viewer
GET /admin/policies List policies
POST /admin/policies Create policy
PUT /admin/policies/{id} Update policy
GET /admin/subscriptions Subscription overview
POST /admin/seed Seed demo data (dev only)

Health

Method Route Description
GET /health Basic health check [public]
GET /health/ready Readiness (DB + Redis) [public]
GET /health/version App version [public]