# adamchainz/django-htmx architecture

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

- Interactive diagram: https://gitdiagram.com/adamchainz/django-htmx
- Repository: https://github.com/adamchainz/django-htmx

## Overview

##### Main Components
- Core Extension Package (located in src/django_htmx):
- http.py – Provides utilities for handling htmx-specific HTTP request/response logic.
- jinja.py – Contains integration code for Jinja templating.
- middleware.py – Implements Django middleware to manage htmx behaviors.
- templatetags/ – Offers custom Django template tags to ease htmx integration.
- static assets – The “django-htmx.js” file under src/django_htmx/static is the client-side component.
- Example Application (located in the example/ directory):
- Contains an example Django project demonstrating how to integrate and use the extension.
- Includes settings, views, forms, URLs, templates, and static files.
- Documentation (docs/ directory):
- Provides instructions, installation guides, middleware usage, etc.
- Tests (tests/ directory):
- Contains unit and integration tests covering the middleware, template tags, and HTTP utilities.
- CI and Configuration:
- .github workflows, tox.ini, and other configuration files ensure code quality, testing, and deployment.

##### Establish Relationships and Interactions
- The Django application (as shown in the “example” folder) uses the django-htmx package by:
- Loading the middleware (from middleware.py) through Django’s MIDDLEWARE setting.
- Employing the provided template tags (from templatetags/) in its HTML templates.
- Utilizing static resources (django-htmx.js) for client-side behavior.
- The http.py and jinja.py modules serve as auxiliary layers that provide helper functions or integrate with Django’s request/response lifecycle.
- Unit tests and integration tests validate that each of these components interacts correctly.
- The documentation and CI pipelines (via .github workflows) ensure the project’s stability and ease of use.

##### Architectural Patterns and Design Principles
- Modular Design: The project is separated into clear modules (HTTP handling, middleware integration, template tagging) to maintain separation of concerns.
- Integration with Django: Leveraging Django’s middleware and templating systems to plug in htmx functionalities.
- Reusability and Extensibility: Clear separation allows developers to extend or modify behaviors through middleware and custom template tags.
- Test-driven Development: A dedicated tests directory indicates an emphasis on verifying functionality across components.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Django-htmx Core Package
    subgraph "Django-htmx Core Package"
        CorePkg["Django-htmx Core Package"]:::core
        HTTP["HTTP Utilities (http.py)"]:::core
        Jinja["Jinja Integration (jinja.py)"]:::core
        Middleware["Middleware (middleware.py)"]:::core
        Templatetags["Template Tags"]:::core
        Static["Static Assets (django-htmx.js)"]:::static
    end

    %% Establish group hierarchy within Core Package
    CorePkg -->|"contains"| HTTP
    CorePkg -->|"contains"| Jinja
    CorePkg -->|"contains"| Middleware
    CorePkg -->|"contains"| Templatetags
    CorePkg -->|"contains"| Static

    %% Example Django Application
    subgraph "Example Django Application"
        ExampleApp["Example Django Application"]:::example
        Settings["settings.py"]:::example
        URLs["URLs"]:::example
        Views["Views"]:::example
        Templates["Templates"]:::example
    end

    %% Hierarchy inside Example App
    ExampleApp -->|"includes"| Settings
    ExampleApp -->|"includes"| URLs
    ExampleApp -->|"includes"| Views
    ExampleApp -->|"includes"| Templates

    %% Documentation and Tests
    subgraph "Documentation & Tests"
        Docs["Documentation"]:::docs
        Tests["Tests"]:::tests
    end

    %% CI and Configuration
    subgraph "CI and Configuration"
        CI["CI Pipelines (.github)"]:::ci
        Tox["tox.ini"]:::ci
    end

    %% Client Side
    subgraph "Client Side"
        Client["Browser (htmx.js)"]:::client
    end

    %% Interactions between Example App and Core Package components
    ExampleApp -->|"loads"| Middleware
    ExampleApp -->|"renders"| Templatetags
    ExampleApp -->|"serves"| Static
    Views -->|"triggers"| Middleware
    Templates -->|"incorporates"| Templatetags

    %% Data flow from Client
    Client -->|"loads"| Static
    Client -->|"sendsRequest"| Middleware

    %% Middleware invoking HTTP utilities
    Middleware -->|"invokes"| HTTP

    %% Testing validations
    Tests -->|"validates"| Middleware
    Tests -->|"validates"| HTTP
    Tests -->|"validates"| Templatetags

    %% Documentation describing usage
    Docs -->|"documents"| Middleware
    Docs -->|"documents"| Templatetags
    Docs -->|"documents"| HTTP
    Docs -->|"documents"| Jinja

    %% CI interactions
    CI -->|"runs"| Tests
    CI -->|"configures"| Tox

    %% Click Events
    click CorePkg "https://github.com/adamchainz/django-htmx/tree/main/src/django_htmx"
    click HTTP "https://github.com/adamchainz/django-htmx/blob/main/src/django_htmx/http.py"
    click Jinja "https://github.com/adamchainz/django-htmx/blob/main/src/django_htmx/jinja.py"
    click Middleware "https://github.com/adamchainz/django-htmx/blob/main/src/django_htmx/middleware.py"
    click Templatetags "https://github.com/adamchainz/django-htmx/tree/main/src/django_htmx/templatetags"
    click Static "https://github.com/adamchainz/django-htmx/blob/main/src/django_htmx/static/django-htmx.js"
    click ExampleApp "https://github.com/adamchainz/django-htmx/tree/main/example/example"
    click Docs "https://github.com/adamchainz/django-htmx/tree/main/docs"
    click Tests "https://github.com/adamchainz/django-htmx/tree/main/tests"
    click CI "https://github.com/adamchainz/django-htmx/blob/main/.github"
    click Tox "https://github.com/adamchainz/django-htmx/blob/main/tox.ini"

    %% Styles
    classDef core fill:#ccf,stroke:#036,stroke-width:2px;
    classDef static fill:#fcc,stroke:#933,stroke-width:2px;
    classDef example fill:#cfc,stroke:#393,stroke-width:2px;
    classDef docs fill:#ffc,stroke:#993,stroke-width:2px;
    classDef tests fill:#eef,stroke:#669,stroke-width:2px;
    classDef ci fill:#fee,stroke:#933,stroke-width:2px;
    classDef client fill:#ddd,stroke:#555,stroke-width:2px;
```
