Architecture overview for the Weam AI platform across Python backend, Node.js API, and Next.js frontend.
Python Backend Architecture
Core Application Stack
| Component | Technology |
|---|
| Backend Framework | FastAPI |
| Task Queue | Celery |
| Broker | Redis |
| Database | MongoDB |
| Authentication | JWT + Middleware |
| Task Monitor | Flower |
| Streaming | FastAPI StreamingResponse |
AI & Vector Layer
| Component | Technology |
|---|
| LLMs | OpenAI, Gemini, Anthropic, HuggingFace |
| Embeddings | LangChain, Gemini, OpenAI |
| Vector Database | Qdrant (Primary), Pinecone (Optional) |
| Web Scraping | Playwright, BeautifulSoup, Crawler4AI |
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
Testing & Debugging
| Tool | Purpose |
|---|
| Pytest | Unit testing |
| Locust | Load testing |
| WDB | Web-based visual debugger |
| Docker Override | Test environment setup |
Infrastructure
| Component | Description |
|---|
| Docker | Service containerization |
| Docker Compose | Multi-environment orchestration |
| GitHub Actions | CI/CD pipeline |
| Prometheus | Metrics and monitoring |
| Async Logger | Custom logging implementation |
Node.js API Architecture
Core Backend
| Component | Technology |
|---|
| Web Server | Express.js |
| Task Queue | Bull (Redis-based) |
| Job Scheduler | Agenda |
| Authentication | JWT Middleware |
| Database ORM | Mongoose (MongoDB) |
| Real-time | Socket.IO |
Security & Middleware
- Role-based access control via JWT
- Rate limiting with
express-rate-limit
- Encrypted API keys with custom middleware
- Environment configuration via
dotenv
- Winston + Morgan for logging
- Chrome DevTools / VSCode debugging
- Live reload with
nodemon
Real-time & Storage
- Socket.IO for live updates
- Redis Pub/Sub for socket scaling
- SMTP email integration
- MinIO / AWS S3 file storage
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
- Modular API clients in
/src/actions/
- LLM provider integration (OpenAI, Gemini, Anthropic)
- Vector search via Qdrant/Pinecone
- Asset serving through S3/MinIO
Python API Request Lifecycle
Client Request
↓
[gateway/] → FastAPI/Nginx entrypoint
↓
[middleware/] → Auth, logging, rate limits
↓
[schema/] → Pydantic validation
↓
[router/] → Endpoint routing
↓
[controller/] → Request logic
↓
[service/] → Business logic
↓
[models/] → MongoDB interaction
↓
[exceptions/] → Error handling
↓
[utils/] → Helper methods
↓
Response → JSON/Streaming to client
Service Communication
- Frontend ↔ Node.js: REST API + Socket.IO
- Node.js ↔ Python: HTTP API calls
- Backend ↔ Database: MongoDB connections
- Task Processing: Celery + Redis queues
- Real-time Updates: Socket.IO + Redis Pub/Sub
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: Prometheus metrics collection
