Skip to main content

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​

LayerTechnology
FrameworkNext.js 15
UIReact 19, Radix UI
StylingTailwind CSS
DatabasePostgreSQL, Prisma ORM
DeploymentVercel, 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.