Skip to content

roadmap.md

Latest commit

 

History

History
498 lines (384 loc) · 22.7 KB

roadmap.md

File metadata and controls

498 lines (384 loc) · 22.7 KB

Roadmap

This roadmap outlines the development priorities for Readr. It balances the current lightweight version with a clear path toward a full-stack MERN application.

🎯 Goals

  • Provide a minimal, offline-first reading log (v1.0).
  • Gradually evolve into a MERN-based app with cloud sync and advanced features.
  • Maintain clarity and simplicity at each stage.

📌 Milestones

✅ Version 1.0 — Core MVP Release

  • Core CRUD (Add books, display list) AC: I can add a book and see it in the list; it stays after refresh.
  • Import/Export JSON backups AC: Export downloads a JSON file; importing the same file restores books.
  • Persist data in localStorage AC: Books remain after closing/reopening browser.
  • Seed data for demos AC: Demo books show up on first use.
  • SemVer release tagging AC: A v1.0.0 tag after completion, with short release notes.

Released: Sep 2025

✅ Version 1.1 — Usability & Goals Update

  • Sorting and filtering AC: Sort by title/author/date; filter by status (e.g., “Reading”).
  • Clear messages for import/export AC: Shows “Import successful” or “Error: invalid file.”
  • Expanded sample seed data AC: At least 10 demo books with different statuses.
  • Small UI fixes AC: Buttons spaced evenly; text easy to read.

Released: Sep 2025

✅ Version 1.2 — Branding & PWA Polish

  • Make installable (PWA manifest + service worker) AC: Can install to desktop/phone; opens offline.
  • JSON schema versioning (prep for future updates) AC: Backup file includes a version number. (pushed to v1.3.0)
  • Logos, favicon, and branding polish AC: Teal and monochrome white wordmark + slogan, favicons, updated README/docs.
  • Toast notifications & empty states AC: Consistent styles, goal/streak widget polished.
  • Social preview assets AC: Teal (GitHUb), dark (PWA demo), monochrome white (docs/blog).
  • Added BRAND_ASSETS.md and PWA.md docs AC: Brand usage guidelines + PWA install guide.

Released: Sep 2025

✅ Version 1.3 — Header & Accessibility Refresh

  • Consolidated header into a single #toolbar Ac: App logo left, settings gear right; no duplicate headers or slogans.
  • Settings dropdown menu Ac: Gear opens animated dropdown; click outside or Esc closes.
  • Full keyboard navigation & accessibility Ac: ↑/↓/Home/End to move; Enter/Space to activatel menuitems have correct roles (menuitem, menuitemcheckbox).
  • Theme toggle with ARIA state Ac: Switch Mode uses menuitemcheckbox; aria-checked reflects dark/light mode.
  • Theming tokens updated Ac: Added --hover-bg with light/dark values; separated --border and --track.
  • Removed legacy classes Ac: .brand, .wordmark, .logo, .slogan deleted from CSS/HTML.

Released: Sep 2025

✅ Version 1.4 — Power-User Features

  • Undo for mistakes AC: Recover a book or session after delete/finish within ~6s window.
  • Inline editing AC: Edit book details in-place; save/cancel flows work without re-adding.
  • Smarter search AC: Support fuzzy/typo tolerance and partial tokens (“Hobbot” → Hobbit, “har pot” → Harry Potter).
  • Session history view AC: Paginated table; edit/save/delete row actions; Undo restores last delete.
  • Install app button in Settings AC: Green action; hybrid flow (retry if dismissed, disable after accepted).
  • Install status pill beside Install app AC: Small badge shows Unavailable → Ready → Installed; updates live without reload.
  • One-click Reset Preferences AC: Grey action in Settings; clears filters/sort and re-renders list.
  • Predictable updates AC: “Check updates” reloads app when a new Service Worker takes over.
  • Modular refactor AC: app.js slimmed down into features/, utils/, ui/ modules; smoke tests cover Undo, Install, storage migration.

Released: Sep 2025

