books/docs/brainstorming-session-results.md

Brainstorming Session Results

Session Date: 2025-11-29 Facilitator: Business Analyst Mary 📊 Participant: Greg

---

Executive Summary

Topic: Book Reading Follow-Up App

Session Goals:

• Design a tactical app to track daily reading progress
• Meet book club deadlines
• Support reading multiple books simultaneously
• Calculate reading pace and pages needed to meet goals

Techniques Used:

1. Five Whys (Deep problem exploration) - ✅ COMPLETE
2. Morphological Analysis (Systematic component exploration) - ✅ COMPLETE

Total Ideas Generated: 9 core components fully explored with implementation decisions

Key Themes Identified:

• Book club accountability drives the core need
• Avoiding spoilers while maintaining enjoyment
• Need for simple, tactical progress tracking
• Cost-conscious single-user solution to start
• Mobile + web access required

---

Technique Sessions

Five Whys - 10 minutes

Description: Deep exploration of the root problem by asking "why" five times to uncover core motivations.

Ideas Generated:

1. Surface need: Track reading progress to meet book club deadlines
2. Level 2: Avoid being late prevents spoilers and maintains enjoyment
3. Level 3: Full participation enables nice, interesting discussions
4. Level 4: Discussions expose user to books outside normal reading preferences
5. Level 5 (Core): Broadens horizons, encourages thinking differently, appreciates diverse perspectives

Insights Discovered:

• The app serves book club accountability first and foremost
• Spoiler avoidance is a key pain point
• User values being challenged with unfamiliar books
• Book club creates social/intellectual engagement
• Not catastrophic to miss deadline, but diminishes experience

Notable Connections:

• Core purpose is intellectual growth, but user wants to focus on tactical features only
• Don't over-engineer toward "learning" or "growth" features
• Keep it simple: track pages, meet deadlines, stay on pace

User Decision: Focus on tactical needs, not deeper philosophical features

---

Morphological Analysis - ✅ COMPLETE

Description: Systematic exploration of app components and implementation options for each.

Core Components Explored:

1. ✅ Book Entry - Open Library API search
2. ✅ Daily Page Logging - Quick log from book list (mobile-first)
3. ✅ Progress Calculation - Pace-to-goal calculation
4. ✅ Multi-Book Management - One book at a time focus
5. ✅ Goal/Deadline Setting - Deadline only (simple)
6. ✅ Progress Visualization - Minimal text with color coding
7. ✅ Interactive Calendar View - Intensity heatmap + smart interactions
8. ✅ Data Persistence - Self-hosted database (Coolify)
9. ✅ Platform/Interface - PWA (React + Vite)

---

Component #1: Book Entry - DECIDED ✅

Options Explored:

• Manual entry (type title, author, pages)
• API lookup (Google Books, Open Library)
• Barcode/ISBN scan
• Import from Goodreads

User Reference: Obsidian Book Search Plugin workflow

• Simple search box (title/author/ISBN)
• API returns results with covers
• Click to select → auto-populates metadata
• Fast and easy (3 clicks)

Decision Made: Use Open Library API - https://openlibrary.org/search.json

Rationale:

• ✅ No API key required (user preference)
• ✅ Completely free
• ✅ Good book data (title, author, pages, covers)
• ✅ Search by title, author, ISBN
• ✅ Decent rate limits for single-user personal use
• ✅ Can switch to Google Books API later if needed

Implementation Notes:

• Search box: user types book title or author
• Query Open Library API
• Display results with cover images
• User clicks to select
• Auto-fill: title, author, total page count
• User adds deadline date
• Book added to library

---

Component #2: Daily Page Logging - DECIDED ✅

Options Explored:

• Manual text entry
• Number stepper/picker
• Quick log from book list
• Calendar-first entry
• Voice/scan entry
• Running total vs. daily snapshot

Decision Made: Quick Log from Book List

User Flow:

1. Open app → See list of currently reading books
2. Tap book → "Log Progress" button appears
3. Pop-up: "What page are you on?" with number input
4. Enter page number → Save
5. Done!

Implementation Notes:

• Primary device: Phone (mobile-optimized UI)
• Backfilling: User can tap any past date on calendar to log retrospectively
• Timing tracking: Not needed - just capture page number, not timestamp
• Quick entry: Minimize taps - tap book, enter number, save (3 actions total)
• Allow backfilling for missed days

