AlsaTalk Architecture

Enterprise AI telephony solution with 6 microservices, 236 APIs, deployed on AWS EKS.

Total Services 6

Microservices on Kubernetes handling auth, calls, campaigns, integrations, admin, and AI tools.

API Endpoints 236

REST APIs across all services. Documented with coupling analysis and dependency mapping.

Database Tables 30+

Shared PostgreSQL database on AWS RDS. All services access the same instance.

Technology Stack

Component	Technology	Purpose
Backend	Python FastAPI	REST API services
Database	PostgreSQL (AWS RDS)	Primary data store
Voice	LiveKit + SIP	Real-time calls
AI	Gemini / GPT-4	Conversation AI
Orchestration	Kubernetes (EKS)	Container management
Gateway	Nginx Ingress	Load balancing, SSL

Microservices

6 services with varying levels of coupling and complexity.

auth-user-service

:8001 54 APIs

Authentication, organizations, users, payments (Stripe), phone number management, SIP trunk creation.

Coupling: MEDIUM | Calls: Twilio, Stripe, LiveKit

ai-call-service

:8002 44 APIs

Core telephony engine. AI agents, LiveKit rooms, SIP trunks, transcriptions, call lifecycle.

Coupling: HIGH | Called by: campaigns, mcp-server

campaign-leads-service

:8003 25 APIs

Campaign management, lead lifecycle, call queue, bulk import, scheduling.

Coupling: HIGH | CIRCULAR with ai-call!

integrations-service

:8004 48 APIs

Third-party integrations: Zoho CRM, Google Calendar, Gmail, Zoom, HubSpot, Pipedrive.

Coupling: LOW | External APIs only

master-service

:8005 57 APIs

Admin dashboard, billing, subscriptions, super admin functions.

Coupling: LOW | Internal admin only

mcp-server

:8089 8 Tools

MCP Protocol server for AI agent tool execution during calls. Book meetings, send SMS, create leads.

Coupling: HIGH | Calls: ai-call, integrations

Call Flows

How calls move through the system from start to finish.

Outbound Campaign Call

1. User clicks "Start Campaign" in Frontend
   ↓
2. POST /campaigns/{id}/start-campaign → campaign-leads-service
   ↓
3. campaign-leads → POST /ai-call/calls/trigger (with lead data)
   ↓
4. ai-call → Creates LiveKit Room + SIP Participant
   ↓
5. LiveKit → Connects to Twilio/Yeastar SIP Trunk
   ↓
6. Call Established → AI Agent starts conversation
   ↓
7. LiveKit → POST /ai-call/webhooks/livekit (events)
   ↓
8. ai-call → POST /campaigns/webhook/call-completed
   ↓
9. ai-call → POST /integrations/zoho/update-lead

Inbound Call

1. Customer dials Twilio/Yeastar number
   ↓
2. SIP Provider → LiveKit Inbound Trunk
   ↓
3. LiveKit → Triggers inbound_agent.py worker
   ↓
4. Worker fetches agent config from ai-call-service
   ↓
5. AI Agent answers, processes conversation
   ↓
6. MCP tools executed (booking, CRM, SMS)
   ↓
7. Transcription saved, CRM synced

Infrastructure Architecture

AWS EKS deployment in me-central-1 (UAE) with Docker containers.

Client Layer

🌐

Web App

React Frontend

📱

Mobile

Future

🔌

API Users

REST API

↓

Ingress Layer

🛡️

Nginx Ingress Controller

SSL Termination • Load Balancing • Routing

↓

☸️ AWS EKS Cluster — me-central-1 (UAE)

🔑

auth-user-service

:8001

54 APIs • Auth, Users, Orgs

🤖

ai-call-service

:8002

44 APIs • HIGH COUPLING

📢

campaign-leads

:8003

25 APIs • CIRCULAR DEP!

🔗

integrations

:8004

48 APIs • Low Coupling

⚙️

master-service

:8005

57 APIs • Admin, Billing

🛠️

mcp-server

:8089

8 Tools • AI Actions

↓ SQL

↑↓ HTTP

↑↓ WebRTC/SIP

Database Layer

🗄️

AWS RDS PostgreSQL

Shared DB (Problem!)

📜

MongoDB

Future: Access Logs

External APIs

🤖

Gemini AI

💳

Stripe

📧

Google APIs

🔗

Zoho CRM

Telephony Layer

📞

LiveKit Cloud

WebRTC + SIP

📱

Twilio

🏢

Yeastar

AWS Services

Component	Service	Region	Purpose
Kubernetes	AWS EKS	me-central-1	Container orchestration
Database	AWS RDS PostgreSQL	me-central-1	Primary data store (shared)
Container Registry	AWS ECR	me-central-1	Docker image storage
Load Balancer	AWS ALB	me-central-1	HTTPS traffic distribution
DNS	Route 53	Global	Domain management
Secrets	K8s Secrets	In-cluster	API keys, credentials

External Service Integrations

LiveKit Cloud WebRTC

Real-time voice infrastructure. Handles SIP trunking, room management, and WebRTC connections.

Twilio SIP

Global SIP provider for USA/International calls. Phone number provisioning.

Yeastar SIP

UAE local SIP provider. Lower latency for Middle East region calls.

Google Gemini AI

Primary AI model for voice conversations. Real-time speech processing.

