Platform Architecture

Technology Stack

Operator is engineered for high-concurrency real-time conversational processing: - Framework: Next.js 16 (App Router, React Server Components, Server Actions). - Database: PostgreSQL with pgvector extension for vector similarity search. - ORM: Drizzle ORM with strict type schemas defined in src/server/db/schema.ts. - Speech & Telephony: Twilio Voice, SIP Webhooks, and bi-directional audio streaming. - AI & Reasoning: Centralized LLM orchestration with automated provider fallback. - Styling & Tokens: Pure CSS Design System tokens mapped to Tailwind CSS utilities.

Service Layers

The codebase enforces clean separation of concerns: - src/server/actions/*: Server actions handling client requests, authentication checks, IDOR assertions, and revalidation. - src/server/services/*: Business domain services (e.g., orchestrator.ts, booking.ts, availability.ts, rag.ts, scoring.ts). - src/server/repositories/*: Data access layer encapsulating Drizzle database queries. - src/server/db/schema.ts: Complete PostgreSQL schema covering organizations, users, conversations, appointments, knowledge base, and billing.

Data Flow Diagram

Customer (Voice / Web / WhatsApp)
               │
               ▼
 Webhook / API Route (/api/webhooks/*, /api/widget/*)
               │
               ▼
 Omnichannel Router (omnichannelRouter.processIncomingMessage)
               │
               ▼
 Orchestrator Service (orchestratorService.processMessage)
    ├── Identity Resolver (CRM profile lookup / creation)
    ├── Intent Classification (intentService.classifyIntent)
    ├── RAG Knowledge Retrieval (ragService.retrieveRelevantChunks)
    ├── Availability Engine (availabilityService.getAvailableSlots)
    └── Dynamic Action Engine (actionEngine.execute)
               │
               ▼
 Database Persistence (channelMessages, conversations, appointments)
               │
               ▼
 Outgoing Dispatcher (sendOutgoingMessage -> Twilio / Meta / Webhook)

Multi-Tenant Data Isolation

Every tenant belongs to an organization. All database tables containing customer or business data enforce an organizationId foreign key. - Server actions call requireOrganizationAccess() to extract the authenticated user's active organization ID from encrypted session cookies. - Server actions invoke assertResourceOwnership() on every mutation, preventing Insecure Direct Object References (IDOR).