System Design

Architecture overview for the Weam AI platform across Node.js backend and Next.js frontend.

Architecture Evolution

Weam AI uses a streamlined architecture with Node.js handling all backend operations through LangGraph for intelligent AI orchestration.

Node.js Backend Architecture

Core Application Stack

Component	Technology
Backend Framework	Express.js
AI Orchestration	LangGraph
Task Queue	Bull (Redis-based)
Job Scheduler	Agenda
Database	MongoDB
Authentication	JWT + Middleware
Streaming	Socket.IO

AI & Vector Layer

Component	Technology
LLMs	OpenAI, Gemini, Anthropic, HuggingFace
AI Orchestration	LangGraph (intelligent routing)
Embeddings	Gemini, OpenAI
Vector Database	Pinecone (Primary), Qdrant (Optional)
Web Search	SearxNG (self-hosted metasearch)
Image Generation	OpenAI DALL·E

Direct API integration for OpenAI, Anthropic, Gemini, and HuggingFace. OpenRouter used for LLaMA, DeepSeek, Grok, and Qwen models.

Security & Configuration

• API key encryption with internal crypto module
• JWT tokens for access and refresh authentication
• Environment-based configuration (.env files)
• Role-based access control

Real-time & Storage

• Socket.IO for live updates and streaming responses
• Redis Pub/Sub for socket scaling
• SMTP email integration
• MinIO / AWS S3 file storage with parallel processing
• Event streaming for optimized file uploads

Socket scaling across multiple servers uses Redis Pub/Sub. See socket scaling guide for implementation details.

Next.js Frontend Architecture

Framework & UI

Component	Technology
Frontend Framework	Next.js (App Router)
Type System	TypeScript
Styling	Tailwind CSS
State Management	Redux Toolkit
Forms	Formik + Custom Inputs
Routing	Next.js File System
Authentication	Firebase + IronSession

Module Structure

Module	Path
Authentication	src/app/(auth) + src/actions/auth.ts
Chat & Threads	src/components/Chat + src/hooks/chat
Custom GPT	src/components/CustomGpt
Workspace	src/components/Workspace + src/hooks/workspace
File Uploads	src/components/FileUpload* + src/hooks/storage
Reports	src/app/(page)/settings/reports

AI Integration

• Socket.IO client for real-time AI responses
• Single event emission for all AI operations
• Backend-driven operation routing
• Asset serving through S3/MinIO

Request Processing Architecture

Client Request (Socket Event)
    ↓
[Node.js Backend] → Single entry point
    ↓
[LangGraph Router] → Intelligent operation detection
    ↓
[Operation Handler] → Execute appropriate flow:
    • Normal Chat → LLM call
    • Web Search → SearxNG + LLM
    • Image Generation → DALL·E
    • Document Chat → Pinecone + LLM
    • Agent Chat → Agent prompt + LLM
    • Agent + Document → Combined context + LLM
    ↓
[Response Stream] → Socket.IO streaming to frontend
    ↓
Response → Real-time display in UI

LangGraph Flow Management

Intelligent Backend Routing

LangGraph handles all decision-making for operation types:

Single Call Operations:

• Normal chat queries
• Document-based questions
• Agent conversations
• Combined agent + document queries

Two-Call Operations (when tools required):

• Web search integration
• Image generation requests
• Vision model processing

Operation Detection

Backend automatically identifies:

• Tool requirements (web search, image generation)
• Document context needs
• Agent selection
• Model capabilities and limitations

Service Communication

• Frontend ↔ Node.js: Single Socket.IO event for all operations
• Node.js ↔ LLMs: Direct API calls through LangGraph
• Backend ↔ Database: MongoDB connections
• Task Processing: Bull + Redis queues
• Real-time Updates: Socket.IO + Redis Pub/Sub
• File Processing: Parallel S3 upload and vector embedding

File Upload Optimization

Parallel Processing Architecture

User Upload
    ↓
Event Streaming to Backend
    ↓
Parallel Processing (2 chunks at a time):
    ├─ Chunk 1 → S3 Upload
    └─ Chunk 2 → Vector Embedding (Pinecone)
    ↓
Optimized Speed & Performance

Web Search Architecture

SearxNG Integration

• Independence: No dependency on OpenAI’s search features
• Self-hosted: Complete control over search infrastructure
• Universal: Works with all models except GPT-4o latest, DeepSeek, and Qwen
• Privacy: No external search API dependencies

Deployment Architecture

All services are containerized using Docker and orchestrated with Docker Compose:

• Development: Local Docker containers
• Production: Multi-container deployment
• Secrets: Environment variables and secret managers
• Monitoring: Socket.IO event tracking and logging