Architecture Overview

High-Level Architecture

┌──────────────────────────────────────────────────────────┐
│                     Clients                               │
│  Mobile App  │  Web Dashboard  │  AI Agents (MCP)        │
└──────┬───────┴────────┬────────┴────────┬────────────────┘
       │                │                 │
       ▼                ▼                 ▼
┌──────────────────────────────────────────────────────────┐
│                   Nginx (Reverse Proxy)                   │
│            HTTP → Gunicorn   WS → Daphne                 │
└──────┬───────────────────────────────┬───────────────────┘
       │                               │
       ▼                               ▼
┌─────────────────┐          ┌──────────────────┐
│  Django REST    │          │  Django Channels  │
│  Framework      │          │  (WebSocket)      │
│                 │          │                   │
│  JWT Auth       │          │  TeamInboxConsumer │
│  ViewSets       │          │  Real-time msgs   │
│  Serializers    │          │                   │
└──────┬──────────┘          └────────┬──────────┘
       │                              │
       ▼                              ▼
┌──────────────────────────────────────────────────────────┐
│                   Channel Registry                        │
│  ┌──────────┐ ┌──────────┐ ┌──────┐ ┌──────┐           │
│  │ WhatsApp │ │ Telegram │ │ SMS  │ │ RCS  │           │
│  │ (Meta,   │ │          │ │(Twil,│ │(GRBM,│           │
│  │ Gupshup) │ │          │ │MSG91,│ │MetaR)│           │
│  │          │ │          │ │F2SMS)│ │      │           │
│  └──────────┘ └──────────┘ └──────┘ └──────┘           │
└──────────────────────────────────────────────────────────┘
       │              │            │          │
       ▼              ▼            ▼          ▼
┌──────────────────────────────────────────────────────────┐
│                   External APIs                           │
│  Meta Graph API │ Telegram Bot │ Twilio │ Google RBM     │
└──────────────────────────────────────────────────────────┘
       │
       ▼
┌──────────────────────────────────────────────────────────┐
│          PostgreSQL  │  Redis  │  Celery Workers         │
└──────────────────────────────────────────────────────────┘

Application Map

Jina Connect is organized into Django apps, each owning a bounded context:

App	Responsibility	Key Models
`users`	User accounts, auth, password reset	`User`
`tenants`	Multi-tenancy, RBAC, API keys, media	`Tenant`, `TenantUser`, `TenantRole`, `TenantAccessKey`
`wa`	WhatsApp messaging, BSP adapters, templates	`WATemplate`, `WAMessage`, `TenantWAApp`
`telegram`	Telegram bot management, messaging	`TelegramBotApp`, `TelegramOutboundMessage`
`sms`	SMS multi-provider messaging	`SMSApp`, `SMSOutboundMessage`
`rcs`	RCS messaging with SMS fallback	`RCSApp`, `RCSOutboundMessage`
`broadcast`	Campaign management, URL tracking	`Broadcast`, `BroadcastMessage`
`contacts`	Unified contact management	`TenantContact`
`team_inbox`	Real-time shared inbox (WebSocket)	`Messages`, `MessageEventIds`
`chat_flow`	Visual conversation flow builder	`ChatFlow`, `ChatFlowNode`, `ChatFlowEdge`
`notifications`	In-app notification system	`Notification`
`razorpay`	Payment gateway integration	`RazorpayOrder`
`transaction`	Wallet credit management	`TenantTransaction`
`mcp_server`	MCP server for AI agent integration	— (stateless tools)

Request Flow

REST API Request

Client sends HTTP request with JWT Authorization: Bearer <token>
Nginx routes to Gunicorn (or Daphne for ASGI)
SimpleJWT authenticates and resolves User
ViewSet validates tenant context from URL/headers
Serializer validates input, creates/updates models
Channel adapter dispatches to appropriate BSP if messaging
Celery handles async tasks (broadcast batches, webhook delivery)
Response returned with standard pagination

WebSocket Connection

Client connects to ws://host/ws/team-inbox/{tenant_id}/
AuthMiddlewareStack validates JWT from query params
TeamInboxConsumer joins tenant-specific channel group
Messages broadcast to all connected agents in real-time
Typing indicators, read receipts, assignment updates — all via WebSocket

Webhook Inbound

External provider (Meta, Telegram, Twilio, Google) sends webhook POST
Webhook view verifies signature (provider-specific)
Raw event stored in *WebhookEvent table
Message parsed and stored in app-specific message model
Team inbox notified via Channels (WebSocket broadcast)
Chat flow engine evaluates if any active flows should trigger

ASGI Configuration

Jina Connect uses Django Channels with a ProtocolTypeRouter:

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": AuthMiddlewareStack(
        URLRouter(
            team_inbox.routing.websocket_urlpatterns
        )
    ),
})

Both HTTP and WebSocket traffic is served through Daphne in Docker. In production, you can split HTTP → Gunicorn and WebSocket → Daphne behind Nginx.

Celery Tasks

Background task processing handles:

Task	Schedule	Description
Template status sync	Every 2 minutes	Syncs template approval status from BSPs
Broadcast status check	Every 1 minute	Updates campaign delivery metrics
Notification cleanup	Daily at 3:00 AM	Removes old notification records
SMS/RCS counter reset	Daily at midnight	Resets daily message counters
Broadcast batch processing	On-demand	Sends messages in configurable batches
Webhook event delivery	On-demand	Delivers webhook events to subscriber endpoints

Database Schema Design

All models inherit from BaseModel (in abstract/models.py) which provides:

id — UUID primary key
created_at — Auto-set creation timestamp
updated_at — Auto-updated modification timestamp

Sensitive fields (API tokens, provider credentials, bot tokens) use django-encrypted-model-fields with the FIELD_ENCRYPTION_KEY Fernet key.