Trucking Planning Module

This repo currently contains the Wave 1 to Wave 3 design docs plus the first implemented Set 5 backend foundation, frontend application shell, and first planner-facing trucking workspace for a Docker-first demand-planning runtime.

Current Scaffold Scope

The following are scaffolded now:

• Docker Compose local development runtime
• Django project bootstrap
• modular Django app package scaffold under backend/trucking_apps
• shared abstract model foundation for UUID and timestamp patterns
• foundational master-data models for locations, truck types, SKUs, and reason codes
• initial app migrations for masters_config and audit_governance
• Postgres wiring
• built-in Django admin route at /admin/
• narrow Django admin registration for the foundational master-data entities
• Next.js plus Tailwind application shell foundation under frontend/
• custom trucking permission declarations and baseline role-group bootstrap command
• canonical planning_batch and planning_input_snapshot header persistence in planning_inputs
• canonical plan_run and plan_version header persistence in truck_planning
• planning-operation persistence, admin visibility, and placeholder worker orchestration seam
• bounded JSON service/API seams for plan summary, route detail, operation status, override, clear, submit, approve, and reopen
• compact demand-planning shell with left sidebar, thin header, main workspace stage, right context rail, and generic module routes
• trucking mounted as the first live module inside the shell with route-aware breadcrumb context and a bounded workspace container
• trucking draft-review workspace bound to real run/version/snapshot headers and latest operation status where available
• planner control invocation wiring for truck override, non-critical clear, submit, approve, and reopen against the bounded backend seams
• local dev trucking workspace bootstrap command and frontend-to-backend dev proxy bridge for the Docker stack
• deterministic local trucking seed loader, seed-context inspection command, and compact dev-session switcher for planner/approver/viewer/admin E2E review
• health endpoint at /healthz/
• worker runtime loop wired to placeholder planning-operation processing

The following are not implemented yet:

• route masters, snapshot detail-line tables, full plan-content tables, and action ledgers
• actual planning jobs and canonical planning API behavior
• lower-level route, truck, stop, pickup, delivery, load, and breach-detail content
• RBAC scope enforcement and planner-facing permission checks

Execution Contract

Read agent.md first for repo execution rules.

For material work, the required read order is:

1. agent.md
2. README.md
3. docs/README.md
4. Wave 1 governance and architecture baseline
5. Wave 2 contracts, lifecycle, RBAC, and app-boundary docs
6. Wave 3 logical-model, API, orchestration, rollout, and sequencing docs
7. only then the runtime or code files relevant to the current chunk

Material work must stop at chunk boundaries with validation and runtime-state reporting.

F:\trucking remains read-only source evidence only.

Local Runtime

Use the local development stack with the explicit env-qualified compose command:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.frontend.yml up -d --build

Stop the stack with:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.frontend.yml down

View logs with:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml logs app

Frontend logs:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.frontend.yml logs frontend

Runtime Endpoints

• frontend base: http://localhost:3000/
• app base: http://localhost:18080/
• health: http://localhost:18080/healthz/
• admin: http://localhost:18080/admin/
• Postgres host port: localhost:15432

Frontend Runtime

The application shell is part of the Docker stack. Do not install frontend dependencies locally and do not run npm run dev from the host repo.

Start the stack with:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.frontend.yml up -d --build

Frontend shell routes now available from the container:

• http://localhost:3000/planning/trucking
• http://localhost:3000/planning/demand
• http://localhost:3000/planning/buffer-health
• http://localhost:3000/planning/rebalancing
• http://localhost:3000/operations/execution
• http://localhost:3000/operations/exceptions
• http://localhost:3000/governance/master-data
• http://localhost:3000/governance/policy

The top header now exposes a compact local Session selector when multiple seeded dev users are configured. Use it to switch between planner, approver, viewer, and admin identities for local end-to-end review.

Admin Bootstrap

Create a superuser after the stack is up:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py createsuperuser

Validation Commands

Check compose rendering:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml config

Check Django startup inside the container:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py check

Apply migrations inside the container:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py migrate

Preview RBAC group bootstrap changes:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py bootstrap_trucking_rbac --dry-run

Apply RBAC group bootstrap:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py bootstrap_trucking_rbac

Bootstrap the bounded local dev trucking workspace:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py ensure_dev_trucking_workspace

Seed the deterministic local trucking E2E dataset:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py seed_trucking_e2e

Inspect the current seeded run, users, and workflow context:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py show_trucking_seed_context

Queue a placeholder planning operation:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py enqueue_planning_operation draft_generation --requested-by admin --idempotency-key local-demo

Run one worker iteration on demand:

docker compose --env-file .env.dev.local -f docker-compose.yml -f docker-compose.dev.yml exec app python manage.py run_planning_worker --once --max-operations 1

Scaffolded API surfaces now available:

• GET /api/trucking/workspace/
• GET /api/plan-runs/{run_id}/plan-summary/
• GET /api/plan-runs/{run_id}/working-plan/
• GET /api/plan-versions/{version_id}/routes/{route_plan_id}/
• GET /api/operations/{operation_id}/
• POST /api/plan-runs/{run_id}/truck-availability-overrides/
• POST /api/plan-versions/{version_id}/non-critical-clear/
• POST /api/plan-versions/{version_id}/submit/
• POST /api/plan-versions/{version_id}/approve/
• POST /api/plan-versions/{version_id}/reopen/

These surfaces are still intentionally bounded. The trucking workspace bootstrap now resolves the latest canonical run plus the current planner-facing plan summary and latest operation status. Plan summary resolves real run, snapshot, and version headers. Operation status resolves canonical run and version identity where available. Submit, approve, and reopen terminate into real plan_run and plan_version header transitions. Route, truck, stop, pickup, delivery, load, breach-detail, approval-decision, and action-ledger content remains scaffold-only.

Local E2E Playbook

For deterministic seed data, local users, and the repeatable trucking walkthrough, use:

• docs/set5_chunk8_e2e_seed_playbook.md

Next Chunk

Set 5’s bounded chunk sequence is now complete through the optional workflow shell integration. Any next instruction should move into a new set or a separate seed-data / end-to-end enablement task rather than extending Set 5 implicitly.