The first idea was a personal tracker: pull the collections together, rate what I’d read, stop doubling up. The original plan also had a second idea tucked inside it, recommendations chosen around a reader’s taste with no stock to shift. By September that second idea had become the whole point.
Between February and September, Shelfie moved from a library tracker with recommendations to a recommendation service that starts from your library. Getting there meant rebuilding the foundations, changing direction, painting a fair few books, and learning that an empty result can hide several different failures.
February: start with the books you already have
The first working version went up on 22 Feb 2026. Google sign-in, and each reader’s collection stored in a spreadsheet in their own Google Drive.
I kept that foundation modest on purpose. The data sat with the person it belonged to, and Shelfie could get on with importing, organising and rating books.
The early history is a catalogue of what happens when real collections meet software. Pasted library pages dragged navigation text in with them. Author names arrived doubled. Titles landed in the author field and the other way round. Verification turned up duplicates the first imports had missed.
Every one of those fixes mattered, because everything downstream depends on knowing which books the library holds.
The look started to arrive then too: warm colours, serif type, covers, and a bookshelf built from the reader’s own collection. Even at that stage I wanted Shelfie to feel like somewhere a reader would want to spend time.
July: rebuild the foundations, then question the failures
In July, Shelfie merged with the catalogue direction from my Bookscanner project. Google Sheets and the original sign-in gave way to Supabase: database-backed libraries, with access rules around each reader’s records.
Search, covers and verification moved to Google Books, with Open Library kept as a second source.
The recommendations taught me the most. A model asked to name real books will also name plausible books that don’t exist, so Shelfie had to check every suggested title and author against catalogue records.
Then the checking grew a problem of its own: when a catalogue was down, a real book could vanish.
An unsuccessful lookup hides three different outcomes: a matching record, a search that found no match, and a service we couldn’t reach. Each deserves different handling. The verification logic now keeps them apart, and a failed lookup no longer counts as evidence against the book. [Verification implementation (src/lib/verifyBook.ts)]
Another empty-results bug turned out to live in our own parser. The model would sometimes produce a short false start and then a proper list. The extraction logic swallowed both as one block and failed to parse it.
What I took from that: before blaming the model, inspect the machinery handling its answer.
September: make recommendations the product
On 04 Sep 2026 the direction became explicit.
I set aside an earlier focus on Australian young-adult readers; the project notes record that the data source it depended on never materialised. Shelfie widened its audience and put recommendations at the centre.
That moved the front door. Importing a whole library should not be the price of admission. Onboarding now asks for a handful of books and what the reader wants next, and preferences offer another way in. [Onboarding implementation (src/app/start/page.tsx)]
It also raised the bar for a recommendation. A title and author were no longer enough. Each suggestion now carries an explanation, the reader’s own signals behind it, and a caveat where one belongs: why this might work, and why it might not.
Readers got a way to push back as well. “Not for me” can carry a reason, so later recommendations can answer the objection itself. [Recommendation implementation (src/lib/claude.ts)]
The ambition narrowed into something I could build: help someone see why a book might suit them, and give them a useful way to disagree.
Give the recommendation somewhere to go
A promising book raises the next question straight away: where do I get it?
Shelfie added independent bookshops, bookseller shelves and borrowing options. I wanted the commercial line drawn before the first listing went in:
Money can buy where you buy a book. It can never buy what you’re told to read.
The recommendation code takes reading signals, preferences and feedback. The shop layer runs afterwards. Paid listings are labelled, and ordering puts locality ahead of a shop’s paid tier. [Shop ordering (src/lib/db/bookshops.ts) · Where-to-find-it panel (src/components/WhereToFindIt.tsx)]
Bookseller recommendations got their own attributed space. Calling them “shelf talkers” pulled the language back towards the cards booksellers tuck under a title on the shelf.
Building the directories was less glamorous: finding sources, resolving links, fixing locality matching. A library around the corner should not lose to an alphabetically earlier service because its location data is missing.
Find the right room for it
The interface changed a lot over the same stretch.
The early bookshelf grew more elaborate, then simpler, and eventually gave way to a painted to-be-read pile. Gouache book textures and a painted room gave Shelfie a setting of its own.
The history is full of corrections to contrast, spine legibility, backgrounds and the footer. The paint had to serve the reading.
The pile had to mean something too. A finished book shouldn’t sit there telling you to read it. Later the pile got its own page, and a way to reach it on a phone.
Let physical shelves become an input
September also brought photo import.
Take a photo of a shelf and Shelfie reads the spines, checks the candidates and lays them out for review. What matters is how it handles doubt. Confirmed matches, unmatched candidates and unchecked candidates stay in separate piles, and only confirmed matches start selected. [Photo triage implementation (src/lib/shelfTriage.ts)]
The photograph becomes a first draft the reader can correct.
Daily quotas and a cap on verification requests shipped with it. One photo can set off a lot of external lookups, and that has to stay manageable.
From a library directory to “has it”
The next borrowing step was connecting books to library holdings through Trove.
The directory settled on the Australian Libraries Gateway, with Trove supplying holdings lookups. Cached holdings expire, and service failures never enter the negative-result cache.
That last rule carries weight. A lookup that times out once should not harden into a stored claim that the library doesn’t have the book. [Holdings implementation (src/lib/db/holdings.ts)]
One visual check is still open in the project notes: watching the “has it” badge appear in a signed-in reader’s recommendation panel. That’s a narrower claim than saying the whole experience is verified, and I’d rather make the narrow one.
Keep the recommendations worth returning to
The latest work, dated 17 Sep 2026, makes recommendations persistent.
Discover now pulls back saved cards with their explanations, signals and caveats. Recent suggestions nobody has acted on form the active list; older or acted-on ones move to an archive. Older records saved without an explanation get handled separately, so they don’t turn up as empty cards. [Saved recommendation implementation (src/lib/db/recommendations.ts)]
A later note records the production migration and deployment, and leaves the signed-in reload check open. I’m keeping that distinction in public: deployed and observed working are separate milestones.
Where Shelfie stands
Operational work ran underneath all of it: sign-in repairs, email configuration, database moves, missing credentials, clearer handling of failed searches. None of it is as pretty as a painted room. All of it decides whether anyone reaches the useful part.
AI sits in both the build and the product, and the history keeps showing where its output needed parsing, catalogue checks, explicit uncertainty and a human reading it over.
Shelfie has a far clearer purpose than the one it started with: understand something about how you read, suggest a book with reasons you can examine, and help you find somewhere to buy or borrow it.
The next check is small and concrete. Sign in, ask for recommendations, reload Discover, and see whether the cards are still there.