Skip to content

Preserve canonical frontend routes and deep links #150

Closed
Closed
Preserve canonical frontend routes and deep links#150
Labels
P0Must havedesignDesign and UXenhancementNew or improved functionalityfrontendFrontend UIportalShared portal shell and UXtestingTests and QA

Description

@alexeygrigorev
alexeygrigorev
opened on Aug 11, 2026

Preserve canonical frontend routes and deep links

Status: pending — groomed and ready for implementation
Tags: enhancement, portal, frontend, testing, design, P0
Parent: #148
Depends on: None
Blocks: #151, #152, #153, and #154
Next owner: Software Engineer

Scope

Implement one hash-route adapter in top-level frontend/. It must translate supported legacy URLs into canonical workspace surfaces and open entity context after the required data loads. It must not add another shell, framework, backend SPA router, or browser bearer-token path.

The supported route matrix is:

Route Required context
#/ Home
#/inbox?intakeId=<id> Inbox and matching intake detail
#/tasks?taskId=<id>&date=<date>&bundleId=<id>&contextBundleId=<id> Tasks and the requested task/context
#/bundles?bundleId=<id>&taskId=<id> Workflow detail and optional task
#/assistants?assistantJobId=<id> Assistant list/detail
#/templates?templateId=<id> Templates and matching template
#/recurring Recurring work
#/notifications Notifications
#/bookkeeping Bookkeeping
#/sponsors?bookingId=<id> Sponsors and matching booking
#/newsletter Newsletter
#/calendar Calendar
#/mailing-exports Mailing exports

Internal task, workflow, intake, assistant, sponsor, notification, and search-result links must write the same canonical URLs. Back/forward and hashchange must restore the matching UI state.

Acceptance criteria

  • Direct navigation and refresh resolve every route in the matrix without a second page shell.
  • Entity parameters are decoded safely and open the correct detail only after its data is available; stale/not-found IDs show an honest recoverable state rather than silently opening a different record.
  • In-app links, browser back/forward, and hash changes preserve the visible surface and entity context.
  • Unknown or malformed hashes normalize to Home, preserve the authenticated session, and never interpolate untrusted route content as HTML.
  • Signed-out page navigation still uses the shared browser login flow; API requests still return JSON 401 and never SPA HTML.
  • Route behavior is covered by executable unit/browser assertions against visible state and URLs, not source-string marker tests.
  • At 1440x900 and 390x844, representative list/detail deep links have no overlap, clipping, horizontal overflow, or unreachable close/back action.
  • No legacy router/assets are deleted in this issue.

Test scenarios

Scenario: Direct entity deep link

Given: deterministic task, workflow, intake, assistant job, template, and sponsor-booking fixtures
When: each entity URL is opened in a fresh authenticated browser page
Then: the canonical surface loads and opens exactly the requested record after data loading

Scenario: Browser navigation

Given: Home, Inbox detail, task detail, and workflow detail have been visited
When: the operator uses Back, Forward, and an in-app relationship link
Then: URL and visible surface/detail stay synchronized without reload-only behavior

Scenario: Invalid route or entity

Given: an unknown hash, malformed encoded parameter, or missing entity
When: the route adapter resolves it
Then: unknown routes return safely to Home and missing entities show a recoverable not-found state without losing auth

Scenario: Mobile deep link

Given: a 390x844 viewport and a direct detail route
When: data finishes loading
Then: the target context is visible, navigation/close controls remain reachable, and the document does not overflow horizontally

Required verification

  • Focused route-adapter unit tests.
  • Deterministic Playwright route-matrix and browser-history tests against the canonical source frontend.
  • npm --prefix backend test
  • npm --prefix backend run typecheck
  • npm --prefix backend run test:e2e
  • Tester screenshots under .tmp/screenshots/issue-150/ at 1440x900 and 390x844, read by Tester.
  • Architect reviews the route/auth boundary; Designer reviews both viewport states; then Tester and PM gates run.

Lifecycle gates

  • Software Engineer implementation, uncommitted
  • Architecture PASS
  • Designer PASS with screenshot findings
  • Tester PASS with commands, exit codes, counts, and screenshots
  • PM ACCEPTED
  • Software Engineer commit with Closes #150
  • Orchestrator local merge and push
  • On-Call source CI/CD PASS

Prototype handoff

The current .tmp/worktrees/issue-148 candidate has navigation buttons but no hash/deep-link contract. Reimplement #150 in a fresh child worktree; do not cherry-pick the monolithic candidate.

Out of scope

Activity

  1. alexeygrigorev
    added
    enhancementNew or improved functionality
    portalShared portal shell and UX
    frontendFrontend UI
    testingTests and QA
    P0Must have
    designDesign and UX
    on Aug 11, 2026

  2. alexeygrigorev commented on Aug 11, 2026

    @alexeygrigorev
    alexeygrigorev
    on Aug 11, 2026
    MemberAuthor

    PM GROOMING PASS

    #150 is now self-contained and is the only currently implementable #148 child. The route/entity matrix, auth/error semantics, behavior tests, desktop/mobile evidence, Architecture/Designer/Tester/PM gates, and prototype disposition are explicit.

    Next owner: Software Engineer in a fresh #150 worktree. Reimplement the adapter; the monolithic issue-148 candidate contains no acceptable route implementation.

  3. alexeygrigorev commented on Aug 11, 2026

    @alexeygrigorev
    alexeygrigorev
    on Aug 11, 2026
    MemberAuthor

    Orchestrator launch pause — active dirty main

    PM grooming makes #150 the only eligible frontend child, but the required clean-main check found an actively changing, uncommitted monolithic frontend-convergence batch in the primary checkout. A read-only audit observed the dirty set grow during inspection and found partial work spanning #150–#154, including premature fallback/test deletion. Ownership is not proven and unique work exists outside the preserved #148 donor.

    Per _docs/PROCESS.md, no #150 worktree will be launched and no stash/reset/stage/merge will occur while that writer is active.

    Resume condition: the current owner identifies and finishes/preserves/discards the batch; no writer remains; main is clean with freshly verified HEAD == origin/main; then launch #150 alone from a fresh worktree while preserving fallback assets/tests. #151–#154 remain dependency-blocked.

    No source mutation, commit, push, workflow dispatch, or AWS call occurred.

  4. alexeygrigorev commented on Aug 11, 2026

    @alexeygrigorev
    alexeygrigorev
    on Aug 11, 2026
    MemberAuthor

    Implemented directly on current main per the explicit 2026-08-11 user override of the role-agent lifecycle. Commit e904a5d preserves the legacy hash-route matrix and task/workflow/intake/assistant entity parameters inside the canonical shell. Canonical route and deep-link Playwright coverage passes. Closing the source task; deployed verification remains #155.

  5. alexeygrigorev
    closed this as completedon Aug 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P0Must havedesignDesign and UXenhancementNew or improved functionalityfrontendFrontend UIportalShared portal shell and UXtestingTests and QA

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions