discdrop/discdrop-plan.md

DiscDrop — Implementation Plan

A self-hosted, single-user app to follow MusicBrainz artists and track their release groups (not individual releases, to avoid duplicate vinyl/CD editions). Shows a combined web feed plus an RSS feed of new release groups, ordered by first-release-date.

Tagline: Drop the needle on every new release from the artists you follow.

---

1. Overview & Goals

Aspect	Decision
Language / framework	Java 17 + Quarkus 3.x
Frontend	Server-rendered Qute templates + htmx + daisyUI (Tailwind)
Persistence	Embedded H2 (file-based) via Quarkus Hibernate ORM + Panache
MBZ access	Quarkus REST Client (MicroProfile) + JSON (no external Java library)
RSS	Single global RSS 2.0 feed of all followed artists
Users	Single-user, local/self-hosted (no auth layer in v1)
MBZ identity	User-Agent: DiscDrop/1.0 ([email protected])
Build / run	Maven (./mvnw quarkus:dev)

Functional requirements covered

1. Modern, adaptive UI with daisyUI theme switching.
2. Logo + favicon reflecting the app's purpose (vinyl "drop").
3. One combined feed of all followed artists.
4. Artist search autocomplete showing disambiguation + area name.
5. Centered, responsive header: logo, app name, search box, settings, theme switcher.
6. Feed rows: artist name, release title, release type, release date, MBZ link; ordered by first-release-date; "load more" pagination.
7. Follow artists from search results.
8. Unfollow already-tracked artists (search shows "unfollow" when tracked).
9. Follow/unfollow updates the feed in place (htmx) and clears the search box.
10. Click-outside closes the autocomplete dropdown.
11. Track release groups, not releases.
12. Separate Artists page: unfollow + per-artist primary-type monitoring toggles.
13. Settings: default primary type for new artists (default album) + sync schedule (6/12/24 h); closes on click-outside.

---

2. Architecture

┌──────────────── Browser (htmx + daisyUI) ────────────────┐
│  Header: logo · DiscDrop · search · settings · theme     │
│  Feed (Qute fragments swapped by htmx)                   │
│  /artists page · /rss feed                               │
└───────────────────────────┬──────────────────────────────┘
                            │ HTTP (HTML fragments / RSS / JSON)
┌─────────────── Quarkus App (DiscDrop) ───────────────────┐
│  Resources (Qute controllers)                            │
│   ├─ PageResource      GET /  (index + feed fragment)    │
│   ├─ SearchResource    GET /search/artists?q= (fragment) │
│   ├─ ArtistResource    POST/DELETE follow · GET /artists │
│   ├─ SettingsResource  GET/POST /settings (fragment)     │
│   └─ RssResource       GET /rss                          │
│  Services                                                │
│   ├─ FeedService       builds ordered feed page          │
│   ├─ ArtistService     follow/unfollow, settings         │
│   ├─ SyncService       refresh release groups            │
│   └─ SettingsService   app-wide settings                 │
│  MusicBrainzClient (REST Client, JSON, rate-limited)     │
│  Panache repositories (FollowedArtist, ReleaseGroup, …)  │
└───────────────┬───────────────────────┬──────────────────┘
        H2 file DB                    MusicBrainz API
        (discdrop.mv.db)              https://musicbrainz.org/ws/2/
                                      (1 req/sec, User-Agent)

Request flow examples

• Search typing → GET /search/artists?q=… → MusicBrainzClient.searchArtists() → Qute fragment (dropdown rows).
• Follow click → POST /artists/follow → persist FollowedArtist (+ default type settings) → enqueue immediate sync for that artist → return updated feed fragment + empty search fragment.
• Scheduled sync → for each followed artist, page through release-group?artist=…&type=… → upsert ReleaseGroup rows.

---

3. Data Model

Panache entities backed by H2. Keep it small; no premature normalization.

FollowedArtist

field	type	notes
id	Long (auto)	PK
mbid	String (UUID)	unique; MBZ artist MBID
name	String	display name
sortName	String
disambiguation	String	e.g. "90s US grunge band"
areaName	String	from area.name
type	String	Person / Group / …
country	String
followedAt	Instant
lastSyncedAt	Instant	nullable