✅ Version 1.5 — Book Enhancements

  • Add Series / Stand-alone flag for books
    • AC: User can mark book as part of a series or stand-alone.
  • Add Digital/ Physical flag for books
    • AC: User can mark book as physical or digital.
  • Optional IBSN field
    • AC: ISBN field is optional and stored if provided.
  • Dropdown auto-suggest in logs based on author, series, genre
    • AC: When typing in logs, suggestions appear from existing metadata.
  • Switch status flow: Planned → Reading → Finished (buttons styled to match theme/mode)
    • AC: User can change status via consistent theme-colored buttons
  • Bulk edit for status/genre
    • AC: Select multiple books and change their status or genre at once.
  • A11y: field labels and bulk-edit modals fully operable via keyboard

Released: Sep 2025

✅ Version 1.6 — Search & Filters

  • Add dedicated Search button (in addition to instant search)
    • AC: Search can be triggered explicitly via button.
  • Autocomplete suggestions for queries (author, title, series, genre)
    • AC: Typing in search shows dropdown of likely matches.
  • Advanced filters (multi-select for genre/status)
    • AC: User can filter by multiple genres or statuses simultaneously.
  • Save favorite searches/filters
    • AC: User can save a filter combo and reapply it with one click.
  • Clear all filters button
    • AC: Reset restores unfiltered book list instantly.

Released: Oct 2025

✅ Version 1.7 — Goals & Layout Polish

  • Extra spacing between daily goal inputs and progress bar
    • AC: Inputs and progress bar visually separated for clarity.
  • Better layout for book goals (monthly/yearly targets grouped visually)
    • AC: Monthly and yearly goal inputs clearly grouped with save button.
  • Browse past goals from previous months/years
    • AC: User can view and scroll through archived goals.
  • Weekly/monthly summaries + streak indicators
    • AC: App shows summaries and highlights streak progress.
  • Goal reminder notifications (optional)
    • AC: User can opt in to daily/weekly reminders about goals.
  • A11y: summaries and streaks announced by screen readers

Released: Nov 2025

✅ Version 1.8 — Sessions & History

  • Add search highlighting to book titles and notes
    • AC: Highlight matching tokens and preserve styling through filters.
  • Improve Session History keyboard navigation
    • AC: ArrowUp/Down, Home/End cycle rows with proper focus and live-region updates.
  • Add truncation + tooltip for long notes
    • AC: Ellipsis on overflow; tooltip on hover; full text visible on row edit.
  • Add small A11y improvements to session table
    • AC: Live region updates for row selection, filter changes, and empty states.
  • Optimize Session History rendering
    • AC: Memoize sorted logs; precompute date keys; patch rows incrementally.
  • Add Session import/export support
    • AC: Sessions included in full backups; sessions-only export/import; safe merge & dedupe.

Released: Dec 2025

✅ Version 1.9 — Visualization & Motivation

  • Basic charts (per-book progress, per-day trends)
    • AC: User can view charts generated from session data; includes per-book progress + per-day/weekly trend; charts update automatically when sessions change; supports light/dark mode.
  • Badges for hitting goals (light gamification)
    • AC: App awards visible badges for milestones (first streaks, books finished, pages/minutes logged); badges appear in a new Profile → Badges view; includes toast on unlock.
  • Keyboard shortcuts for quick session logging
    • AC: User can open New Session with a shortcut (e.g., N), navigate Session History rows with arrows + Enter, and toggle shortcuts in Settings for accessibility.
  • Shareable progress snapshot
    • AC: User can export/share an image containing reading streak, book progress, and earned badges; snapshot uses a branded layout and works in PWA and browser.
  • A11y: charts + badges readable without visuals
    • AC: Charts include alt-text summaries (“Reading increased 15% week-over-week”); badges have ARIA labels; shareable snapshot generates a text-based equivalent.
  • Chart themes (optional aesthetic/accent modes)
    • AC: User can toggle light, dark, and monochrome chart themes; themes persist and respect system settings.
  • Trend ranges (weekly, monthly, yearly)
    • AC: User can switch between time ranges; app calculates percent change (e.g., “27% more reading this week”).
  • Stats layer / analytics module
    • AC: Centralize all reading metrics into an analytics module (pages, minutes, streaks, trends); charts read from this layer; memoization improves performance on large libraries.
  • Cleanup & structure: charts + badges modules
    • AC: Add features/charts.js, features/badges.js, and reusable <chart-container> UI; remove old streak logic replaced by analytics layer.

