# matthewlbitz/shelf-lookup architecture

> Architecture diagram of the GitHub repository matthewlbitz/shelf-lookup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matthewlbitz/shelf-lookup
- Repository: https://github.com/matthewlbitz/shelf-lookup

## Overview

KTRU Shelf Lookup is a local web application for managing a physical music collection. Operators search the catalog, assign or scan barcodes, and use guided stacks to move records through assignment, column sorting, and shelf placement; progress is persisted for later resumption. Separate workflows support artist-name sorting and legacy batch handoffs. The graph includes the indexed core modules and documented capabilities; some browser-to-server links are based on README descriptions because those page implementations were not excerpted.

Main entry points: [`server.js`](https://github.com/matthewlbitz/shelf-lookup/blob/main/server.js) (HTTP server), [`discogs-lookup.js`](https://github.com/matthewlbitz/shelf-lookup/blob/main/discogs-lookup.js) (UPC lookup), [`workflow-store.js`](https://github.com/matthewlbitz/shelf-lookup/blob/main/workflow-store.js) (Guided workflow API), [`masterAlbums.db`](https://github.com/matthewlbitz/shelf-lookup/blob/main/masterAlbums.db) (Collection database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator_workflows["Operator workflows"]
  node_catalog_ui["Catalog tools<br/>[index.html]"]
  node_guided_ui["Guided stacks<br/>[workflow.html]"]
  node_guided_client["Workflow client<br/>[workflow.js]"]
  node_batch_ui["Batch sorting<br/>[batch-sort.js]"]
  node_receive_ui["Stack receiving"]
  node_receive_client["Stack receiver<br/>[receive-stacks.js]"]
  node_artist_ui["Artist sorter<br/>[artist-sorter.html]"]
end

subgraph group_catalog_services["Catalog services"]
  node_server["HTTP server<br/>[server.js]"]
  node_catalog_utils["Catalog normalization<br/>[catalog-utils.js]"]
  node_search_rank["Search ranking<br/>[search-ranking.js]"]
  node_ordered_search["Ordered barcodes<br/>[ordered-search.js]"]
  node_discogs["UPC lookup<br/>[discogs-lookup.js]"]
  node_discogs_service["Discogs API"]
end

subgraph group_artist_sorting["Artist sorting"]
  node_artist_resolution["Artist rules"]
  node_artist_resolver["Artist resolver<br/>[resolve-artists.js]"]
  node_musicbrainz["MusicBrainz"]
end

subgraph group_persistence["Persistence"]
  node_workflow_store["Guided workflow API<br/>[workflow-store.js]"]
  node_shared_stacks["Shared stack API<br/>[shared-stacks.js]"]
  node_database[("Collection database<br/>[masterAlbums.db]")]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_catalog_ui
node_operator -->|"uses"| node_guided_ui
node_operator -->|"uses"| node_artist_ui
node_catalog_ui -->|"requests catalog actions"| node_server
node_guided_ui -->|"runs workflow"| node_guided_client
node_guided_client -.->|"updates stacks"| node_workflow_store
node_workflow_store -->|"reads and writes"| node_database
node_workflow_store -->|"uses barcode ranges"| node_ordered_search
node_batch_ui -->|"looks up barcodes"| node_server
node_batch_ui -.->|"hands off stacks"| node_shared_stacks
node_receive_ui -->|"runs receiver"| node_receive_client
node_receive_client -.->|"claims and advances"| node_shared_stacks
node_shared_stacks -->|"stores handoffs"| node_database
node_artist_ui -->|"requests sort actions"| node_server
node_server -->|"queries and updates"| node_database
node_server -->|"installs routes"| node_workflow_store
node_server -->|"fills local values"| node_artist_resolution
node_server -->|"looks up UPCs"| node_discogs
node_server -->|"imports utilities"| node_catalog_utils
node_server -->|"uses ranking"| node_search_rank
node_search_rank -->|"normalizes queries"| node_catalog_utils
node_discogs -->|"normalizes UPCs"| node_catalog_utils
node_discogs -->|"ranks suggestions"| node_search_rank
node_discogs -->|"queries releases"| node_discogs_service
node_artist_resolver -->|"uses shared rules"| node_artist_resolution
node_artist_resolver -->|"queries artists"| node_musicbrainz
node_artist_resolver -->|"reads and updates"| node_database

click node_catalog_ui "https://github.com/matthewlbitz/shelf-lookup/blob/main/index.html"
click node_guided_ui "https://github.com/matthewlbitz/shelf-lookup/blob/main/workflow.html"
click node_guided_client "https://github.com/matthewlbitz/shelf-lookup/blob/main/workflow.js"
click node_batch_ui "https://github.com/matthewlbitz/shelf-lookup/blob/main/batch-sort.js"
click node_receive_ui "https://github.com/matthewlbitz/shelf-lookup/blob/main/receive-stacks.html"
click node_receive_client "https://github.com/matthewlbitz/shelf-lookup/blob/main/receive-stacks.js"
click node_artist_ui "https://github.com/matthewlbitz/shelf-lookup/blob/main/artist-sorter.html"
click node_server "https://github.com/matthewlbitz/shelf-lookup/blob/main/server.js"
click node_catalog_utils "https://github.com/matthewlbitz/shelf-lookup/blob/main/catalog-utils.js"
click node_search_rank "https://github.com/matthewlbitz/shelf-lookup/blob/main/search-ranking.js"
click node_ordered_search "https://github.com/matthewlbitz/shelf-lookup/blob/main/ordered-search.js"
click node_discogs "https://github.com/matthewlbitz/shelf-lookup/blob/main/discogs-lookup.js"
click node_workflow_store "https://github.com/matthewlbitz/shelf-lookup/blob/main/workflow-store.js"
click node_shared_stacks "https://github.com/matthewlbitz/shelf-lookup/blob/main/shared-stacks.js"
click node_database "https://github.com/matthewlbitz/shelf-lookup/blob/main/masterAlbums.db"
click node_artist_resolution "https://github.com/matthewlbitz/shelf-lookup/blob/main/artist-resolution.js"
click node_artist_resolver "https://github.com/matthewlbitz/shelf-lookup/blob/main/resolve-artists.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_catalog_ui,node_guided_ui,node_guided_client,node_batch_ui,node_receive_ui,node_receive_client,node_artist_ui toneBlue
class node_server,node_catalog_utils,node_search_rank,node_ordered_search,node_discogs,node_discogs_service toneAmber
class node_artist_resolution,node_artist_resolver,node_musicbrainz toneMint
class node_workflow_store,node_shared_stacks,node_database toneRose
class node_operator toneIndigo
```

## Components

### Operator workflows

- [Catalog tools](https://github.com/matthewlbitz/shelf-lookup/blob/main/index.html): `index.html`
- [Guided stacks](https://github.com/matthewlbitz/shelf-lookup/blob/main/workflow.html): `workflow.html`
- [Workflow client](https://github.com/matthewlbitz/shelf-lookup/blob/main/workflow.js): `workflow.js`
- [Batch sorting](https://github.com/matthewlbitz/shelf-lookup/blob/main/batch-sort.js): `batch-sort.js`
- [Stack receiving](https://github.com/matthewlbitz/shelf-lookup/blob/main/receive-stacks.html): `receive-stacks.html`
- [Stack receiver](https://github.com/matthewlbitz/shelf-lookup/blob/main/receive-stacks.js): `receive-stacks.js`
- [Artist sorter](https://github.com/matthewlbitz/shelf-lookup/blob/main/artist-sorter.html): `artist-sorter.html`

### Catalog services

- [HTTP server](https://github.com/matthewlbitz/shelf-lookup/blob/main/server.js): `server.js`
- [Catalog normalization](https://github.com/matthewlbitz/shelf-lookup/blob/main/catalog-utils.js): `catalog-utils.js`
- [Search ranking](https://github.com/matthewlbitz/shelf-lookup/blob/main/search-ranking.js): `search-ranking.js`
- [Ordered barcodes](https://github.com/matthewlbitz/shelf-lookup/blob/main/ordered-search.js): `ordered-search.js`
- [UPC lookup](https://github.com/matthewlbitz/shelf-lookup/blob/main/discogs-lookup.js): `discogs-lookup.js`
- **Discogs API**

### Artist sorting

- [Artist rules](https://github.com/matthewlbitz/shelf-lookup/blob/main/artist-resolution.js): `artist-resolution.js`
- [Artist resolver](https://github.com/matthewlbitz/shelf-lookup/blob/main/resolve-artists.js): `resolve-artists.js`
- **MusicBrainz**

### Persistence

- [Guided workflow API](https://github.com/matthewlbitz/shelf-lookup/blob/main/workflow-store.js): `workflow-store.js`
- [Shared stack API](https://github.com/matthewlbitz/shelf-lookup/blob/main/shared-stacks.js): `shared-stacks.js`
- [Collection database](https://github.com/matthewlbitz/shelf-lookup/blob/main/masterAlbums.db): `masterAlbums.db`

### Other components

- **Operator**

## Connections

- Operator → Catalog tools: uses (evidence: `README.md`)
- Operator → Guided stacks: uses (evidence: `README.md`)
- Operator → Artist sorter: uses (evidence: `README.md`)
- Catalog tools → HTTP server: requests catalog actions (evidence: `README.md`)
- Guided stacks → Workflow client: runs workflow (evidence: `README.md`)
- Workflow client → Guided workflow API: updates stacks
- Guided workflow API → Collection database: reads and writes (evidence: `README.md`)
- Guided workflow API → Ordered barcodes: uses barcode ranges (evidence: `workflow-store.js`)
- Batch sorting → HTTP server: looks up barcodes (evidence: `batch-sort.js`)
- Batch sorting → Shared stack API: hands off stacks (evidence: `README.md`)
- Stack receiving → Stack receiver: runs receiver (evidence: `README.md`)
- Stack receiver → Shared stack API: claims and advances
- Shared stack API → Collection database: stores handoffs (evidence: `README.md`)
- Artist sorter → HTTP server: requests sort actions (evidence: `README.md`)
- HTTP server → Collection database: queries and updates (evidence: `README.md`)
- HTTP server → Guided workflow API: installs routes (evidence: `server.js`)
- HTTP server → Artist rules: fills local values (evidence: `server.js`)
- HTTP server → UPC lookup: looks up UPCs (evidence: `server.js`)
- HTTP server → Catalog normalization: imports utilities (evidence: `server.js`)
- HTTP server → Search ranking: uses ranking (evidence: `server.js`)
- Search ranking → Catalog normalization: normalizes queries (evidence: `search-ranking.js`)
- UPC lookup → Catalog normalization: normalizes UPCs (evidence: `discogs-lookup.js`)
- UPC lookup → Search ranking: ranks suggestions (evidence: `discogs-lookup.js`)
- UPC lookup → Discogs API: queries releases (evidence: `discogs-lookup.js`)
- Artist resolver → Artist rules: uses shared rules (evidence: `resolve-artists.js`)
- Artist resolver → MusicBrainz: queries artists (evidence: `resolve-artists.js`)
- Artist resolver → Collection database: reads and updates (evidence: `resolve-artists.js`)
