How datarohit/agentsphere works
Project Type and Purpose
• Type: Full-stack web application
• Purpose: A dynamic AI platform where users manage AI agents (single & group), run conversations in real time via WebSockets, integrate external tools (MCP servers), and collaborate in organizations.
• Tech Highlights:
– Frontend: Next.js + React + Tailwind + Redux Toolkit
– Backend: Django 5 + Django REST Framework + Channels (WebSockets)
– Infrastructure: Docker Compose, Nginx, PostgreSQL, Redis, Celery, Vault, MinIO
File Structure
• Top-level dirs:
– backend/: Django “monolithic” code broken into Django apps (agents, chats, conversation, llms, organization, tools, users, common, contrib)
– frontend/: Next.js App Router pages under /app plus reusable UI components; Redux slices in store/
– compose/: Docker-compose fragments for each service (django, nextjs, nginx, postgres)
– docker-compose.yml: Orchestrates all containers
– makefile: Dev commands
• Patterns & config:
– backend/config/: Django settings, ASGI (for WebSockets), Celery, routing, OpenAPI
– Celery tasks (in apps/chats/tasks, conversation/tasks, organization/tasks)
– WebSockets via Django Channels (apps/conversation/consumers + routing)
– Vault and MinIO clients under apps/common/utils
– Frontend state management via Redux Toolkit (store), fetch calls to REST API, WebSocket clients for live chat
README Insights
• Architecture hints:
– Docker Compose services: Django app, Next.js app, Nginx reverse proxy, PostgreSQL, Redis, Vault, MinIO, Celery worker & beat & flower, Mailpit, PgAdmin
– Security: JWT auth, Vault for API keys, CSRF protection
– Real-time: WebSocket via Django Channels
• External dependencies: LLM providers (Gemini), Email (Mailpit), Monitoring (Sentry, Silk)
Main Components & Interactions
a. Components
1. Client / Browser
– Next.js frontend (React pages, UI components, Redux store, WebSocket client)
2. Reverse Proxy
– Nginx (routes HTTP to Next.js or Django, handles SSL if any)
3. Frontend Service
– Next.js server (Docker container)
4. Backend Service
– Django ASGI app (Docker container) exposing:
• REST API (Django REST Framework) on /api/v1/
• WebSocket endpoint (/ws/conversation/)
5. Task Queue
– Celery worker + Celery beat + Flower monitor
6. Datastore
– PostgreSQL (persistent data: users, agents, chats, orgs, tools)
7. Cache / Broker
– Redis (cache, Celery broker, Channels layer)
8. Secret Manager
– Vault (stores LLM API keys, other secrets)
9. Object Storage
– MinIO (S3-compatible for file uploads, avatars)
10. Auxiliary Services
– Mailpit (email dev server)
– PgAdmin (DB admin)
11. External Services
– LLM Provider (Gemini, others)
– MCP Tool Endpoints
b. Relationships & Data Flows
– Browser ↔ Nginx ↔ Next.js (HTTP)
– Browser WebSocket ↔ Nginx ↔ Django Channels
– Next.js ↔ Django REST (HTTP) for API calls
– Django ↔ PostgreSQL (ORM read/write)
– Django ↔ Redis (cache, Channels Pub/Sub, Celery broker)
– Django/Celery ↔ Vault (secrets lookup)
– Django ↔ MinIO (object storage)
– Celery workers consume tasks enqueued by Django for background processing (message deletion, chat summary generation, org cleanup)
– Django ↔ LLM Provider (external HTTP) to generate AI responses
– Mailpit captures outbound emails for activation, password reset
– PgAdmin connects to PostgreSQL for DB maintenance
c. Architectural Patterns & Principles
– Modular Monolith: Django apps isolate domain logic
– REST + WebSockets: Separate synchronous and asynchronous communication
– Event-driven: Celery tasks for offloaded workloads
– 12-factor: Configuration via env files, Dockerized services
– Secure by design: Vault-backed secrets, JWT, CSRF
– Component reuse: shadcn/ui + Radix UI for consistent frontend
d. Key Technologies & Frameworks
– Django, DRF, Channels, Celery, PostgreSQL, Redis, Vault, MinIO, Nginx, Next.js, React, Redux Toolkit, Tailwind CSS
Detailed Notes for the Engineer
– Show inter-service ports (e.g., Redis:6379, PostgreSQL:5432, API:8080, Next.js:3000)
– Illustrate Celery beat → task schedule → queue → worker
– Highlight that Channels uses Redis as channel layer for WebSocket group messaging
– Capture that Vault is read at app start or on demand for LLM API keys
– Indicate where static assets (CSS, JS) and media files are served (Next.js public folder, MinIO)
– Label environment config mounts (e.g., .env files injected into containers)