Request Lifecycle Specification

This document details the exact, step-by-step traversal of HTTP REST requests and WebSocket connections through the MetaPilot architecture stack.

1. HTTP REST Request Lifecycle

Rendering diagram...

Detailed Pipeline Traversal Breakdown

Phase A: Socket Ingestion & ASGI Processing

TCP Socket Ingestion: Daphne listens on
```
0.0.0.0:8000
```
via Twisted event loop.

ASGI Scope Construction: Converts raw HTTP headers into an ASGI scope dictionary:

python

{
    'type': 'http',
    'method': 'POST',
    'path': '/api/clients/',
    'headers': [(b'host', b'localhost:8000'), (b'authorization', b'Bearer eyJ...'), (b'x-tenant-id', b'96598ec0...')]
}

Phase B: Django Middleware Pipeline Execution

CorsMiddleware
: Evaluates
```
Origin
```
header against
```
CORS_ALLOWED_ORIGINS
```
(
```
http://localhost:3000
```
). If preflight
```
OPTIONS
```
request, returns
```
200 OK
```
immediately with CORS response headers.
SecurityMiddleware
&
WhiteNoiseMiddleware
: Applies strict transport security, content-type nosniff rules, and static asset routing.

TenantMiddleware
(
tenants.middleware
):

Inspects
```
X-Tenant-ID
```
HTTP header.
If missing, decodes JWT access token claim
```
tenant_id
```
.

Queries database:

Tenant.objects.filter(id=tenant_id, is_active=True).first()

Attaches resolved instance to
```
request.tenant
```
.

AuthenticationMiddleware
& SimpleJWT (
rest_framework_simplejwt.authentication.JWTAuthentication
):
- Extracts Bearer token from
```
Authorization
```
  header.
- Decodes token using
```
settings.SECRET_KEY
```
  and algorithm
```
HS256
```
  .
- Verifies signature, expiration timestamp (
```
exp
```
  ), and ensures token type is
```
access
```
  .
- Fetches active user and attaches
```
request.user
```
  .

Phase C: ViewSet & Permission Execution

DRF Permission Layer: Evaluates

permission_classes = [IsAuthenticated, IsSuperAdmin]

. If user role fails RBAC check, raises

PermissionDenied

(

403 Forbidden

Serializer Field & Business Validation:
- ```
TenantSerializer.is_valid(raise_exception=True)
```
  runs validations on
```
name
```
  ,
```
slug
```
  , and
```
wa_access_token
```
  .
- Verifies slug uniqueness in database.
Cryptographic Encryption & Model Persistence:
- Inside
```
TenantSerializer.create()
```
  , calls
```
config.set_value(wa_access_token)
```
  .
- ```
TenantConfig.set_value()
```
  encrypts plaintext access token using
```
Fernet(settings.FERNET_KEY)
```
  .
- Executes SQL
```
INSERT
```
  inside atomic transaction (
```
transaction.atomic()
```
  ).

Phase D: Response Serialization

DTO Construction: Serializer maps model attributes to JSON representation (omitting sensitive decrypted values).
HTTP Output Dispatch: Returns
```
Response(data, status=status.HTTP_201_CREATED)
```
back through middleware stack to client.

2. WebSocket Request & Connection Lifecycle

Rendering diagram...

Detailed Pipeline Traversal Breakdown

Protocol Protocol Routing:
```
core/asgi.py
```
routes
```
websocket
```
connections through
```
ProtocolTypeRouter
```
to
```
URLRouter
```
.

Channel Group Registration:

InboxConsumer.connect()

extracts

tenant_id

from URL keyword arguments, verifies agent membership, and calls

async_to_sync(self.channel_layer.group_add)(f"inbox_{tenant_id}", self.channel_name)

Redis Subscription: The connection is registered under Redis Pub/Sub channel
```
inbox_<tenant_id>
```
in Redis DB 1.
Realtime Broadcast Dispatch:
- Inbound webhook arrives or agent replies to conversation.
- Django publishes event:
```
channel_layer.group_send(f"inbox_{tenant_id}", {"type": "new_message", "data": ...})
```
  .
- Redis broadcasts event payload to all connected WebSocket worker processes.
- ```
InboxConsumer
```
  encodes payload as JSON string and pushes frame over WebSocket connection.

Request Lifecycle Specs

Request Lifecycle Specification

1. HTTP REST Request Lifecycle

Detailed Pipeline Traversal Breakdown

Phase A: Socket Ingestion & ASGI Processing

Phase B: Django Middleware Pipeline Execution

Phase C: ViewSet & Permission Execution

Phase D: Response Serialization

2. WebSocket Request & Connection Lifecycle

Detailed Pipeline Traversal Breakdown