Released: Dec 2025

🚀 Version 2.0 — React Frontend (MERN Start)

  • Scaffold React app (with JSX)
    • AC: npm run dev runs without errors; root component renders; README updated with “How to run.”
  • Port Add/Import/Export to React components
    • AC: Behaves identically to v1.x; invalid JSON import properly rejected; all dialogs functional.
  • Port Book List, Filters, and Search UI
    • AC: Core book browsing features match v1.9; search/filtering identical in results and performance.
  • Choose UI styling framework (Tailwind preferred, Bootstrap optional)
    • AC: Shared Button, Card, Input components exist; global teal theme (#008080) applied consistently.
  • Implement React state architecture (Context or Redux-lite)
    • AC: Books, settings, and UI state managed consistently; no prop-drilling for major features.
  • CI pipeline: lint, type-check (optional TS), test baseline
    • AC: GitHub Actions runs lint + tests on PRs; npm test and npm run lint clean locally.

Planned: Q1 2026

🌐 Version 2.1 — Express API + PostgreSQL

  • Setup Node/Express backend
    • AC: npm start serves /health → 200 with {status:"ok"} JSON.
  • Define PostgreSQL models for Books + Sessions
    • AC: Book schema includes title, author, status, createdAt; Session includes bookId, minutes, notes, date.
  • CRUD API routes for books (+ pagination)
    • AC: POST/GET/PUT/DELETE return correct codes; GET supports ?page=&limit=; validation rejects empty fields.
  • CRUD API for reading sessions
    • AC: Sessions can be created, edited, listed, and deleted; invalid/malformed session data rejected.
  • Connect React frontend to API
    • AC: Books and Sessions load from API; creating or editing updates UI without reload.
  • Import/Export via API
    • AC: POST /import accepts validated backup JSON; GET /export returns user’s current books + sessions.
  • Security baseline (production-ready)
    • AC: Helmet enabled; CORS limited to frontend domain; rate limiting applied; only HTTPS documented.
  • Local dev environment setup (Docker optional)
    • AC: docker-compose up runs API + PostgreSQL locally; DB migrations documented.

Planned: Q1 2026

🔑 Version 2.2 — Authentication

  • Add per-user accounts (JWT or OAuth)
    • AC: Signup/login works; passwords hashed; tokens signed with secret.
  • Scope reading logs to users
    • AC: Users only sees and modify their own books; 401/403 returned otherwise.
  • Secure routes and API access
    • AC: Auth middleware validates tokens; refresh/expiry rules documented.
  • Token storage strategy documented
    • AC: One-paragraph note in README explains where tokens live (cookie vs storage) and why.

Planned: Q2 2026

👨🏻‍💻 Version 2.3 — UI & Experience

  • Dark mode toggle
    • AC: Toggle persists across reload; system preference respected on first load.
  • Notes/annotations per book
    • AC: Add/edit/delete a note inline; notes persist in DB.
  • Responsive design (Bootstrap/Tailwind layouts)
    • AC: Works on ~360px wide; no horizontal scroll; tap targets ≥ 44px.
  • Empty states & toasts for better UX
    • AC: Empty list shows a friendly hint; add/delete triggers a toast.

Planned: Q2 2026

🎖️ Version 2.4 — Badge System Overhaul

Goals

Establish badges as a structured, scalable, motivating system backed by server-side evaluation, categories, tiers, progress tracking, and deeper integration with Snapshot & Stats. This upgrade forms the foundation for future badge expansions without UI or logic bloat.

👨🏻‍💻 Data Model & Backend Foundations

  • Badge definitions stored server-side
    • AC: badges table/collection includes: category, tier, description, hint, iconKey, colorKey, sortOrder, isHidden.
  • User badge state persisted
    • AC: user_badges table/collection tracks unlockedAt, progressValue, progressMax, seen, lastEvaluatedAt.
  • Backend badge evaluation engine
    • AC: Server recomputes badge progress/unlocks on session save, book completion, and scheduled daily job.
  • Category-based evaluators
    • AC: Each badge category (streak, volume, time, diversity, special) has a dedicated evaluator module.

Planned: TBD

🌐 API & Client Integration

  • Unified /api/user/badges endpoint
    • AC: Returns list of badges with state, progress, hints, and unlocked history.
  • Badge highlight aggregator
    • AC: API provides recentUnlocked and nextTarget to support Snapshot & Stats.
  • Real-time unlock notifications
    • AC: Frontend receives badge unlock events via polling/WebSocket.

Planned: TBD

🔑 Badge Categories, Tiers & Visual System

  • Introduce badge categories
    • AC: UI groups badges under Streak, Volume, Time, Diversity, Special.
  • Introduce tiers
    • AC: Bronze/Silver/Gold/Legendary tiers styled consistently with color tokens.
  • Tier-driven card styling
    • AC: Badge cards visually reflect tier (border, color, emphasis).
  • Icon system refresh
    • AC: Icon keys map to consistent glyph collection (e.g., book-stack, flame, compass).

Planned: TBD

🎨 Front-End UI/UX Upgrades

  • Progress indicators for in-progress badges
    • AC: Locked/in-progress badges show progress bars or x/y text.
  • Badge detail modal
    • AC: Clicking a badge opens modal with tier, category, description, progress, conditions, and unlock history.
  • Improved badge grid layout
    • AC: Grid supports category group headers; distributes locked/unlocked badges cleanly.
  • Hint system
    • AC: Locked badges show dynamic hints (e.g., “Read 2 more days to unlock”).

Planned: TBD

🌍 Integration With Snapshot & Reading Stats

  • Snapshot badge highlight
    • AC: Snapshot displays most recent unlocked badge or closest badge to unlocking.
  • Stats panel badge summary
    • AC: Stats show total unlocked, recent badges, and next target.
  • Optional badge export support
    • AC: Exported snapshot includes highlighted badge icon + name.

Planned: TBD

🦾 Accessibility & Notifications

  • Accessible unlock announcements
    • AC: Badge unlock events trigger ARIA live region updates (toast + summary).
  • Keyboard navigable badge grid
    • AC: Arrow-key navigation works across all categories and tiers.
  • Accessible progress messages
    • AC: Each badge exposes descriptive progress text (“1 day remaining”).

Planned: TBD

🎯 Long-Term Extensions (Beyond v2.1)

  • Event/seasonal badges
  • Secret badges (hidden until unlocked)
  • Badge-based profile customization
  • XP/Reader Level system
  • Social achievement feed (optional)
  • Badge rarity statistics (“Unlocked by 12% of readers”)

🌍 Version 3.0 — Deployment & Growth

  • Deploy backend (Render, Railway, or Fly.io)
    • AC: Public URL /health is 200; env vars set server-side.
  • Deploy frontend (Netlify or Vercel)
    • AC: Public URL loads app and communicates with live API.
  • Environment variable setup for API URLs
    • AC: No hard-coded localhost in production build; README lists .env keys.
  • CI/CD pipeline (build, test, deploy)
    • AC: README explains deployment process; minimal script included.
  • Public demo with live data sync
    • AC: Demo account works; reset/demo steps documented.

Planned: TBD

🔮 Long-Term Ideas

  • Tags and categories for books AC: User can add/remove free-form tags and select one category per book. AC: Tags autocomplete from existing tags; new tags can be created inline. AC: Filter panel supports multi-select by tags and single-select by category. AC: Tag and category choices persist across app reloads and appear in backups/exports. AC: Bulk edit lets user add/remove a tag to multiple selected books. AC: A11y: tag editor is fully keyboard-operable (Tab, Enter to confirm, Backspace to remove); screen readers announce “tag added/removed”.

  • Statistics dashboard (books read per month, genres, etc.) AC: Dashboard shows monthly books read, total pages/minutes, top genres, average session length for a selected time range. AC: Time range selector supports presets (This month, Last 3 months, Year to date) and custom dates. AC: Metrics update instantly when the range changes (≤150ms on typical datasets). AC: Clicking a metric or chart segment deep-links to the filtered Books/Sessions view. AC: Data remains correct after import/migration; missing fields are handled gracefully (excluded and noted). AC: A11y: each card has an accessible name/description; charts include text summaries for screen readers.

  • Data visualization (charts of reading progress) AC: Provide at least these charts: Line (daily/weekly reading time or pages), Bar (books completed per month), Donut/Pie (genre distribution). AC: Hover tooltips show exact values; legends toggle series on/off. AC: Export chart image (PNG/SVG) and data (CSV) per chart. AC: Charts reflect active filters (date range, tags, category, status). AC: Performance: charts render ≤300ms for 2k+ sessions on mid-range devices. AC: A11y: keyboard focusable data points/legend toggles; “Describe chart” text available for screen readers.

  • Export to additional formats (CSV, Markdown, PDF) AC: Export dialog lets user choose CSV, Markdown, or PDF, with scope options: Books, Sessions, or Both. AC: CSV uses stable headers and UTF-8; Markdown includes readable tables and totals; PDF is paginated with header/footer & date range. AC: Exports respect active filters and selected time range. AC: File names include app name, data type, and ISO date (e.g., readr-books-2025-10-01.csv). AC: Large exports (5k+ rows) stream or chunk without freezing UI; user sees progress and success/failure toast. AC: A11y: export flow operable with keyboard; buttons have clear labels; progress is announced to screen readers.

  • Integration with external APIs (e.g., Goodreads) AC: User can connect an external account via OAuth; connection state is visible and revocable. AC: After connect, user can import book metadata (title, author, cover, ISBN, genres) and optionally sync reading status. AC: Conflicts show a clear merge dialog (keep local / keep remote / merge fields); user choice is remembered per field when selected. AC: Rate-limit and error states display actionable messages (retry/backoff) without data loss. AC: Privacy: user consent required before any data leaves the device; a clear Disconnect & delete option removes tokens and remote copies if supported. AC: A11y: OAuth flow and merge dialogs are labeled, focus-trapped, and fully keyboard accessible.

  • Team collaboration features (shared reading groups) AC: User can create/join a Group and invite members by link or email. AC: Group has shared reading lists, sessions feed, and goal board; each item shows author and timestamp. AC: Permissions: Owner/Moderator/Member roles control invite, edit, and delete actions; defaults are least-privilege. AC: Presence/conflict: optimistic UI shows edits immediately; concurrent edits resolve with last-writer wins + non-destructive history for recovery. AC: Notifications (in-app) for mentions, new sessions on a followed book, and milestone completions; user can mute per group. AC: Export honors group scope (own data vs. group aggregate) and redacts private fields when required. AC: A11y: all group actions operable via keyboard; live region announces new posts/sessions.

  • Offline sync & conflict resolution AC: Changes made offline sync automatically when back online. AC: Conflict resolution shows clear merge options (keep local/remote/both). AC: Sync status visible (Last synced at …). AC: A11y: sync indicators have text equivalents for screen readers.

  • Customizable home dashboard AC: User can add/remove widgets (e.g., current streak, top genres, quick add). AC: Widgets can be reordered via drag-and-drop (keyboard accessible). AC: Preferences persist across sessions and devices.

  • Reading reminders & notifications AC: User can schedule reminders (daily/weekly at chosen time). AC: Notifications integrate with browser/mobile (push API). AC: Snooze/dismiss flows are accessible and persist user choices.

  • Audiobook & media support AC: Books can be marked as “Audiobook” or “Other media type”. AC: Session logging supports listening time alongside pages/minutes. AC: Stats and charts include listening data in totals.

  • Custom fields & templates AC: User can define custom fields (e.g., translator, edition, language). AC: Fields are included in add/edit dialogs, exports, and filters. AC: Templates allow reusing field sets when adding similar books.

  • Reading challenges & public profiles AC: User can set public yearly challenges (e.g., “Read 20 books in 2026”). AC: Public profile URL shows selected stats/goals. AC: Privacy controls let user toggle what’s visible (books, sessions, goals).

  • AI-powered insights (optional) AC: Generate summaries of reading habits (e.g., “Most active on Sundays”). AC: Suggest books based on tags, genres, and past completions. AC: Recommendations explain why (transparent reasoning). AC: Opt-in only; clear toggle to disable insights.

🤝 Contributing to the Roadmap

  • Check open issues ofr active discussions.
  • Suggest new features via the feature request template.
  • Contributions welcome for both the current vanilla JS app and the future MERN build.