todo.

todo. — Offline-First Gamified Task Management Platform

A high-performance, offline-resilient, gamified task management system built on the MERN stack.
Featuring real-time IndexedDB synchronization, Duolingo-style daily streaks, GitHub-inspired 365-day heatmaps, recurring tasks, subtasks, interactive calendar planning, and dual-phase OTP email security.

📖 Table of Contents

• Project Overview
• Key Features
  • Offline-First Sync Engine
  • Gamification & Streaks
  • Task Management & Subtasks
  • Recurring Tasks & Reminders
  • Visual Planner
  • Security & Authentication
  • UI/UX & Dynamic Theme
• System Architecture
  • High-Level Architecture
  • Offline Synchronization Flow
• Database Schema Design
  • User Model
  • Todo Model
  • Streak Entry Model
• REST API Reference
• Technology Stack
• Prerequisites
• Installation & Getting Started
  • 1. Clone Repository
  • 2. Install Dependencies
  • 3. Configure Environment Variables
  • 4. Run in Development Mode
  • 5. Run Streak Cron Script
• Building for Production & Deployment
• Project Directory Structure
• Testing Offline Mode & Debugging
• Contributing
• License & Author

🌟 Project Overview

todo. bridges the gap between simple, fragile to-do lists and bloated project management suites. Standard single-page applications crash, drop user inputs, or freeze when network connectivity fluctuates or drops. todo. solves this by putting Offline-First Resilience at the core of its architecture:

• 📶 Uninterrupted Workflow: Create, edit, prioritize, subtask, star, and check off tasks completely offline.
• 🔄 Autonomous Reconnection & Reconciliation: A FIFO transactional sync queue resolves temporary IDs and updates MongoDB Atlas automatically the moment the network returns.
• 🎮 Gamified Habit Loops: Stay motivated with XP rewards, level progression, Duolingo-style daily streak maintenance (with a 1-day grace window), milestone badges, and a 365-day GitHub-style activity heatmap.
• 🛡️ Zero Compromises on Security: JWT authentication over custom headers, bcrypt salted hashing, rate-limiting, and dual-phase OTP verification for account activation, password resets, and account deletion via Brevo transactional emails.

✨ Key Features

1. Offline-First Synchronization Engine

• Axios Network Interceptor: Transparently intercepts all outbound HTTP requests. If the client is offline (navigator.onLine === false), writes and reads are rerouted locally to browser IndexedDB stores without crashing.
• Temporary ID Mapping (tempIdMap): Offline-created tasks receive deterministic temporary IDs (temp_<timestamp>). Downstream actions (starring, completing, updating) reference this temporary ID. Upon reconnection, the creation request runs first, returns the MongoDB _id, and automatically replaces temporary IDs throughout the queue before subsequent requests execute. This guarantees zero CastError exceptions in MongoDB.
• Optimistic UI Updates: Interactions render in 0ms on the client interface and mutate Redux state immediately while background jobs sync with the database.
• Auto Reconnect Ping: When offline, a non-blocking background heartbeat polls the server every 10 seconds. On the first successful handshake, the offline queue is drained sequentially.

2. Gamified Productivity & Streaks

• Duolingo-Style Streak System: Consecutive daily task completions earn streak counters. Features a 1-day grace period (if you completed a task yesterday, your streak remains protected today until midnight).
• GitHub-Inspired 365-Day Heatmap: Visualizes productivity history over the past year. Deleting a completed task from your current list does not erase historical completion records.
• XP, Levels & Points:
  • Base XP per task completion.
  • Multipliers based on active streak length and task priority tier (high > medium > low).
  • Unmarking a task reverses exact awarded XP without altering past history.
• Milestone Badges: Earn unlockable badges based on your longest streak:
  • ⚡ Starter Spark (3-day streak)
  • ⚔️ Week Warrior (7-day streak)
  • 🛡️ Fortnight Force (14-day streak)
  • 👑 Monthly Master (30-day streak)
  • 🏆 Century Centurion (100-day streak)
  • 🌌 Legendary (365-day streak)
• Global Leaderboard: Public top-rankings displaying user levels, XP, streaks, and ranks.
• Automated Streak Alerts: Background worker checks verified accounts and sends transactional email warnings when streaks are at risk or lost.

3. Advanced Task Management

• Full CRUD Support: Create, read, update, reorganize, star, and delete tasks.
• Subtasks / Checklist Items: Break complex projects into subtask items with individual completion checkmarks and progress bars.
• Tagging & Filtering: Assign color-coded category tags to tasks with instant multi-tag filtering.
• Priority Tiers: Categorize urgency as Low, Medium, or High with distinctive colored badges and glowing indicators.
• Soft Deletion & Trash Bin: Deleting a task moves it to Trash for 15 days, allowing instant restoration. Tasks can be permanently purged in bulk.
• Smart Filter Views:
  • All Tasks (active items)
  • Starred (high importance)
  • Completed (finished tasks)
  • Today (scheduled or due today)
  • This Week (due or created within 7 days)
  • Trash (soft-deleted items)

4. Recurring Tasks & Reminders

• Recurrence Engine: Supports Daily, Weekly (with custom weekday selection: Mon-Sun), and Monthly intervals with optional end dates.
• Non-Destructive Spawning: Completing a recurring task retains the completed record (preserving streak and XP) and automatically generates the next scheduled instance with parent-child linkage.
• Explicit Reminders (reminderAt): Separate from due dates; triggers service worker notifications to keep you on schedule.

