lupon1/django-project-assistant

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.