Reading Tracker

Family reading tracker built with Next.js 15 and Firebase featuring achievements, activity feeds, and monthly calendar visualizations. The dashboard requires Firebase email/password auth before it loads any data.

Prerequisites

• Node.js 22+
• npm 10+
• Firebase CLI (npx firebase --version)
• Access to the Firebase project reading-tracker-7a90d

Getting Started

1. Install dependencies:

   npm install

2. Copy the environment template and populate the Firebase web config plus the allowed email list:

   cp .env.local.example .env.local
   # Fill NEXT_PUBLIC_FIREBASE_* and NEXT_PUBLIC_ALLOWED_EMAILS

3. (Optional) Start the Functions + Firestore emulators in another terminal:

   npm --prefix functions run serve -- --only "functions,firestore"

4. Launch the Next.js dev server:

   npm run dev

Authentication

Accounts are provisioned manually in Firebase Authentication. Create email/password users for the family members and list their emails in NEXT_PUBLIC_ALLOWED_EMAILS so the login screen accepts them. The app signs users out via the Firebase web SDK.

Firebase Tooling

• Functions code lives in functions/ and is written in TypeScript.
• Deploy Functions only:

  npm --prefix functions run deploy

• Run the Firebase emulators (Functions + Firestore):

  npm --prefix functions run serve -- --only "functions,firestore"

  When emulators are running, set NEXT_PUBLIC_HELLO_ENDPOINT in .env.local so the UI points at the local function.

Deploying to Firebase

1. Build the static Next.js site:

   npm run build:static

2. Deploy Hosting, Functions, Firestore rules, and indexes:

   npm run firebase:deploy

Features

• Reading Log Form: Log daily reading by minutes, pages, or books with optional book title/author
• Live Statistics: Current streak, last log date, and totals for minutes, pages, and books
• Achievements System: 20 milestone badges across streak, pages, minutes, and books categories
• Recent Activity Feed: Last 10 reading entries with book details
• Monthly Overview: Calendar heatmap showing logged days, monthly stats, and completion percentage
• Book-Themed Design: Warm, calm UI with amber/orange gradients and book icons
• Theme Toggle: Choose light, dark, or system mode (respects OS preference by default)
• Mobile Responsive: Optimized layout for all screen sizes with proper overflow handling

PDF Imports

Use the built-in CLI to import Beanstack log summary PDFs directly into Firestore:

# Preview the parsed rows without writing data
node scripts/import-pdf.js path/to/Log-Summary-ReaderA.pdf reader-a --dry-run

# Run without --dry-run to import into readers/<readerId>/logs
node scripts/import-pdf.js path/to/Log-Summary-ReaderB.pdf reader-b

Each row is stored as readers/<readerId>/logs with matching importBatches metadata. The parser handles multi-line titles/authors and page breaks, so no external scripts/repositories are required.

Next Steps

• Performance optimization: Materialize stats into readers/{readerId}/dailyStats for faster loads
• Multi-reader support: Add UI for selecting/managing multiple readers
• Data export: Add CSV export functionality
• Add automated tests for the auth flow and data components