Package the canonical frontend and delete the backend fallback SPA

Status: blocked — groomed; implementation and all deletion wait for accepted integration of #150–#153
Tags: bug, migration, portal, frontend, backend, infra, testing, design, P0
Parent: #148
Depends on: #150, #151, #152, and #153 — each must be Tester-passed, PM-accepted, committed, merged/pushed to main, and through its applicable source On-Call gate
Blocks: #155
Next owner: Software Engineer only after every dependency resume condition is recorded

Scope

After #150–#153 are accepted and integrated, package top-level frontend/ into the actual SAM BackendFunction artifact and serve it as the only application shell. Fail closed when required canonical assets are missing. Only then remove backend/src/pages/, backend/src/public/, their build copies/routes, fallback branches, and implementation-specific tests.

Before deletion, complete a public-safe capability/test inventory. For every surface/action found in either UI, record legacy location, canonical location, read/mutation API, role boundary, loading/empty/validation/conflict/error/mobile behavior, legacy test, accepted replacement test/evidence, and final disposition. At minimum cover auth/session/logout, Home, Inbox, tasks/detail/proof/files/artifacts/SOP return context/waiting, workflows, templates/recurring, assistants, notifications, bookkeeping, Sponsors finance/communications, Newsletter, Calendar, mailing exports, users/roles, docs/search/edit/publish, and admin/process quality.

Acceptance criteria

Dependency-safe removal

• Tracker evidence proves Preserve canonical frontend routes and deep links #150–Port runtime template and workflow administration to the canonical frontend #153 are accepted and integrated before the first legacy source/test deletion in the Package the canonical frontend and delete the backend fallback SPA #154 candidate.
• The inventory has no unclassified, “to follow,” or silently retired capability. Any retirement requires a PM-approved issue amendment.
• Meaningful legacy tests are first replaced by behavior-level canonical assertions; only implementation/selector-specific coverage is removed.
• backend/src/pages/, backend/src/public/, compiled pages/public, direct /public/app.js and /public/api.js serving, alternate-server seams, and fallback assumptions are absent only after the replacement matrix is green.
• A repository guard fails if a second independently maintained backend HTML/JS SPA entry point is added.

Actual SAM artifact/runtime

• make sam-validate and make sam-build pass against infra/template.full.yaml.
• The verifier inspects .aws-sam/build/BackendFunction, not only backend/dist: its dist/frontend/index.html, src/app.js, and src/styles.css exist and are byte-identical to canonical source unless an explicit deterministic manifest proves a transform.
• The built SAM template/config selects that packaged path and never an adjacent checkout or alternate frontend.
• An isolated copy of the built BackendFunction runs without repository frontend/ access and serves /, extensionless SPA routes, /src/app.js, and /src/styles.css with correct content/body.
• Removing any required canonical asset from an isolated negative artifact produces a deterministic non-success configuration/asset response for page/assets and never router fall-through to another SPA.
• Path traversal and unknown static extensions return safe 404 responses; API routes keep JSON semantics and never receive SPA HTML.
• /public/app.js and /public/api.js are not served or packaged.

Paired product evidence

• Default Playwright starts the canonical source frontend; no suite boots the retired shell.
• Under the same fixed Europe/Berlin clock, stable IDs/data, disabled animation, and deterministic backend fixture, source-served and isolated SAM-artifact-served runs prove the same canonical DOM marker, URL/deep-link behavior, API results, and asset bytes.
• Paired 1440x900 and 390x844 screenshots cover Home, Inbox/detail, task proof/waiting/SOP return, workflow, assistant review with safe artifact link, structured runtime-template Admin, Sponsors, and Docs plus any other ported surface.
• Tester and Designer read every paired screenshot; no image shows a different shell, 404/error page, auth leak, overlap, clipping, horizontal overflow, missing context, or unusable mobile action.
• Screenshot similarity is supporting evidence, not a substitute for byte and behavior assertions.

Test scenarios

Scenario: Built SAM artifact is self-contained

Given: a clean make sam-build and a copy of .aws-sam/build/BackendFunction outside the source checkout
When: its compiled router serves root, deep link, JS, CSS, and authenticated/API cases
Then: all UI bytes come from the packaged canonical frontend with correct content types and behavior

Scenario: Required asset is missing

Given: an otherwise valid isolated SAM artifact with one required asset removed
When: root, deep-link, and asset requests are made
Then: each fails explicitly and no legacy HTML/JS or API-to-SPA fall-through occurs

Scenario: Legacy behavior remains covered

Given: the completed inventory and accepted #150–#153 behavior suites
When: legacy source and implementation-specific tests are removed
Then: every retained behavior still has a passing canonical test and evidence pointer

Scenario: Source/artifact parity at mobile and desktop

Given: identical deterministic fixture/state
When: representative journeys run against source and the isolated SAM artifact at 1440x900 and 390x844
Then: routes, visible states, mutations, artifact links, DOM marker, and canonical asset bytes match

Required verification

• npm --prefix backend test
• npm --prefix backend run typecheck
• npm --prefix backend run build
• npm --prefix backend run test:e2e
• The issue's artifact verifier against both backend/dist and the actual .aws-sam/build/BackendFunction
• make sam-validate
• make sam-build
• A post-make sam-build isolated SAM-runtime positive/negative test
• Tester reports commands, exit codes, counts, inventory result, and evidence paths.
• Architect reviews packaging/fail-closed/auth boundaries; Designer reviews paired screenshots; then Tester and PM gates run.

Lifecycle gates

• Preserve canonical frontend routes and deep links #150 accepted and integrated
• Port Inbox and intake lifecycle to the canonical frontend #151 accepted and integrated
• Port assistant job lifecycle to the canonical frontend #152 accepted and integrated
• Port runtime template and workflow administration to the canonical frontend #153 accepted and integrated
• Software Engineer implementation, uncommitted
• Architecture PASS
• Designer PASS with paired screenshot findings
• Tester PASS with commands, exit codes, counts, matrix, and paired evidence
• PM ACCEPTED
• Software Engineer commit with Closes #154
• Orchestrator local merge and push
• On-Call source CI/CD PASS
• Verify the canonical frontend through normal DataOps deployment #155 owns deployed/HUMAN acceptance; Migrate Sponsor CRM GSIs in a protected stage-only workflow #136/Reconcile Sponsor CRM table ownership with CloudFormation #143 do not block local Package the canonical frontend and delete the backend fallback SPA #154 work once dependencies are integrated

Prototype handoff

Reimplement/rebase the issue-148 portal/router/package/template changes only after #150–#153 integrate. The existing artifact verifier validates backend/dist and manually selected frontend paths but does not gate the actual SAM BackendFunction. Its bulk deletion of legacy UI/unit/E2E files is premature and must not be committed. The capability matrix and paired screenshots are research inputs, not accepted lifecycle evidence.

Rollout and rollback

Rollout remains the normal accepted-commit → local merge → push-main → GitHub Actions OIDC path. Do not call AWS, manually deploy, dispatch workflows, or bypass deployment guards. #155 performs deployed acceptance when the existing blockers permit it. Rollback is a normal source revert through the same pipeline, never a runtime fallback switch.

Out of scope

• Implementing Preserve canonical frontend routes and deep links #150–Port runtime template and workflow administration to the canonical frontend #153 inside this cutover issue.
• Broad visual/IA redesign.
• Manual application deployment or AWS mutation.
• Changes to source repos outside dataops.