DjangoForge Wizard Dashboard Documentation

This document describes the authenticated DjangoForge Wizard dashboard, its shared layout, form workflow, generated configuration, help dialogs, settings page, API behavior, and responsive interaction model.

Overview

The Wizard Dashboard is the visual configuration interface for DjangoForge. It allows an authenticated user to:

• Select a Django project template.
• Choose compatible Python and Django versions.
• Configure SQLite or MySQL.
• Select CSS frameworks, icon fonts, JavaScript libraries, and custom asset scaffolding.
• Enable optional Django modules.
• Configure setup scripts, admin credentials, server startup, and GitHub publishing.
• Review the final configuration and mockup.
• Generate and download a complete project ZIP archive.

The dashboard is intentionally guided: users move through six configuration steps, while the sidebar provides direct access to each step after Build a project is expanded.

Access and routes

All dashboard routes require authentication.

Unauthenticated users are redirected to /login/?next=/wizard/ or the relevant protected URL. Successful login returns the user to the requested destination, normally /wizard/.

Shared dashboard layout

The dashboard and settings page inherit the shared wizard layout:

• generator/wizard_base.html — common HTML shell, font, Tailwind CSS, Font Awesome, header, sidebar, and content area.
• generator/_wizard_sidebar.html — responsive full-height navigation sidebar.
• generator/_wizard_header.html — shared responsive header, account indicator, and logout control.

Typography and visual system

• Font: Barlow, loaded through the shared base layout.
• Primary color: Django green, represented by the customized indigo Tailwind palette.
• Secondary color: Forge orange, represented by the customized violet Tailwind palette and explicit orange accents.
• Cards: White surfaces, thin slate borders, rounded corners, and restrained shadows.
• Focus states: Visible indigo or orange focus rings for keyboard navigation.

Desktop sidebar

At large desktop widths, the sidebar is fixed to the left and fills the viewport height. The main header and content are offset to account for its width.

The sidebar contains:

1. DjangoForge brand link.
2. Dashboard link.
3. Build a project expandable menu.
4. Wizard step links, hidden until Build a project is selected.
5. Account section with Change password.
6. Back to website link.

The account section is fixed near the bottom of the sidebar, immediately above Back to website.

Mobile and tablet sidebar

On mobile and tablet widths:

• The sidebar starts off-canvas.
• A hamburger button opens it.
• A close button and backdrop close it.
• Page scrolling is locked while the drawer is open.
• The menu remains full height and scrollable internally.

Active navigation state

Only the current destination or wizard panel is visually active.

• Dashboard is active on the dashboard overview.
• A wizard step receives .is-active when selected.
• Dashboard loses its active state when a wizard step is selected.
• Change password is active only on /wizard/settings/.
• Active wizard steps also receive aria-current="step".

Dashboard overview

Before the form starts, the dashboard displays:

• DjangoForge branding.
• A short explanation of the generator.
• Feature cards describing templates, modules, databases, frontend assets, setup, admin, versions, and output.
• A Get started button.

Selecting Get started hides the overview, shows the form, reveals progress, and opens Step 1.

Wizard navigation

The progress header displays:

• Current step number, such as Step 2 of 6.
• Current step title.
• Animated progress bar.

The six steps are:

1. Project basics
2. Database
3. Frontend assets
4. Modules
5. Post-generation setup
6. Review & generate

Users can navigate with Next and Back or select a visible sidebar step. Direct sidebar selection intentionally shows the selected panel immediately; normal Next navigation validates the current panel first.

Every step includes a How to configure this step link. The link opens a modal explaining the purpose of the fields, recommended choices, and resulting behavior.

Step 1: Project basics

Project name

The project name is required. It must:

• Start with a letter.
• Contain only letters, digits, and underscores.
• Be no longer than 50 characters.
• Not use a reserved name such as django, test, settings, config, static, templates, venv, or python.

Example: my_company

Template

Available templates:

• General Django Project — a clean reusable foundation for applications, APIs, dashboards, and custom products.
• Corporate Website — responsive Home, About, Services, Contact, and custom 404 pages.

The Corporate template automatically enables Contact and prevents duplicate module configuration.

Python version

Available versions:

• Python 3.10
• Python 3.11
• Python 3.12
• Python 3.13

The generator validates version compatibility with the selected Django version.

Django version

Available versions:

• Django 4.2 LTS
• Django 5.0
• Django 5.1
• Django 5.2 LTS
• Django 6.0
• Django 6.1

Website title

Optional site title used for generated metadata and branding. If omitted, the project name is used.

Description

Optional project or website description used as generated project metadata.

Step 2: Database

The dashboard currently supports:

• SQLite — default, zero-configuration local development database.
• MySQL — production-oriented configuration using environment variables and PyMySQL compatibility support.

PostgreSQL is not currently supported by the generator and must not be selected or treated as an active generator option.

Generated database credentials are environment-driven rather than hard-coded into project settings.

Step 3: Frontend assets

CSS handling

• Tailwind CSS — compiled and included locally; no Node.js runtime is required by the generated project.
• Bootstrap — local Bootstrap-based styling.
• None — use the project’s general CSS scaffold without a selected framework.

Icon font

• Font Awesome
• Bootstrap Icons
• Material Symbols
• No icon font

JavaScript libraries

The dashboard can vendor any combination of the following libraries:

Each library name in the dashboard opens its official website in a secure new tab. Select2 automatically enables its jQuery dependency.

Custom CSS and JavaScript scaffolds

When enabled, the generator creates empty custom CSS and JavaScript files for project-specific changes.

Step 4: Modules

Modules are independent and composable. Each module has a question-mark help button that opens a guide describing its purpose, generated models, and model relationships.

