# unfoldadmin/formula architecture

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

- Interactive diagram: https://gitdiagram.com/unfoldadmin/formula
- Repository: https://github.com/unfoldadmin/formula

## Overview

##### Project type and purpose
- This is a monolithic, full-stack Django application whose sole purpose is to demonstrate the Unfold admin theme and custom dashboard widgets.
- It provides an admin UI for viewing sample Formula 1 data (drivers, races, standings, etc.) loaded from fixtures.

##### File structure
- Top-level artifacts:
- Dockerfile & docker-compose.yml → containerized deployment
- pyproject.toml → Python/Poetry deps
- package.json → Node/Tailwind build scripts
- manage.py → Django CLI entrypoint
- “formula/” directory: the Django project & app code (settings, URLs, WSGI/ASGI, models, views, templates, static CSS, fixtures, migrations).
- Templates & static: custom admin/index.html + components under templates/admin/components, plus formula/styles.css for Tailwind extensions.
- Fixtures folder contains JSON data for initial load (users, constructors, races, etc.).

##### README for additional insights
- Confirms Unfold theme integration via UNFOLD → STYLES in settings.py.
- Describes custom dashboard override: admin index.html + components.
- Shows asset pipeline: npm scripts for tailwind:build and tailwind:watch.

##### Main components & their relationships
a. Client (Browser/Admin UI)
– Sends HTTP requests; renders HTML/CSS (Unfold + custom Tailwind).
b. Web/Application Layer (Docker “web” service)
– Django app (“formula” package) behind WSGI/ASGI server.
– Loads fixtures on startup; runs migrations.
c. Database (Docker “db” service, e.g. PostgreSQL)
– Stores domain tables (drivers, circuits, standings).
d. Static Asset Pipeline (Local or CI)
– Node.js + TailwindCSS generates compiled CSS from templates & styles.css.
– Output served as Django static files (via Whitenoise or Nginx).
e. Docker Compose orchestration
– Defines and networks web and db services; mounts volumes.
f. Development tooling
– GitHub (repo, Dependabot), pre-commit hooks, Docker registry.

##### Architectural patterns & design principles
- Monolithic MVC:
- Models layer (“formula/models.py”)
- Views & forms (views.py, forms.py)
- Templates (formula/templates)
- Layered separation: presentation (templates), application logic (views/forms), domain (models), infrastructure (settings, Docker).
- Theme plug-in pattern: UNFOLD settings + context processors feeding into admin templates.
- External asset pipeline: decoupled CSS build via npm.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Browser (Admin UI)"]:::browser
    Templates["Admin Templates"]:::service
    Styles["Static Styles"]:::service

    Client -->|HTTP Requests| WebCore
    Client --> Templates
    Client --> Styles

    %% Docker Compose Boundary
    subgraph "Docker Compose"
        direction TB

        subgraph "Web Container"
            direction TB
            WebCore["Django Web Service"]:::service

            subgraph "Django Code"
                direction TB
                E1["manage.py"]:::service
                E2["settings.py"]:::service
                E3["urls.py"]:::service
                E4["asgi.py"]:::service
                E5["wsgi.py"]:::service
                E6["apps.py"]:::service
                E7["admin.py"]:::service
                E8["views.py"]:::service
                E9["forms.py"]:::service
                E10["models.py"]:::service
                E11["context_processors.py"]:::service
                E12["signals.py"]:::service
                E13["middleware.py"]:::service
                E14["utils.py"]:::service
                E15["encoders.py"]:::service
                E16["exceptions.py"]:::service
                E17["sites.py"]:::service
                E18["resources.py"]:::service
                E19["translation.py"]:::service
            end
        end

        subgraph "DB Container"
            direction TB
            DBCore["PostgreSQL"]:::db
            DF["Initial Fixtures (JSON)"]:::db
        end

        subgraph "Build Job"
            direction TB
            Tailwind["Tailwind Build (npm scripts)"]:::build
            PackageJSON["package.json"]:::build
            PackageLock["package-lock.json"]:::build
        end
    end

    %% CI/CD & Tools
    CI["CI/CD & Dev Tools"]:::ci

    %% External Configs
    ComposeFile["docker-compose.yml"]:::service
    DockerfileNode["Dockerfile"]:::service
    Dependabot[".github/dependabot.yml"]:::ci
    Precommit[".pre-commit-config.yaml"]:::ci
    Pyproject["pyproject.toml"]:::ci

    %% Data Flows
    WebCore -->|ORM/SQL| DBCore
    Tailwind -->|Generates CSS| WebCore
    CI -->|Deploy & Build| ComposeFile
    ComposeFile -.->|Orchestrates| WebCore
    ComposeFile -.->|Orchestrates| DBCore
    ComposeFile -.->|Configures| Tailwind
    DockerfileNode -.->|Builds Image| WebCore

    %% Click Events
    click Templates "https://github.com/unfoldadmin/formula/tree/main/formula/templates/admin"
    click Styles "https://github.com/unfoldadmin/formula/blob/main/formula/styles.css"
    click E1 "https://github.com/unfoldadmin/formula/blob/main/manage.py"
    click E2 "https://github.com/unfoldadmin/formula/blob/main/formula/settings.py"
    click E3 "https://github.com/unfoldadmin/formula/blob/main/formula/urls.py"
    click E4 "https://github.com/unfoldadmin/formula/blob/main/formula/asgi.py"
    click E5 "https://github.com/unfoldadmin/formula/blob/main/formula/wsgi.py"
    click E6 "https://github.com/unfoldadmin/formula/blob/main/formula/apps.py"
    click E7 "https://github.com/unfoldadmin/formula/blob/main/formula/admin.py"
    click E8 "https://github.com/unfoldadmin/formula/blob/main/formula/views.py"
    click E9 "https://github.com/unfoldadmin/formula/blob/main/formula/forms.py"
    click E10 "https://github.com/unfoldadmin/formula/blob/main/formula/models.py"
    click E11 "https://github.com/unfoldadmin/formula/blob/main/formula/context_processors.py"
    click E12 "https://github.com/unfoldadmin/formula/blob/main/formula/signals.py"
    click E13 "https://github.com/unfoldadmin/formula/blob/main/formula/middleware.py"
    click E14 "https://github.com/unfoldadmin/formula/blob/main/formula/utils.py"
    click E15 "https://github.com/unfoldadmin/formula/blob/main/formula/encoders.py"
    click E16 "https://github.com/unfoldadmin/formula/blob/main/formula/exceptions.py"
    click E17 "https://github.com/unfoldadmin/formula/blob/main/formula/sites.py"
    click E18 "https://github.com/unfoldadmin/formula/blob/main/formula/resources.py"
    click E19 "https://github.com/unfoldadmin/formula/blob/main/formula/translation.py"
    click DF "https://github.com/unfoldadmin/formula/tree/main/formula/fixtures"
    click ComposeFile "https://github.com/unfoldadmin/formula/blob/main/docker-compose.yml"
    click DockerfileNode "https://github.com/unfoldadmin/formula/tree/main/Dockerfile"
    click PackageJSON "https://github.com/unfoldadmin/formula/blob/main/package.json"
    click PackageLock "https://github.com/unfoldadmin/formula/blob/main/package-lock.json"
    click Dependabot "https://github.com/unfoldadmin/formula/blob/main/.github/dependabot.yml"
    click Precommit "https://github.com/unfoldadmin/formula/blob/main/.pre-commit-config.yaml"
    click Pyproject "https://github.com/unfoldadmin/formula/blob/main/pyproject.toml"

    %% Styles
    classDef service fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef browser fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef db fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef build fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef ci fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
