Django Scaffold

Django Project Scaffolding

Read reference.md in full before doing anything else. Then run the question flow below.

Assumed Starting Point

The user is already inside the project directory with:

• uv init done — pyproject.toml exists
• .venv created and activated
• django (or django + wagtail) already installed via uv add

Do not generate setup instructions for creating the directory or installing Django. Do not cd anywhere.

Question Flow

Ask these questions one at a time, in order. Wait for each answer before asking the next.

Q1 — Project type:

• A. Django full-stack — templates + Tailwind CSS, server-rendered UI
• B. Wagtail CMS full-stack — same as A but with Wagtail
• C. Django REST API — DRF only. No Django templates beyond admin.

Q2 — Project name: Used for pyproject.toml name, Railway service, and database name. Derive the Python package name automatically: replace hyphens with underscores. Example: my-project → package name: my_project

Q3 — Main app name: The primary local Django app beyond users (default: core). Apps live at the project root — flat structure, no apps/ subdirectory.

Q4 — Celery + Redis? (yes / no) Recommend yes only if: background jobs >5s, retry logic, scheduled tasks, or high-volume async email. Single transactional emails do NOT need Celery.

Q5 [Full-stack and Wagtail only] — Frontend interactivity? (select any, default: both) Both HTMX and Alpine.js are served from static/js/ as downloaded minified files — no CDN, no pip package required.

• HTMX — server-driven interactions; place htmx.min.js in static/js/
• Alpine.js — client-side reactivity; place alpine.min.js in static/js/
• Both (recommended default)
• Neither

Q6 — Authentication:

• A. django-allauth — recommended default; handles email + password
• B. django-allauth with Google OAuth — adds [socialaccount] and Google provider
• C. Built-in Django auth only — simple projects, internal tools

Q7 — Languages? (default: English only) List only the languages the project actually needs. English is always included. Common additions: French (fr), Spanish (es), Portuguese (pt). If English only, no extra i18n setup is generated. If multiple, activates LANGUAGES and LOCALE_PATHS in base.py.

Once you have all seven answers, generate the complete project without further questions.

Version Resolution

Before generating any files, look up the current versions using web search or available tools:

• Python — latest stable release (e.g. python.org/downloads)
• Node.js — latest LTS release (e.g. nodejs.org)
• Django — latest LTS release, which is always the x.2 series (e.g. djangoproject.com/download)

Use these resolved versions in railpack.json (packages.python, packages.node), pyproject.toml (target-version, python_version), and anywhere else a version string appears. Do not fall back to values from your training data.

Generation Checklist

Generate every file in the list below. Use reference.md for all non-trivial templates. For files marked standard, generate from Django conventions. Substitute {project_slug} (kebab-case), {project_name} (snake_case), {app_name} throughout.

Root

• manage.py — standard; DJANGO_SETTINGS_MODULE = "config.settings.local"
• pyproject.toml — update the existing file: update [project] name/description; add all [tool.*] sections from reference.md § pyproject.toml. Do NOT replace dependencies — those are managed by uv add.
• .env — reference.md § .env.example; substitute {project_name}; this is the working local file
• .env.example — same as .env (committed; no real secrets)
• .gitignore — standard Django gitignore (include .env, staticfiles/, media/, *.pyc, node_modules/, etc.)
• .pre-commit-config.yaml — reference.md § Pre-commit; omit djlint hooks for API-only (Q1=C)
• railpack.json — reference.md § Deployment: railpack.json; if Q7 has multiple languages, add gettext apt packages (reference.md § Multilingual projects)
• railway.json — reference.md § Deployment: railway.json; omit npm build step for API-only (Q1=C); if Q7 has multiple languages, add compilemessages to startCommand (reference.md § Multilingual projects)
• docker-compose.yml — reference.md § docker-compose; uncomment Redis/Celery/Flower if Q4=yes
• package.json — reference.md § package.json; full-stack and Wagtail only (Q1=A or B)
• assets/css/input.css — @import "tailwindcss";; full-stack and Wagtail only; input lives in assets/, NOT static/
• tailwind.config.js — do not generate; Tailwind v4 does not need one