What's Working Well

Current strengths of the platform.

Real-time AI Voice Working

LiveKit + Gemini integration enables natural AI conversations with low latency.

Multi-provider SIP Working

Twilio (USA/Global) and Yeastar (UAE/Local) support. Flexible provider choice.

CRM Integrations Working

Deep Zoho integration with HubSpot, Pipedrive, Close support.

MCP Tool Framework Working

AI agents execute real actions during calls: meetings, SMS, leads.

Campaign Management Working

Bulk import, scheduling, queue management, automatic retries.

Live Transcription Working

Real-time transcription with speaker identification.

What Needs Modification

Changes required to make these features enterprise-ready.

Real-time AI Voice Modify

Add fallback AI providers (OpenAI, Anthropic). Currently single-provider dependency. Add circuit breaker for AI API failures.

Multi-provider SIP Modify

Implement automatic failover between Twilio and Yeastar. Add health monitoring for SIP trunks. Need retry logic on SIP failures.

CRM Integrations Modify

Add webhook retry queue for failed CRM syncs. Implement rate limiting to avoid API throttling. Add sync conflict resolution.

MCP Tool Framework Modify

Add tool execution timeout handling. Implement rollback for partially completed actions. Add audit logging for all tool executions.

Campaign Management Modify

Break circular dependency with ai-call-service. Add async event-driven updates via message queue. Implement proper retry backoff.

Live Transcription Modify

Add transcription storage optimization (currently storing raw). Implement summarization pipeline. Add PII redaction for compliance.

Critical Flaws

Issues preventing enterprise-grade scalability.

Shared Database Critical

All 6 services share ONE PostgreSQL database. No isolation, can't scale independently, compliance risk.

Circular Dependencies Critical

campaign-leads ↔ ai-call circular HTTP calls. One down = both fail. No circuit breakers.

Shared JWT Secret High

Same JWT_SECRET_KEY across all services. Token compromise = full system breach.

No Rate Limiting High

CORS set to "*" in some services. No rate limiting between services.

Code Duplication Medium

5 copies of models.py across services. Merge conflicts, inconsistent enums.

No Audit Logging Medium

No infrastructure for compliance audit trails. GDPR/HIPAA gap.

API Coupling Analysis

236 APIs with inter-service dependency mapping.

Service	Port	APIs	Coupling	Dependencies
auth-user-service	8001	54	Medium	Twilio, Stripe, LiveKit
ai-call-service	8002	44	High	LiveKit, campaigns, integrations
campaign-leads	8003	25	High	ai-call (circular!)
integrations	8004	48	Low	Zoho, Gmail, Zoom, etc.
master-service	8005	57	Low	Twilio, Stripe
mcp-server	8089	8	High	ai-call, integrations

Critical Circular Dependency

campaign-leads → POST /ai-call/calls/trigger (start call)
            ↓
ai-call → LiveKit (establish call)
            ↓
LiveKit → POST /ai-call/webhooks/livekit (events)
            ↓
ai-call → POST /campaigns/webhook/call-completed
            ↓
⚠️ If ai-call down → campaigns can't start calls
⚠️ If campaigns down → ai-call can't update status
⚠️ RESULT: Cascading failures, no resilience

Proposed Changes

Phased approach to fix critical issues.

Priority 1: Shared Library Urgent

Create shared/ package with models, schemas, security. Eliminates 80% of merge conflicts.

Priority 2: API Contracts High

OpenAPI specs for inter-service APIs. Breaking change detection in CI/CD.

Priority 3: Multi-DB per Org Medium

Each organization gets its own PostgreSQL database. Complete data isolation.

Future: MongoDB Access Logs Future

Central MongoDB for platform logs: org CRUD, frontend actions, audit trails.

Future Architecture

👥

Clients

↓

🛡️
Kong Gateway

↓

🔑

Auth

🤖

AI Engine

📢

Campaigns

🔗

Integrations

↓ Direct HTTP

🗄️
Org DB 1

🗄️
Org DB 2

🗄️
Org DB N

↓ Access Logs

📜

MongoDB (Future)

Multi-Database Architecture

One PostgreSQL database per organization for complete isolation.

Component	Database	Purpose
Organization Data	PostgreSQL (per org)	Users, agents, campaigns, leads, calls, transcriptions
Platform Logs	MongoDB (central)	Org CRUD, frontend actions, access logs, audit trails
Master Data	PostgreSQL (shared)	Subscriptions, billing, super admin

Benefits

Data Privacy

Complete isolation. One org's breach doesn't affect others.

Compliance

GDPR, HIPAA, SOC2 ready. Auditable data boundaries.

Performance

No noisy neighbor. Heavy queries don't affect others.

Data Residency

Regional database placement for legal compliance.

Migration Plan

Phased approach with zero downtime.

Phase 1: Shared LibraryPriority

Create shared package, migrate models.py, update all imports.

Phase 2: API ContractsHigh

Document inter-service APIs, create OpenAPI specs, set up contract testing.

Phase 3: Multi-DB per OrgMedium

Create org provisioning system, auto-create PostgreSQL DB for each new org.

Phase 4: API GatewayNormal

Deploy Kong, configure rate limiting, JWT validation.

Future: MongoDB Access LogsFuture

Central MongoDB for platform logs, org CRUD tracking, frontend action audit.