Problem
apps/backend/routes/library.route.ts mounts three different library-search endpoints with overlapping responsibilities and no documentation explaining when to use which:
| Path |
Permissions |
Controller |
Use case |
GET /library/search |
{} (any JWT) |
requestLineController.searchLibraryEndpoint |
public — request line feature |
GET /library/ |
catalog:read |
libraryController.searchForAlbum |
dj-site catalog search (legacy shape) |
GET /library/query |
catalog:read |
libraryController.searchLibraryQueryEndpoint |
dj-site catalog search (advanced / tsvector-based — Catalog Track Search project) |
A reader trying to add a new search-shape feature has to read three controllers and infer the boundaries. The differences (auth scope, search shape, response field set, ranking, what's filtered) aren't documented anywhere. Anyone trying to do a security audit has the same problem in reverse.
End state
JSDoc block on each controller (and matching prose on each route file line) that calls out:
- Who's the canonical caller (request line / dj-site catalog / iOS / etc.)
- What's the response shape (which fields, ranking, pagination semantics)
- Why this exists alongside the others (or, if one shouldn't exist alongside the others, file a deprecation follow-up)
- What gates / feature flags affect it (
NEXT_PUBLIC_CATALOG_TRACK_SEARCH_UI_ENABLED on dj-site? backend-side flags?)
Plus a top-of-file comment block in apps/backend/routes/library.route.ts (or a sibling docs/library-endpoints.md if it grows) that lays out the three search variants as a single decision tree for future readers.
Acceptance
Why now
Surfaced during the endpoint-discipline review on 2026-05-21. Cheap doc work that prevents a class of "which endpoint should I call?" questions, and saves a future security audit hours.
Related
- Catalog Track Search project (WXYC/projects/30)
- BS#871 —
library.search_doc extension; lands in this same surface area
Problem
apps/backend/routes/library.route.tsmounts three different library-search endpoints with overlapping responsibilities and no documentation explaining when to use which:GET /library/search{}(any JWT)requestLineController.searchLibraryEndpointGET /library/catalog:readlibraryController.searchForAlbumGET /library/querycatalog:readlibraryController.searchLibraryQueryEndpointA reader trying to add a new search-shape feature has to read three controllers and infer the boundaries. The differences (auth scope, search shape, response field set, ranking, what's filtered) aren't documented anywhere. Anyone trying to do a security audit has the same problem in reverse.
End state
JSDoc block on each controller (and matching prose on each route file line) that calls out:
NEXT_PUBLIC_CATALOG_TRACK_SEARCH_UI_ENABLEDon dj-site? backend-side flags?)Plus a top-of-file comment block in
apps/backend/routes/library.route.ts(or a siblingdocs/library-endpoints.mdif it grows) that lays out the three search variants as a single decision tree for future readers.Acceptance
searchLibraryEndpoint,searchForAlbum,searchLibraryQueryEndpointcovering: caller context, response shape, ranking/filter semantics, related flags.apps/backend/routes/library.route.tsthat names the three variants and points readers at the controller docstrings.GET /library/superseded by/library/querypost-Catalog-Track-Search), file a separate deprecation ticket. Do not delete in this PR.Why now
Surfaced during the endpoint-discipline review on 2026-05-21. Cheap doc work that prevents a class of "which endpoint should I call?" questions, and saves a future security audit hours.
Related
library.search_docextension; lands in this same surface area