Runtime architecture

Runtime architecture

This repository is a Django REST backend whose runtime is assembled from backend_project/settings/core.py, backend_project/urls.py, api/urls.py, and backend_project/celery.py. The important architectural question is not just which packages exist, but in what order they execute.

Composition root

Django settings

backend_project/settings/core.py defines the cross-cutting runtime contract:

• INSTALLED_APPS includes Django core apps plus rest_framework, rest_framework_simplejwt.token_blacklist, drf_spectacular, django_user_agents, csp, audit, api.tenancy, and api.
• MIDDLEWARE establishes the request order: CORS, security, CSP, telemetry, compression, sessions, common middleware, CSRF, authentication, tenancy resolution, user-agent parsing, audit logging, messages, clickjacking, API versioning, version headers, and deprecation handling.
• DEBUG_TOOLBAR is gated by both the environment and package availability.
• Static/media roots and upload size limits are centralized here.
• The debug-toolbar callback reads settings.DEBUG at call time so tests do not leak the development toolbar.

URL composition

backend_project/urls.py is the top-level URL composition root. It wires:

• admin at admin/
• DRF auth at api-auth/
• all API routes under api/
• the double-versioned compatibility include at api/v1/v1/
• development media serving when DEBUG is true
• debug-toolbar URLs when enabled

api/urls.py then splits the API into:

• infrastructure endpoints such as /health/
• the unauthenticated API root
• versioned API routes
• docs/OpenAPI routes
• legacy redirect patterns

api/versions/v1_urls.py contains the canonical business endpoints.

Celery bootstrapping

backend_project/celery.py sets DJANGO_SETTINGS_MODULE, creates the Celery app, loads Django settings with the CELERY_ namespace, and autodiscovers tasks. Document upload processing is dispatched into this worker path.

Startup hooks

api/apps.py performs two side effects when the app registry is ready:

1. It imports api.signals unconditionally so signal handlers are active in every process, including workers.
2. It connects audit signals for tracked models and optionally syncs admin users from DJANGO_ADMINS in the main process.

Request lifecycle

The runtime ordering matters because later layers assume earlier ones have populated request context.

sequenceDiagram
    participant Client
    participant Django as Django URL resolver
    participant MW as Middleware chain
    participant View as API view / viewset
    participant DB as Database
    participant Celery as Celery worker

    Client->>Django: HTTP request
    Django->>MW: resolve path, build request
    MW->>MW: CORS, security, CSP, telemetry, compression
    MW->>MW: session, CSRF, auth, tenancy, audit
    MW->>View: dispatch with request.user and request.tenant
    View->>DB: query models / persist changes
    alt async document upload
        View->>Celery: enqueue process_document_upload_async
        Celery->>DB: update ProcessingDocument / AIStudioProcessing
    end
    View-->>Client: response

Runtime invariants

• Tenant-aware code assumes TenantMiddleware runs before views that read request.tenant.
• Many endpoints require an X-Tenant-ID header and a membership check; the API page and tenancy page document the exact routes.
• Document-processing endpoints assume the upload path has already persisted a ProcessingDocument row before background work starts.
• Version headers and deprecation middleware depend on the route layout in api/urls.py and api/versions/v1_urls.py.

Focused validation

• tests/unit/misc/test_django_functionality.py — settings-level behavior and runtime wiring.
• tests/integration/test_health.py — the top-level request path that confirms middleware and database access are healthy.
• tests/unit/api/test_api_endpoints.py — route-level contract checks.

Scope boundary

This page documents the runtime assembly, not the internals of each endpoint family. For endpoint behavior, use the subsystem pages linked from API surface.