books/docs/brief.md

# Project Brief: Book Reading Follow-Up App

**Project Name:** Book Reading Tracker (working title)
**Author:** Greg
**Facilitator:** Business Analyst Mary 📊
**Date:** 2025-12-01
**Version:** 1.0
**Status:** Planning

---

## Executive Summary

A mobile-first Progressive Web App designed to help book club members track daily reading progress and meet book club deadlines. The app calculates required reading pace, tracks actual progress, and provides clear visual feedback on whether users are on track to finish books on time. Built as a self-hosted solution leveraging existing Coolify infrastructure with zero ongoing costs.

**Key Value Proposition:** Never miss a book club deadline or suffer spoilers again. Simple, tactical tracking that tells you exactly how many pages to read per day to stay on schedule.

**Primary Problem:** Book club members need to finish books by specific deadlines to participate fully in discussions and avoid spoilers, but lack a simple tool to track progress and calculate required reading pace.

**Target Market:** Individual book club participants (starting with single-user deployment, Greg as initial user).

---

## Problem Statement

### Current State & Pain Points

Greg participates in book clubs with fixed discussion dates. Missing these deadlines has several negative consequences:
- **Spoiler exposure** - Late arrival or absence means discussions happen without you, spoiling the book
- **Diminished experience** - Partial participation reduces the quality of intellectual engagement
- **Lost opportunities** - Book clubs expose readers to books outside normal preferences, broadening horizons

Currently, there's no simple tool that:
- Tracks reading progress across multiple books simultaneously
- Calculates required daily pages to meet specific deadlines
- Provides actionable feedback on whether you're on track
- Works seamlessly on mobile (primary reading tracking context)

### Why Existing Solutions Fall Short

**Goodreads:**
- Social reading platform, not deadline-focused
- No pace calculation based on specific finish dates
- Overly complex for simple progress tracking

**Generic habit trackers:**
- Don't understand book-specific metrics (pages, deadlines)
- Require manual calculation of reading pace
- Not optimized for the book reading use case

**Manual tracking (spreadsheets, notes):**
- High friction for daily logging
- Requires manual math every time
- Lacks mobile-friendly UX

### Urgency & Importance

This is a recurring problem that happens with every book club selection. The solution needs to be:
- **Tactical** - Focus on the specific problem (meeting deadlines)
- **Low friction** - 3 taps to log progress daily
- **Mobile-first** - Accessible when and where reading happens
- **Cost-effective** - Leverage existing infrastructure (Coolify)

---

## Proposed Solution

### Core Concept

A Progressive Web App that combines:
1. **Book metadata** from Open Library API (no API key needed, free)
2. **Daily page logging** with minimal friction (quick tap workflow)
3. **Pace calculation engine** that compares required vs. actual reading pace
4. **Visual feedback** with color-coded status indicators
5. **Calendar view** showing reading activity and deadline milestones

### Key Differentiators

- **Deadline-first design:** Built specifically for meeting book club deadlines, not general reading tracking
- **Pace calculation focus:** Always shows "read X pages/day to finish on time"
- **Minimal UX:** 3-tap workflow to log progress (tap book → enter page → save)
- **Self-hosted:** No vendor lock-in, zero recurring costs, full privacy
- **PWA approach:** No app store hassle, works on all devices via browser

### Why This Will Succeed

1. **Solves a specific, recurring pain point** (book club deadlines)
2. **Extremely simple UX** (minimal friction for daily habit)
3. **Actionable information** (tells you exactly what to do)
4. **Leverages existing infrastructure** (Coolify instance already running)
5. **Built for actual user need** (designed through brainstorming with target user)

### High-Level Vision

A lightweight, focused tool that does one thing exceptionally well: helps you meet book reading deadlines. No social features, no gamification in MVP - just clear, actionable progress tracking that fits seamlessly into daily reading habits.

---

## Target Users

### Primary User Segment: Book Club Participant (Single User - Greg)

