How it works

Documentation Index

Fetch the complete documentation index at: https://docs.vorel.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

The big picture

ingress  →  conversation context  →  router  →  sub-agent  →  terminal

• Ingress receives the customer event from a telephony / messaging vendor and verifies the signature.
• Conversation context hydrates the conversation history, customer identity, vertical pack, and persona.
• Router is a small LLM (Gemini 2.5 Flash-Lite) that classifies the customer’s intent into one of ~10 categories.
• Sub-agent (qualification / FAQ / booking / handoff) runs the actual reply-generation loop with the tools it’s allowed to call.
• Terminal persists the agent reply, runs guardrails (forbidden-phrase + hallucination), and ships the reply back to the customer.

​

The components

​

Voice flow, end to end

Customer phone → Telnyx DID → Telnyx SIP trunk → Vapi
                                                  ├─ Deepgram nova-3 (multi) — STT
                                                  ├─ ElevenLabs eleven_turbo_v2_5 — TTS
                                                  └─ Vorel custom-LLM proxy
                                                       ↓
                                                  /api/vapi/chat/completions
                                                       ↓
                                                  router → sub-agent → tool calls
                                                       ↓
                                                  reply text
                                                       ↓
                                                  ElevenLabs TTS → Vapi → caller

1. assistant-request — fired by Vapi on call connect. We resolve the tenant by vapi_phone_number_id, build a per-tenant assistant config (persona-interpolated system prompt, tool ids, voice + transcriber), and return it within Vapi’s 7.5s budget. This is what makes per-tenant config possible without re-publishing to the Vapi dashboard on every persona edit.
2. /api/vapi/chat/completions — Vapi’s OpenAI-compatible proxy hits this on every LLM turn. We translate the request to Gemini, run the agent dispatch (router + sub-agent + tools), and stream the reply back as a chat.completion chunk stream.
3. end-of-call-report — fired by Vapi when the call ends. The worker processes the report, persists the transcript + recording URL + Vapi cost breakdown, runs the QA scoring pipeline, and emits the cost rollup events.

​

Chat flow, end to end

Customer WhatsApp → 360dialog Cloud → /api/webhooks/whatsapp (signature-verified)
                                          ↓
                                       BullMQ (message-processor queue)
                                          ↓
                                       worker:
                                          ├─ persists customer turn + upserts Customer
                                          └─ POSTs /api/internal/agent/dispatch
                                                  ↓
                                              router → sub-agent → tool calls
                                                  ↓
                                              send_whatsapp_message (writes outbox)

​

The router → sub-agent shape

• greeting · faq · new_lead_inquiry · existing_lead_update · booking · reschedule_or_cancel · human_request · complaint · spam_or_unrelated · out_of_scope

​

The tool layer

1. JWT verification + per-(tenant, tool) rate limit (50 req/min).
2. withTenantContext — opens a Postgres transaction with SET LOCAL app.current_tenant_id, so RLS is set before any query runs.
3. Tool body — handles its specific job (DB read, vector similarity over offerings / KB, CRM proxy call, calendar check, etc.).
4. tool_call + tool_result log lines are emitted with W3C trace-context propagation, so an operator can follow a single conversation across web + worker + the post-call QA pipeline.

​

The customer identity model

​

Storage layout (high-level)

​

QA scoring pipeline

• A normalised score (0–11)
• Per-criterion breakdown
• Hallucination flags graded by a separate v1 grader (severity: low / medium / high)

​

Reliability posture

• Gemini 5xx / DEADLINE_EXCEEDED — withGeminiRetry retries with backoff; a terminal failure inside the sub-agent dispatch falls through to a short ack (“One moment, please”) plus a fell_back: true flag the inbox surfaces.
• Redis blip on rate limit — fail-open: a Redis outage admits the request rather than 429-ing every customer. Logged as rate_limit.redis_failed.
• CRM driver 401 — OAuth drivers refresh + retry once; refreshed tokens get re-encrypted and persisted back into tenant_credentials (rotated_at updated). Refresh failures audit-log + return auth_error to the agent, which falls back to a polite “I’ll have someone reach out” rather than hallucinating CRM data.
• Vendor outage on a hot path — see SLOs. Tool-route success rate (99.9%) and voice-call success rate (99.5%) are the two we measure most aggressively; webhook delivery rides a 6-attempt retry ladder over [60s, 300s, 1800s, 7200s, 43200s].

​

What’s NOT in the picture today

• Per-region routing. tenants.region is captured at create time; routing on it (running EU tenants out of an EU Postgres replica) is on the roadmap.
• Stripe billing. Cost rollup is captured in billing_events; invoicing is operator-driven from the rollup until the Stripe model lands.
• Outbound voice (Vorel-initiated calls). Inbound only today.
• Voicemail / fallback when LLM provider is down. A failed call disconnects.
• Real n8n deployment. The around-the-brain templates exist on disk + the operator-side discoverability page lists them, but n8n is not yet deployed as a Railway service. Per-turn dispatch (router + sub-agent + tools) runs in TypeScript inside the web app, not in n8n.

​

Where to go next