How intervo/intervo works
1. Overall shape
- This is a monorepo for a conversational AI platform with three main product surfaces: an admin/dashboard web app, an embeddable customer-facing chat widget, and a Node.js backend that powers agent runtime, telephony, billing, and integrations.
- There is also a separate Python-based RAG service for knowledge ingestion/search, indicating a split between the core app server and the retrieval pipeline.
2. Frontend workspace: operator dashboard
- packages/intervo-frontend is a Next.js app using React and a large component/context structure.
- Its job is to let users sign up/log in, create workspaces, configure agents, build workflows, manage phone numbers, inspect activities/calls, and handle billing/settings.
- The frontend is state-heavy and organized by workspace/agent routes, with contexts for auth, workspace, agents, sources, phone numbers, activities, and admin tools.
3. Widget workspace: embeddable client UI
- packages/intervo-widget is a separate Vite-based React app intended to be embedded on external websites.
- It provides the end-user chat/call entry point, data collection, and conversation UI.
- This is the narrowest UI boundary in the system: it should talk to backend APIs/services, but not own business logic or persistence.
4. Backend workspace: core orchestration server
- packages/intervo-backend is the central runtime. It is a Node.js service with Express-style routing, models, services, handlers, and websocket logic.
- It owns business data, agent execution, call/session state, credential checks, billing hooks, and provider integrations.
- MongoDB is the primary persistence layer, inferred from the presence of Mongoose-style models/, DB config, and migration scripts.
5. Primary backend domains
- The backend is split into recognizable subsystems:
- Auth and workspace management: users, workspaces, verification, admin middleware, ownership checks.
- Agent and workflow management: agents, tools, intents, workflow routing, interactive sessions.
- Telephony and conversation runtime: Twilio handlers, call lifecycle helpers, websocket streaming, call recording/stopping.
- Billing/usage: Stripe handlers, credit service, usage routes.
- Knowledge base / RAG: knowledge sources, vector-backed retrieval, source ingestion.
- These domains are surfaced via route modules rather than a single monolith, which helps separate API boundaries.
6. Real-time conversation path
- The most important runtime path is the real-time voice/chat loop.
- For voice, Twilio streams audio to the backend websocket layer; the backend transcribes speech, routes to the agent/orchestration layer, generates a response with an LLM, then sends audio back via TTS and/or call control.
- Supporting services include multiple speech-to-text providers, multiple text-to-speech providers, and call recording/output utilities, so the backend acts as an adapter/orchestrator over external media APIs.
7. Agent orchestration and tool execution
- The repo has an explicit orchestration layer (services/OrchestrationManager.js, ToolManager.js, ai-flow.js, agent classes in agents/).
- This suggests agent behavior is not just prompt-response; it is workflow-driven, with routing based on intent, sub-agents, and tool calls.
- The backend is the boundary where the agent graph, tool invocation, and conversation state are coordinated before sending results back to the UI or call channel.
8. Knowledge ingestion and retrieval architecture
- There are two RAG implementations: JavaScript/Node modules under rag/ and a more fully featured Python service under rag_py/.
- The Python side includes crawler, storage, LLM service adapters, and a dedicated API, while the Node side exposes RAG service wrappers and tests.
- This implies knowledge base flows are: content ingestion from files/web/text/FAQ → chunking/embedding/vector storage → retrieval at runtime to augment agent responses.
9. External integrations and provider abstraction
- The backend is built around pluggable providers rather than a single AI vendor.
- It supports multiple LLMs, STT engines, TTS engines, Twilio for telephony, Stripe for billing, and email/utility services.
- The services/ and config/ folders show the integration boundary: provider-specific code is isolated so the agent runtime can switch vendors without changing higher-level business flow.
10. Routes and API surface
- API modules are grouped by domain: auth, users, workspace, agents, tools, voice, phone numbers, contacts, activity, usage, webhooks, workflow, stream, and interactive sessions.
- That layout indicates the backend is both a REST API for the dashboard/widget and a webhook/event processor for third-party services like Twilio and Stripe.
- The presence of websocket-specific files alongside REST routes shows the server exposes both request/response and streaming interfaces.
11. Persistence and domain models
- The models/ directory contains entities for users, workspaces, agents, calls, contacts, phone numbers, conversations, sources, tools, voices, integrations, and verification state.
- This is a multi-tenant SaaS data model centered on workspace ownership.
- The backend enforces tenant boundaries with middleware and ownership utilities, which is a key architectural boundary for diagramming.
12. Deployment and operational structure
- The repo supports Docker Compose for local full-stack startup and has a PM2-style ecosystem config for backend process management.
- This implies the production footprint is at least three services: frontend, backend API, and RAG service, plus external dependencies like MongoDB and third-party AI/telephony services.
- There are also export/sync scripts and open-source-specific compose files, showing the repo is designed for self-hosting and packaging.
13. How to draw the main architecture diagram
- Put the dashboard frontend and embeddable widget as separate clients on the left.
- Put the Node backend in the center as the system of record and orchestration hub.
- Connect the backend to MongoDB for persistence, Twilio for voice streaming/calls, Stripe for billing, and LLM/STT/TTS providers for AI/media processing.
- Place the Python RAG service as a sidecar/service boundary used by the backend for indexing and retrieval from knowledge sources.
- Show the backend as the only component that should own business logic and multi-tenant access control; the clients are presentation/control planes only.
Main entry points: server.js API Server · streamRouter.js Voice Runtime · knowledgebaseRouter.js Knowledge · api.py Python RAG
Components 19
Clients
User-facing dashboard and embedded widget
Backend
Node.js orchestration and API server
- API Server · Main backend entrypoint and request routing
packages/intervo-backend/server.js - Auth · Login, verification, middleware, and ownership checks
packages/intervo-backend/routes/authRouter.js - Workspace · Multi-tenant workspace state and user membership
packages/intervo-backend/lib/workspaceService.js - Agents · Agent classes and orchestration logic
packages/intervo-backend/services/OrchestrationManager.js - Tools · Tool selection, invocation, and MCP integration
packages/intervo-backend/services/ToolManager.js - Voice Runtime · Call lifecycle, websocket streaming, and telephony handling
packages/intervo-backend/routes/streamRouter.js - Twilio · Call control and media stream handling
packages/intervo-backend/handlers/twilioHandler.js - Billing · Credits, usage, and payment hooks
packages/intervo-backend/lib/stripeHandlers.js - Knowledge · Knowledge base routes and runtime retrieval helpers
packages/intervo-backend/routes/knowledgebaseRouter.js - Speech · Provider adapters for recognition and synthesis
packages/intervo-backend/services/openAI.js - Domain Models · Core multi-tenant data entities and call state
packages/intervo-backend/models/Workspace.js
RAG
Knowledge ingestion and retrieval services
- Node RAG · JavaScript wrapper around vector search and embeddings
packages/intervo-backend/rag/RagService.js - Python RAG · Python API for crawling, storage, and retrieval
packages/intervo-backend/rag_py/api.py
Infra
Persistence and external providers
- MongoDB · Primary persistence layer for app state
packages/intervo-backend/config/dbConfig.js - LLM APIs · External model providers used by orchestration and speech
packages/intervo-backend/services/geminiService.js - Twilio Cloud · External call and streaming infrastructure
- Stripe · External billing and subscription infrastructure
Connections 21
- Dashboard → API Server: REST · Admin UI drives workspace, agent, billing, and activity APIs
- Widget → API Server: chat API · Embedded client sends conversations and session events
- API Server → Auth: middleware · Protects routes and verifies identity/tenant access
- API Server → Workspace: tenant ops · Creates and manages workspaces and membership
- API Server → Agents: orchestrates · Runs agent behavior and conversation routing
- API Server → Tools: executes · Invokes tools and workflow actions
- API Server → Voice Runtime: streams · Handles websocket and call runtime
- Voice Runtime → Twilio: media/calls · Connects Twilio streams and call lifecycle handlers
- API Server → Billing: usage/payments · Tracks credits, plans, and payment events
- API Server → Knowledge: kb API · Exposes knowledge source and retrieval endpoints
- Agents → Speech: AI/media · Uses STT/TTS and model adapters during runtime
- Speech → LLM APIs: providers · Delegates to external AI model services
- API Server → Domain Models: domain data · Reads and writes core business entities
- Domain Models → MongoDB: persist · Stores multi-tenant state in MongoDB
- Knowledge → Node RAG: retrieval · Uses Node-side retrieval wrapper for runtime augmentation
- Knowledge → Python RAG: index/search · Delegates heavier ingestion and retrieval jobs to Python service
- Python RAG → MongoDB: storage · Persists knowledge data and vector-related state
- Voice Runtime → Twilio Cloud: external · Twilio provides streaming and call transport
- Billing → Stripe: external · Stripe processes subscriptions and payments
- API Server → Python RAG: kb sync · Backend calls the Python RAG service for ingestion and query support
- API Server → Twilio Cloud: webhooks · Receives and responds to third-party callbacks