# rsvedant/dial0 architecture

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

- Interactive diagram: https://gitdiagram.com/rsvedant/dial0
- Repository: https://github.com/rsvedant/dial0

## Overview

##### Project Type and Purpose
- DialZero is a full-stack, real-time customer service automation platform.
- The frontend is built with Next.js (App Router), React, TypeScript and Tailwind CSS.
- The backend is powered by Convex (serverless DB + functions), supplemented by Next.js API routes.
- It integrates multiple external AI and voice services: Vapi AI (voice orchestration & cloning), ElevenLabs (voice synthesis), Inkeep (knowledge base), OpenAI/Google/Anthropic (NLP models).
- Real-time features use Convex subscriptions, WebRTC and the MediaRecorder API.

##### File-Tree Analysis and Architectural Patterns
- app/ (Next.js “App Router”): pages + layout + global providers + API routes under app/api/…
- components/ & hooks/: reusable UI components & custom hooks for chat, calls, toasts, mobile detection
- convex/: Convex schema, serverless functions (actions), authentication config, orchestration logic
- lib/: client- and server-side helper modules for auth, Inkeep, geo, search, utilities
- public/: static assets & manifest
- scripts/: tooling (e.g., fetch voice library)
- next.config.mjs, package.json, tsconfig.json, tailwind/postcss configs

Patterns:
- BFF (Next.js API routes) for authentication, chat, call start/events, Inkeep integration
- Serverless functions (Convex actions) for database operations, orchestration and external API calls
- Pub/Sub style real-time updates via Convex live queries
- Component-driven UI with Radix and Tailwind

##### Key Components
a. Frontend (Next.js App)
- React UI Components (components/)
- App Router pages (app/)
- ConvexClientProvider & AutumnClientProvider (GraphQL/WebSocket clients)
- WebRTC + MediaRecorder (browser audio capture)

b. Backend Services
- Next.js API Routes (app/api/…) acting as a BFF layer
- Convex Backend
- Real-time DB (collections: Issues, Settings, ChatMessages, CallEvents, OrchestrationContexts)
- Serverless Functions (“actions” in convex/actions/)
- Auth (convex/auth.ts + auth.config.ts)
- Orchestration Engine (convex/orchestration.ts)

c. External Services
- Vapi AI: call lifecycle & webhooks (app/api/vapi)
- ElevenLabs: advanced voice synthesis via Vapi
- Inkeep: context-aware KB queries
- OpenAI / Google Generative AI / Anthropic Claude: chat completions & NLP
- Convex Webhooks: to receive real-time events from Vapi

d. Data Flow & Interactions
1. User interacts with Next.js UI → triggers BFF endpoints or Convex live mutation
2. BFF (API Route) or Convex action calls External AI/Voice services → receives response
3. Convex action writes/transforms data in real-time DB → subscriptions push updates to UI
4. Webhooks from Vapi hit API routes → Convex actions update call state and transcription
5. React UI subscribes to Convex live queries → renders new chat messages, call transcription, analytics

