# intervo/intervo architecture

> Architecture diagram of the GitHub repository intervo/intervo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/intervo/intervo
- Repository: https://github.com/intervo/intervo

## Overview

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: [`packages/intervo-backend/server.js`](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/server.js) (API Server), [`packages/intervo-backend/routes/streamRouter.js`](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/routes/streamRouter.js) (Voice Runtime), [`packages/intervo-backend/routes/knowledgebaseRouter.js`](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/routes/knowledgebaseRouter.js) (Knowledge), [`packages/intervo-backend/rag_py/api.py`](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/rag_py/api.py) (Python RAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_dashboard["Dashboard<br/>next.js admin app<br/>[page.js]"]
  node_widget["Widget<br/>vite chat client<br/>[App.jsx]"]
end

subgraph group_backend["Backend"]
  node_api["API Server<br/>node/express app<br/>[server.js]"]
  node_auth["Auth<br/>access control<br/>[authRouter.js]"]
  node_workspace["Workspace<br/>tenant mgmt"]
  node_agents["Agents<br/>agent runtime"]
  node_tools["Tools<br/>tooling layer<br/>[ToolManager.js]"]
  node_voice["Voice Runtime<br/>realtime media<br/>[streamRouter.js]"]
  node_twilio["Twilio<br/>telephony adapter<br/>[twilioHandler.js]"]
  node_billing["Billing<br/>usage/stripe<br/>[stripeHandlers.js]"]
  node_knowledge["Knowledge<br/>kb/rag api"]
  node_speech["Speech<br/>stt/tts adapters<br/>[openAI.js]"]
  node_models[("Domain Models<br/>mongoose models<br/>[Workspace.js]")]
end

subgraph group_rag["RAG"]
  node_rag_node["Node RAG<br/>retrieval wrapper<br/>[RagService.js]"]
  node_rag_py["Python RAG<br/>retrieval service<br/>[api.py]"]
end

subgraph group_infra["Infra"]
  node_db[("MongoDB<br/>document store<br/>[dbConfig.js]")]
  node_llm["LLM APIs<br/>ai providers<br/>[geminiService.js]"]
  node_twilio_ext["Twilio Cloud<br/>telephony service"]
  node_stripe_ext["Stripe<br/>payments service"]
end

node_dashboard -->|"REST"| node_api
node_widget -->|"chat API"| node_api
node_api -->|"middleware"| node_auth
node_api -->|"tenant ops"| node_workspace
node_api -->|"orchestrates"| node_agents
node_api -->|"executes"| node_tools
node_api -->|"streams"| node_voice
node_voice -->|"media/calls"| node_twilio
node_api -->|"usage/payments"| node_billing
node_api -->|"kb API"| node_knowledge
node_agents -->|"AI/media"| node_speech
node_speech -->|"providers"| node_llm
node_api -->|"domain data"| node_models
node_models -->|"persist"| node_db
node_knowledge -->|"retrieval"| node_rag_node
node_knowledge -.->|"index/search"| node_rag_py
node_rag_py -->|"storage"| node_db
node_voice -->|"external"| node_twilio_ext
node_billing -->|"external"| node_stripe_ext
node_api -.->|"kb sync"| node_rag_py
node_api -.->|"webhooks"| node_twilio_ext

click node_dashboard "https://github.com/intervo/intervo/blob/main/packages/intervo-frontend/src/app/(workspace)/[workspaceid]/studio/page.js"
click node_widget "https://github.com/intervo/intervo/blob/main/packages/intervo-widget/src/App.jsx"
click node_api "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/server.js"
click node_auth "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/routes/authRouter.js"
click node_workspace "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/lib/workspaceService.js"
click node_agents "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/services/OrchestrationManager.js"
click node_tools "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/services/ToolManager.js"
click node_voice "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/routes/streamRouter.js"
click node_twilio "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/handlers/twilioHandler.js"
click node_billing "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/lib/stripeHandlers.js"
click node_knowledge "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/routes/knowledgebaseRouter.js"
click node_speech "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/services/openAI.js"
click node_models "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/models/Workspace.js"
click node_db "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/config/dbConfig.js"
click node_llm "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/services/geminiService.js"
click node_rag_node "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/rag/RagService.js"
click node_rag_py "https://github.com/intervo/intervo/blob/main/packages/intervo-backend/rag_py/api.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_widget toneBlue
class node_api,node_auth,node_workspace,node_agents,node_tools,node_voice,node_twilio,node_billing,node_knowledge,node_speech,node_models toneAmber
class node_rag_node,node_rag_py toneMint
class node_db,node_llm,node_twilio_ext,node_stripe_ext toneRose
```

## Components

### Clients

User-facing dashboard and embedded widget

- [Dashboard](https://github.com/intervo/intervo/blob/main/packages/intervo-frontend/src/app/(workspace)/[workspaceid]/studio/page.js): next.js admin app · Operator UI for workspaces, agents, billing, and activity · `packages/intervo-frontend/src/app/(workspace)/[workspaceid]/studio/page.js`
- [Widget](https://github.com/intervo/intervo/blob/main/packages/intervo-widget/src/App.jsx): vite chat client · Embeddable customer-facing chat and call entry UI · `packages/intervo-widget/src/App.jsx`

### Backend

Node.js orchestration and API server

- [API Server](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/server.js): node/express app · Main backend entrypoint and request routing · `packages/intervo-backend/server.js`
- [Auth](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/routes/authRouter.js): access control · Login, verification, middleware, and ownership checks · `packages/intervo-backend/routes/authRouter.js`
- [Workspace](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/lib/workspaceService.js): tenant mgmt · Multi-tenant workspace state and user membership · `packages/intervo-backend/lib/workspaceService.js`
- [Agents](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/services/OrchestrationManager.js): agent runtime · Agent classes and orchestration logic · `packages/intervo-backend/services/OrchestrationManager.js`
- [Tools](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/services/ToolManager.js): tooling layer · Tool selection, invocation, and MCP integration · `packages/intervo-backend/services/ToolManager.js`
- [Voice Runtime](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/routes/streamRouter.js): realtime media · Call lifecycle, websocket streaming, and telephony handling · `packages/intervo-backend/routes/streamRouter.js`
- [Twilio](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/handlers/twilioHandler.js): telephony adapter · Call control and media stream handling · `packages/intervo-backend/handlers/twilioHandler.js`
- [Billing](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/lib/stripeHandlers.js): usage/stripe · Credits, usage, and payment hooks · `packages/intervo-backend/lib/stripeHandlers.js`
- [Knowledge](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/routes/knowledgebaseRouter.js): kb/rag api · Knowledge base routes and runtime retrieval helpers · `packages/intervo-backend/routes/knowledgebaseRouter.js`
- [Speech](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/services/openAI.js): stt/tts adapters · Provider adapters for recognition and synthesis · `packages/intervo-backend/services/openAI.js`
- [Domain Models](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/models/Workspace.js): mongoose models · Core multi-tenant data entities and call state · `packages/intervo-backend/models/Workspace.js`

### RAG

Knowledge ingestion and retrieval services

- [Node RAG](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/rag/RagService.js): retrieval wrapper · JavaScript wrapper around vector search and embeddings · `packages/intervo-backend/rag/RagService.js`
- [Python RAG](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/rag_py/api.py): retrieval service · Python API for crawling, storage, and retrieval · `packages/intervo-backend/rag_py/api.py`

### Infra

Persistence and external providers

- [MongoDB](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/config/dbConfig.js): document store · Primary persistence layer for app state · `packages/intervo-backend/config/dbConfig.js`
- [LLM APIs](https://github.com/intervo/intervo/blob/main/packages/intervo-backend/services/geminiService.js): ai providers · External model providers used by orchestration and speech · `packages/intervo-backend/services/geminiService.js`
- **Twilio Cloud**: telephony service · External call and streaming infrastructure
- **Stripe**: payments service · External billing and subscription infrastructure

## Connections

- 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
