Achievements screen

[chornonoh-vova]

Feature: Achievements Screen

Overview

Add a new achievements screen that displays user reading accomplishments across four categories: Reading Sessions, Pages, Books, and Reading Days.

Motivation

Gamification through achievements will increase user engagement and motivation to maintain consistent reading habits. Visual progress tracking provides users with tangible goals and a sense of accomplishment.

Requirements

Achievement Categories

📖 A. Reading Sessions Achievements

Data Source: reading_sessions table
Stats Required:

• totalSessions (count of all sessions)
• totalReadingTimeMinutes (sum of session durations)

Achievements:

Type 1 — One-time:

• First Session
  • id: first_session
  • Condition: Complete 1 reading session

Type 2 — Tiered (Session Count):

• Getting Warmed Up (sessions_10) — 10 sessions
• Bookworm (sessions_50) — 50 sessions
• Reading Machine (sessions_100) — 100 sessions
• Reading Veteran (sessions_250) — 250 sessions

Type 2 — Tiered (Total Reading Time):

• One Hour (time_60) — 60 minutes
• Dedicated Reader (time_600) — 10 hours (600 min)
• Marathon Reader (time_3000) — 50 hours (3,000 min)
• Master Reader (time_6000) — 100 hours (6,000 min)

---

📚 B. Pages Achievements

Data Source: Sum of pages from all sessions
Stats Required:

• totalPages (sum of pages read across all sessions)

Type 2 — Tiered:

• First Steps (pages_100) — 100 pages
• Turning Pages (pages_500) — 500 pages
• Book Explorer (pages_1000) — 1,000 pages
• Avid Reader (pages_5000) — 5,000 pages
• Book Devourer (pages_10000) — 10,000 pages
• Library Spirit (pages_25000) — 25,000 pages

---

📗 C. Books Achievements

Data Source: books.completed_at (non-null values indicate completed books)
Stats Required:

• completedBooks (count of books with completed_at set)

Type 1 — One-time:

• First Book Finished (first_book) — Complete 1 book

Type 2 — Tiered:

• Growing Collection (books_5) — 5 books
• Serious Reader (books_10) — 10 books
• Book Lover (books_25) — 25 books
• Book Master (books_50) — 50 books
• Legend (books_100) — 100 books

---

📅 D. Reading Days Achievements

Data Source: Distinct days with reading sessions
Stats Required:

• uniqueReadingDays (count of unique dates from sessions)

Type 2 — Tiered:

• Weekly Habit (days_7) — 7 unique days
• Monthly Reader (days_30) — 30 unique days
• Reading Lifestyle (days_100) — 100 unique days
• One Year of Reading (days_365) — 365 unique days

---

UI/UX Considerations

• Display achievements grouped by category (Sessions, Pages, Books, Days)
• Show locked/unlocked state for each achievement
• Display progress bars for achievements in progress
• Visual indicators (icons, colors) for completed achievements
• Show current stats for each category at the top
• Consider adding achievement unlock animations/notifications

Data Structure

Consider creating an achievements configuration file or database table that includes:

• id (unique identifier)
• title (display name)
• category (sessions/pages/books/days)
• type (one-time/tiered)
• target (numeric goal)
• icon (emoji or icon identifier)
• description (optional flavor text)

Acceptance Criteria

• New achievements screen is accessible from main navigation
• All four achievement categories are displayed
• User's current progress is accurately calculated and displayed
• Unlocked achievements are visually distinct from locked ones
• Progress towards next tier is shown for tiered achievements
• Performance is optimized (consider caching stats)
• Works correctly for users with no data (all achievements locked)
• Responsive design works on mobile and desktop