Implement the Elm frontend for shanty-web #10

New Issue

connor · 2026-03-17T16:27:20-04:00

connor commented

2026-03-17 16:27:20 -04:00

The Elm frontend is the "face" of Shanty — the primary way users interact with the application. It communicates with the Actix backend via the REST API defined in Issue #9. The philosophy is that the user should be able to add artists/albums/songs to their library and have the app handle everything else automatically.

This issue covers the MVP frontend:

Project setup:
- Initialize an Elm project in a subdirectory (e.g., shanty-web/frontend/ or a top-level frontend/ directory)
- Set up a build pipeline (e.g., elm make with an npm script or a Makefile target) that compiles to a JS bundle served by the Actix backend
- Basic HTML shell with the Elm app mounted
Core pages/views:

Dashboard
- Overview of library stats (total artists, albums, tracks)
- Recent additions
- Current download queue status
- Any running background tasks
Library Browser
- Browse artists → albums → tracks hierarchy
- Show watchlist status per item (wanted/downloaded/owned)
- Filter and sort options
- Click into an artist to see their albums, click into an album to see its tracks
Search & Add
- Search bar that queries the backend's search API
- Display search results (artists, albums, tracks) in a clear layout
- "Add to Library" button on each result that adds it to the watchlist
- When adding an artist, show their discography and let the user select which albums to monitor
Downloads
- View the download queue (pending, in-progress, completed, failed)
- Trigger manual downloads by entering a search query or URL
- Retry failed downloads
- Cancel pending downloads
Settings
- View and edit configuration (library path, download directory, format template, etc.)
- Trigger manual actions (re-index, re-tag)
Styling:
- Use a clean, dark-theme design (fitting the "high seas" aesthetic)
- Responsive layout that works on desktop and tablet
- No CSS framework required — keep it simple with custom CSS or a minimal utility approach
Real-time updates:
- Use WebSocket or SSE to receive progress updates from background tasks
- Update the UI live when downloads complete or indexing finishes

Design Considerations

Elm enforces a clean architecture (Model-View-Update) — lean into this. Define clear message types for each action.
Use elm/http for API calls and elm/json for decoding responses.
Consider using elm/url for client-side routing (SPA with browser history).
Keep the UI functional over pretty for MVP — polish can come later.
All API types should have corresponding Elm decoders/encoders.

Acceptance Criteria

Elm project compiles and the frontend loads in a browser when served by the Actix backend
Dashboard shows library stats, recent additions, and queue status
Library browser allows navigating artists → albums → tracks
Search works and displays results from MusicBrainz
Users can add artists/albums/tracks to their library from search results
Download queue is viewable and manageable (retry, cancel)
Manual download by query/URL works
Settings page allows viewing and editing configuration
UI updates in real-time for background tasks
Client-side routing works (SPA navigation)
Layout is responsive and uses a dark theme
No runtime errors in the Elm app (Elm's type system should help here)

Dependencies

Issue #9 (Actix web backend — the API must exist for the frontend to consume)

The Elm frontend is the "face" of Shanty — the primary way users interact with the application. It communicates with the Actix backend via the REST API defined in Issue #9. The philosophy is that the user should be able to add artists/albums/songs to their library and have the app handle everything else automatically. This issue covers the MVP frontend: 1. **Project setup:** - Initialize an Elm project in a subdirectory (e.g., `shanty-web/frontend/` or a top-level `frontend/` directory) - Set up a build pipeline (e.g., `elm make` with an npm script or a Makefile target) that compiles to a JS bundle served by the Actix backend - Basic HTML shell with the Elm app mounted 2. **Core pages/views:** **Dashboard** - Overview of library stats (total artists, albums, tracks) - Recent additions - Current download queue status - Any running background tasks **Library Browser** - Browse artists → albums → tracks hierarchy - Show watchlist status per item (wanted/downloaded/owned) - Filter and sort options - Click into an artist to see their albums, click into an album to see its tracks **Search & Add** - Search bar that queries the backend's search API - Display search results (artists, albums, tracks) in a clear layout - "Add to Library" button on each result that adds it to the watchlist - When adding an artist, show their discography and let the user select which albums to monitor **Downloads** - View the download queue (pending, in-progress, completed, failed) - Trigger manual downloads by entering a search query or URL - Retry failed downloads - Cancel pending downloads **Settings** - View and edit configuration (library path, download directory, format template, etc.) - Trigger manual actions (re-index, re-tag) 3. **Styling:** - Use a clean, dark-theme design (fitting the "high seas" aesthetic) - Responsive layout that works on desktop and tablet - No CSS framework required — keep it simple with custom CSS or a minimal utility approach 4. **Real-time updates:** - Use WebSocket or SSE to receive progress updates from background tasks - Update the UI live when downloads complete or indexing finishes ### Design Considerations - Elm enforces a clean architecture (Model-View-Update) — lean into this. Define clear message types for each action. - Use `elm/http` for API calls and `elm/json` for decoding responses. - Consider using `elm/url` for client-side routing (SPA with browser history). - Keep the UI functional over pretty for MVP — polish can come later. - All API types should have corresponding Elm decoders/encoders. ### Acceptance Criteria - [ ] Elm project compiles and the frontend loads in a browser when served by the Actix backend - [ ] Dashboard shows library stats, recent additions, and queue status - [ ] Library browser allows navigating artists → albums → tracks - [ ] Search works and displays results from MusicBrainz - [ ] Users can add artists/albums/tracks to their library from search results - [ ] Download queue is viewable and manageable (retry, cancel) - [ ] Manual download by query/URL works - [ ] Settings page allows viewing and editing configuration - [ ] UI updates in real-time for background tasks - [ ] Client-side routing works (SPA navigation) - [ ] Layout is responsive and uses a dark theme - [ ] No runtime errors in the Elm app (Elm's type system should help here) ### Dependencies - Issue #9 (Actix web backend — the API must exist for the frontend to consume)

connor added the HighPriority MVP labels 2026-03-17 16:27:27 -04:00

connor referenced this issue

2026-03-17 16:33:56 -04:00

Implement Docker packaging and deployment #15

connor referenced this issue

2026-03-17 16:41:54 -04:00

Implement built-in web player in the Elm frontend #23

connor referenced this issue

2026-03-17 16:45:12 -04:00

Add multi-user support #28

connor closed this issue

2026-03-18 10:37:27 -04:00