5. Visual Planner & Calendar Scheduling

• Interactive Calendar View: Switch between Day, Week, and Month layouts.
• Unscheduled Backlog Drawer: View tasks without dates and drag/drop or assign them directly onto the timeline.
• Start and End Date Ranges: Plan multi-day objectives with visible timeline spans.

6. Enterprise-Grade Security & Auth

• Stateless JWT Authentication: Tokens passed securely via X-Authorization: Bearer <token> header to prevent header collisions.
• Bcrypt Salted Passwords: Industry-standard cryptographic hashing.
• Dual-Phase OTP Verification: 6-digit cryptographically random OTPs sent via Brevo SMTP API (valid for 15 minutes) required for:
  • Account Registration & Verification
  • Forgot Password & Credential Reset
  • Permanent Account Deletion
• Hardened HTTP Headers: Helmet protection against Cross-Site Scripting (XSS), clickjacking, and MIME-type sniffing.
• Brute-Force Rate Limiting: Strict windowed rate limits on sensitive authentication and API endpoints.
• Email Template Sandbox: Protected /email preview portal to inspect responsive HTML transactional email templates.

7. Glassmorphic Design & Illustrative UX

• Dark Glassmorphic Theme: Deep obsidian palettes (#0e0e11), subtle borders (border-zinc-900/60), and backdrop blurs (backdrop-blur-xl).
• Dynamic Time-of-Day Artwork: Animated SVG greetings that automatically reflect your local time:
  • 🌅 05:00 - 11:59: Morning Sun & Sky
  • ☀️ 12:00 - 16:59: Radiant Afternoon Orbit
  • 🌇 17:00 - 21:59: Evening Horizon
  • 🌙 22:00 - 04:59: Starlit Crescent Moon
• Fluid Micro-Interactions: Smooth state transitions and drawer slide-outs powered by Framer Motion.
• Progressive Web App (PWA): Installable directly on Windows, macOS, Android, and iOS with standalone app windows.
• Audio Feedback: Pleasant audio tones on task completions and milestone achievements.

🏗️ System Architecture

High-Level Architecture

graph TD
    subgraph Browser ["Client Environment (PWA)"]
        UI[React 18 + Tailwind v4 UI]
        Redux[Redux Toolkit Store]
        SW[Service Worker Cache]
        Axios[Axios Interceptor]
        IDB[(IndexedDB Local Store)]
        Queue[Transactional Offline Write Queue]
    end

    subgraph BackendServer ["Server Environment (Node.js & Express)"]
        API[Express REST API]
        AuthMid[JWT Auth Middleware]
        XPService[XP & Gamification Service]
        StreakCron[Streak Email Cron Runner]
    end

    subgraph ExternalCloud ["Cloud Services"]
        MongoAtlas[(MongoDB Atlas Database)]
        Brevo[Brevo SMTP Transactional Email API]
    end

    UI --> Redux
    UI --> Axios
    SW --> UI
    Axios -->|Online| API
    Axios -->|Offline Intercept| IDB
    Axios -->|Write Actions| Queue
    Queue -->|On Reconnect: Drain & Map IDs| API

    API --> AuthMid
    AuthMid --> XPService
    API --> MongoAtlas
    StreakCron --> MongoAtlas
    API --> Brevo
    StreakCron --> Brevo

Offline Synchronization Flow

sequenceDiagram
    autonumber
    actor User
    participant React as React UI & Redux
    participant Interceptor as Axios Interceptor
    participant IDB as IndexedDB (Local)
    participant Server as Express Server
    participant DB as MongoDB Atlas

    User->>React: Create task offline
    React->>Interceptor: POST /todo/addTask
    Note over Interceptor: Network offline detected!
    Interceptor->>IDB: Generate temp ID (temp_1719...) & save locally
    Interceptor->>IDB: Enqueue write payload to offline sync queue
    Interceptor-->>React: Optimistic 200 response with temp ID
    React-->>User: Task visible immediately in UI

    User->>React: Stars task offline
    React->>Interceptor: POST /todo/markStarred (ID: temp_1719...)
    Interceptor->>IDB: Enqueue star action with temp_1719...

    Note over Interceptor,Server: Network connectivity restored!
    Interceptor->>Server: Process Sync Queue Item 1: POST /todo/addTask
    Server->>DB: Save document
    DB-->>Server: Real ObjectId (6678ab12...)
    Server-->>Interceptor: 201 Created with real ObjectId
    Note over Interceptor: Record mapping: temp_1719... -> 6678ab12...
    Note over Interceptor: Rewrite pending queue payloads with real ID!
    Interceptor->>Server: Process Sync Queue Item 2: POST /todo/markStarred (ID: 6678ab12...)
    Server->>DB: Update document starred: true
    DB-->>Server: OK
    Server-->>Interceptor: 200 Success
    Note over Interceptor: Sync Queue drained successfully.

🗄️ Database Schema Design

The application utilizes three primary Mongoose collections.

User Schema (users)

Todo Schema (todos)

Streak Entry Schema (streakentries)

Compound Unique Index: { userId: 1, dateKey: 1 } guarantees atomic streak increments with zero duplicates even under rapid offline syncing.

📡 REST API Reference

All protected routes require the JWT token passed in the request header:

X-Authorization: Bearer <your_jwt_token>

1. Authentication Endpoints (/user)

2. Task Management Endpoints (/todo)

3. Filter & Analytics Endpoints (/filters)

4. Leaderboard & System (/leaderboard, /health)