ArtistTypeSetting

Per-artist toggle for each primary type (requirement 12).

field	type	notes
id	Long	PK
artist	FollowedArtist	FK
primaryType	String	album / single / ep / broadcast / other
enabled	boolean

Primary types come from the MBZ spec: album, single, ep, broadcast, other. On follow, seed one row per primary type with enabled derived from the default primary types setting (album enabled by default).

ReleaseGroup

Cached release groups (one row per MBZ release group per artist).

field	type	notes
id	Long	PK
mbid	String (UUID)	unique
artist	FollowedArtist	FK
title	String
firstReleaseDate	LocalDate	sortable; may be null/partial
firstReleaseDateRaw	String	preserve "2024-03" / "2024" granularity
primaryType	String	album / single / ep / …
secondaryTypes	String	comma-joined (live, compilation, …)
mbzUrl	String	https://musicbrainz.org/release-group/{mbid}
discoveredAt	Instant	when first seen by sync

Unique on mbid. Index on (firstReleaseDate DESC) for feed ordering.

Cover art needs no stored field — the front-cover URL is deterministic from the MBID: https://coverartarchive.org/release-group/{mbid}/front (Cover Art Archive, an MBZ-affiliated service). See §4.5.

AppSetting

Key/value for global settings (requirement 13).

key	example value	notes
defaultPrimaryTypes	album	comma-list applied to new artists
syncScheduleHours	6	one of 6, 12, 24
theme	dark	optional server-side mirror of client theme

---

4. MusicBrainz Integration

4.1 Endpoints used (all fmt=json)

Purpose	Method + URL
Artist search (autocomplete)	GET /ws/2/artist?query={q}&limit=10&fmt=json
Browse release groups by artist	GET /ws/2/release-group?artist={mbid}&type={types}&limit=100&offset={n}&inc=artist-credits&fmt=json&release-group-status=website-default
(Optional) Artist lookup on follow	GET /ws/2/artist/{mbid}?inc=aliases&fmt=json

Notes:

• type accepts primary types joined by | (e.g. album|ep); maps directly to each artist's enabled ArtistTypeSetting rows.
• release-group-status=website-default excludes groups that contain only promotional/bootleg/pseudo-release editions — keeps the feed clean. Default on; can later expose all.
• Release-group JSON fields we use: id, title, first-release-date, primary-type, secondary-types[], artist-credit[] (for display name fallback).
• Artist search JSON fields we use: id, name, disambiguation, area.name, type, country, score.

4.2 REST Client definition (sketch)

The User-Agent is not hardcoded in the interface — it is supplied at runtime by a ClientHeadersFactory that reads discdrop.mbz.user-agent from application.properties (see §10). This keeps MBZ contact info out of source so it can be overridden per environment (dev vs. prod, different maintainer email) without recompiling.

@ApplicationScoped
@RegisterRestClient(configKey = "musicbrainz")
@RegisterClientHeaders(MusicBrainzHeadersFactory.class)
public interface MusicBrainzClient {
    @GET @Path("/artist")
    ArtistSearchResult searchArtists(@QueryParam("query") String q,
                                     @QueryParam("limit") int limit,
                                     @QueryParam("fmt") String fmt);

    @GET @Path("/release-group")
    ReleaseGroupBrowseResult browseReleaseGroups(@QueryParam("artist") String mbid,
                                                 @QueryParam("type") String types,
                                                 @QueryParam("limit") int limit,
                                                 @QueryParam("offset") int offset,
                                                 @QueryParam("inc") String inc,
                                                 @QueryParam("fmt") String fmt,
                                                 @QueryParam("release-group-status") String status);
}

@ApplicationScoped
public class MusicBrainzHeadersFactory implements ClientHeadersFactory {
    @ConfigProperty(name = "discdrop.mbz.user-agent")
    String userAgent;

    @Override
    public MultivaluedMap<String, String> update(MultivaluedMap<String, String> incoming,
                                                 MultivaluedMap<String, String> outgoing) {
        outgoing.putSingle("User-Agent", userAgent);
        return outgoing;
    }
}