**Profile:**
- Active book club member with regular meeting schedules
- Reads 1-3 books simultaneously (at least one with a deadline)
- Values intellectual engagement and diverse reading experiences
- Comfortable with technology and self-hosted solutions
- Has existing Coolify infrastructure for containerized apps

**Current Behaviors & Workflows:**
- Reads books assigned by book club with fixed discussion dates
- Often reading multiple books at once (one primary focus book)
- Uses mobile phone as primary device for quick tasks
- Values simplicity and minimal cognitive load

**Specific Needs & Pain Points:**
- Needs to know if current reading pace will meet deadline
- Wants to avoid spoilers by finishing on time
- Needs quick daily logging (habit formation critical)
- Wants backfill capability for missed logging days
- Doesn't care about "when" reading happens, just "how much"

**Goals:**
- Finish book club books on time to participate fully in discussions
- Maintain enjoyment of reading (avoid pressure/stress)
- Track progress with minimal daily effort
- Stay exposed to books outside normal preferences

**Success Criteria for This User:**
- Logs reading progress in <10 seconds per day
- Understands at a glance whether on track to meet deadline
- Can easily manage 2-3 concurrent book club books
- Never misses a book club deadline due to poor planning

---

## Goals & Success Metrics

### Business Objectives

- **Build functional MVP** within 4-6 weeks of development start
- **Zero ongoing costs** - Fully self-hosted on existing infrastructure
- **Single user deployment** initially, with potential for future expansion
- **Prove concept** for potential broader use (book clubs, reading groups)

### User Success Metrics

- **Daily engagement:** User logs progress 5+ days per week
- **Deadline achievement:** User finishes ≥80% of books by deadline
- **Habit formation:** Continued use beyond first book club cycle
- **Time to log:** <10 seconds from app open to save
- **User satisfaction:** Tool becomes part of daily reading routine

### Key Performance Indicators (KPIs)

- **Logging frequency:** % of days with logged progress (target: 70%+)
- **Pace accuracy:** Average % difference between required and actual pace (target: ±10%)
- **Deadline success rate:** % of books finished on or before deadline (target: 80%+)
- **Time to log:** Average time from tap to save (target: <10 sec)
- **Session frequency:** Average days between app opens (target: ≤2 days)
- **Backfill usage:** % of entries that are backfilled vs. day-of (indicates UX friction)

---

## MVP Scope

### Core Features (Must Have)

- **Book Entry via Open Library API**
  - Search by title, author, or ISBN
  - Select from results with cover images
  - Auto-populate: title, author, total pages
  - Set deadline date
  - Add book to active reading list

- **Daily Page Logging**
  - Quick tap from book list
  - Pop-up: "What page are you on?"
  - Number input → Save
  - 3-tap workflow: Tap book → Enter page → Save

- **Pace-to-Goal Calculation**
  - Calculate: (Pages Remaining) ÷ (Days Remaining) = Required Pages/Day
  - Track actual pace using rolling 7-day average
  - Display: "Target: X pages/day" vs. "Your pace: Y pages/day"
  - Recalculate dynamically as deadline approaches

- **Progress Visualization**
  - Minimal text-based display
  - Key metrics: Pages left, days left, required pace, actual pace
  - Color-coded status indicator:
    - 🟢 Green: On track (actual ≥ required)
    - 🟡 Yellow: Slightly behind (within 10%)
    - 🔴 Red: Falling behind (>10% below target)

- **Basic Calendar View**
  - Show which days user logged progress
  - Highlight current date
  - Display deadline dates

- **PWA Foundation**
  - Mobile-responsive design
  - Works on mobile browsers
  - Basic offline capability
  - "Add to Home Screen" functionality

### Out of Scope for MVP

- Multi-book management (reading 2-3 books simultaneously)
- Calendar intensity heatmap (visual activity patterns)
- Calendar backfilling and editing past entries
- Advanced calendar interactions (context-aware tapping)
- Reminders/notifications
- Reading statistics and insights
- Social features (sharing with book club)
- Goodreads integration
- Notes/highlights per book
- Reading streaks or gamification
- User authentication (single-user deployment)
- Multiple user support

