# lupon1/django-project-assistant architecture

> Architecture diagram of the GitHub repository lupon1/django-project-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lupon1/django-project-assistant
- Repository: https://github.com/lupon1/django-project-assistant

## Overview

#### Purpose and Runtime

Django Project Assistant is a cross-platform desktop GUI that scaffolds and configures new Django projects. It runs as Python 3.8+ locally, using Tkinter-based UI infrastructure and the external `uv` CLI for Python environments and package installation. Primary launch point: `main.py`.

#### Application Composition

- **GUI bootstrap and interaction layer** — initializes the desktop application, gathers project, environment, package, template, and optional-feature selections.  
  Paths: `main.py`, `custom_dialogs.py`, `themes/forest-dark.tcl`

- **Project orchestration layer** — translates UI selections into an ordered Django bootstrap workflow: create directories/environment, initialize Django, install packages, generate apps/files, and optionally run the server.  
  Paths: `project_logic.py`, `main.py`

- **Configuration model/loader** — supplies selectable Django packages, external web libraries, and defaults consumed by the UI and orchestration logic. The README describes `config.json`, while the available tree exposes its management code rather than the JSON file itself.  
  Paths: `config_manager.py`, `main.py`

#### Primary Control Flow

1. User starts `main.py` and selects a project name, project parent directory, Python version, venv location, packages, template collection, and feature flags.
2. The GUI delegates build actions to `project_logic.py`.
3. The builder invokes `uv` to create/manage the target virtual environment and install Django plus selected optional dependencies.
4. It creates the Django project and applies generated configuration, including installed apps, middleware, and other settings from selected package definitions.
5. It copies a chosen template collection into the created project and injects selected CSS/JavaScript references into template placeholders.
6. Optional custom-user setup generates an `accounts` app from templates; optional superuser creation and development-server/browser launch occur after project generation.

#### Template and Code-Generation Boundary

The repository is a generator, not a Django project itself. Static source templates are copied or rendered into the generated target project, isolating reusable starter assets from generated output.

- **HTML starter collections** provide framework-specific base/index pages, selected dynamically by top-level collection directory.  
  Paths: `html_templates/bootstrap/core/base.html`, `html_templates/bootstrap/core/index.html`, `html_templates/bulma/core/base.html`

- **Custom user-model templates** define generated Django `accounts` app artifacts when enabled.  
  Paths: `code_templates/accounts/models.py.template`, `code_templates/accounts/admin.py.template`, `code_templates/accounts/apps.py.template`

#### Configuration and Extension Points

Package definitions can declare Django apps, middleware, and settings additions; external-library definitions supply head/body asset URLs. Template collections are extensible by adding correctly structured directories under `html_templates/`. Base templates must retain the assistant’s head/body injection markers.

Relevant paths: `config_manager.py`, `html_templates`, `code_templates`.

#### External Dependencies and Boundaries

- **`uv`** is mandatory and is executed as an external process for venv and dependency lifecycle management.
- **Django** and optional Django ecosystem packages are installed into each generated project, not necessarily into this assistant’s runtime.
- **Tkinter** is the desktop GUI runtime; Linux may require OS-level Tk libraries.
- **`pywinstyles`** is an optional Windows-only dependency for themed window styling.
- Generated files, installed dependencies, user filesystem paths, browser launching, and Django server processes are all side effects owned by the orchestration boundary in `project_logic.py`.

