Architecture Overview

SmarterAvatar is built on a modular architecture that separates concerns and enables flexible provider selection.

High-Level Architecture

┌────────────────────────────────────────────────────────────────┐
│                         Client Layer                            │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │   Avatar UI      │  │   Chat Interface │  │  Admin Panel │  │
│  │   (Video/Audio)  │  │   (Text/Voice)   │  │  (Config)    │  │
│  └──────────────────┘  └──────────────────┘  └──────────────┘  │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                       API Layer (Next.js)                       │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │   /api/chat      │  │   /api/admin     │  │  /api/token  │  │
│  │   Chat endpoint  │  │   Admin APIs     │  │  Session mgmt│  │
│  └──────────────────┘  └──────────────────┘  └──────────────┘  │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                     Provider Abstraction                        │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │   LLM Provider   │  │   STT Provider   │  │Avatar Provider│  │
│  │   Interface      │  │   Interface      │  │   Interface  │  │
│  └──────────────────┘  └──────────────────┘  └──────────────┘  │
└────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
        ┌──────────┐   ┌──────────┐   ┌──────────┐
        │  Gemini  │   │  Whisper │   │  HeyGen  │
        │  OpenAI  │   │ Deepgram │   │  (more)  │
        │ Anthropic│   └──────────┘   └──────────┘
        └──────────┘

Core Components

1. Client Layer

The frontend is built with Next.js 15 and React 19, providing:

• Interactive Avatar - Real-time video streaming with lip-sync
• Dual-mode Input - Text and voice interaction
• Responsive Design - Works on desktop and mobile
• Theme Support - Light and dark modes

2. API Layer

Server-side Next.js API routes handle:

• Chat Processing - Message handling, RAG retrieval, response generation
• Session Management - Avatar session tokens and lifecycle
• Admin Operations - Configuration, analytics, knowledge base management
• Health Checks - Deployment verification

3. Provider Layer

The provider abstraction enables swapping AI services:

• LLM Providers - Gemini, OpenAI, Anthropic
• STT Providers - Whisper, Deepgram
• Avatar Providers - HeyGen LiveAvatar

4. Data Layer

PostgreSQL stores:

• Conversation history and messages
• Session analytics and engagement metrics
• Admin configuration (prompts, overrides, phonetics)
• Knowledge base file references

Request Flow

A typical user interaction:

1. User speaks or types → Client captures input
2. Voice transcription (if voice) → STT provider converts to text
3. RAG retrieval → Knowledge base searched for relevant context
4. LLM inference → Provider generates response with context
5. Avatar synthesis → HeyGen renders video with response audio
6. Stream to client → Video/audio delivered in real-time

Technology Stack

Layer	Technology
Framework	Next.js 15
UI	React 19, Radix UI
Styling	Tailwind CSS
Database	PostgreSQL, Prisma ORM
Deployment	Vercel, Docker

Design Principles

Provider Agnostic

Switch between providers without code changes. Configure via environment variables.

White-Label First

All branding is configurable. No hardcoded company names, colors, or assets.

Cost Transparent

Clear per-request pricing. No hidden platform fees on API calls.

Enterprise Ready

Session analytics, admin controls, knowledge base management built-in.