Base URI and other REST Client settings are externalized via quarkus.rest-client."musicbrainz".* keys in application.properties (see §10).

4.3 Rate limiting (mandatory: ≤ 1 req/sec)

A single shared gate that all MBZ calls pass through:

• MusicBrainzService wraps the client with a synchronized acquire() that enforces ≥1000 ms between outgoing requests (track lastCallMillis).
• The background sync loop naturally spaces calls (one artist/page at a time).
• Live search also goes through acquire(); combined with 300 ms client-side debounce, this keeps us compliant even with fast typing.

4.4 DTOs (Jackson)

ArtistSearchResult { count, artists[] } → ArtistDto { id, name, disambiguation, area { name }, type, country, score }. ReleaseGroupBrowseResult { "release-group-count", "release-group-offset", "release-groups[] } → ReleaseGroupDto { id, title, first-release-date, primary-type, secondary-types[], artist-credit[] }.

4.5 Cover Art Archive

Cover art comes from the Cover Art Archive (https://coverartarchive.org), the MBZ-affiliated image service hosted by the Internet Archive. No API key required.

• Front cover by release-group MBID: https://coverartarchive.org/release-group/{mbid}/front — responds with 307 redirect to the archived image (JPEG), or 404 if no art exists.
• This URL is deterministic from the MBID, so:
  • No extra HTTP calls during sync.
  • No coverArtUrl field on ReleaseGroup needed.
  • Templates render <img src="https://coverartarchive.org/release-group/{mbid}/front" onerror="this.src='/img/no-cover.svg'"> — the browser follows the redirect, and a small JS onerror swaps to a local placeholder when a release group has no art (common for bootlegs/obscure releases).
• Optional optimization (later): during sync, issue a HEAD per release group and store a hasCoverArt boolean to avoid any broken-image flashes. Defer this unless the onerror flicker is bothersome; it adds N calls per sync and is unnecessary for v1.
• Rate limits on coverartarchive.org are more lenient than the MBZ web service, and since we hit it client-side (browser <img>) or not at all, it never contends with our 1 req/sec MBZ gate.

---

5. Sync / Scheduler

• SyncService with a @Scheduled method. The cadence is read from AppSetting.syncScheduleHours and reconfigured at runtime (Quarkus supports programmatic scheduler via Scheduler / ScheduledExecutor, or simply restart after settings change for v1).
• Per run, iterate FollowedArtist rows; for each, build the type= filter from its enabled ArtistTypeSetting rows, page through release groups (offset increments by received count, up to limit=100), and upsert into ReleaseGroup.
• After an artist is processed, update lastSyncedAt.
• Immediate sync on follow: when a user follows an artist, trigger a one-off sync for that artist (async, fire-and-forget) so the feed populates without waiting for the next schedule.
• Honor rate limit between every MBZ call.

---

6. UI / UX

6.1 Layout & theming

• Single base template (templates/index.html) with a sticky header and the feed below.
• daisyUI via CDN for rapid dev (daisyui full CSS + Tailwind Play CDN); switch to a built/minified local Tailwind CSS for production.
• Theme switching: toggle data-theme on <html> (e.g. light/dark or a daisyUI pair like nord/dim). Persist in localStorage for instant restore; optionally mirror to AppSetting.theme. Small vanilla JS handler on the theme switcher button.

6.2 Header (centered, responsive, consistent gap)

A flex container, justify-center, gap-4, wrapping gracefully on narrow screens: [logo] [DiscDrop] [search box] [settings btn] [theme switcher]

• Logo: small SVG (see §7).
• App name: "DiscDrop" wordmark.
• Search box: text input with autocomplete dropdown anchored below it.
• Settings button: opens a dropdown panel (§6.6).
• Theme switcher: icon button cycling/toggling themes.

6.3 Search + autocomplete (requirements 4, 7, 8, 9, 10)

• Input wired with htmx: hx-get="/search/artists?q=...", hx-trigger="input changed delay:300ms, keyup changed", hx-target="#search-dropdown", hx-swap="innerHTML".
• Dropdown rows render: name · disambiguation (muted) · area name (badge). Each row carries a Follow/Unfollow button depending on whether the MBID is already in FollowedArtist.
• Follow/Unfollow buttons: hx-post="/artists/follow" / hx-delete="/artists/{mbid}" with:
  • hx-target="#feed-list" and hx-swap="innerHTML" (refresh feed), and
  • hx-on::after-request="this.closest('form').reset(); document.querySelector('#search-dropdown').innerHTML='';" (clear input + close dropdown) — satisfying requirement 9.
• Click-outside to close (requirement 10): a tiny JS helper listens for document clicks; if the target is outside #search-wrap, it empties #search-dropdown. (Same helper pattern reused for settings.)

6.4 Feed (requirements 3, 6, 11)

• Server renders the first page of release groups ordered by firstReleaseDate DESC.
• Each row: cover art thumbnail (see §4.5 — <img src="https://coverartarchive.org/release-group/{mbid}/front" onerror="…no-cover placeholder…">, sized ~64–96px, lazy-loaded), artist name (link to artist page section), release title, release type badge(s) (primary + secondary), release date (human-friendly, with raw granularity preserved), and an external link to https://musicbrainz.org/release-group/{mbid}.
• Load more: a button hx-get="/feed?offset={N+page}" hx-target="this" hx-swap="outerHTML" that appends the next page and re-emits itself with the new offset, until exhausted (then no button).

6.5 Artists page (requirement 12)

• Route /artists listing every FollowedArtist as a card/row with:
  • name + disambiguation + area,
  • Unfollow button (hx-delete="/artists/{mbid}", target the row, swap outerHTML → removes row),
  • primary-type toggles: a set of daisyUI checkboxes/switches for album, single, ep, broadcast, other; each change hx-post="/artists/{mbid}/types" (persist + re-sync that artist) with hx-swap="none" and an out-of-band feed refresh.

6.6 Settings (requirement 13)

• Settings button opens a dropdown panel (anchored, same click-outside helper).
• Controls:
  • Default primary types for newly followed artists (checkbox set; default album checked) → AppSetting.defaultPrimaryTypes.
  • Sync schedule: radio/select among 6h / 12h / 24h → AppSetting.syncScheduleHours.
• Save: hx-post="/settings" with hx-swap="innerHTML" on the panel (re-render + confirm). Click-outside closes (does not save unsaved changes in v1, or autosave on change — pick autosave-on-change to keep it simple).

---

7. Branding: Logo & Favicon

Concept: a vinyl record dropping into a slot — reinforces "DiscDrop".

Logo SVG (inline, scales in header)

• Outer black circle (vinyl) with 2–3 thin concentric groove rings.
• Colored center label (accent theme color) with a tiny spindle hole.
• A subtle downward chevron / motion line at the bottom-right indicating "drop".
• Wordmark "DiscDrop" next to it in the header.

Favicon

• Simplified 32×32 / SVG: just the vinyl circle + center label + a small downward arrow. Provide favicon.svg (modern browsers) plus a generated favicon.ico/192.png for broader support.

Assets live in src/main/resources/static/img/ and are referenced from the base template (<link rel="icon" ...> and header <img>).

---

8. htmx Interaction Flows (summary)

Action	Request	Targets / effects
Type in search	GET /search/artists?q=	swap #search-dropdown
Follow	POST /artists/follow	swap #feed-list + clear search + close dropdown
Unfollow (from search)	DELETE /artists/{mbid}	swap #feed-list + clear search + close dropdown
Unfollow (artists page)	DELETE /artists/{mbid}	remove row (outerHTML) + OOB feed refresh
Toggle artist type	POST /artists/{mbid}/types	OOB #feed-list refresh
Load more	GET /feed?offset=	append rows, replace button
Save settings	POST /settings	re-render panel
Theme switch	(client JS)	toggle data-theme, save localStorage

Out-of-band swaps (hx-swap-oob) keep the feed consistent when follow/unfollow/type-toggle happens from anywhere but the feed itself.

---

9. RSS Feed

• GET /rss returns RSS 2.0 (application/rss+xml; Qute template generating XML, or a small builder).
• Single global feed: latest N (e.g. 50) release groups across all followed artists, ordered by firstReleaseDate DESC.
• Each <item>: title = {artist} – {title}; link = https://musicbrainz.org/release-group/{mbid}; pubDate = firstReleaseDate; description = type(s) + date; <guid> = the MBZ MBID (stable).
• Cover art: each item embeds the front cover via the Media RSS namespace (xmlns:media="http://search.yahoo.com/mrss/"):

  <media:content url="https://coverartarchive.org/release-group/{mbid}/front"
                 type="image/jpeg" medium="image" />
  

  Media RSS is preferred over a plain <enclosure> because <enclosure> requires a length (byte size) attribute we don't know without a HEAD probe, whereas <media:content> has no such requirement and is widely supported by modern RSS readers. Add xmlns:media to the <rss> root element.
• Channel metadata: "DiscDrop – New Releases", link to the app root.
• Discoverable via <link rel="alternate" type="application/rss+xml" ...> in the base template.

---

10. Project Structure

discdrop/
├── pom.xml
├── README.md
├── src/main/java/io/discdrop/
│   ├── DiscDropApp.java
│   ├── resource/
│   │   ├── PageResource.java          # GET / (index + feed fragment), GET /feed
│   │   ├── SearchResource.java        # GET /search/artists
│   │   ├── ArtistResource.java        # follow/unfollow, GET /artists, type toggles
│   │   ├── SettingsResource.java      # GET/POST /settings
│   │   └── RssResource.java           # GET /rss
│   ├── service/
│   │   ├── FeedService.java
│   │   ├── ArtistService.java
│   │   ├── SyncService.java
│   │   └── SettingsService.java
│   ├── mbz/
│   │   ├── MusicBrainzClient.java     # REST Client interface (no hardcoded User-Agent)
│   │   ├── MusicBrainzHeadersFactory.java  # injects discdrop.mbz.user-agent from config
│   │   ├── MusicBrainzService.java    # rate-limited wrapper
│   │   └── dto/{ArtistSearchResult,ArtistDto,ReleaseGroupBrowseResult,ReleaseGroupDto}.java
│   └── persistence/
│       ├── FollowedArtist.java
│       ├── ArtistTypeSetting.java
│       ├── ReleaseGroupEntity.java
│       └── AppSetting.java
├── src/main/resources/
│   ├── application.properties
│   ├── templates/
│   │   ├── index.html                 # base: header + feed
│   │   ├── artists.html
│   │   ├── rss.xml
│   │   └── fragments/
│   │       ├── feed-list.html
│   │       ├── feed-row.html
│   │       ├── search-dropdown.html
│   │       ├── settings-panel.html
│   │       └── artist-row.html
│   └── static/
│       ├── img/{logo.svg, favicon.svg, favicon.ico, no-cover.svg}
│       ├── css/  (daisyUI/Tailwind, dev via CDN or built)
│       └── js/app.js  (theme switch + click-outside helper)

Key application.properties

quarkus.application.name=DiscDrop
quarkus.http.port=8080

# H2 file DB
quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:file:./data/discdrop;DB_CLOSE_DELAY=-1
quarkus.datasource.username=sa
quarkus.datasource.password=
quarkus.hibernate-orm.database.generation=update

# MusicBrainz REST client
quarkus.rest-client."musicbrainz".url=https://musicbrainz.org/ws/2
# User-Agent (MBZ requires a meaningful contact string) — override per environment, never hardcode in code
discdrop.mbz.user-agent=DiscDrop/1.0 ([email protected])
discdrop.mbz.rate-limit-ms=1000
discdrop.feed.page-size=25
discdrop.rss.item-count=50

On startup, validate that discdrop.mbz.user-agent is non-empty (fail fast with a clear StartupException rather than emitting anonymous requests MBZ may block).

Maven dependencies (essentials)

• quarkus-resteasy-reactive-qute, quarkus-rest-client-jackson, quarkus-hibernate-orm, quarkus-jdbc-h2, quarkus-panache, quarkus-scheduler, quarkus-resteasy-reactive-jackson.

---

11. Implementation Phases

Phase 0 — Scaffold (0.5 day)

• quarkus create app (Java 17, Maven, REST + Qute + Hibernate + H2 + Scheduler + REST Client).
• Base template with daisyUI CDN, htmx CDN, logo/favicon placeholders, header layout.
• Verify ./mvnw quarkus:dev boots and renders the header.

Phase 1 — MBZ client + search (1 day)

• MusicBrainzClient + DTOs + rate-limited MusicBrainzService.
• /search/artists returning Qute dropdown fragment (name, disambiguation, area).
• Click-outside close helper.

Phase 2 — Persistence + follow/unfollow (1 day)

• Panache entities + repositories; SettingsService defaults.
• Follow/unfollow endpoints; seed ArtistTypeSetting from default primary types.
• Immediate one-off sync on follow; feed fragment endpoint.
• Wire follow buttons in search dropdown; clear search + refresh feed via htmx.

Phase 3 — Sync + feed (1 day)

• SyncService scheduler (configurable 6/12/24 h); paged release-group browse + upsert.
• Feed ordering by firstReleaseDate DESC, row fragment with cover art thumbnail (Cover Art Archive URL + onerror placeholder), load more pagination.
• MBZ external links on each row.

Phase 4 — Artists page + type toggles (0.5 day)

• /artists page with unfollow + per-artist primary-type switches; OOB feed refresh on change.

Phase 5 — Settings panel (0.5 day)

• Settings dropdown: default primary types + sync schedule; autosave-on-change; click-outside close.

Phase 6 — RSS + branding polish (0.5 day)

• /rss RSS 2.0 with <media:content> cover art per item; <link rel="alternate"> discovery.
• Finalize logo/favicon SVG + no-cover.svg placeholder; theme switcher; responsive pass.

Phase 7 — Hardening (0.5 day)

• Error states (MBZ down / rate-limited / empty feed) with friendly UI.
• README with run + config instructions.
• Optional: replace daisyUI/Tailwind CDN with a built local CSS for production.

Estimated total: ~5–6 days.

---

12. Out of Scope (v1) / Future

• Multi-user / auth (currently single-user local).
• Cover-art HEAD probing during sync (to pre-flag missing art and avoid broken-image flashes); the onerror placeholder handles this client-side for v1.
• Secondary-type per-artist filters (only primary types are toggled per requirement 12; secondary types are shown as badges).
• Notifications (email/webhook) beyond RSS.
• Migration to PostgreSQL (entity model is portable; only datasource config changes).
• Replacing the daisyUI/Tailwind CDN with a production Tailwind build.

---

13. Key Design Decisions & Rationale

• Release groups, not releases (req 11): browse release-group with inc=artist-credits; one row per group, no duplicate vinyl/CD.
• release-group-status=website-default: filters promo/bootleg/pseudo-release-only groups → cleaner feed.
• Server-side rate limiting shared by search + sync: guarantees the 1 req/sec MBZ rule regardless of UI activity.
• Quarkus REST Client + JSON over the dead/GPL musicbrainzws2-java library: lighter, idiomatic, no licensing constraints.
• Externalized User-Agent via ClientHeadersFactory: the MBZ contact string lives in application.properties (discdrop.mbz.user-agent), not in code — so it can be overridden per environment and updated without a recompile. App fails fast at startup if the property is missing, to avoid sending anonymous requests MBZ may block.
• H2 file-based: zero-ops for a personal app; portable to Postgres later by changing datasource props.
• htmx + Qute fragments: the feed, search dropdown, and settings all swap HTML fragments — no SPA needed; matches requirements 9 and 10 (in-place updates, dropdown close).
• Cover art via deterministic Cover Art Archive URLs: https://coverartarchive.org/release-group/{mbid}/front needs no per-item API call or storage — the URL is derived from the MBID, fetched lazily by the browser <img>, with a JS onerror placeholder for release groups without art. Keeps sync fast and the data model lean.
• Media RSS <media:content> over <enclosure> for RSS images: avoids the mandatory length (byte-size) attribute that <enclosure> requires and that we'd need a HEAD probe to obtain.
• Autosave settings on change: avoids a "save" button and keeps the settings panel simple (closes on click-outside per req 13).