config/

• config/__init__.py — import celery_app if Q4=yes (reference.md § Celery); else empty
• config/asgi.py — standard; DJANGO_SETTINGS_MODULE = "config.settings.local"
• config/wsgi.py — standard; DJANGO_SETTINGS_MODULE = "config.settings.local"
• config/celery.py — reference.md § Celery; only if Q4=yes; substitute {project_name}
• config/urls.py — reference.md § config/urls.py; include admin, allauth (if Q6=A or B), and app URLs
• config/settings/__init__.py — empty
• config/settings/base.py — reference.md § base.py; customize INSTALLED_APPS per all answers; add LANGUAGES + LOCALE_PATHS only if Q7 has more than one language
• locale/.gitkeep — only if Q7 has more than one language; empty placeholder so the directory is committed and compilemessages doesn't error on first deploy
• config/settings/local.py — reference.md § local.py
• config/settings/production.py — reference.md § production.py (use in full, do not abbreviate)

.github/

• .github/workflows/ci.yml — reference.md § GitHub Actions; add Redis service if Q4=yes

users/ (always included)

• users/__init__.py — empty
• users/apps.py — standard AppConfig; name = "users"
• users/models.py — reference.md § Authentication → users/models.py
• users/admin.py — reference.md § users app — admin.py
• users/migrations/__init__.py — empty
• users/tests/__init__.py — empty
• users/tests/factories.py — reference.md § UserFactory
• users/tests/test_users.py — reference.md § Authentication → users/tests/test_users.py
• users/views.py — empty initially

{app_name}/ (main app)

• {app_name}/__init__.py — empty
• {app_name}/apps.py — standard AppConfig; name = "{app_name}"
• {app_name}/admin.py — empty initially
• {app_name}/models.py — empty initially
• {app_name}/urls.py — empty urlpatterns list
• {app_name}/views.py — empty initially
• {app_name}/migrations/__init__.py — empty
• {app_name}/tests/__init__.py — empty

templates/ (full-stack and Wagtail only, Q1=A or B)

• templates/base.html — minimal HTML5 boilerplate; Tailwind CSS link ({% static 'css/tailwind.css' %}); HTMX script tag from static if selected ({% static 'js/htmx.min.js' %}); Alpine.js script tag from static if selected ({% static 'js/alpine.min.js' %}); {% block content %}{% endblock %}

After Generating All Files

Print a Next Steps section:

Install dependencies (run uv add for each you need):
  Core:      uv add gunicorn whitenoise dj-database-url psycopg[binary] django-environ
  Auth:      uv add django-allauth          # or django-allauth[socialaccount]
  Media:     uv add django-storages[s3] boto3
  Email:     uv add django-anymail[mailtrap]
  Monitoring: uv add sentry-sdk[django]
  API only:  uv add djangorestframework drf-spectacular djangorestframework-simplejwt django-cors-headers django-filter
  Wagtail:   already installed; add uv add django-allauth if needed
  Celery:    uv add celery[redis] django-celery-beat flower  # only if Q4=yes

Dev dependencies:
  uv add --dev django-debug-toolbar pytest pytest-django factory-boy faker coverage[toml] django-stubs[compatible-mypy] mypy pre-commit

Download static JS files (if HTMX or Alpine selected):
  curl -o static/js/htmx.min.js https://unpkg.com/htmx.org/dist/htmx.min.js
  curl -o static/js/alpine.min.js https://unpkg.com/alpinejs/dist/cdn.min.js

Setup:
  cp .env.example .env
  # Set SECRET_KEY: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"
  docker compose up -d
  uv run pre-commit install
  python manage.py migrate
  python manage.py createsuperuser

Frontend (full-stack/Wagtail only):
  npm install
  npm run dev:css   ← keep running in a separate terminal

Railway deployment — set in Railway dashboard:
  SECRET_KEY, ALLOWED_HOSTS, DJANGO_SETTINGS_MODULE=config.settings.production
  DATABASE_URL and REDIS_URL are auto-injected by Railway plugins
  SENTRY_DSN, MAILTRAP_API_TOKEN, AWS_* — set when ready