# mammhoud/devstart-django architecture

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

- Interactive diagram: https://gitdiagram.com/mammhoud/devstart-django
- Repository: https://github.com/mammhoud/devstart-django

## Overview

##### Project Type and Purpose
- This is a full-stack web application “starter” template built with Django (Python) for the backend, webpack (Node.js) for the frontend assets pipeline, and Celery for asynchronous tasks.
- It’s configured for both local development (via Docker Compose) and production deployments (Docker Compose + Traefik + AWS maintenance containers).
- It follows an MVC-like pattern (Django’s MTV), plus a task queue, and serves static assets compiled by webpack.

##### File Structure to Uncover Architectural Layers
- Top-level “config/”: central Django settings (base, local, production) and ASGI/WSGI entrypoints.
- “src/”: your Django project and apps:
– src/static + src/templates: frontend assets (CSS/JS/Sass) and HTML templates.
– src/users and src/contrib/sites: two sample Django apps (models, views, tasks, tests).
- “webpack/”: Node.js build pipeline, with common/dev/prod configs.
- “compose/”: Docker Compose definitions:
– compose/local/…: local development services (django, celery, node, docs).
– compose/production/…: production services (django w/ entrypoint, celery, Postgres, Traefik proxy, AWS maintenance helpers).
- “docker-compose.local.yml” and “docker-compose.production.yml”: orchestrators that tie everything together.

##### Extract Insights from the README
- Backend server uses `hatch run dev-backend` / `prod-backend` for Django runserver or Gunicorn/Uvicorn.
- Frontend assets served by webpack dev server or built to static files.
- Dependencies managed by “uv” (fast pip alternative) and Node’s npm.
- Docker integration for both local and CI/CD.

##### Out the Main Components
a. User Clients
– Browser (interacts via HTTP/HTTPS and WebSocket).
b. Frontend
– Webpack Dev Server (in dev) or Static files served by Django/Traefik.
– Node.js build pipeline.
c. Backend (Django)
– ASGI server (channels/websocket support)
– WSGI server (Gunicorn)
– Django application code (src/users, src/contrib)
– REST or template-based views (Django templates).
d. Task Queue
– Celery Worker(s)
– Celery Beat Scheduler
– Celery Flower (monitoring)
– message broker (e.g., Redis, as configured via environment variables)
e. Data Store
– PostgreSQL database
– (Optionally) file storage (S3 or local volume) for media/static in production
f. Reverse Proxy / Load Balancer
– Traefik in front of Django and static services in production
g. External/Cloud Services
– AWS maintenance containers (backup/restore scripts for Postgres)
– Any S3 buckets or similar for asset storage

##### Architectural Patterns and Technologies
- Layered MVC (Django’s MTV) architecture
- Asynchronous task pattern (Celery + message broker)
- Containerized environments (Docker Compose for local & production)
- Reverse proxy pattern (Traefik for routing, HTTPS termination)
- Build pipeline pattern (webpack for frontend assets)