### MVP Success Criteria

**Functional:**
- User can add a book with a deadline
- User can log current page number daily
- System calculates and displays required pace vs. actual pace
- User can see at a glance if on track (color coding works)
- Data persists across sessions
- Works on mobile browser

**Non-Functional:**
- Page load time <2 seconds
- Log entry completes in <10 seconds
- Mobile-responsive on standard screen sizes
- Deployed successfully to Coolify
- Data backed up (standard PostgreSQL backup)

**User Validation:**
- Greg successfully uses app for one complete book club cycle
- Meets deadline for tracked book
- Continues using app for subsequent books

---

## Post-MVP Vision

### Phase 2 Features (v1.1)

**Enhanced Multi-Book Management:**
- Track 2-3 books simultaneously
- Primary book focus (one book prominent, others accessible)
- Easy switching between primary book
- Individual pace tracking per book

**Advanced Calendar Features:**
- Intensity heatmap (color gradient based on pages read)
- Backfill capability (tap past dates to log missed entries)
- Edit past entries (fix mistakes)
- Context-aware interactions:
  - Tap past date → Backfill or edit
  - Tap today → Quick log
  - Tap future date → View projections
- Deadline markers on calendar

**Enhanced Calculations:**
- Rolling 7-day average for smoother pace tracking
- Projected finish date based on current pace
- Ahead/behind indicator ("You're 2 days ahead")

### Long-term Vision (v2.0+)

**Personal Reading Insights:**
- Reading statistics (books/month, average pace, total pages)
- Reading patterns (weekday vs. weekend, seasonal trends)
- Genre preferences and diversity metrics

