SecondShelf

Help libraries choose a reviewable book display from reader taste and the books already on their shelves.

Comment

Inspiration

A recommendation is not very useful if the library has no copy to lend. I wanted to close that small but frustrating gap: begin with what is actually on the shelf, use a reader's volunteered film, music or book favourites as cultural signals, and still leave the final decision with a librarian.

What it does

SecondShelf turns a reviewed set of favourites and available books into a draft reading list. A librarian can:

  • search a sample catalogue and select only books with available copies;
  • review the identity matched to every favourite and candidate book;
  • ask Qloo to rank only that reviewed, available shelf;
  • exclude titles, narrow by category or change the list size;
  • approve the final draft and export CSV plus a complete evidence record.

The approval step is deliberate. A replaced draft cannot be approved, unresolved matches stop the workflow, and a short result stays short instead of being padded with invented recommendations.

How I built it

The local app uses Node.js and plain browser JavaScript. The public demo runs on a Cloudflare Worker with D1-backed state, signed review capsules and conservative network quotas.

In Qloo mode, the backend calls Search for the typed favourites and catalogue titles. After the librarian reviews those identities, Insights receives the favourite entity IDs as signals and the reviewed in-stock book IDs as the only allowed results. Qloo's returned order becomes the draft order. Credentials remain on the server, and a provider error stops the live action instead of silently swapping in sample data.

The workflow is deterministic—resolution, review, inventory grounding, ranking, refinement, approval and export—so every decision can be inspected later.

Qloo integration I verified

On October 14, I completed a small end-to-end run with the event-issued key: three Search requests resolved one film and two available books, I reviewed each match, and one Insights request produced a two-book draft. I approved that draft and exported its JSON and CSV evidence.

The raw provider records stay private because the event developer guide says not to publish Qloo response data. The public evidence records the date, request counts and workflow outcome without exposing returned identities or affinities.

The public sample workflow is fully usable without an account and labels its fixtures as synthetic. A hosted live request timed out on October 21 and returned a clear error with no fallback; I am not presenting that timeout as a hosted Qloo success. The verified live run was local.

Challenges

The hardest part was preserving identity. A query such as a title or artist name is not the same thing as the entity a person reviewed. SecondShelf stores both, rejects conflicting mappings, and keeps Qloo's actual response order instead of inventing a local score.

The other challenge was preventing stale approvals. Refinement creates a new revision, so the previous draft can no longer become the saved list. That sounds like a small detail, but it is what makes the human approval boundary meaningful.

What I learned and what I am proud of

Recommendation provenance is more than a number beside a title. It needs the original query, the reviewed identity, the constrained candidate set, the returned order and the human decision that followed.

The project now has 39 passing tests across the local and hosted workflows. They cover review, provider boundaries, streamed-response limits, quotas, refinement, approval conflicts, restart persistence and exports. I am proudest that the demo fails plainly: it never relabels authored sample rankings as live Qloo output.

What's next

I would investigate the hosted provider timeout, broaden book and edition coverage, add a real library-catalogue connector and test the workflow with librarians. The current catalogue and stock counts are fictional demonstration data, and the small live run does not claim measured recommendation quality or broad coverage.

Try it

Development note

Codex assisted with implementation, tests, documentation and browser verification. I made the product decisions and reviewed the final submission. The shipped application itself uses deterministic orchestration and no connected language model.

Built With

Share this project:

Updates

Submission history