- Refresh the route inventory for the current shell
- Capture the renamed and split pages: search, watchlist, wishlist, active-downloads, and tools
- Update the migration waves and platform unlock notes to match the current app
- This document inventories the current hybrid WebUI shell and recommends an incremental migration order from legacy vanilla-JS rendering to the Vite + React + TanStack Router app.
- The canonical shell route list currently contains 15 page IDs in `webui/src/platform/shell/route-manifest.ts`.
- Only `issues` is React-owned today. Every other route is still rendered by the legacy shell, primarily through `webui/static/script.js`, `webui/index.html`, and the global stylesheet.
- The recommended order optimizes for low-risk wins first while still calling out a few high-value platform unlocks for later waves.
- The shell route manifest now has 18 page ids.
- `issues` is still the only React-owned route.
- Since the last snapshot, the biggest changes are:
- `downloads` was renamed into `search`.
- The live queue became `active-downloads`.
- `watchlist` and `wishlist` became full sidebar pages.
- `tools` was split off from `dashboard`.
- `artists` is no longer a route id.
- The shell is also more modular now. The old monolithic `script.js` has been split across `core.js`, `init.js`, `shared-helpers.js`, and feature modules such as `search.js`, `api-monitor.js`, `pages-extra.js`, `stats-automations.js`, and `wishlist-tools.js`.
- Current profile compatibility still normalizes old `downloads` and `artists` references to `search`, so the docs and the route ids are not always using the same historical language.
## What Changed Since The Last Snapshot
- `search` is now the canonical route for the old download/search experience.
- `active-downloads` owns the dedicated live queue that used to sit inside the search flow.
- `watchlist` and `wishlist` moved out of dashboard-era chrome and into their own routes.
- `tools` moved off the dashboard into a dedicated sidebar page.
- `dashboard` is a bit narrower now, because several operational surfaces were split out.
- `artist-detail` is still a first-class route, but its permission relationship is now tied to `library` and `search`, not to an `artists` page.
- The contextual help system still contains some historical `downloads` and `artists` wording, so those labels should be treated as legacy text rather than route ids.
## Current Architecture
- `webui/index.html` is still the Flask-served shell. It owns the sidebar, media player, global overlays, and legacy `.page` containers for every non-React page.
- `#webui-react-root` is the single React mount point. It is treated like a shell page and becomes active when the current route belongs to React.
- `webui/static/script.js` is still the main rendering coordinator:
- route activation and page switching
- shell bridge exposure via `window.SoulSyncWebShellBridge`
- `loadPageData()` dispatch for nearly every legacy route
- page-local state, global shell state, polling, and many modal/workflow implementations
- TanStack Router delegates legacy pages back to the shell through `webui/src/routes/$.tsx` and `LegacyRouteController`, while React routes use `useReactPageShell()` to set shell chrome and show the React host.
- `issues` is the reference migration pattern:
- canonical route ownership lives in `route-manifest.ts`
- route UI lives under `webui/src/routes/issues/`
- React owns route rendering, data loading, and detail modal behavior
- the shell still owns route gating, nav chrome, and the page host
- HTML `.page` containers exist for every shell page except `issues`.
- `issues` is the only route that resolves through the React host instead of a legacy `.page` container.
- `artist-detail` is a first-class route in the manifest and HTML, but it behaves like an extension of `library`, not a truly independent feature area.
- `webui/index.html` still hosts the Flask-rendered shell, the sidebar, the media player, the legacy `.page` containers, and the React mount point.
- `webui/static/core.js` now holds a lot of the shared global state that used to live in the old monolith.
- `webui/static/init.js` still owns page activation, permission gating, nav highlighting, legacy routing, and the `window.SoulSyncWebRouter` bridge.
- `webui/static/shell-bridge.js` and the TanStack Router adapter still decide whether a route is handled by the React host or handed back to the legacy shell.
- `issues` remains the reference pattern for React-owned pages: route manifest ownership, shell bridge integration, route-local data loading, and detail-modal behavior all live in the React subtree.
- The legacy shell is now spread across feature modules rather than one giant coordinator file, which makes the migration seams a little clearer than they were a month ago.
- `downloads` and `artists` are no longer manifest ids.
- HTML `.page` containers exist for every legacy page plus `webui-react-root` for React.
- `watchlist`, `wishlist`, and `active-downloads` are now standalone route targets instead of dashboard overlays.
- `tools` is now a dedicated page, so dashboard can be treated as a monitoring hub instead of the one-stop maintenance surface.
- `help` and `issues` remain always-allowed for non-admins.
- `settings` remains admin-only.
- `artist-detail` is allowed when the profile can access `library` or `search`.
## Cross-Cutting Features
These features are not owned by one page, but they affect migration scope, shell contracts, and ordering.
- Profile and permission routing
- Owned in `script.js` profile initialization and `isPageAllowed()` logic.
- Controls route gating, home-page redirects, admin-only settings, and the special `artist-detail -> library` permission relationship.
- Sidebar and shell chrome
- Nav highlighting, page activation, global search visibility, discover sidebar visibility, and route-path synchronization all stay shell-owned today.
- Any route migration must preserve these shell behaviors through the bridge rather than re-implementing them per route.
- Media player and queue
- The sidebar player, expanded player, queue, streaming preview, and media-session integration live outside page boundaries.
- Several pages launch playback or update queue state, so migration work has to preserve these entry points.
- WebSocket and polling infrastructure
- Socket.IO initialization is global.
- Many pages depend on active-process polling, sync/discovery polling, worker status polling, wishlist/watchlist polling, or progress refresh loops.
- Pages with heavy polling or live progress are materially riskier to migrate.
- Helper and docs systems
- `webui/static/docs.js` owns the Help page content.
- `webui/static/helper.js` owns contextual help, tours, setup flows, and page-specific selector metadata across the app.
- The Help page itself is easy to migrate, but the helper system is cross-cutting and should remain shell-owned until route migrations are further along.
- Visual shell effects
- `particles.js` and `worker-orbs.js` are shell/global effects.
- `worker-orbs.js` is dashboard-specific but mounted globally.
- These are low priority to migrate and should be treated as shell integrations unless a page migration explicitly needs to absorb them.
- Profile and permission routing still live in the shell bootstrap.
- Shell chrome and nav highlighting are still shared shell responsibilities.
- Media player behavior, queue handling, and global overlays still cut across multiple pages.
- Socket/WebSocket and polling behavior remain the biggest migration risks for live pages.
- The help system, tours, and helper annotations still reference some historical route names, so route-migration work should use the manifest as the source of truth.
- Visual effects such as `particles.js` and `worker-orbs.js` remain shell-global.
- Main surface: search/results/detail view switching inside one route, artist caching, discography snippets, similar artists, watchlist interactions, download bubbles
- Coupling: media player, queue, settings-derived source configuration, modal reuse across other pages
- Blockers or prerequisites: shared result-card, album-detail, and mutation-state primitives would help, but they do not have to exist before migration starts
- Scores: `4 / 4 / 4 / 3 / 4`
- Rationale: feature-rich and mutation-heavy, but valuable once the app already has a few safer route wins
- Recommendation: migrate only after help/hydrabase/stats/import/artists establish a stable pattern
- Main surface: activity feed, service cards, worker buttons, backup manager, metadata cache, history modals, repair dashboard, recent sync history
- Async behavior: high polling density, worker status updates, activity feed refresh, backup and maintenance actions
- Coupling: almost every cross-cutting system eventually surfaces here
- Blockers or prerequisites: keep worker-orb visuals and global helper affordances shell-owned; route migration should focus on dashboard content first
- Scores: `4 / 4 / 4 / 4 / 4`
- Rationale: central page with broad read/write coverage and high shell entanglement
- Recommendation: treat as a mid-program migration, not an opening move
- Main surface: five-tab admin settings area, API/service credentials, media server setup, download source and quality config, file organization, appearance, advanced settings, profile/security integration, API keys
- Async behavior: large form hydration, auto-save, many service auth/test flows, dynamic source-specific form sections, media-library selectors
- Coupling: almost every other page depends on settings-derived behavior or stored configuration
- Blockers or prerequisites: route migration should be delayed until the app has settled conventions for large forms, auth/test actions, and configuration write flows
- Scores: `5 / 5 / 4 / 5 / 5`
- Rationale: the biggest shell container in `index.html` and one of the most globally coupled feature areas
- Recommendation: late migration despite the lack of constant polling, because the blast radius is large
- Coupling: uses many domain concepts but is less shell-dependent than settings or sync
- Blockers or prerequisites: migrating the builder safely requires a strong React approach for nested editable state and drag-like canvas interactions
- Scores: `4 / 5 / 4 / 3 / 4`
- Rationale: smaller shell footprint than settings or sync, but high internal interaction complexity
- Recommendation: save for the final wave with other complex authoring surfaces
### Wave 0: Baseline
## Platform Unlocks
These are not the primary ordering rule, but they are useful to recognize because they can lower later migration cost.
- `artists`
- Likely unlocks reusable artist search, discography preview, and watchlist primitives for `discover`, `library`, and `artist-detail`.
- `downloads`
- Likely unlocks reusable album/track result cards, playback-launch patterns, and download mutation handling for `discover`, `library`, and issue-detail admin actions.
- Likely unlock shared admin form patterns and service-auth/test primitives, but the route is risky enough that it should not be used as an early proving ground.
- Key coupling: global search widget parity, shared search controller, download modal handoff, legacy DOM ids that still say `downloads`.
- Recommendation: this is the renamed download/search surface, so it should be treated as a distinct migration from the queue view, not as the old monolith.
- Main surface: automation list, visual builder, run history, one-click hub groups, config editing.
- Key coupling: nested editable state, polling, run/deploy/toggle flows, and other system-level actions.
- Recommendation: save this for the final wave with the other complex authoring surfaces.
### Wave 1: Safest wins
- `help`
- `hydrabase`
- `stats`
- `import`
- Why: these routes offer the best ratio of migration confidence to regression risk. They let the app add more React-owned routes without immediately entangling the team in global shell state or long-running workflow recovery.
### Wave 2: First medium-complexity route
- `artists`
- Why: good proving ground for async search, route-local cache/state, artist cards, and watchlist interactions before touching the full library-management stack.
### Wave 3: High-value operational routes
- `downloads`
- `dashboard`
- Why: both are important and complex, but by this point the team should already have route-local data-loading, mutation, and shell-bridge patterns that reduce migration risk.
### Wave 4: Broad discovery surface
- `discover`
- Why: very large rendering surface with many semi-independent sections. It should follow several prior migrations so the shared UI and query patterns are already mature.
### Wave 5: Library stack
- `library`
- `artist-detail`
- Why: these routes are tightly coupled and should be planned together. `artist-detail` is not an independent easy win and should not be pulled forward ahead of `library`.
### Wave 6: Visual interaction route
- `playlist-explorer`
- Why: highly interactive canvas/tree behaviors are easier to migrate once the broader React route architecture is already established.
### Wave 7: Multi-source orchestration route
- `sync`
- Why: this route has the deepest async orchestration, state rehydration, and external-service surface. It should be migrated only after the team has already de-risked several other route families.
### Wave 8: Final complex authoring/admin routes
- `settings`
- `automations`
- Why: these are high-blast-radius authoring surfaces with large state trees. They should land after the route architecture, shared UI patterns, and shell contracts are already stable.
## Platform Unlocks
- `search` likely unlocks reusable search-controller and download-launch primitives for the global search widget and other search entry points.
- `watchlist` likely unlocks artist-card, per-artist config, and scan-status primitives for `discover` and `wishlist`.
- `wishlist` likely unlocks queue/cycle visualization, live polling, and retry-state handling for `active-downloads` and sync-driven download flows.
- `active-downloads` likely unlocks batch grouping, queue filtering, and cancellation patterns for other download-related surfaces.
- `tools` likely unlocks maintenance-card and operational-action patterns that can be reused from `dashboard`.
- `library` + `artist-detail` still unlock entity-detail patterns, bulk actions, and file-management workflows.
## Why Earlier Waves Are Safer
- Wave 1 routes are either mostly static or bounded data UIs with limited cross-route side effects.
- Wave 2 adds moderate route-local state without forcing the app to solve shell-global task orchestration yet.
- Waves 3-4 add high-value routes once the migration pattern is established, rather than trying to learn the pattern inside the most coupled pages.
- Wave 5 intentionally treats the library stack as one problem space instead of creating a half-migrated split between `library` and `artist-detail`.
- Waves 6-8 defer the most interaction-heavy, orchestration-heavy, or configuration-heavy surfaces until the team has the most leverage.
- Wave 2 adds the renamed search surface without dragging in the full queue history.
- Wave 3 introduces the new watchlist/wishlist split, which is important but still narrower than discovery or library management.
- Wave 4 adds the live queue and tools split once the route-local patterns are already in place.
- Wave 5 keeps the dashboard after its maintenance responsibilities have been peeled away.
- Waves 6-10 defer the broadest, most coupled, or most orchestration-heavy surfaces until the team has the most leverage.
## Final Recommendation
- Keep `issues` as the reference implementation and preserve the existing bridge contract.
- Migrate the low-risk routes first: `help`, `hydrabase`, `stats`, and `import`.
- Use `artists` as the first medium-complexity proving ground.
- Treat `search`, `watchlist`, `wishlist`, `active-downloads`, and `tools` as the current route ids, and keep `downloads` and `artists` only as compatibility history.
- Migrate the safe routes first: `help`, `hydrabase`, `stats`, and `import`.
- Use `search` as the next meaningful proving ground now that the download queue has been split out.
- Avoid pulling `settings`, `sync`, `library`, `artist-detail`, or `automations` forward unless there is a separate product priority strong enough to justify the added regression risk.
Antti Kettunen
2 weeks ago