Skip to main content

Architecture Overview

Verriflo has evolved from a live streaming platform into a comprehensive education infrastructure with multiple integrated services.

Service Architecture​

Verriflo consists of several microservices, all accessible through a unified Server API:

┌─────────────────────────────────────────────────────────────┐
│                    Your Application                          │
│  (Dashboard, Mobile App, Web App, etc.)                     │
└───────────────────────┬─────────────────────────────────────┘
                        │
                        │ HTTPS / REST API
                        │
┌───────────────────────▼─────────────────────────────────────┐
│              Server API (api.verriflo.com)                   │
│  • Authentication & Authorization                            │
│  • Request Routing & Proxying                                │
│  • Rate Limiting & Security                                 │
│  • Usage Tracking & Billing                                  │
└───────┬───────────┬──────────────┬──────────────┬────────────┘
        │           │              │              │
        │           │              │              │
    ┌───▼───┐  ┌───▼───┐    ┌─────▼─────┐  ┌────▼────┐
    │ Live  │  │ AI    │    │ AI API    │  │  CDN    │
    │Stream │  │ Tutor │    │(voice-    │  │ & Media │
    │       │  │       │    │ agent)    │  │         │
    └───────┘  └───────┘    └───────────┘  └─────────┘

Core Services​

1. Server API (server/)​

Purpose: Central API gateway and orchestration layer

Responsibilities:

  • Single entry point for all external requests
  • Authentication and authorization (VF-ORG-ID header)
  • Request routing and proxying to internal services
  • Rate limiting and security
  • Usage tracking and billing aggregation
  • Database operations (MongoDB)
  • Webhook management

Key Endpoints:

  • /v1/room/* - Room management
  • /v1/ai-agent/* - AI API (proxies to voice-agent)
  • /v1/ai-tutor/* - AI Tutor (proxies to teacher-agent)
  • /v1/cdn/* - CDN operations
  • /v1/billing/* - Billing and credits
  • /v1/health/* - Health checks

Technology: Express.js, TypeScript, MongoDB

2. Live Streaming (live/)​

Purpose: Web-based classroom interface and iframe embedding

Responsibilities:

  • Live classroom UI (iframe embeddable)
  • LiveKit client integration
  • Participant management UI
  • Recording controls
  • AI Tutor UI integration

Technology: Next.js, React, LiveKit Client SDK

3. AI Tutor (teacher-agent/)​

Purpose: Real-time AI assistant for students during live classes

Responsibilities:

  • Student Q&A during live classes
  • Context-aware responses (aware of current class topic)
  • Multi-modal support (text, voice)
  • Class summary generation
  • Usage tracking per room

Key Endpoints:

  • POST /api/ai-tutor/chat - Send message
  • POST /api/ai-tutor/chat/stream - Stream responses (SSE)
  • GET /api/ai-tutor/summary/:roomId - Get class summary
  • GET /api/ai-tutor/usage/:roomId - Get usage stats

Technology: Express.js, LiveKit Agents

Access: Via Server API at /v1/ai-tutor/*

4. AI API (voice-agent/)​

Purpose: Conversational AI service (branded as "AI API")

Responsibilities:

  • General-purpose conversational AI
  • Text, voice, and image input/output
  • Knowledge base management
  • Chat history management
  • Streaming responses (NDJSON)

Key Endpoints:

  • POST /api/v1/generate - Send message
  • POST /api/v1/generate/stream - Stream responses (NDJSON)
  • Knowledge CRUD operations

Technology: Express.js, Redis

Access: Via Server API at /v1/ai-agent/*

5. CDN & Media (Verriflo-CDN/)​

Purpose: Video transcoding, storage, and delivery

Responsibilities:

  • Video transcoding and optimization
  • Cloud storage management
  • Recording file management
  • Stream proxy and delivery

Technology: Python, FFmpeg, Cloud Storage

Access: Via Server API at /v1/cdn/*

Request Flow Examples​

Example 1: AI Chat from Dashboard​

Dashboard → Next.js API Route → Server API → voice-agent
   ↓              ↓                  ↓            ↓
User sends    /api/v1/ai-    /v1/ai-agent/   /api/v1/
message       agent/chat/    chat/stream     generate/stream
              stream
  1. User sends message in dashboard
  2. Dashboard calls Next.js API route (/api/v1/ai-agent/chat/stream)
  3. Next.js route adds VF-ORG-ID header and proxies to Server API
  4. Server API validates and proxies to voice-agent with dispatch secret
  5. voice-agent processes the request and streams response back
  6. Response flows back through the chain to the user

Example 2: Student Asks AI Tutor​

Live UI → Next.js API Route → Server API → teacher-agent
   ↓              ↓                  ↓            ↓
Student      /api/v1/ai-    /v1/ai-tutor/   /api/ai-tutor/
asks         tutor/chat/   chat/stream     chat/stream
question     stream
  1. Student asks question in live classroom
  2. Live UI calls Next.js API route
  3. Next.js route proxies to Server API
  4. Server API proxies to teacher-agent
  5. teacher-agent processes with class context
  6. Response streams back to student

Example 3: Create Classroom​

Your Backend → Server API → LiveKit → Live UI
     ↓              ↓           ↓         ↓
POST /v1/    Create room   Generate   Return
room/create  in MongoDB    token     iframe URL

Authentication Flow​

All services use a unified authentication model:

  1. External Requests: Require VF-ORG-ID header
  2. Internal Service Communication: Uses X-Dispatch-Secret header
  3. Token-Based Auth: JWT tokens for user sessions (dashboard)

Data Flow​

Live Streaming​

  • Media: WebRTC → LiveKit SFU → Students
  • Signaling: WebSocket → LiveKit Server
  • Metadata: REST API → Server → MongoDB

AI Services​

  • Requests: REST/SSE → Server → AI Service
  • Responses: Stream back through same path
  • Storage: Chat history in Redis, usage in MongoDB

CDN​

  • Upload: Client → Server → CDN Service → Cloud Storage
  • Download: Cloud Storage → CDN Service → Client

Deployment Architecture​

All services are containerized and can be deployed:

  • Kubernetes: Recommended for production
  • Docker Compose: For local development
  • Individual Services: Can run independently

Service Communication​

Internal Services​

  • Use X-Dispatch-Secret for authentication
  • Communicate via HTTP/REST
  • Service URLs configured via environment variables

External Access​

  • All external access goes through Server API
  • Server API handles authentication, routing, and proxying
  • Users never directly access internal services

Benefits of This Architecture​

  1. Single API: Users only integrate with one API (Server API)
  2. Scalability: Each service can scale independently
  3. Security: Internal services not exposed to internet
  4. Maintainability: Clear separation of concerns
  5. Flexibility: Services can be updated independently

Next Steps​