Authentication

• Uses Django’s built-in User model.
• No custom authentication model is generated.
• Adds registration, login, logout, password change, password reset, and profile functionality.
• Other modules can reference the configured User model.

Blog

Generated model: Post

Important fields include title, slug, excerpt, content, featured image, publication status, publication date, and timestamps.

Relationship:

• Post.author is a ForeignKey to the configured User model.
• One user can author many posts.

Draft posts are hidden from public pages. Search, pagination, detail pages, and admin management are included.

Contact

Generated model: ContactMessage

Stores name, email, subject, message, handled state, and creation time.

Relationship:

• Standalone model with no foreign-key relationships.

Corporate Website automatically enables Contact.

Inline image upload

Generated model: EditableImage

Stores a unique content key, image file, and update timestamp.

Relationship:

• Standalone model.
• Templates resolve replaceable images through the unique key.

Image replacement is staff-only and includes a localized placeholder when no image is available.

Inline text edit

Generated model: EditableText

Stores content key, language, translated value, and update timestamp.

Relationship:

• The combination of key and language is unique.
• Each content key can therefore have one override per language.

Editing is staff-only and performed through AJAX-enabled interface controls.

FAQ

Generated model: Faq

Stores question, answer, display order, publication state, and creation time.

Relationship:

• Standalone model with no foreign-key relationships.

FAQ entries can be ordered and managed in the Django admin.

Site settings

Generated model: SiteSettings

Stores title, slogan, phone, email, address, logo, favicon, about text, and copyright text.

Relationship:

• Singleton model with primary key 1.
• No foreign-key relationships.

Multilingual

Multilingual infrastructure does not create one standalone module model. It adds:

• Locale directories and translation files.
• Language switching and i18n_patterns support.
• RTL/LTR layout support.
• Translation configuration through modeltranslation where applicable.

When enabled, the dashboard lets the user select languages and a primary language.

Step 5: Post-generation setup

Setup script

When enabled, DjangoForge creates setup helpers that can:

• Create a virtual environment.
• Install dependencies.
• Run migrations.
• Create the admin superuser.
• Seed supported sample data.
• Optionally start the development server.

Target operating system

• Windows
• macOS
• Linux

Admin username and password

These values are used by the generated setup process to create the initial Django admin account. The default password should be changed before production use.

GitHub publishing

When enabled, the setup helper can:

1. Initialize Git.
2. Create the initial commit.
3. Add the configured repository URL.
4. Push the configured branch.

The repository URL and branch are entered in the dashboard. Credentials are read from GITHUB_TOKEN or GITHUB_ACCESS_TOKEN in .env.

The built-in GitHub guide explains installation, repository setup, token configuration, setup commands, and token safety.

Development server

The generated setup script can optionally launch the development server after setup.

Step 6: Review and generate

The review screen contains two tabs:

All Details

Displays the resolved project configuration, including:

• Project name.
• Template.
• Python and Django versions.
• Database.
• CSS framework.
• Icon font.
• JavaScript libraries.
• Enabled modules.
• Setup and GitHub options.

Mockup

Available mockup styles:

• Classic corporate
• Minimal starter
• Dashboard

The mockup previews the selected corporate or general visual direction. It is a visual preview and does not replace the generated project.

Generate project

The Generate project button submits the assembled configuration to /wizard/api/generate/. On success, the dashboard displays:

• Project-created confirmation.
• Download ZIP link.
• Extraction instructions.
• Operating-system-specific setup commands.
• Admin URL and local development URL.

Validation and dependencies

The dashboard performs client-side validation before advancing:

• Project name format and reserved-name validation.
• At least one language when multilingual mode is enabled.
• Primary language must be selected.
• Admin password is required when setup scripts are enabled.

The backend performs authoritative validation again before writing files. Client-side validation must not be treated as a security boundary.

JavaScript dependency behavior:

• Select2 automatically enables jQuery.
• The dependency message is shown immediately when needed.

User settings page

The User Settings sidebar item opens /wizard/settings/.

The current settings scope is intentionally limited to password management:

• Current password.
• New password.
• New password confirmation.

The page uses Django’s PasswordChangeForm and preserves the current authenticated session after a successful password change with update_session_auth_hash.

The page includes:

• Shared header and sidebar.
• Responsive mobile sidebar drawer.
• Password security card.
• Field-level validation errors.
• Success confirmation.
• Secure CSRF-protected POST submission.

Frontend implementation

Important files:

The dashboard uses progressive enhancement-style JavaScript for:

• Step visibility.
• Progress updates.
• Sidebar expansion and mobile drawer behavior.
• Help modals.
• GitHub guide modal.
• Module guide modal.
• Language panel updates.
• Setup panel visibility.
• Mockup rendering.
• Review rendering.
• Generation requests.

Responsive behavior

• Mobile: single-column form controls, off-canvas sidebar, stacked action buttons, full-width dialogs.
• Tablet: readable single-column or compact grid controls, drawer sidebar, responsive library/module cards.
• Desktop: persistent full-height sidebar, wider form card, two-column field groups where appropriate, and expanded library grids.

All modal dialogs use viewport-aware scrolling so long help content remains usable on small screens.

Security notes

• Wizard and settings routes require login.
• Password changes use Django’s built-in secure form and CSRF protection.
• GitHub tokens must remain in .env and must never be committed.
• Generated admin credentials should be changed before production deployment.
• Backend validation runs independently of browser validation.
• Generated projects use environment-driven production configuration.

Verification checklist

After changing the dashboard or shared layouts, run:

.\.venv\Scripts\python.exe studio\manage.py check
.\.venv\Scripts\python.exe -m pytest

The current project verification baseline is 111 passing tests.