Main entry points: [`project_logic.py`](https://github.com/lupon1/django-project-assistant/blob/main/project_logic.py) (Project builder), [`main.py`](https://github.com/lupon1/django-project-assistant/blob/main/main.py) (Selection GUI), [`html_templates`](https://github.com/lupon1/django-project-assistant/tree/main/html_templates) (HTML collections), [`config_manager.py`](https://github.com/lupon1/django-project-assistant/blob/main/config_manager.py) (Package definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_assistant["Desktop Assistant"]
  node_entry["Application launcher<br/>Python entry point<br/>[main.py]"]
  node_gui["Selection GUI<br/>Tkinter UI<br/>[main.py]"]
  node_dialogs["Custom dialogs<br/>UI components<br/>[custom_dialogs.py]"]
  node_theme["Forest dark theme<br/>Tk theme<br/>[forest-dark.tcl]"]
  node_config["Package definitions<br/>configuration loader<br/>[config_manager.py]"]
  node_orchestrator["Project builder<br/>workflow orchestrator<br/>[project_logic.py]"]
end

subgraph group_templates["Generator Assets"]
  node_html["HTML collections<br/>starter templates"]
  node_bootstrap["Bootstrap starter<br/>HTML collection<br/>[base.html]"]
  node_bulma["Bulma starter<br/>HTML collection<br/>[base.html]"]
  node_accounts_templates["Accounts app templates<br/>code templates<br/>[models.py.template]"]
end

subgraph group_target["Generated Django Project"]
  node_django_project["Django project output<br/>generated project"]
  node_target_env{{"Target virtual environment<br/>generated environment"}}
  node_accounts_app["Generated accounts app<br/>generated Django app"]
  node_runtime_actions(("Server and browser launch<br/>side effects"))
end

node_uv{{"uv CLI<br/>external process"}}

node_entry -->|"starts"| node_gui
node_gui -->|"uses"| node_dialogs
node_gui -->|"loads"| node_theme
node_gui -->|"reads choices from"| node_config
node_gui -->|"submits selections"| node_orchestrator
node_orchestrator -->|"executes"| node_uv
node_uv -->|"creates and populates"| node_target_env
node_orchestrator -->|"creates and configures"| node_django_project
node_config -->|"supplies apps, middleware, settings, and assets"| node_orchestrator
node_html -.->|"contains collection"| node_bootstrap
node_html -.->|"contains collection"| node_bulma
node_orchestrator -->|"selects and copies"| node_html
node_html -->|"becomes generated templates"| node_django_project
node_orchestrator -->|"renders when enabled"| node_accounts_templates
node_accounts_templates -->|"generates"| node_accounts_app
node_accounts_app -->|"is added to"| node_django_project
node_orchestrator -->|"optionally performs"| node_runtime_actions
node_runtime_actions -->|"runs against"| node_django_project

click node_entry "https://github.com/lupon1/django-project-assistant/blob/main/main.py"
click node_gui "https://github.com/lupon1/django-project-assistant/blob/main/main.py"
click node_dialogs "https://github.com/lupon1/django-project-assistant/blob/main/custom_dialogs.py"
click node_theme "https://github.com/lupon1/django-project-assistant/blob/main/themes/forest-dark.tcl"
click node_config "https://github.com/lupon1/django-project-assistant/blob/main/config_manager.py"
click node_orchestrator "https://github.com/lupon1/django-project-assistant/blob/main/project_logic.py"
click node_html "https://github.com/lupon1/django-project-assistant/tree/main/html_templates"
click node_bootstrap "https://github.com/lupon1/django-project-assistant/blob/main/html_templates/bootstrap/core/base.html"
click node_bulma "https://github.com/lupon1/django-project-assistant/blob/main/html_templates/bulma/core/base.html"
click node_accounts_templates "https://github.com/lupon1/django-project-assistant/blob/main/code_templates/accounts/models.py.template"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_gui,node_dialogs,node_theme,node_config,node_orchestrator toneBlue
class node_html,node_bootstrap,node_bulma,node_accounts_templates toneAmber
class node_django_project,node_target_env,node_accounts_app,node_runtime_actions toneMint
class node_uv toneNeutral
```

## Components

### Desktop Assistant

- [Application launcher](https://github.com/lupon1/django-project-assistant/blob/main/main.py): Python entry point · Starts the desktop assistant. · `main.py`
- [Selection GUI](https://github.com/lupon1/django-project-assistant/blob/main/main.py): Tkinter UI · Collects project, environment, package, template, and feature choices. · `main.py`
- [Custom dialogs](https://github.com/lupon1/django-project-assistant/blob/main/custom_dialogs.py): UI components · `custom_dialogs.py`
- [Forest dark theme](https://github.com/lupon1/django-project-assistant/blob/main/themes/forest-dark.tcl): Tk theme · `themes/forest-dark.tcl`
- [Package definitions](https://github.com/lupon1/django-project-assistant/blob/main/config_manager.py): configuration loader · Provides package, external-library, and default definitions. · `config_manager.py`
- [Project builder](https://github.com/lupon1/django-project-assistant/blob/main/project_logic.py): workflow orchestrator · Creates and configures the selected Django project. · `project_logic.py`

### Generator Assets

- [HTML collections](https://github.com/lupon1/django-project-assistant/tree/main/html_templates): starter templates · Selectable base and index templates with asset injection markers. · `html_templates`
- [Bootstrap starter](https://github.com/lupon1/django-project-assistant/blob/main/html_templates/bootstrap/core/base.html): HTML collection · `html_templates/bootstrap/core/base.html`
- [Bulma starter](https://github.com/lupon1/django-project-assistant/blob/main/html_templates/bulma/core/base.html): HTML collection · `html_templates/bulma/core/base.html`
- [Accounts app templates](https://github.com/lupon1/django-project-assistant/blob/main/code_templates/accounts/models.py.template): code templates · Rendered when custom-user setup is selected. · `code_templates/accounts/models.py.template`

### Generated Django Project

Created in the user-selected filesystem location.

- **Django project output**: generated project · Project files and generated settings, apps, and templates.
- **Target virtual environment**: generated environment · Contains Django and selected dependencies.
- **Generated accounts app**: generated Django app · Optional custom user-model application.
- **Server and browser launch**: side effects · Optional superuser creation, development server, and browser launch.

### Other components

- **uv CLI**: external process · Manages target environments and package installation.

## Connections

- Application launcher → Selection GUI: starts
- Selection GUI → Custom dialogs: uses
- Selection GUI → Forest dark theme: loads
- Selection GUI → Package definitions: reads choices from
- Selection GUI → Project builder: submits selections
- Project builder → uv CLI: executes · Creates the environment and installs dependencies.
- uv CLI → Target virtual environment: creates and populates
- Project builder → Django project output: creates and configures
- Package definitions → Project builder: supplies apps, middleware, settings, and assets
- HTML collections → Bootstrap starter: contains collection
- HTML collections → Bulma starter: contains collection
- Project builder → HTML collections: selects and copies
- HTML collections → Django project output: becomes generated templates
- Project builder → Accounts app templates: renders when enabled
- Accounts app templates → Generated accounts app: generates
- Generated accounts app → Django project output: is added to
- Project builder → Server and browser launch: optionally performs
- Server and browser launch → Django project output: runs against