##### Architectural Patterns & Principles
- Separation of Concerns: UI vs. BFF vs. Data Layer vs. External Integrations
- Event-driven & Real-time: DB subscriptions, webhooks, WebRTC streams
- Serverless Functions: stateless, ephemeral, on-demand
- Modular Components: hooks, lib helpers, convex actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        NextApp["Next.js App"]:::frontend
        ReactUI["React UI Components"]:::frontend
        ConvexProvider["ConvexClientProvider"]:::frontend
        AutumnProvider["AutumnClientProvider"]:::frontend
        MediaRecorder["WebRTC + MediaRecorder"]:::frontend
    end

    %% Server Layer
    subgraph "Server"
        direction TB
        subgraph "API Routes (BFF)" 
            direction TB
            AuthAPI["/api/auth/..."]:::backend
            ChatAPI["/api/chat"]:::backend
            InkeepAPI["/api/inkeep"]:::backend
            VapiStartAPI["/api/vapi/start-call"]:::backend
            VapiWebhookAPI["/api/vapi/webhook"]:::backend
        end
        subgraph "Convex Backend"
            direction TB
            DB["Real-time DB (collections)"]:::datastore
            AuthConfig["Convex Auth Config"]:::backend
            subgraph "Actions (Serverless)"
                direction TB
                AutumnAction["Orchestration Helper (Autumn)"]:::backend
                VoiceCloningAction["Voice Cloning (ElevenLabs)"]:::backend
                OrchestrationEngine["Orchestration Engine"]:::backend
            end
        end
    end

    %% External Layer
    subgraph "External Services"
        direction TB
        VapiAI["Vapi AI"]:::external
        ElevenLabs["ElevenLabs"]:::external
        InkeepService["Inkeep KB"]:::external
        OpenAI["OpenAI/Google/Anthropic"]:::external
    end

    %% Connections
    NextApp -->|"HTTP/REST"| AuthAPI
    NextApp -->|"HTTP/REST"| ChatAPI
    NextApp -->|"HTTP/REST"| InkeepAPI
    NextApp -->|"HTTP/REST"| VapiStartAPI

    AuthAPI -->|"invoke"| AutumnAction
    ChatAPI -->|"invoke"| OrchestrationEngine
    InkeepAPI -->|"invoke"| OrchestrationEngine
    VapiStartAPI -->|"invoke"| OrchestrationEngine
    VapiWebhookAPI -->|"webhook"| OrchestrationEngine

    OrchestrationEngine -->|"read/write"| DB
    AutumnAction -->|"read/write"| DB
    VoiceCloningAction -->|"read/write"| DB

    NextApp <-->|"WebSocket (live query)"| DB

    AutumnAction -->|"HTTP API"| VapiAI
    OrchestrationEngine -->|"HTTP API"| ElevenLabs
    OrchestrationEngine -->|"HTTP API"| InkeepService
    OrchestrationEngine -->|"HTTP API"| OpenAI

    VapiAI -->|"webhook"| VapiWebhookAPI

    %% Click Events
    click NextApp "https://github.com/rsvedant/dial0/tree/master/app/"
    click ReactUI "https://github.com/rsvedant/dial0/tree/master/components/"
    click ConvexProvider "https://github.com/rsvedant/dial0/blob/master/app/ConvexClientProvider.tsx"
    click AutumnProvider "https://github.com/rsvedant/dial0/blob/master/app/AutumnClientProvider.tsx"
    click MediaRecorder "https://github.com/rsvedant/dial0/blob/master/hooks/use-call-audio.ts"
    click AuthAPI "https://github.com/rsvedant/dial0/blob/master/app/api/auth/[...all]/route.ts"
    click ChatAPI "https://github.com/rsvedant/dial0/blob/master/app/api/chat/route.ts"
    click InkeepAPI "https://github.com/rsvedant/dial0/blob/master/app/api/inkeep/route.ts"
    click VapiStartAPI "https://github.com/rsvedant/dial0/blob/master/app/api/vapi/start-call/route.ts"
    click VapiWebhookAPI "https://github.com/rsvedant/dial0/blob/master/app/api/vapi/webhook/route.ts"
    click DB "https://github.com/rsvedant/dial0/blob/master/convex/schema.ts"
    click AutumnAction "https://github.com/rsvedant/dial0/blob/master/convex/actions/autumn.ts"
    click VoiceCloningAction "https://github.com/rsvedant/dial0/blob/master/convex/actions/voiceCloning.ts"
    click OrchestrationEngine "https://github.com/rsvedant/dial0/blob/master/convex/orchestration.ts"
    click AuthConfig "https://github.com/rsvedant/dial0/blob/master/convex/auth.ts"
    click InkeepService "https://github.com/rsvedant/dial0/blob/master/lib/inkeep-service.ts"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085;
    classDef backend fill:#d4edda,stroke:#155724;
    classDef external fill:#ffe5b4,stroke:#c66900;
    classDef datastore fill:#e2e3e5,stroke:#6c757d;
```