**Social & Sharing:**
- Share progress with book club members
- Book club group view (who's on track?)
- Discussion reminders tied to deadlines

**Enhanced Book Management:**
- Goodreads import/export
- Book recommendations based on reading history
- Notes and highlights per book
- Book ratings and personal reviews

**Gamification & Motivation:**
- Reading streaks
- Achievement badges
- Progress milestones
- Celebration animations for meeting deadlines

**Smart Features:**
- Reminders/notifications (daily log reminder, deadline approaching)
- Smart deadline suggestions based on reading pace history
- Auto-detect reading speed and adjust recommendations

### Expansion Opportunities

- **Multi-user hosting:** Allow others to deploy their own instances
- **SaaS offering:** Hosted version with user accounts and subscriptions
- **Book club features:** Groups, discussions, scheduling
- **Integration marketplace:** Goodreads, Kindle, Apple Books, library systems
- **Mobile native apps:** iOS and Android for better offline/notification support

---

## Technical Considerations

### Platform Requirements

- **Target Platforms:** Mobile (primary) + Desktop (secondary) via web browser
- **Browser/OS Support:**
  - Mobile: Chrome/Safari on iOS and Android (last 2 versions)
  - Desktop: Chrome, Firefox, Safari, Edge (last 2 versions)
- **Performance Requirements:**
  - Page load: <2 seconds on 3G connection
  - Log entry save: <1 second
  - Offline capability for basic viewing and logging (sync when online)

### Technology Preferences

**Frontend:**
- **Framework:** React 18+
- **Build Tool:** Vite
- **Language:** JavaScript (TypeScript optional for future)
- **Styling:** Tailwind CSS (utility-first, mobile-friendly)
- **State Management:** React Context API (built-in, no external library)
- **PWA:** vite-plugin-pwa for service worker and manifest

**Backend:**
- **API Framework:** Node.js with Express (lightweight, JavaScript consistency)
  - Alternative: Python with FastAPI (if Python preference)
- **API Style:** REST (simple, well-understood)
- **Authentication:** None for MVP (single-user)
  - Future: JWT tokens for multi-user

**Database:**
- **Primary DB:** PostgreSQL 15+
- **ORM:** Prisma (type-safe, great DX) or raw SQL
- **Migrations:** Managed via Prisma or custom migration scripts

**Hosting/Infrastructure:**
- **Platform:** Coolify (existing instance)
- **Containerization:** Docker + Docker Compose
- **Reverse Proxy:** Caddy or Nginx (via Coolify)
- **SSL:** Automatic via Coolify/Let's Encrypt
- **Backups:** PostgreSQL automated backups (Coolify managed)

### Architecture Considerations

**Repository Structure:**
```
books/
├── frontend/          # React + Vite PWA
│   ├── src/
│   ├── public/
│   └── Dockerfile
├── backend/           # Node.js + Express API
│   ├── src/
│   ├── prisma/
│   └── Dockerfile
├── docker-compose.yml # Local development
└── docs/              # Project documentation
```

**Service Architecture:**
- **Monorepo:** Frontend + Backend in single repo
- **Deployment:** Two containers (frontend, backend) + PostgreSQL
- **Communication:** Frontend → REST API → PostgreSQL
- **PWA Service Worker:** Cache-first strategy for offline support

**Integration Requirements:**
- **Open Library API:** HTTP requests to `https://openlibrary.org/search.json`
- **No authentication required** for Open Library
- **Rate limiting:** Respect Open Library's limits (cache book metadata)

**Security/Compliance:**
- **Data privacy:** All data self-hosted, no third-party analytics
- **HTTPS:** Required for PWA (handled by Coolify)
- **Input validation:** Sanitize all user inputs (XSS prevention)
- **SQL injection prevention:** Use parameterized queries/ORM
- **CORS:** Configure for frontend-backend communication

---

## Constraints & Assumptions

### Constraints

**Budget:**
- Zero ongoing costs (no SaaS, no cloud services)
- Uses existing Coolify infrastructure (already paid for)
- Open Library API is free (no API key required)

**Timeline:**
- Target: Functional MVP within 4-6 weeks of development start
- Flexible timeline (personal project, no external deadline)
- Iterative development approach (ship MVP, then enhance)

**Resources:**
- Single developer (Greg)
- AI-assisted development ("vibe coding" with Claude Code)
- No design resources (simple, functional UI)
- No QA team (manual testing by user)

**Technical:**
- Must be containerizable for Coolify deployment
- Must work on mobile browsers (no native app build process)
- Must be self-hostable (no vendor dependencies)
- Limited offline capability (PWA constraints)

### Key Assumptions

- Greg will consistently log reading progress (habit formation critical)
- Open Library API will remain free and available
- Single user deployment is sufficient for MVP validation
- Mobile browser PWA provides adequate UX (no native app needed)
- Coolify instance has sufficient resources (CPU, RAM, storage)
- PostgreSQL is appropriate for data model (no need for NoSQL)
- React ecosystem knowledge is sufficient for development
- Self-hosting is acceptable trade-off vs. managed services
- Book club deadlines provide sufficient motivation for usage
- Rolling 7-day average smooths reading pace variance adequately

---

## Risks & Open Questions

### Key Risks

- **Habit formation failure:** User forgets to log daily, app becomes unused
  - *Mitigation:* Ultra-simple 3-tap logging, mobile-first design, future: notifications

- **Open Library API reliability:** API downtime or rate limiting
  - *Mitigation:* Cache book metadata, fallback to manual entry, consider Google Books API backup

- **Reading pace variance:** User reads inconsistently (weekends vs. weekdays)
  - *Mitigation:* 7-day rolling average smooths variance, allows catch-up

- **Mobile UX challenges:** Browser-based PWA may have friction vs. native app
  - *Mitigation:* Extensive mobile testing, "Add to Home Screen" for app-like feel

- **Scope creep:** Temptation to add features before validating MVP
  - *Mitigation:* Strict MVP feature list, resist feature additions until MVP validated

- **Data loss:** No redundancy in single-instance deployment
  - *Mitigation:* Regular PostgreSQL backups, export capability in future version

### Open Questions

- Should the calendar show one book at a time, or all books overlaid?
- How to handle books without page numbers (eBooks with location numbers)?
- What happens if user finishes book early? (Celebrate? Suggest next book?)
- Should there be a "pause reading" feature for books on hold?
- How to handle reading multiple books on the same day? (Split pages logged?)
- What visual design style? (Minimal/text-heavy vs. more visual/colorful?)
- Should there be data export capability in MVP? (Backup/portability)

### Areas Needing Further Research

- **PWA offline capabilities:** How much offline functionality is realistic?
- **Mobile calendar UX:** Best practices for date picking and calendar interaction on small screens
- **Data visualization:** Simplest effective way to show reading patterns (if adding charts later)
- **Book metadata quality:** How consistent is Open Library data? (Page counts, covers)
- **Performance optimization:** What's the baseline performance with PostgreSQL + React?
- **Deployment automation:** Coolify best practices for multi-container apps

---

## Appendices

### A. Research Summary

**Brainstorming Session (2025-11-29):**
- Conducted Five Whys analysis to uncover root motivation
- Core insight: Book club accountability drives need, intellectual growth is deeper benefit
- User explicitly wants tactical features, not philosophical/learning enhancements
- Morphological analysis explored 9 core components with implementation options
- All major technical decisions made collaboratively

**Key Findings:**
- User typically reads 1-3 books with deadlines simultaneously
- Primary book receives most focus (absorbed in one book at a time)
- Mobile is primary context for logging (convenience critical)
- Backfilling is important (user sometimes forgets to log)
- Timing of reading not important (just amount/progress)
- User values simplicity over feature richness

**Competitive Landscape (Informal):**
- Goodreads: Social-focused, no deadline/pace features
- StoryGraph: Better than Goodreads for tracking, but still not deadline-focused
- Generic habit trackers: Don't understand book-specific metrics
- Spreadsheets: High friction, manual calculations

### B. Stakeholder Input

**Primary Stakeholder:** Greg (target user)
- Strong preference for self-hosted solution (privacy, control, cost)
- Existing Coolify infrastructure makes deployment straightforward
- Comfortable with technical implementation (will "vibe code" with AI assistance)
- Wants simple, focused tool (no over-engineering)
- Mobile-first usage pattern
- Values minimal dependencies and easy setup

### C. References

**Technical Resources:**
- [Open Library Search API](https://openlibrary.org/dev/docs/api/search)
- [Vite PWA Plugin](https://vite-pwa-org.netlify.app/)
- [React Documentation](https://react.dev/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Coolify Documentation](https://coolify.io/docs)

**Related Documents:**
- `docs/brainstorming-session-results.md` - Full brainstorming session transcript

---

## Next Steps

### Immediate Actions

1. **Review and approve this Project Brief** - Validate all decisions and assumptions
2. **Create Product Requirements Document (PRD)** - Detailed feature specifications
3. **Define database schema** - Books and ReadingLogs tables (draft exists in brainstorm doc)
4. **Set up development environment** - Initialize React + Vite frontend, Node.js backend
5. **Create GitHub repository** (optional) - Version control and backup
6. **Design basic UI mockups/wireframes** (optional) - Visual reference for implementation
7. **Set up Coolify deployment pipeline** - Docker configs, environment variables

### PM Handoff

This Project Brief provides the full context for **Book Reading Tracker**. The next step is to create a detailed Product Requirements Document (PRD) that translates these high-level decisions into specific, implementable feature requirements.

**Recommended Approach:**
- Use BMAD PM agent to facilitate PRD creation
- Work section-by-section through PRD template
- Reference brainstorming session results for technical details
- Keep MVP scope strict (resist feature creep)
- Define clear acceptance criteria for each feature

**Success Criteria for PRD:**
- All MVP features have detailed specifications
- User flows are documented with wireframes or descriptions
- API endpoints are defined
- Database schema is finalized
- Non-functional requirements are clear (performance, security, etc.)

---

*Project Brief created using BMAD-METHOD™ framework*
*Based on brainstorming session conducted 2025-11-29*