Rationale:

• ✅ Mobile-first design for quick daily logging
• ✅ Minimal friction (3 taps to log)
• ✅ Backfill capability for forgotten days
• ✅ No complex timestamp tracking needed

---

Component #3: Progress Calculation - DECIDED ✅

Options Explored:

• Simple daily delta
• Pace-to-goal calculation
• Days remaining + pages remaining
• Ahead/behind indicator
• Projected finish date
• Multiple metrics dashboard

Decision Made: Pace-to-Goal Calculation

How It Works:

1. System calculates: (Pages Remaining) ÷ (Days Remaining) = Required Pages/Day
2. Tracks your actual pace from recent logging history
3. Compares: Required vs. Actual pace

Display Example:

• "Target: 50 pages/day to finish on time"
• "Your pace: 45 pages/day (last 7 days)"
• Status indicator: On track / Slightly behind / Need to catch up

Implementation Notes:

• Recalculates every time you log progress
• Uses rolling 7-day average for "your pace" (smooths out weekend vs. weekday variance)
• Clear, actionable number: "You need to read X pages/day"
• Visual indicator if you're on track or falling behind

Rationale:

• ✅ Directly supports goal of meeting deadlines
• ✅ Actionable information (tells you what to do)
• ✅ Accounts for variance in reading patterns
• ✅ Adjusts dynamically as deadline approaches

---

Component #4: Multi-Book Management - DECIDED ✅

Options Explored:

• Unified view (all books together)
• One book at a time focus
• Separate tracking per book
• Smart context switching
• Book status categories

Decision Made: One Book at a Time Focus

How It Works:

1. Primary Book displayed prominently at top
   • Shows pace calculation, progress, deadline
   • Quick "Log Progress" button front and center
2. Other Active Books shown below (collapsed or minimal)
   • Tap to expand and see details
   • Tap "Make Primary" to switch focus
3. Easy switching when you want to focus on a different book

Implementation Notes:

• Typically tracking 1-3 books with deadlines simultaneously
• User is usually more absorbed in one "current" book
• Primary book gets the spotlight in UI
• Other books accessible but not distracting
• Simple tap to switch which book is primary

Rationale:

• ✅ Reduces cognitive load (focus on one book at a time)
• ✅ Matches user's reading pattern (absorbed in one main book)
• ✅ Still supports multi-book tracking
• ✅ Makes daily logging simple (usually logging the primary book)

---

Component #5: Goal/Deadline Setting - DECIDED ✅

Options Explored:

• Deadline only
• Deadline + start date
• Flexible milestones
• "Days to read" input
• Auto-calculate from book club date

Decision Made: Deadline Only

How It Works:

1. When adding a book, user sets: "Finish by [Date]"
2. System calculates required pages/day from today until deadline
3. Adjusts automatically each day as deadline gets closer

Implementation Notes:

• Simple date picker: "When do you need to finish this book?"
• System assumes "start date" = today (or first logged page)
• Deadline can be edited anytime (book club rescheduled, etc.)
• Recalculates pace whenever deadline changes

Rationale:

• ✅ Minimal input required
• ✅ Focus on the constraint that matters (deadline)
• ✅ Flexible - works whether you've started or not
• ✅ Simple UX - one date picker

---

Component #6: Progress Visualization - DECIDED ✅

Options Explored:

• Simple progress bar
• Pace indicator gauge
• Calendar heat map
• Timeline view
• Minimal text-only
• Dashboard with multiple views

Decision Made: Minimal Text-Only with Green/Red Color Coding

Display Example:

📖 The Name of the Wind

312 pages left, 18 days remaining
Target: 50 pages/day
Your pace: 45 pages/day (last 7 days)

[Color-coded status indicator]
🟢 On track
🟡 Slightly behind
🔴 Need to catch up

Implementation Notes:

• Clean text-based display
• Key numbers prominent: pages left, days left, required pace
• Color coding for quick status check:
  • Green: Your pace ≥ target pace
  • Yellow: Within 10% of target
  • Red: Falling behind (>10% below target)
• Mobile-friendly: easy to read, no chart rendering

Rationale:

• ✅ Fastest to understand at a glance
• ✅ Minimal screen space
• ✅ Clear, actionable information
• ✅ No unnecessary graphics
• ✅ Works great on mobile

