gizmoduck/docs/superpowers/plans/2026-09-06-application-skeleton.md

Application Skeleton Implementation Plan

Goal: Execute the approved application skeleton design. Spec: Design. Architecture: Compose services separate runtime, migration, and test access. Stack: Python 3.13, Django 5.2, PostgreSQL 17, uv and pytest.

• Create locked dependency configuration, Docker image, and minimal Django configuration. Add health success/failure tests and observe failure before implementing the endpoint.
• Provision development database roles using initialization scripts; run migrations explicitly. Run pytest on an isolated PostgreSQL test service.
• Add runtime permission checks using rolled-back synthetic rows and denied DDL/role escalation. Verify the real database grants.
• Document setup and existing-volume behavior, verify HTTP startup, migration drift, system checks, and secret exclusions. Review all changes before completion.

Files: config/, core/, tests/, docker/postgres/, manage.py, pyproject.toml, uv.lock, Dockerfile, .dockerignore, compose.yaml, .env.example and README.md. No financial models or real data. Application startup never runs migrations. Verification commands: docker compose config --quiet; docker compose build; docker compose run --rm manage migrate; docker compose run --rm test; docker compose run --rm permissions; docker compose run --rm manage check; docker compose run --rm manage makemigrations --check --dry-run; docker compose run --rm manage migrate --check; request localhost:8000/health/.

Verification results (2026-09-06)

• Locked Docker build succeeded; Django 5.2.17 installed under Python 3.13.
• Three pytest tests passed against isolated PostgreSQL, including HTTP success, generic database failure, and missing-secret validation.
• Fourteen built-in migrations applied on a fresh development volume; system checks passed and no pending or missing migrations were detected.
• Runtime permission checks passed for DML, sequences, denied DDL, role escalation, and privileged role attributes.
• Actual HTTP readiness returned 200; a separate container with an unreachable database returned generic 503 without connection details.
• Independent review identified a temporary-server readiness race. Both database healthchecks now require TCP. Fresh-volume migrations, permissions and tests passed again in the isolated gizmoduck-skeleton-verify Compose project.
• Verification-project containers are stopped; its synthetic database volume is retained. The main local application remains running.
• Documentation links, whitespace, and candidate files were checked for local secret values. Existing foundation changes remain uncommitted with this work.