System Architecture
A complete technical overview of the Twallia platform — AI-powered voice teammates for the front line of small and medium business.
System Architecture Diagram
Four layers — external users, telephony & frontend, core backend, and data & AI services.
Key System Flows
How data moves through the platform for the four most important user journeys.
Inbound Call Flow
Sign-Up Flow
Appointment Booking
Outbound Campaign
Platform Components
Each component and its responsibility within the system.
Marketing Frontend
React 19 + Vite SPA. Homepage, auth flows, contact, blog, and dynamic CMS-driven pages. Communicates with backend via REST API.
CMS Portal
Next.js 15 + Payload CMS. Self-service portal: profile, phone settings, agent config, transcripts, usage analytics, billing and outbound campaigns.
Auth API
JWT-based auth with email verification. Dual persistence (MongoDB + JSON fallback). Rate-limited signup/verify routes. SSO token for portal login.
Voice Engine
Real-time audio pipeline. Converts Twilio μ-law 8kHz to PCM for OpenAI/Gemini. Streams bidirectionally. Supports function calling mid-call.
Appointment Engine
Server-side booking logic. AI cannot directly access the calendar — all intent parsing, slot checking and booking happens server-side. Anti-hallucination by design.
Telephony Layer
Twilio provider with TwiML generation, media stream routing, SMS, SIP domains, softphone (Twilio.js) and per-second call cost tracking.
Outbound Scheduler
Cron-based campaign dialer. Fetches active CallSchedules from CMS, respects office hours, initiates Twilio calls and tracks results and cost.
Chat Widget
Embeddable JS snippet for any website. No auth required, rate-limited. Uses GPT-4.1-mini for conversations, captures leads and supports appointment booking.
MongoDB / CMS Collections
20 Payload CMS collections: Users, Tenants, TenantProfiles, CallSessions, Transcripts, Customers, CallSchedules, Appointments, UsageEvents and more.
Billing (Stripe)
Three subscription tiers — Starter $39, Growth $89, Pro $199/mo. Checkout sessions, webhook handler for subscription lifecycle events.
External Services
Third-party services the platform depends on and their role.
| Service | Purpose | Auth | Tier |
|---|---|---|---|
| Twilio | Phone numbers, inbound/outbound calls, SMS, media streams, SIP domains, softphone tokens | Account SID + Auth Token | Core |
| OpenAI | GPT-4o Realtime (voice), gpt-4.1-mini (chat), gpt-4.1-nano (summaries) | API Key | Core |
| Google Gemini | Gemini Live — alternate real-time voice provider | API Key | Core |
| MongoDB Atlas | Primary database for all 20 CMS collections | Connection URI | Core |
| Stripe | Subscription management, checkout sessions, webhook events | Secret Key + Webhook Secret | Core |
| Google Calendar | Appointment availability, booking and cancellation via OAuth 2.0 | OAuth 2.0 (per tenant) | Core |
| Microsoft Outlook | Alternate calendar provider for Microsoft 365 users | OAuth 2.0 (per tenant) | Optional |
| Brevo | Transactional email — verification codes, password reset, contact notifications | API Key + SMTP | Core |
| Google Analytics | Website analytics, page views, user behaviour on twallia.com | Measurement ID | Analytics |
| Coolify | Self-hosted deployment — CI/CD, environment variables, SSL, domain routing | Deploy webhook | Infra |