todo. — Offline-First Gamified Task Management Platform

todo. Logo

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
System Architecture
- High-Level Architecture
- Offline Synchronization Flow
Database Schema Design
REST API Reference
Technology Stack
Prerequisites
Installation & Getting Started
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`)

Field	Type	Attributes	Description
`name`	`String`	Required	Full display name of the user
`username`	`String`	Required, Unique, Lowercase	Unique handle for login
`email`	`String`	Required, Unique, Lowercase	Account email address (target for OTPs)
`password`	`String`	Required	Salted bcrypt hash
`date`	`String`	Required	Account registration date string
`isVerified`	`Boolean`	Default: `false`	Gatekeeper toggle; true only after OTP activation
`otp`	`String`	Optional	6-digit registration OTP code
`otpExpires`	`Date`	Optional	Expiration time of registration OTP (15 min)
`resetPasswordOtp`	`String`	Optional	6-digit password recovery code
`resetPasswordOtpExpires`	`Date`	Optional	Expiration of password reset code
`deleteAccountOtp`	`String`	Optional	6-digit confirmation code for account purge
`deleteAccountOtpExpires`	`Date`	Optional	Expiration of delete confirmation code
`xp`	`Number`	Default: `0`	Cumulative experience points
`level`	`Number`	Default: `1`	Current user level
`points`	`Number`	Default: `0`	Gamification points balance
`currentStreak`	`Number`	Default: `0`	Active daily streak count
`longestStreak`	`Number`	Default: `0`	Lifetime highest streak (badges are permanently retained)
`lastStreakWarningSentAt`	`String`	Optional	Date key when last warning email was dispatched
`lastStreakLostSentAt`	`String`	Optional	Date key when last lost-streak alert was dispatched

Todo Schema (`todos`)

Field	Type	Attributes	Description
`userId`	`String`	Required, Indexed	Reference to user document ID
`task`	`String`	Required, Trimmed	Task title / headline
`description`	`String`	Optional	Detailed Markdown or plain-text notes
`completed`	`Boolean`	Required, Default: `false`	Completion status toggle
`starred`	`Boolean`	Required, Default: `false`	Pin as high-priority starred item
`deleted`	`Boolean`	Required, Default: `false`	Soft-deletion flag (Trash bin state)
`priority`	`String`	Enum: `['low', 'medium', 'high']`	Task urgency level (Default: `low`)
`date`	`Date`	Required	Creation timestamp
`dueDate`	`Date`	Optional	Task deadline boundary
`reminderAt`	`Date`	Optional	Explicit time for push notification
`completedAt`	`Date`	Default: `null`	Exact timestamp when marked complete
`subtasks`	`Array`	`[{ title: String, done: Boolean }]`	Checklist sub-items
`tags`	`[String]`	Indexed	Categorization labels (e.g., `#Work`, `#Personal`)
`rankIndex`	`Number`	Default: `0`	Position order for manual reordering
`startDate`	`Date`	Default: `null`	Scheduled start date for calendar planner
`endDate`	`Date`	Default: `null`	Scheduled end date for calendar planner
`recurrence`	`Object`	See Recurrence details	Frequency, interval, days-of-week, end date
`recurrenceParentId`	`String`	Default: `null`	Links spawned recurring tasks to original
`xpAwarded`	`Number`	Default: `0`	Stored XP awarded on completion (for clean undo)
`pointsAwarded`	`Number`	Default: `0`	Stored points awarded on completion

Streak Entry Schema (`streakentries`)

