§ masterplan.md
Private Book Library
A classy minimal catalog for a personal book collection with reading stats, notes and lending tracker.
01
App overview and objectives
A private catalogue of the books you actually own: shelf view, reading stats, margin notes, and a record of what you lent to whom. It is a personal tool first, with optional public shelves.
02
The problem worth solving
Reading apps are social networks that happen to track books. Many readers want the opposite — a quiet, private record they own, including the awkward question of who still has their copy of that novel.
03
Target audience
- Primary — Serious readers with physical libraries of a few hundred books.
- Secondary — Small community or classroom libraries that lend informally.
04
Roles and permissions
- Visitor — read-only public pages, can sign up.
- Member — owns their own records, cannot see other users' data.
05
Core features
- Add books by ISBN scan, search or manual entry
- Shelf view with cover grid and physical location tags (room, shelf)
- Reading log with start/finish dates, ratings and progress
- Notes and quotes attached to page numbers, searchable across the library
- Lending record: who, when, reminder, returned
- Wishlist with price alerts or simple manual tracking
Deliberately later
- Public shelf sharing
- Import from other services
- Household multi-user libraries
06
Technical stack
React with offline-first local caching, Postgres backend, book metadata from an open bibliographic API.
Why: Cataloguing happens standing at a bookshelf, often with poor signal; entries must queue locally and sync later.
Alternatives: Spreadsheet (free, no scanning or notes) or an existing reading social network (feature-rich, your data lives with them).
07
Conceptual data model
Book — title, authors, ISBN, cover, publisher, year
Copy — book, owner, condition, location tag, acquired date
ReadingLog — copy, start, finish, rating, review
Note — copy, page, text, tags
Loan — copy, borrower, lent_on, due, returned_on
08
Integrations
- Open book metadata API
- Barcode scanning via device camera
- Optional export to CSV
09
UI design principles
- Generous whitespace, a two-font system, and a palette of three colours at most.
- Photography and typography do the work; borders, shadows and gradients stay almost invisible.
- Every screen has one clear primary action, placed in the same spot each time.
10
Security considerations
- Everything private by default; public shelves are an explicit per-shelf opt-in.
- Borrower names are personal data — keep them local to the owner's account.
- Full export and account deletion available without asking support.
11
Development phases
Phase 1 — Prove the core
- — Add books by ISBN scan, search or manual entry
- — Shelf view with cover grid and physical location tags (room, shelf)
- — Reading log with start/finish dates, ratings and progress
- — Static content and design system in place
- — Basic analytics
Phase 2 — Make it real
- — Notes and quotes attached to page numbers, searchable across the library
- — Lending record: who, when, reminder, returned
- — Wishlist with price alerts or simple manual tracking
- — Accounts, sign-in and password reset
- — Empty, loading and error states everywhere
Phase 3 — Polish and launch
- — Performance, accessibility and SEO pass
- — Legal pages, contact route and 404 handling
- — Wire up: Open book metadata API
- — Wire up: Barcode scanning via device camera
Phase 4 — Grow
- — Public shelf sharing
- — Import from other services
- — Household multi-user libraries
12
Challenges and solutions
Risk — Bulk entry is tedious
Solution — Continuous barcode scanning mode that adds books without leaving the camera.
Risk — Metadata gaps for local-language books
Solution — Manual entry with cover photo capture as a first-class path, not a fallback.
Risk — Sync conflicts across devices
Solution — Last-write-wins per field with a visible conflict log for notes.
13
Future expansion
- Neighbourhood lending network
- Reading goals and yearly review
- Insurance-ready collection valuation
14
Page list (13 pages)
- 01 PUBLIC Shelf — The library itself, browsable and searchable.
- 02 PUBLIC Stats — Pages, genres, pace and yearly review.
- 03 PUBLIC Notes — All quotes and margin notes, searchable.
- 04 PUBLIC Lent — What is out of the house and when it is due.
- 05 PUBLIC Wishlist — Books to acquire.
- 06 AUTH Sign up — Create an account with email or a social provider.
- 07 AUTH Log in — Return to the account, with error and lockout states.
- 08 AUTH Reset password — Request a reset link and set a new password.
- 09 APP (signed in) Account settings — Profile, email, password, language and delete account.
- 10 PUBLIC Contact — Contact form plus real address, phone and email.
- 11 LEGAL & SYSTEM Privacy policy — What data is collected, why, and how to remove it.
- 12 LEGAL & SYSTEM Terms of service — Rules of use, liability and account termination.
- 13 LEGAL & SYSTEM 404 not found — Friendly dead end with search and links back.
15
Page map
PUBLIC AUTH APP (signed in) LEGAL & SYSTEM ─────────── ───────────────── ─────────────────── ─────────────────── ├─ Shelf ├─ Sign up └─ Account settings ├─ Privacy policy ├─ Stats ├─ Log in ├─ Terms of service ├─ Notes └─ Reset password └─ 404 not found ├─ Lent ├─ Wishlist └─ Contact key flows: Shelf ──▶ Notes Shelf ──▶ Lent Wishlist ──▶ Shelf