331 lines
22 KiB
Markdown
331 lines
22 KiB
Markdown
# WebUI Page Migration Analysis
|
|
|
|
Snapshot date: 2026-04-06
|
|
|
|
## Summary
|
|
- 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.
|
|
|
|
## 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
|
|
|
|
### Inventory Notes
|
|
- Manifest page IDs: `dashboard`, `sync`, `downloads`, `discover`, `playlist-explorer`, `artists`, `automations`, `library`, `artist-detail`, `stats`, `import`, `settings`, `issues`, `help`, `hydrabase`
|
|
- 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.
|
|
|
|
## 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.
|
|
|
|
## Scoring Rubric
|
|
Each page is scored from 1 to 5 on five axes:
|
|
|
|
- Rendering surface size: HTML/UI area and number of distinct render states
|
|
- State/coupling complexity: amount of local state plus coupling to other pages or shell-global state
|
|
- Async/realtime complexity: fetch fan-out, polling, WebSocket/live progress, streaming, or long-running workflows
|
|
- Cross-cutting shell dependency: reliance on shared shell behaviors, globals, overlays, or non-route contracts
|
|
- Testability/parity difficulty: how hard it is to prove route parity without regressions
|
|
|
|
Rollups:
|
|
|
|
- Migration effort
|
|
- `Low`: total score 9-11
|
|
- `Medium`: total score 12-17
|
|
- `High`: total score 18-21
|
|
- `Very High`: total score 22-25
|
|
- Regression risk
|
|
- `Low`: mostly isolated UI with limited async and minimal shell coupling
|
|
- `Medium`: moderate data flow or workflow complexity with bounded blast radius
|
|
- `High`: broad coupling, many async states, or sensitive user workflows
|
|
|
|
## Summary Matrix
|
|
|
|
| Page | Owner | Scores (R/S/A/C/T) | Effort | Risk | Recommended Wave |
|
|
| --- | --- | --- | --- | --- | --- |
|
|
| `issues` | React | 2 / 2 / 2 / 2 / 2 | Low | Low | Baseline only |
|
|
| `help` | Legacy | 3 / 2 / 1 / 1 / 2 | Low | Low | Wave 1 |
|
|
| `hydrabase` | Legacy | 2 / 2 / 2 / 2 / 2 | Low | Low | Wave 1 |
|
|
| `stats` | Legacy | 2 / 2 / 2 / 2 / 2 | Low | Low | Wave 1 |
|
|
| `import` | Legacy | 3 / 3 / 3 / 2 / 3 | Medium | Medium | Wave 1 |
|
|
| `artists` | Legacy | 3 / 4 / 3 / 3 / 3 | Medium | Medium | Wave 2 |
|
|
| `downloads` | Legacy | 4 / 4 / 4 / 3 / 4 | High | High | Wave 3 |
|
|
| `dashboard` | Legacy | 4 / 4 / 4 / 4 / 4 | High | High | Wave 3 |
|
|
| `discover` | Legacy | 5 / 5 / 4 / 4 / 5 | Very High | High | Wave 4 |
|
|
| `library` | Legacy | 4 / 5 / 4 / 4 / 5 | Very High | High | Wave 5 |
|
|
| `artist-detail` | Legacy | 5 / 5 / 4 / 5 / 5 | Very High | High | Wave 5 |
|
|
| `playlist-explorer` | Legacy | 4 / 4 / 4 / 3 / 4 | High | High | Wave 6 |
|
|
| `sync` | Legacy | 5 / 5 / 5 / 4 / 5 | Very High | High | Wave 7 |
|
|
| `settings` | Legacy | 5 / 5 / 4 / 5 / 5 | Very High | High | Wave 8 |
|
|
| `automations` | Legacy | 4 / 5 / 4 / 3 / 4 | High | High | Wave 8 |
|
|
|
|
## Page Catalog
|
|
|
|
### `issues`
|
|
- Current owner: React
|
|
- Primary files: `webui/src/routes/issues/*`, `webui/src/platform/shell/*`, `plans/webui-issues-migration-plan.md`
|
|
- Main surface: counts cards, filtered issue list, issue-detail modal, mutation flows
|
|
- Async behavior: route loader prefetch, React Query list/detail/count queries, mutation-driven refresh
|
|
- Coupling: shell page gating, shell nav badge refresh, bridge-controlled chrome
|
|
- Blockers or prerequisites: none; this is the migration baseline
|
|
- Scores: `2 / 2 / 2 / 2 / 2`
|
|
- Rationale: already proves the route-manifest + bridge + React-host pattern with limited shell leakage
|
|
|
|
### `help`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/docs.js`, `webui/static/script.js`
|
|
- Main surface: documentation navigation, long-form content sections, screenshot lightbox, docs deep linking
|
|
- Async behavior: effectively none beyond image loading
|
|
- Coupling: shell nav and page activation only; contextual help metadata lives elsewhere but does not need to migrate with the page
|
|
- Blockers or prerequisites: keep `helper.js` shell-owned for now; migrate the Help route only, not the whole helper system
|
|
- Scores: `3 / 2 / 1 / 1 / 2`
|
|
- Rationale: large content surface, but low runtime complexity and limited cross-page coordination
|
|
- Recommendation: best low-risk route after `issues`
|
|
|
|
### `hydrabase`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`
|
|
- Main surface: connection state, saved credentials, peer count, comparison list
|
|
- Async behavior: status fetch, connect/disconnect flows, comparisons load
|
|
- Coupling: dev-mode visibility, settings linkage, shell route gating
|
|
- Blockers or prerequisites: keep the Hydrabase shell toggle behavior outside the route initially
|
|
- Scores: `2 / 2 / 2 / 2 / 2`
|
|
- Rationale: bounded feature area with limited UI states and no broad reusable legacy entanglement
|
|
- Recommendation: safe early migration
|
|
|
|
### `stats`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`
|
|
- Main surface: ranked lists, charts, db storage visualization, listening-stats refresh
|
|
- Async behavior: cached stats fetches, chart rendering, one-off sync actions
|
|
- Coupling: shell page activation, some library deep links back to artist/library routes
|
|
- Blockers or prerequisites: preserve chart library loading and route-to-library deep links
|
|
- Scores: `2 / 2 / 2 / 2 / 2`
|
|
- Rationale: read-heavy page with mostly isolated rendering and modest mutation behavior
|
|
- Recommendation: early migration candidate with good parity-test potential
|
|
|
|
### `import`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`
|
|
- Main surface: staging files, grouped import candidates, album/track search, suggestions, match and process flows
|
|
- Async behavior: multiple search/match/process endpoints, modal-like step transitions inside the page
|
|
- Coupling: settings-derived staging path assumptions, downstream library state
|
|
- Blockers or prerequisites: likely benefits from shared album-search and suggestion primitives, but does not require them
|
|
- Scores: `3 / 3 / 3 / 2 / 3`
|
|
- Rationale: moderate workflow complexity, but still much more self-contained than discovery, sync, or library management
|
|
- Recommendation: last route in the initial low-risk wave
|
|
|
|
### `artists`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`
|
|
- Main surface: search/results/detail view switching inside one route, artist caching, discography snippets, similar artists, watchlist interactions, download bubbles
|
|
- Async behavior: search debouncing, cancellation via abort controllers, detail/discography fetches, similar-artist loading
|
|
- Coupling: shares artist concepts with `library`, `artist-detail`, `discover`, and watchlist workflows
|
|
- Blockers or prerequisites: decide whether route migration should keep its internal view-state approach or split search/detail sub-routes later
|
|
- Scores: `3 / 4 / 3 / 3 / 3`
|
|
- Rationale: not tiny, but still a manageable route for establishing artist-focused React patterns before touching library detail
|
|
- Recommendation: first medium-complexity route after the initial safe wave
|
|
|
|
### `downloads`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`
|
|
- Main surface: enhanced search, basic search, source tabs, filters, result cards, preview playback, candidate selection, download manager queues
|
|
- Async behavior: many search endpoints, batch downloads, active-process rehydration, polling, streaming preview
|
|
- 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
|
|
|
|
### `dashboard`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`, `webui/static/worker-orbs.js`
|
|
- 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
|
|
|
|
### `discover`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`
|
|
- Main surface: hero carousel, your artists, Spotify library, recent releases, seasonal content, personalized shelves, ListenBrainz tabs, decade browser, genre browser, discovery blacklist
|
|
- Async behavior: very large parallel fetch fan-out, sync-status polling, watchlist integration, persistent playlist state hydration
|
|
- Coupling: shared album cards, watchlist/wishlist flows, sync actions, discovery-download sidebars, artist navigation
|
|
- Blockers or prerequisites: benefits from reusable album/artist card primitives, but the main risk is breadth rather than missing infrastructure
|
|
- Scores: `5 / 5 / 4 / 4 / 5`
|
|
- Rationale: one of the broadest pages in the app, with many semi-independent sections that still share global behaviors
|
|
- Recommendation: move after the team has already migrated a few medium-complexity, data-heavy routes
|
|
|
|
### `library`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`
|
|
- Main surface: searchable artist grid, alphabet navigation, watchlist filters, pagination, download bubbles, deep links into `artist-detail`
|
|
- Async behavior: paginated fetches, watchlist mutations, shell-to-detail navigation
|
|
- Coupling: tightly bound to `artist-detail`, watchlist systems, active metadata source, and library-wide expectations
|
|
- Blockers or prerequisites: should not be migrated independently from the `artist-detail` strategy
|
|
- Scores: `4 / 5 / 4 / 4 / 5`
|
|
- Rationale: modest-looking page, but it is the entry point into the most complex library-management workflows
|
|
- Recommendation: migrate in the same program wave as `artist-detail`, not as an isolated quick win
|
|
|
|
### `artist-detail`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`
|
|
- Main surface: hero section, standard discography, enhanced view, filters, selection/bulk operations, inline editing, manual match, tag preview/write, reorganize, quality enhancement
|
|
- Async behavior: detail fetches, streaming library-completion checks, multiple mutation workflows, modal stacks, playback actions
|
|
- Coupling: explicitly coupled to `library`; also touches watchlist settings, downloads, playback, metadata services, and file-organization settings
|
|
- Blockers or prerequisites: requires a clear React strategy for complex table/grid state, inline editing, and bulk actions before migration begins
|
|
- Scores: `5 / 5 / 4 / 5 / 5`
|
|
- Rationale: highest combined shell and workflow complexity outside `sync` and `settings`
|
|
- Recommendation: treat as a paired migration with `library`, and keep it out of early waves
|
|
|
|
### `playlist-explorer`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`
|
|
- Main surface: visual discovery tree, artist tiers, album expansion, selection model, wishlist submission flow, zoom/pan interactions
|
|
- Async behavior: tree build, album-track fetches, wishlist processing, drag-like navigation, global document listeners for pointer/wheel events
|
|
- Coupling: artist navigation, wishlist flows, page-level document event handlers
|
|
- Blockers or prerequisites: needs a deliberate React strategy for viewport interactions and document-level listeners before migration starts
|
|
- Scores: `4 / 4 / 4 / 3 / 4`
|
|
- Rationale: narrower than `sync`, but still interaction-heavy and easy to regress
|
|
- Recommendation: late-mid program route after the team is comfortable migrating complex visual state
|
|
|
|
### `sync`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`
|
|
- Main surface: Spotify/Tidal/Deezer/YouTube/Beatport/ListenBrainz/public Spotify playlists, mirrored playlists, URL histories, server playlist manager, discovery and sync phases, modal rehydration
|
|
- Async behavior: the heaviest page in the app; many endpoints, long-running workflows, state rehydration, polling, and live progress
|
|
- Coupling: download manager, server integrations, discovery workflows, active-process hydration, and multiple global state buckets
|
|
- Blockers or prerequisites: likely needs reusable route-local infrastructure for task state, progress polling, and source-specific adapters
|
|
- Scores: `5 / 5 / 5 / 4 / 5`
|
|
- Rationale: broadest operational surface and highest parity burden
|
|
- Recommendation: one of the last major migrations
|
|
|
|
### `settings`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`, `webui/static/docs.js`
|
|
- 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
|
|
|
|
### `automations`
|
|
- Current owner: Legacy
|
|
- Primary files: `webui/index.html`, `webui/static/script.js`, `webui/static/helper.js`
|
|
- Main surface: automation list, filters, execution status, run history modal, one-click hub groups, visual builder, block placement and config editing
|
|
- Async behavior: list loading, progress polling, run/deploy/toggle/history actions, builder save/load flows
|
|
- 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
|
|
|
|
## 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.
|
|
- `library` + `artist-detail`
|
|
- Likely unlock reusable entity-detail patterns, richer table state, batch actions, and file-management workflows.
|
|
- `settings`
|
|
- 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.
|
|
|
|
## Recommended Migration Waves
|
|
|
|
### Wave 0: Reference baseline
|
|
- `issues`
|
|
- Goal: keep using the current Issues route as the canonical example for route ownership, shell bridge usage, and React-host activation.
|
|
|
|
### 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
- 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.
|