---

Component #7: Interactive Calendar View - DECIDED ✅

Options Explored:

Display:

• Read/no-read indicator
• Pages-read intensity
• Multi-book calendar
• Progress milestones

Interaction:

• Tap to log (backfill)
• Tap to view details
• Tap to edit
• Context-aware quick entry

Decision Made: Pages-Read Intensity + Progress Milestones with Smart Tap Interactions

Display Features:

1. Pages-Read Intensity

   • Color intensity based on pages read that day
   • Light → Few pages, Dark → Many pages
   • Visual pattern of reading activity over time

2. Progress Milestones

   • Deadline dates marked prominently
   • "Today" highlighted
   • Visual indicator of where you should be vs. where you are

Interaction Features:

1. Tap to Edit

   • Tap any logged date → View and edit page number
   • Fix mistakes or update entries
   • Full editing capability

2. Context-Aware Quick Entry

   • Tap past date → Backfill log (if missing) or edit (if exists)
   • Tap today → Quick log current page
   • Tap future date → View projected pace/milestones
   • Smart behavior based on date context

Implementation Notes:

• Calendar uses color intensity gradient (e.g., light blue → dark blue)
• Deadline dates have special marker (e.g., 🎯 or colored border)
• Single tap opens context-appropriate action
• Easy to backfill missed days or correct errors

Rationale:

• ✅ Quick visual scan of reading consistency
• ✅ Easy backfilling for missed days
• ✅ See deadlines in context
• ✅ Edit capability for mistakes
• ✅ Rich information without clutter

---

Component #8: Data Persistence - DECIDED ✅

Options Explored:

• Local storage only (browser/app)
• Cloud database (Firebase, Supabase, etc.)
• Self-hosted database (Coolify)
• Hybrid: Local-first + cloud sync
• Export/import capability

Decision Made: Self-Hosted Database on Coolify

Implementation Approach:

• Database runs as container on your Coolify instance
• Web + mobile apps connect to your hosted API
• All data stays on your infrastructure
• You control backups and data retention

Technology Options to Consider:

• PostgreSQL - Robust, well-supported, great for structured data
• SQLite (with Litestream) - Lightweight, simple, auto-backup to S3
• MongoDB - If you prefer document storage
• Supabase (self-hosted) - PostgreSQL + built-in REST API + auth

Implementation Notes:

• Containerized deployment (Docker)
• Data stays private on your server
• No third-party cloud dependencies
• No recurring API costs
• You manage backups (but already doing this for Coolify)

Rationale:

• ✅ Zero ongoing costs (already have Coolify)
• ✅ Full privacy and control
• ✅ No vendor lock-in
• ✅ Multi-device access (through your API)
• ✅ Fits your technical comfort level

---

Component #9: Platform/Interface - DECIDED ✅

Options Explored:

Architecture:

• Progressive Web App (PWA)
• Native mobile app + web app
• Hybrid framework (same code, multiple platforms)

Frontend Framework:

• React-based
• Vue-based
• Svelte/SvelteKit
• Flutter

Decision Made: Progressive Web App (PWA) with React + Vite

Architecture:

• Single codebase for mobile + desktop
• Accessed via browser
• "Add to Home Screen" for app-like experience
• No app store submission needed
• Containerized deployment on Coolify

Frontend Framework: React + Vite

Why:

• ✅ LLM Knowledge: React has the most training data - Claude Code excels at React
• ✅ Easiest Setup: npm create vite@latest → Choose React → Done
• ✅ Minimal Dependencies: Vite is lean and fast
• ✅ Best Documentation: Massive community, easy to find answers
• ✅ Modern Tooling: Fast dev server, hot reload, optimized builds
• ✅ PWA Support: Add vite-plugin-pwa for easy PWA configuration

Tech Stack Summary:

Frontend: React + Vite + TypeScript (optional)
Styling: Tailwind CSS or plain CSS
API Client: Fetch or Axios
State Management: React Context (built-in, no extra library needed)
Database: PostgreSQL on Coolify
API: Node.js/Express or Python/FastAPI
Deployment: Docker container on Coolify

Implementation Notes:

• Mobile-first responsive design
• PWA features: offline capability, home screen install
• Fast, lightweight
• Single containerized deployment

Rationale:

