weirsoe-party-protocol/docs/plans/2026-03-18-mvp-deployable-testable-plan.md

MVP Plan — Deployable and Testable Repository

Date: 2026-03-18
Status: In progress

Goal

Get the repository into a state where one person can deploy it to staging or a local VM, run one documented setup flow, and verify one full playable round through the intended UI without ad hoc fixes.

For this plan, deployable and testable means:

• backend boots with documented env vars
• frontend assets build successfully
• one UI path is designated as the MVP path
• a development docker compose setup exists for the app and its required services
• CI covers the checks needed to trust a release candidate
• a smoke flow proves host + 3 players can complete one full round

Current Baseline

Verified on 2026-03-18:

• manage.py check passes
• manage.py test lobby fupogfakta passes
• npm --prefix frontend test passes
• npm --prefix frontend run build passes
• npm --prefix frontend/angular test passes
• npm --prefix frontend/angular run build fails

Main blockers observed:

1. Angular production build fails on strict template nullability in host/player reveal panels.
2. shared/i18n/lobby.json contains duplicate keys and produces build warnings.
3. The repo still has two UI modes (USE_SPA_UI ON/OFF), so the MVP “real path” is ambiguous.
4. CI does not yet enforce the full MVP gate.

Progress Snapshot

Implemented on 2026-03-18:

• legacy UI (USE_SPA_UI=false) is the explicit MVP path
• Angular build and test pipeline passes
• duplicate shared i18n keys were removed and drift is checked
• development docker compose exists for Django + MySQL + Redis
• local deterministic bootstrap is available via python manage.py bootstrap_mvp
• local release verification is available via ./scripts/verify_mvp_release.sh
• staging deploy + smoke wrappers exist via infra/staging/deploy_and_smoke_staging.sh

Remaining MVP sign-off item:

• run the real staging deploy + smoke flow and record the resulting artifact

Plan

Batch 1 — Make the chosen UI path buildable

• Decide the MVP runtime path:
  • Current choice: legacy UI (USE_SPA_UI=false)
  • SPA remains a follow-up cutover path after the MVP release gate is stable
• Fix Angular template errors in frontend/angular/src/app/features/host/host-shell.component.ts and frontend/angular/src/app/features/player/player-shell.component.ts.
• Remove duplicate i18n keys in shared/i18n/lobby.json.
• Require these checks to pass locally:
  • npm --prefix frontend/angular test
  • npm --prefix frontend/angular run build

Batch 2 — Make local/staging setup deterministic

• Add one documented bootstrap path for:
  • backend venv install
  • database migrate
  • host user creation
  • sample category/question seed
• Create a development docker compose file that can start the services needed for local work:
  • Django app
  • MySQL or the chosen dev database
  • Redis for Channels
  • optional frontend dev server if the team wants one-command startup
• Ensure the compose setup matches the documented env var contract and supports the chosen MVP UI path.
• Keep SQLite acceptable for local try-out; keep MySQL/Redis for staging.
• Document the exact env vars and USE_SPA_UI setting required for the MVP path.

Batch 3 — Make smoke verification release-grade

• Treat one canonical smoke as required:
  • create session
  • 3 players join
  • start round
  • submit lies
  • submit guesses
  • reveal
  • scoreboard
  • next round or finish
• Keep python manage.py smoke_staging --artifact <path> as the canonical backend smoke entrypoint.
• Provide one staging wrapper command that chains deploy + MVP smoke for release candidates.
• Add one short manual UI smoke checklist for the chosen MVP path only.

Batch 4 — Align CI with MVP readiness

• Expand CI to run:
  • python manage.py check
  • python manage.py test lobby fupogfakta
  • npm --prefix frontend test
  • npm --prefix frontend run build
  • npm --prefix frontend/angular test
  • npm --prefix frontend/angular run build
• Update lint scope so it no longer only checks lobby/.
• Provide one local wrapper command for the same MVP gate before staging deploy.

Batch 5 — Freeze the MVP boundary

• Declare which items are required for MVP and which are explicitly deferred.
• Defer non-blockers:
  • broader game-driver redesign
  • extra cartridges
  • polished host presentation UX
  • voice integration
  • post-game awards or richer reactions

Definition of Done

The repo is MVP-deployable and testable when all of the following are true:

• one UI path is explicitly marked as the MVP path
• Angular production build passes for that path
• a development docker compose setup can bring up the required local dependencies
• staging deploy docs match the code and env flags
• CI enforces the same checks used for release sign-off
• one full smoke round passes through host/player UI and is captured as evidence

Recommended Order

1. Fix Angular build blockers and i18n duplication.
2. Choose SPA ON or legacy as the single MVP runtime path.
3. Add the development docker compose setup.
4. Write the bootstrap/setup doc and seed flow.
5. Expand CI to the full MVP gate.
6. Re-run staging smoke and record the artifact.