Field	Type	Attributes	Description
`userId`	`String`	Required, Indexed	Reference to user document ID
`dateKey`	`String`	Required, Regex `YYYY-MM-DD`	Date representation of completed day
`count`	`Number`	Required, Default: `0`, Min: `0`	Net tasks completed on this calendar day

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`)

Method	Endpoint	Access	Description
`POST`	`/user/register`	Public	Register new account. Generates 6-digit OTP email.
`POST`	`/user/verifyOtp`	Public	Verify 6-digit registration OTP. Activates user account.
`POST`	`/user/signin`	Public	Authenticate credentials. Returns user object and JWT token.
`POST`	`/user/forgotPassword`	Public	Requests password reset OTP sent to registered email.
`POST`	`/user/resetPassword`	Public	Verifies reset OTP and replaces password hash.
`POST`	`/user/sendDeleteAccountOtp`	Protected	Requests confirmation OTP for permanent account deletion.
`POST`	`/user/deleteAccount`	Protected	Verifies OTP and permanently deletes user, todos, and streak history.

2. Task Management Endpoints (`/todo`)

Method	Endpoint	Access	Description
`POST`	`/todo/addTask`	Protected	Create new task (handles tags, subtasks, recurrence, due dates).
`POST`	`/todo/updateTask`	Protected	Update task properties, titles, checklists, or schedule dates.
`POST`	`/todo/markComplete`	Protected	Mark task complete. Calculates XP, updates streaks, spawns recurring tasks.
`POST`	`/todo/unMarkComplete`	Protected	Unmark task complete. Reverses awarded XP and cleans up spawned children.
`POST`	`/todo/markStarred`	Protected	Star task for priority highlights.
`POST`	`/todo/unMarkStarred`	Protected	Remove starred priority flag.
`POST`	`/todo/deleteTask`	Protected	Soft-delete task (moves to 15-day Trash bin).
`POST`	`/todo/undoDelete`	Protected	Restore soft-deleted task from Trash.
`POST`	`/todo/deleteall`	Protected	Permanently purge all soft-deleted tasks from Trash.

3. Filter & Analytics Endpoints (`/filters`)

Method	Endpoint	Access	Description
`POST`	`/filters/all`	Protected	Fetch all active (non-deleted) tasks for authenticated user.
`POST`	`/filters/completed`	Protected	Fetch completed tasks.
`POST`	`/filters/starred`	Protected	Fetch starred high-priority tasks.
`POST`	`/filters/today`	Protected	Fetch tasks scheduled or created for today.
`POST`	`/filters/week`	Protected	Fetch tasks created or scheduled within the past 7 days.
`POST`	`/filters/deleted`	Protected	Fetch soft-deleted tasks currently sitting in Trash.
`POST`	`/filters/counts`	Protected	Fetch real-time count metrics for all filter categories.
`POST`	`/filters/activity`	Protected	Fetch 365-day calendar activity map for streak heatmap.

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

Method	Endpoint	Access	Description
`GET`	`/leaderboard/top`	Public / Protected	Returns global top users ranked by XP, streaks, and levels.
`GET`	`/health`	Public	Server health check endpoint (

todo.

todo. — Offline-First Gamified Task Management Platform

📖 Table of Contents

🌟 Project Overview

✨ Key Features

1. Offline-First Synchronization Engine

2. Gamified Productivity & Streaks

3. Advanced Task Management

4. Recurring Tasks & Reminders

5. Visual Planner & Calendar Scheduling

6. Enterprise-Grade Security & Auth

7. Glassmorphic Design & Illustrative UX

🏗️ System Architecture

High-Level Architecture

Offline Synchronization Flow

🗄️ Database Schema Design

User Schema (`users`)

Todo Schema (`todos`)

Streak Entry Schema (`streakentries`)

📡 REST API Reference

1. Authentication Endpoints (`/user`)

2. Task Management Endpoints (`/todo`)

3. Filter & Analytics Endpoints (`/filters`)

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

Ratings

Comments 0

Related apps

Słonecznik PV

Frink

Worktable

Frontstep

todo.

todo. — Offline-First Gamified Task Management Platform

📖 Table of Contents

🌟 Project Overview

✨ Key Features

1. Offline-First Synchronization Engine

2. Gamified Productivity & Streaks

3. Advanced Task Management

4. Recurring Tasks & Reminders

5. Visual Planner & Calendar Scheduling

6. Enterprise-Grade Security & Auth

7. Glassmorphic Design & Illustrative UX

🏗️ System Architecture

High-Level Architecture

Offline Synchronization Flow

🗄️ Database Schema Design

User Schema (users)

Todo Schema (todos)

Streak Entry Schema (streakentries)

📡 REST API Reference

1. Authentication Endpoints (/user)

2. Task Management Endpoints (/todo)

3. Filter & Analytics Endpoints (/filters)

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

Ratings

Comments 0

Related apps

Słonecznik PV

Frink

Worktable

Frontstep

User Schema (`users`)

Todo Schema (`todos`)

Streak Entry Schema (`streakentries`)

1. Authentication Endpoints (`/user`)

2. Task Management Endpoints (`/todo`)

3. Filter & Analytics Endpoints (`/filters`)

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