Helm

A full-stack product-management application based on the Product Backlog Web Application reference specification.

Stack

• React + TypeScript + Vite
• Django 5 + Django REST Framework
• PostgreSQL
• Docker Compose

Implemented

• Responsive application shell and client-side routes
• Dashboard summary, recent activity, priority work, and Epic progress
• Searchable/filterable Product Backlog
• PBI detail, create, edit, delete, and archive API action
• Dynamic Hypothesis, Requirement, and Technical PBI fields
• Acceptance criteria, PBI dependencies, and references
• Epic list/cards with derived progress
• Epic detail, create, edit, delete, and archive API action
• Epic dependencies and associated-PBI navigation
• DRF filtering, search, ordering, validation, and dashboard aggregation
• PostgreSQL persistence and Docker Compose development environment
• Backend API test suite source

Run with Docker

docker compose up

Open http://localhost:5173. The API is at http://localhost:8000/api/v1/.

Seed optional demonstration data:

docker compose exec backend python manage.py seed_demo

Run without Docker

Backend:

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# configure PostgreSQL environment variables
python manage.py migrate
python manage.py runserver

Frontend:

cd frontend
npm install
npm run dev

Tests

A DRF API test suite is included in backend/backlog/tests.py. For a lightweight SQLite test run:

cd backend
USE_SQLITE=1 python manage.py test backlog

Current product boundary

The specification's core MVP is now represented in the codebase: Dashboard, Backlog, PBI CRUD, Epic CRUD, three PBI types, acceptance criteria, search/filtering, and persistent API/database storage. Settings remains intentionally deferred because the specification says to add it only when there is a real setting to manage.

The next major decisions are product-level rather than routine implementation: authentication/multi-user behavior, collaboration features, release/sprint planning, and production deployment target.

Milestone 5

The application is intentionally single-user/personal for now; authentication and multi-user ownership remain deferred. A Kanban workflow view is available at /kanban. It displays active PBIs in Backlog, Ready, In Progress, Blocked, and Completed columns. Cards can be dragged between columns and the new PBI status is persisted through the DRF API. Type, priority, and Epic filters are available on the board.

Milestone 6 — Quality and refinement

• Added an API health endpoint at /api/v1/health/.
• Expanded backend API coverage for health, type-specific validation, filtering/search/ordering, archiving, Epic progress, and dashboard archive behavior.
• Added a keyboard-accessible status selector to every Kanban card so drag-and-drop is not the only way to move work.
• Added visible keyboard focus treatment and reduced-motion support.
• Added Backlog sorting for recent updates, title, and priority.
• Added PostgreSQL health checking and startup dependency handling to Docker Compose.
• Made allowed hosts and CORS origins environment-configurable.

The product remains intentionally personal/single-user. Authentication, collaboration, and permissions are still deferred.

Milestone 7 — Hardening & deployment preparation

This milestone keeps the product intentionally single-user while hardening the implementation:

• DRF page-number pagination with bounded page sizes.
• Frontend API collection adapter that preserves existing UI contracts while accepting paginated DRF responses.
• Structured ApiError objects for better future field-level error presentation.
• React error boundary for unexpected render failures.
• Production-oriented backend and frontend Dockerfiles.
• Nginx SPA hosting and /api/ reverse proxy configuration.
• Gunicorn application server for production containers.
• Separate docker-compose.prod.yml for a production-like local deployment.
• Additional pagination API coverage.

Production-like local run

Copy .env.example to .env, replace the development secret/password values, then run:

docker compose -f docker-compose.prod.yml up --build

The application is served at http://localhost:8080 in this configuration.

Authentication remains intentionally deferred because this is currently a personal application. Do not expose the app directly to the public Internet without adding an access-control layer and HTTPS.

Milestone 8 — Lifecycle, CI, and data safety

• Added Archive controls to PBI and Epic detail screens so routine lifecycle management does not require destructive deletion.
• Added reusable DRF error-message extraction for clearer API validation failures.
• Added Woodpecker CI for the Django test suite and React/TypeScript production build.
• Added a Makefile for common development, test, production, backup, and restore commands.
• Added PostgreSQL backup/restore scripts for the personal application's data.

Useful commands:

make dev
make test-backend
make build-frontend
make backup
make restore FILE=backups/product-backlog-YYYYMMDD-HHMMSS.sql

Backups contain the application's database data and should be stored with the same care as the live database.

Milestone 9 — Secure operational MVP, planning, and analytics API

This is the stopping point for the requested MVP feature scope.

Security

All application API endpoints except /api/v1/health/ now require DRF token authentication. Create the personal owner account after first startup:

docker compose exec backend python manage.py createsuperuser

The web app has a sign-in screen. It exchanges the username/password for a DRF token at POST /api/v1/auth/token/; subsequent requests use Authorization: Token <token>. Sign out removes the token from browser storage.

Production requirement: serve the application only over HTTPS. The included Nginx container is an application reverse proxy, not a public TLS configuration. Put it behind a trusted HTTPS reverse proxy/load balancer, set strong random DJANGO_SECRET_KEY and PostgreSQL credentials, and enable DJANGO_SECURE_COOKIES=1, DJANGO_SECURE_SSL_REDIRECT=1, and DJANGO_BEHIND_HTTPS_PROXY=1 when HTTPS forwarding is configured correctly. Keep the database private to the Compose network and do not publish PostgreSQL directly.

Sprints and releases

The application now supports first-class Sprints and Releases, with a /planning UI for creating them. PBIs have optional sprint and release foreign keys.

REST resources:

• GET/POST /api/v1/sprints/
• GET/PATCH/DELETE /api/v1/sprints/{id}/
• GET/POST /api/v1/releases/
• GET/PATCH/DELETE /api/v1/releases/{id}/
• POST /api/v1/releases/{id}/mark_released/
• PBI filtering: /api/v1/pbis/?sprint={id} and /api/v1/pbis/?release={id}

Analytics-ready APIs

The API exposes normalized operational data plus aggregate endpoints suitable for a BI/analytics client:

• GET /api/v1/analytics/overview/ — completion rate, average cycle time, status/type/priority distributions
• GET /api/v1/analytics/throughput/?days=30 — daily completed-PBI throughput (1–365 days)
• GET /api/v1/analytics/sprints/ — sprint progress/count metrics
• GET /api/v1/analytics/releases/ — release progress/count metrics
• GET /api/v1/pbis/{id}/history/ — status transition history
• Core resources remain queryable/filterable under /api/v1/pbis/, /epics/, /sprints/, and /releases/

A completed_at timestamp and PBI status-event history are now captured so analytics are based on explicit lifecycle data instead of inferring completion from updated_at.

MVP boundary

The requested operational MVP now stops at: personal authentication, Product/Epic/PBI management, table and Kanban execution, Sprint/Release planning, analytics-ready REST APIs, PostgreSQL persistence, backups, CI, tests, and production-oriented containers. Collaboration, comments, attachments, notifications, roadmaps, and complex permissions remain out of scope.

Rebuilt Helm project

Project directory and Compose project name: helm-project. Application name: Helm. The backend WSJF migration 0003 is retained; the editor, detail screen and backlog sorting now expose WSJF. Unscored work sorts last, with PBI ID as the tie-breaker.

Data safety and Genesis installation

This source archive contains no live database or .env. The new Compose project uses its own helm-project_postgres_data volume, so it will initially have an empty database. Do not delete the original Compose project or its volumes. Back up the old database before migrating any data.

1. Extract this archive alongside the original project, not over it.
2. Copy .env.example to .env and configure unique strong secrets and the correct allowed hosts. Do not paste secrets into chat.
3. Run sudo docker compose config, then sudo docker compose up -d --build. Development frontend is on port 5173, backend on host port 8080. Stop the original stack first if these ports are occupied, without deleting volumes; or adjust the published ports for a parallel test.
4. Run sudo docker compose exec backend python manage.py check and sudo docker compose exec backend python manage.py test.
5. For production-like Compose, sudo docker compose -f docker-compose.prod.yml up -d --build serves on port 8081 by default. It still requires a properly configured HTTPS reverse proxy for remote production access.
6. Verify login, existing data after a separately planned restore, PBI editing, WSJF persistence, sorting and backups before retiring the original deployment.

The original source's README may mention historical milestones; verify functionality in the running rebuilt app.