System Architecture Overview

MetaPilot is designed as a Modular Monolith Monorepo providing unified codebase management, high developer velocity, and clear subsystem isolation.

High-Level Architecture Diagram

Rendering diagram...

Monorepo Structure Layout

text

metapilot/
├── apps/                         # Frontend Application (Next.js 16)
│   ├── src/
│   │   ├── app/                  # Next.js App Router pages (/dashboard, /auth, etc.)
│   │   ├── components/           # UI Components (landing, dashboard, modals)
│   │   ├── services/             # Frontend API integration services
│   │   ├── hooks/                # Custom React hooks (useAuth, useInbox, useWebSocket)
│   │   └── lib/                  # Utilities & API client
├── services/
│   └── api/                      # Backend Service (Django 5.0 Modular Monolith)
│       ├── core/                 # Settings, ASGI, WSGI, URLs configuration
│       ├── users/                # Custom User model & authentication
│       ├── tenants/              # Multi-tenancy, Agencies, Encryption, Audit Logs
│       ├── api/                  # Unified ViewSets & REST endpoints
│       ├── messaging/            # Conversations & WhatsApp message models
│       ├── campaigns/            # Broadcast campaigns & recipient targeting
│       ├── templates/            # WhatsApp HSM message templates
│       ├── inbox/                # Realtime chat inbox & WebSockets
│       ├── scheduler/            # Celery broadcast scheduler & token bucket
│       ├── chatbot/              # Platform AI assistant & RAG context
│       ├── wa_chatbot/           # WhatsApp AI auto-responder & vision handler
│       ├── notifications/        # System alerts & unread counters
│       └── webhooks/             # Meta Graph API webhook ingestion
├── scripts/                      # Developer automation & operational CLI scripts
├── infrastructure/               # Docker & Compose deployment configurations
└── docs/                         # Documentation suite

Subsystem Component Breakdown

Next.js 16 Web Application: Rendered with Turbopack, providing dashboard pages for Client management, User management, Broadcast creation, Template builder, Realtime Chat Inbox, and Audit logs.
Daphne ASGI Server: High-throughput async server handling both HTTP REST requests and long-lived WebSocket connections on port 8000.
Django 5 REST API: Modular Django applications providing RESTful endpoints, JWT validation, and RBAC permissions.
Django Channels & Redis: Handles live WebSocket connections under
```
/ws/inbox/<tenant_id>/
```
, broadcasting messages across agents instantly.
Celery Worker & Beat Engine: Asynchronous job runner executing scheduled broadcasts, webhook retries, and AI context processing.