Second Shelf

Inspiration

A shopper may know their favorite film before knowing their next author. A bookseller needs suggestions that respect what is actually on the shelf, what it costs, and the shop's judgment. Second Shelf connects cultural discovery to that practical bookstore workflow.

What it does

The public app runs the repaired candidate with live Qloo search and cultural ranking enabled. Inventory, prices, stores and checkout outcomes are explicitly synthetic. Qloo associations are real provider results; simulated comparison results are separately labeled. A persistent cap limits the demo to 100 Qloo calls per UTC day.

Booksellers review book identities and dated stock, save a selection, inspect a cultural proposal, and explicitly approve and activate its shopper display. Shoppers choose an interest and budget, reject unwanted suggestions, and take a counter code to staff. Authorized staff record fictional purchases, returns and corrections in an append-only ledger. The review view reports activity for an explicitly applied UTC period.

The candidate also exposes three read-only MCP tools. An external agent can inspect an active display, resolve a film or music interest, and request books constrained by the display's selection, available stock, confirmed identity, budget and rejected works. The agent cannot approve displays, reserve stock, take payments or record purchases.

How we built it

Second Shelf uses Next.js, React, TypeScript and PostgreSQL, with embedded PostgreSQL for isolated local reproduction. Its live integration uses Qloo search and insights for cultural associations. Application logic enforces eligibility, price, inventory, approval and access boundaries; cultural affinity is not treated as purchase probability.

The MCP interface lets an external agent use those capabilities without adding an embedded LLM planner. Tool results distinguish synthetic fixture data from live provider results. Live access is separately controlled by configuration, authorization and persistent usage accounting.

I am entering solo with AI assistance and no human teammates. Codex helped with implementation, debugging, automated tests and evidence preparation. AI-assisted development is separate from an agent using the application at runtime.

Challenges and verification

Book-title matches can be ambiguous. The first private Qloo test stopped when a title returned multiple matches. The authorized continuation reused two unique-title matches and verified MCP search, budget-constrained ranking and rejection. The two runs used six API calls in total. Unique titles are not independent edition or ISBN verification.

An actual assistant separately used MCP on synthetic data, chose tool inputs and explained alternatives. That is distinct from the scripted live-provider test. Local verification also covers browser journeys, cross-store access denial, purchase/return arithmetic, deletion, database persistence and MCP protocol behavior.

On October 29, the released candidate passed eleven automated hosted workflow checks: live health and database persistence, isolated store bootstrap, inventory import, owner approval and cross-store isolation, staff permissions, shopper discovery and rejection, MCP tools, stale handoff safeguards, purchase/return arithmetic, scoped export, and deletion/access revocation. Both transient test stores were independently confirmed deleted. A separate rendered-page check verified the live disclosure and a real film lookup. This release used seven Qloo calls with synthetic bookstore data; these are technical checks, not customer validation. A prior failed attempt was rolled back and its evidence preserved before the verifier correction and successful continuation.

The public repository now includes the October 29 stale-availability repair at commit 54862acb8052fbe34fb4931840ae5d377aa80db9. Handoff rechecks the selected book's current eligibility, including cached retries; stale cards clear the previous code and offer an explicit refresh. The exact 128-file public package passed 176 automated tests, and separate local browser, build, type, lint, API-contract and restoration checks passed. Those checks used synthetic data and an isolated declared-dependency runtime. This exact source is now released to the public app.

The outside tester confirmed to me that they used automated testing. I treat their walkthrough as automated feedback, not an unassisted human usability study. I have chosen to skip a separate human test for this hackathon release; no human-usability pass is claimed.

Try it

Start at https://second-shelf-liard.vercel.app/ and choose Try a bookstore demo. In Your inventory, review the identities for Piranesi and The Night Circus, confirming only matching book results. In Cultural displays, retain those eligible books, save the draft, approve it and activate it. Open the shopper experience, choose a film or musician and a budget, then request books. Recommendations use live Qloo associations with synthetic inventory. Unconfirmed books are excluded. A store and its dated stock expire after 24 hours; create a fresh demo from the canonical app if yours expires. Requests share a 100-call UTC-day Qloo cap. Use fictional outcomes only; do not enter real customer or payment data.

Temporary quick-start display, valid only until October 30 at 16:13 Eastern: https://second-shelf-liard.vercel.app/discover/b345a3b24ab7186cc732f3937d148825 . The canonical fresh-store path above remains the entry point after this display expires.

Source and local setup instructions: https://github.com/vijay-v-bhoyar/second-shelf . The read-only MCP endpoint is https://second-shelf-liard.vercel.app/mcp ; use an active public display token as described in the repository's MCP guide.

What we learned and what is next

A useful recommendation must remain connected to stock, identity and human approval. Making a suggestion is only part of the journey; the system also needs understandable rejection, counter verification and honest outcome reporting.

The public repository is MIT licensed. The current recording uses synthetic data. Qloo's hackathon guide permits private server-side response caching and prohibits placing response data in a public repository. Broader public redistribution and the applicable account scope remain unverified; the private integration test is not a blanket rights grant.

Next steps are to maintain and refresh the time-limited judge demo, confirm applicable provider-use terms, evaluate usability and the idea with booksellers after the hackathon. We have not demonstrated sales uplift, time savings, representative accessibility or superiority to an LLM-only system.

Built With

• neon
• next.js
• pglite
• playwright
• postgresql
• qloo
• react
• typescript
• vercel
• zod