• ✅ Less hassle than native apps (no app stores)
• ✅ Single codebase = faster development
• ✅ Best LLM support for development assistance
• ✅ Minimal dependencies and complexity
• ✅ Great documentation and community

---

Must-Have Features (User Requirements)

1. ✅ Add books - Open Library API search
2. ✅ Daily page logging - Quick log from book list (mobile-first)
3. ✅ Calculate pages read per day - Pace-to-goal calculation with 7-day average
4. ✅ Support multiple books being read simultaneously - One book at a time focus (1-3 books)
5. ✅ Show total pages needed to meet goals - Minimal text with color coding
6. ✅ Interactive calendar view - Intensity heatmap + smart tap interactions

---

Technical Decisions

• Platform: Progressive Web App (PWA) - Mobile + Web
• Frontend: React + Vite
• Styling: Tailwind CSS or plain CSS
• Database: PostgreSQL on Coolify (self-hosted)
• API: Node.js/Express or Python/FastAPI
• Deployment: Docker container on Coolify (containerized)
• Target Audience: Single user initially (Greg)
• Budget: Zero ongoing costs (using existing Coolify infrastructure)

---

Action Planning

Current Status:

✅ Morphological Analysis: 100% complete (9 of 9 components decided)

Completed in This Session:

1. ✅ Morphological Analysis - All 9 core components explored and decided
   • Book entry: Open Library API
   • Daily page logging: Quick log from book list
   • Progress calculation: Pace-to-goal with 7-day average
   • Multi-book management: Primary book focus
   • Goal/deadline setting: Deadline only
   • Progress visualization: Minimal text with color coding
   • Interactive calendar: Intensity heatmap + smart interactions
   • Data persistence: Self-hosted PostgreSQL on Coolify
   • Platform/interface: PWA with React + Vite

Next Phase Tasks:

NOW: Convergent Phase - Organize and prioritize

• ✅ All technical decisions made
• ⏳ Categorize into MVP vs. Future features
• ⏳ Identify technical dependencies
• ⏳ Create implementation priority order

LATER: Synthesis Phase - Build actionable development plan

• Define data model (Books, ReadingLogs, etc.)
• Create development roadmap
• Break into implementation phases (MVP, v1.1, v2.0)
• Consider creating PRD or project brief

---

Reflection & Follow-up

What Worked Well:

• ✅ Five Whys uncovered deeper context while respecting user's tactical focus
• ✅ Morphological analysis provided systematic framework for exploring all 9 components
• ✅ Obsidian plugin reference gave clear UX inspiration for book entry
• ✅ Open Library API solves book entry without API key hassle
• ✅ Mobile-first approach aligns with primary use case
• ✅ Self-hosted infrastructure leverages existing Coolify setup
• ✅ React + Vite chosen for best LLM support during development
• ✅ All core decisions made efficiently in single session

Key Decisions Summary:

1. Book Entry: Open Library API with search
2. Daily Logging: Quick tap from book list (3-tap flow)
3. Progress Calc: Pace-to-goal with 7-day average
4. Multi-Book: Primary book focus (1-3 books tracked)
5. Deadlines: Simple deadline-only approach
6. Visualization: Minimal text with color coding
7. Calendar: Intensity heatmap + smart tap interactions
8. Data: Self-hosted PostgreSQL on Coolify
9. Platform: PWA with React + Vite

Questions Resolved:

• ✅ Should calendar show all books or one at a time? → Per-book calendar (selected from primary/other books)
• ✅ What happens if user forgets to log for several days? → Backfill capability via calendar tap
• ✅ Should there be reminders/notifications? → Not in MVP (keep it simple)
• ✅ What if user changes deadline mid-reading? → Deadline is editable, pace recalculates automatically
• ✅ Multi-book management approach? → Primary book + others accessible

Areas for Future Enhancement (Post-MVP):

• Reminders/notifications to log daily
• Reading statistics and insights (books per month, favorite genres, etc.)
• Social features (share with book club members)
• Integration with Goodreads for import/export
• Reading streaks and gamification
• Notes/highlights per book
• Book recommendations based on reading history

Next Steps:

• NOW: Move to Convergent Phase - Organize features into MVP vs. Future
• AFTER: Create Project Brief or PRD
• THEN: Define data model and API structure
• FINALLY: Begin development with clear roadmap

---

Session facilitated using the BMAD-METHOD™ brainstorming framework