> ## Documentation Index
> Fetch the complete documentation index at: https://opensource.weam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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                          |

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

### 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

<Note>
  Socket scaling across multiple servers uses Redis Pub/Sub. See [socket scaling guide](/knowledgebase/socket-scale) for implementation details.
</Note>

## 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