##### Detail Without Over-Complication
- Every service from `compose/local` and `compose/production` relevant to runtime.
- How `webpack` configs feed into the static asset pipeline.
- Both synchronous HTTP paths and asynchronous task paths.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Browser["Browser"]:::external

    %% Local Environment
    subgraph "Local Environment" 
        direction TB
        subgraph "Docker Compose: Local" 
            direction TB
            LocalDjango["Django Dev Server (runserver)"]:::backend
            LocalCeleryWorker["Celery Worker"]:::backend
            LocalCeleryBeat["Celery Beat Scheduler"]:::backend
            LocalCeleryFlower["Celery Flower"]:::backend
            WebpackDev["Webpack Dev Server"]:::frontend
        end
    end

    %% Production Environment
    subgraph "Production Environment"
        direction TB
        subgraph "Docker Compose: Production"
            direction TB
            Traefik["Traefik Proxy"]:::external
            ProdDjango["Django ASGI/WSGI (Gunicorn/Uvicorn)"]:::backend
            ProdCeleryWorker["Celery Worker"]:::backend
            ProdCeleryBeat["Celery Beat Scheduler"]:::backend
            ProdCeleryFlower["Celery Flower"]:::backend
            Postgres["PostgreSQL 14"]:::datastore
            subgraph "AWS Maintenance"
                direction TB
                AWSBackup["Backup Container"]:::external
                AWSRestore["Restore Container"]:::external
            end
        end
    end

    %% Frontend Assets & Templates
    subgraph "Frontend Assets"
        direction TB
        StaticAssets["Static Files (built)"]:::frontend
        Templates["HTML Templates"]:::frontend
        WebpackCommon["Webpack Common Config"]:::pipeline
        WebpackDevCfg["Webpack Dev Config"]:::pipeline
        WebpackProdCfg["Webpack Prod Config"]:::pipeline
    end

    %% Django Project Configuration
    subgraph "Django Project"
        direction TB
        SettingsBase["Base Settings"]:::backend
        SettingsLocal["Local Settings"]:::backend
        SettingsProd["Production Settings"]:::backend
        ASGI["ASGI Entry Point"]:::backend
        WSGI["WSGI Entry Point"]:::backend
        WebsocketRoute["WebSocket Routing"]:::backend
        CeleryConfig["Celery App Config"]:::backend
        URLConf["URL Configuration"]:::backend
        ManagePy["manage.py"]:::backend
        UsersApp["src/users App"]:::backend
        SitesApp["src/contrib/sites App"]:::backend
    end

    %% Connections
    Browser -->|"HTTPS / HTTP"| Traefik
    Traefik -->|"Routes Requests"| ProdDjango
    Browser -->|"WebSocket"| ProdDjango
    Browser -->|"HTTP Dev"| LocalDjango
    LocalDjango -->|"Serves Webpack Dev"| WebpackDev
    LocalDjango -->|"API/Pages"| UsersApp
    LocalDjango -->|"API/Pages"| SitesApp
    ProdDjango -->|"Reads/Writes"| Postgres
    ProdDjango -->|"Enqueues Tasks"| ProdCeleryWorker
    ProdCeleryWorker -->|"Uses Broker"| ProdCeleryBeat
    ProdCeleryWorker -->|"Reads/Writes"| Postgres
    ProdCeleryBeat -->|"Schedules"| ProdCeleryWorker
    ProdCeleryFlower -->|"Monitors"| ProdCeleryWorker
    LocalCeleryWorker -->|"Processes Tasks"| LocalDjango
    LocalCeleryBeat -->|"Schedules"| LocalCeleryWorker
    LocalCeleryFlower -->|"Monitors"| LocalCeleryWorker
    LocalDjango -->|"Static Files"| StaticAssets
    StaticAssets -->|"Served by"| Traefik
    WebpackDev -->|"Compiles"| StaticAssets
    WebpackCommon --> WebpackDevCfg
    WebpackCommon --> WebpackProdCfg
    WebpackProdCfg --> StaticAssets
    Templates --> LocalDjango
    Templates --> ProdDjango

    %% Django config links
    SettingsBase --> SettingsLocal
    SettingsBase --> SettingsProd
    ASGI --> WebsocketRoute
    ASGI --> URLConf
    WSGI --> URLConf
    CeleryConfig --> URLConf

    %% Click Events
    click SettingsBase "https://github.com/mammhoud/devstart-django/blob/master/config/settings/base.py"
    click SettingsLocal "https://github.com/mammhoud/devstart-django/blob/master/config/settings/local.py"
    click SettingsProd "https://github.com/mammhoud/devstart-django/blob/master/config/settings/production.py"
    click ASGI "https://github.com/mammhoud/devstart-django/blob/master/config/asgi.py"
    click WSGI "https://github.com/mammhoud/devstart-django/blob/master/config/wsgi.py"
    click WebsocketRoute "https://github.com/mammhoud/devstart-django/blob/master/config/websocket.py"
    click CeleryConfig "https://github.com/mammhoud/devstart-django/blob/master/config/celery_app.py"
    click URLConf "https://github.com/mammhoud/devstart-django/blob/master/config/urls.py"
    click ManagePy "https://github.com/mammhoud/devstart-django/blob/master/manage.py"
    click UsersApp "https://github.com/mammhoud/devstart-django/tree/master/src/users/"
    click SitesApp "https://github.com/mammhoud/devstart-django/tree/master/src/contrib/sites/"
    click StaticAssets "https://github.com/mammhoud/devstart-django/tree/master/src/static/"
    click Templates "https://github.com/mammhoud/devstart-django/tree/master/src/templates/"
    click WebpackCommon "https://github.com/mammhoud/devstart-django/blob/master/webpack/common.config.js"
    click WebpackDevCfg "https://github.com/mammhoud/devstart-django/blob/master/webpack/dev.config.js"
    click WebpackProdCfg "https://github.com/mammhoud/devstart-django/blob/master/webpack/prod.config.js"
    click LocalDjango "https://github.com/mammhoud/devstart-django/tree/master/compose/local/django/Dockerfile"
    click LocalCeleryWorker "https://github.com/mammhoud/devstart-django/tree/master/compose/local/django/celery/worker"
    click LocalCeleryBeat "https://github.com/mammhoud/devstart-django/tree/master/compose/local/django/celery/beat"
    click LocalCeleryFlower "https://github.com/mammhoud/devstart-django/tree/master/compose/local/django/celery/flower"
    click ProdDjango "https://github.com/mammhoud/devstart-django/tree/master/compose/production/django/Dockerfile"
    click ProdCeleryWorker "https://github.com/mammhoud/devstart-django/tree/master/compose/production/django/celery/worker"
    click ProdCeleryBeat "https://github.com/mammhoud/devstart-django/tree/master/compose/production/django/celery/beat"
    click ProdCeleryFlower "https://github.com/mammhoud/devstart-django/tree/master/compose/production/django/celery/flower"
    click Postgres "https://github.com/mammhoud/devstart-django/tree/master/compose/production/postgres/"
    click Traefik "https://github.com/mammhoud/devstart-django/blob/master/compose/production/traefik/traefik.yml"
    click AWSBackup "https://github.com/mammhoud/devstart-django/tree/master/compose/production/aws/maintenance/"
    click AWSRestore "https://github.com/mammhoud/devstart-django/tree/master/compose/production/aws/maintenance/"

    %% Styles
    classDef frontend fill:#cfe2f3,stroke:#4682b4,color:#000
    classDef backend fill:#d9ead3,stroke:#6aa84f,color:#000
    classDef datastore fill:#ffe599,stroke:#b45f06,color:#000
    classDef external fill:#f4cccc,stroke:#a61c00,color:#000
    classDef pipeline fill:#d0e0e3,stroke:#76a5af,color:#000
```
