# querateam/django-nextjs architecture

> Architecture diagram of the GitHub repository querateam/django-nextjs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/querateam/django-nextjs
- Repository: https://github.com/querateam/django-nextjs

## Overview

##### Project type and purpose
- This is an open-source Django app (Python package) whose sole purpose is to integrate Next.js frontend pages into a Django project by acting as an ASGI middleware and URL-based proxy.
- It lets Django handle initial HTTP and WebSocket requests for Next.js pages (including fast-refresh pipelines) and optionally proxies Next.js assets in development, while in production you delegate asset handling to a standard reverse proxy (e.g., Nginx).

##### File-structure analysis
- Top-level files: setup.py/pyproject.toml (package metadata), README.md, LICENSE, tests/, .github/ (CI).
- Core package directory: django_nextjs/
- asgi.py: defines NextJsMiddleware that wraps your ASGI app
- proxy.py: HTTP and WebSocket proxy consumers
- views.py & urls.py: nextjs_page view factory and URL inclusion
- render.py: logic for streaming vs. non-streaming HTML responses
- templates/django_nextjs/document_base.html: base HTML template for injection
- app_settings.py, utils.py, exceptions.py: configuration and helper routines
- tests/: unit tests for render, middleware, template integration

##### README insights
a. Development (Django dev server proxies Next.js dev server, handles fast-refresh)
b. Production (use external reverse proxy for Next.js assets, Django only routes page requests)
- Configuration via NEXTJS_SETTINGS for server URL, CSRF injection, public subdirectory
- Usage patterns: ASGI middleware or URL inclusion fallback, streaming flag for App Router

##### Main components
- Browser (client)
- Django ASGI application
- NextJsMiddleware (HTTP & WebSocket entrypoint)
- Django URL router (routes “/my/page” to nextjs_page view)
- Template engine (for document_base.html injection if customizing)
- Next.js server (dev on :3000 or prod standalone)
- .next/static and public assets
- (Optional in production) Reverse proxy server (Nginx/Caddy) for static paths
- Settings store (NEXTJS_SETTINGS)

##### Component relationships and data flow
- Browser → HTTP GET “/some-next-page” → Django ASGI
→ NextJsMiddleware forwards to Next.js server (nextjs_server_url)
← HTML response streams back through middleware (render logic applies)
← Final HTML returned to Browser
- Browser → WebSocket (/_next/webpack-hmr) → Django ASGI
→ NextJsMiddleware forwards to Next.js WS endpoint
→ Middleware pipes WS frames back to Browser (fast refresh)
- In DEBUG mode: Browser → “/_next/static/…” → Django ASGI
→ NextJsMiddleware proxies asset requests to Next.js
- In PRODUCTION: Browser → “/_next/static/…” → Nginx serves from .next/static
Browser → “/_next/…” → Nginx proxies to Next.js
Browser → “/next/…” → Nginx serves from public/next

##### Architectural patterns and design principles
- Middleware pattern: NextJsMiddleware wraps any ASGI application
- Proxy pattern: HTTPConsumer / WebSocketConsumer to transparently forward requests
- Template-injection extension point: document_base.html + customize via blocks
- Configuration-driven behavior (NEXTJS_SETTINGS dictionary)

##### Essential elements to capture
- Two modes of operation (DEBUG vs production)
- Settings injection (NEXTJS_SETTINGS)
- Template-injection extension point
- HTTP vs WebSocket proxying

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Development Mode"
        Browser["Browser"]
        Browser -->|GET /my/page| DjangoASGI["Django ASGI App"]
        Browser -->|WS /_next/webpack-hmr| DjangoASGI
        Browser -->|GET /_next/static/...| DjangoASGI

        subgraph "Django ASGI App"
            NextJsMiddleware["NextJsMiddleware (ASGI)"]:::middleware
            URLRouter["URL Router"]:::service
            NextPage["nextjs_page View"]:::service
            HTTPProxy["HTTP Consumer"]:::http
            WSProxy["WebSocket Consumer"]:::websocket
            RenderLogic["Render Logic"]:::service
            TemplateEngine["Template Engine"]:::template
            DocumentTemplate["document_base.html"]:::template
            Settings["NEXTJS_SETTINGS"]:::config
            Utils["utils.py"]:::config
            Exceptions["exceptions.py"]:::config

            NextJsMiddleware --> URLRouter
            URLRouter --> NextPage
            NextJsMiddleware -->|forwards HTTP| HTTPProxy
            NextJsMiddleware -->|forwards WS| WSProxy
            HTTPProxy --> NextJsServer
            WSProxy --> NextJsServer
            NextPage --> RenderLogic
            RenderLogic --> TemplateEngine
            TemplateEngine --> DocumentTemplate
            NextJsMiddleware --> Settings
            NextJsMiddleware --> Utils
            NextJsMiddleware --> Exceptions
        end

        NextJsServer["Next.js Server"]:::service
    end

    subgraph "Production Mode"
        BrowserP["Browser"]
        BrowserP -->|GET /my/page| DjangoASGIProd["Django ASGI App (pages only)"]:::service
        BrowserP -->|GET /_next/static/...| NginxStatic["Nginx (static)"]:::prod
        BrowserP -->|GET /public/next/...| NginxPublic["Nginx (public)"]:::prod
        BrowserP -->|GET /_next/...| NginxProxy["Nginx (proxy)"]:::prod

        DjangoASGIProd -->|forwards GET| NextJsServer
        NginxProxy --> NextJsServer
    end

    click NextJsMiddleware "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/asgi.py"
    click HTTPProxy "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/proxy.py"
    click WSProxy "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/proxy.py"
    click NextPage "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/views.py"
    click URLRouter "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/urls.py"
    click RenderLogic "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/render.py"
    click DocumentTemplate "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/templates/django_nextjs/document_base.html"
    click Settings "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/app_settings.py"
    click Utils "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/utils.py"
    click Exceptions "https://github.com/querateam/django-nextjs/blob/main/django_nextjs/exceptions.py"
    click setup "https://github.com/querateam/django-nextjs/blob/main/setup.py"
    click pyproject "https://github.com/querateam/django-nextjs/blob/main/pyproject.toml"
    click README "https://github.com/querateam/django-nextjs/blob/main/README.md"
    click TestRender "https://github.com/querateam/django-nextjs/blob/main/tests/test_render.py"
    click TestSettings "https://github.com/querateam/django-nextjs/blob/main/tests/settings.py"
    click TestTemplate "https://github.com/querateam/django-nextjs/blob/main/tests/templates/custom_document.html"
    click CI "https://github.com/querateam/django-nextjs/blob/main/.github/workflows/test.yml"

    classDef http fill:#ADD8E6,stroke:#000
    classDef websocket fill:#90EE90,stroke:#000
    classDef config fill:#D3D3D3,stroke:#000
    classDef prod fill:#FFA500,stroke:#000
    classDef template fill:#D3D3D3,stroke:#000,stroke-dasharray: 5 5
    classDef service fill:#EFEFEF,stroke:#000
    classDef middleware fill:#EFEFEF,stroke:#000,stroke-width:2px,stroke-dasharray: 2 2
```
