Skip to main content

​
Overview

Voxora is built as a modern, scalable monorepo application with separate frontend and backend services that communicate via REST APIs and WebSocket connections.

​
System Architecture

​
Core Components

​
1. Web Application (apps/web)

Technology Stack

  • Framework: Next.js 15 (App Router)
  • UI Library: React 19
  • Styling: Tailwind CSS
  • State Management: React Hooks + Context
  • Build Tool: Turbopack
Responsibilities:
  • Agent dashboard and admin interface
  • Real-time conversation management
  • Team and department management
  • Analytics and reporting
  • User authentication
Key Features:
  • Server-side rendering (SSR)
  • Static site generation (SSG) where applicable
  • Real-time updates via Socket.IO
  • Responsive design with Tailwind CSS

​
2. API Server (apps/api)

Technology Stack

  • Framework: Express 5
  • Real-time: Socket.IO
  • Database ORM: Mongoose
  • Caching: Redis
  • Authentication: JWT
Responsibilities:
  • RESTful API endpoints
  • WebSocket connections for real-time chat
  • User authentication and authorization
  • Business logic and data validation
  • Database operations
  • Email notifications
API Structure: 
/api/v1
├── /auth          # Authentication endpoints
├── /users         # User management
├── /conversations # Chat conversations
├── /messages      # Message handling
├── /agents        # Agent management
├── /departments   # Department organization
└── /analytics     # Usage statistics

​
3. Chat Widget

Technology Stack

  • Format: Vanilla JavaScript
  • Styling: Inline CSS + customizable themes
  • Size: Lightweight (~50KB minified)
  • Integration: Single script tag
Features:
  • Embeddable in any website
  • Customizable appearance
  • Real-time messaging
  • Typing indicators
  • File uploads
  • Notification sounds

​
Data Layer

​
MongoDB

Primary database for persistent data storage. Collections:
  • users - User accounts (agents, admins)
  • customers - Customer information
  • conversations - Chat sessions
  • messages - Individual messages
  • departments - Team organization
  • settings - Application configuration
Indexes:
  • User email (unique)
  • Conversation timestamps
  • Message conversation ID
  • Full-text search on messages

​
Redis

In-memory data store for caching and session management. Use Cases:
  • Session storage
  • Real-time user presence
  • Rate limiting
  • Caching frequently accessed data
  • Pub/Sub for distributed events

​
Communication Patterns

​
REST API

Used for:
  • CRUD operations
  • Authentication
  • File uploads
  • Configuration management
Request Flow: 
Client → API Gateway → Middleware → Controller → Service → Database

​
WebSocket (Socket.IO)

Used for:
  • Real-time messaging
  • Typing indicators
  • User presence
  • Live notifications
  • Connection status
Event Flow: 
Client → Socket.IO → Event Handler → Business Logic → Broadcast → Clients

​
Authentication & Authorization

​
JWT-based Authentication

1

User Login

User submits credentials to /api/v1/auth/login
2

Token Generation

Server validates credentials and generates JWT
3

Token Storage

Client stores JWT in localStorage or httpOnly cookie
4

Authenticated Requests

Client includes JWT in Authorization header
5

Token Validation

Server validates JWT on each protected request

​
Role-Based Access Control (RBAC)

Roles:
  • Admin: Full system access
  • Agent: Access to assigned conversations
  • Customer: Access to own conversations

​
Scalability Considerations

​
Horizontal Scaling

  • API Servers: Stateless design allows multiple instances
  • Socket.IO: Redis adapter for multi-server support
  • Database: MongoDB replica sets for read scaling

​
Caching Strategy

// Check Redis first
const cached = await redis.get(key);
if (cached) return JSON.parse(cached);

// Fetch from database
const data = await db.find(query);

// Store in cache
await redis.setex(key, 3600, JSON.stringify(data));
return data;

​
Load Balancing

Recommended setup for production: 
Internet → Load Balancer → [API Server 1, API Server 2, API Server 3]
                          ↓
                    [MongoDB Cluster]
                          ↓
                    [Redis Cluster]

​
Security Architecture

Authentication

JWT tokens with short expiry times

Authorization

Role-based access control (RBAC)

Data Encryption

HTTPS/TLS for data in transit

Input Validation

Request validation and sanitization

​
Monitoring & Logging

​
Application Logging

  • Request/response logging
  • Error tracking
  • Performance metrics
  • Audit trails

​
Health Checks

GET /health
{
  "status": "healthy",
  "services": {
    "mongodb": "connected",
    "redis": "connected"
  },
  "uptime": 12345
}

​
Next Steps

Monorepo Structure

Explore the codebase organization

Real-time Chat

Learn about the chat system

Development Setup

Set up your development environment

API Reference

Browse API endpoints