FastTodo - Offline-First Task Manager

A production-ready, offline-first todo application with authentication, multi-list organization, and rich task metadata. Built with Next.js 15, TypeScript, and MongoDB.

✨ Features

🔐 Authentication & Security

• undefinedSecure Authentication: Email/Password signup and login with JWT
• undefinedHTTP-only Cookies: Session management with secure, HTTP-only cookies
• undefinedRoute Protection: Automatic redirect to login for protected routes
• undefinedData Isolation: Complete user data privacy and separation
• undefinedRobust Logout: Clean session termination with client-side cleanup

📋 Multi-List Organization

• undefinedUnlimited Lists: Create and manage multiple todo lists
• undefinedList Management: Rename and delete lists with ease
• undefinedCascading Delete: Deleting a list removes all associated todos
• undefinedSmart Defaults: Auto-select first list on load
• undefinedList Switching: Quick dropdown navigation between lists

✅ Rich Todo Metadata

Each todo includes:

• undefinedTitle and Descriptionundefined
• undefinedStatus: Pending | Todo | In Progress | Completed
• undefinedCategory: Bug | Feature | Docs | Improvement | Refactor
• undefinedPriority: Minor | Normal | Important | Critical
• undefinedVisual Badges: Color-coded badges for quick identification

🚀 Offline-First Architecture

• undefinedInstant Updates: Optimistic UI for immediate feedback
• undefinedLocalStorage Caching: Persistent offline data storage
• undefinedSmart Sync: Automatic synchronization when online
• undefinedNo Loading Flash: Skeleton loaders during hydration
• undefinedConflict Resolution: Intelligent merge strategy for sync conflicts

🎨 Premium User Experience

• undefinedDark Mode: System, light, and dark theme support
• undefinedSmooth Transitions: No jarring UI changes
• undefinedModern Design: Clean interface with shadcn/ui components
• undefinedResponsive Layout: Works on all screen sizes
• undefinedAccessible: ARIA labels and keyboard navigation

🛠️ Tech Stack

• undefinedFrontend: Next.js 15 (App Router), React 19, TypeScript
• undefinedState Management: Zustand with localStorage persistence
• undefinedStyling: Tailwind CSS, shadcn/ui components
• undefinedBackend: Next.js API Routes
• undefinedDatabase: MongoDB with Mongoose ODM
• undefinedAuthentication: JWT with jose, HTTP-only cookies
• undefinedTheme: next-themes for dark mode support

📋 Prerequisites

• Node.js 18+ and npm
• MongoDB instance (local or cloud like MongoDB Atlas)
• Git

🚀 Installation

1. Clone the repository

git clone https://github.com/yourusername/fasttodo.git
cd fasttodo

2. Install dependencies

npm install

3. Environment Setup

Create a .env.local file in the root directory:

# MongoDB Connection String
MONGODB_URI=mongodb://localhost:27017/fasttodo
# OR for MongoDB Atlas:
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/fasttodo

# JWT Secret (use a strong random string)
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

undefinedGenerate a secure JWT secret:undefined

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

4. Run the development server

npm run dev

Open http://localhost:3000 in your browser.

📖 Usage

First Time Setup

1. Navigate to http://localhost:3000
2. You’ll be redirected to /login
3. Click “Sign Up” and create an account
4. After signup, you’ll be automatically logged in

Creating Your First List

1. Click the “Create List” button
2. Enter a list name (e.g., “Work Tasks”)
3. Click “Done”undefined

Adding Todos

1. Make sure a list is selected (shown in the dropdown)
2. Click “Create Todo”undefined
3. Fill in the details:
   • undefinedTitle (required)
   • undefinedDescription (optional)
   • undefinedStatus (default: Todo)
   • undefinedCategory (default: Feature)
   • undefinedPriority (default: Normal)
4. Click “Save changes”undefined

Managing Lists

• undefinedSwitch Lists: Click the list dropdown, select a different list
• undefinedRename List: Click the ⋮ menu next to the list dropdown → “Rename list”
• undefinedDelete List: Click the ⋮ menu → “Delete list” (deletes all todos in the list)

Offline Usage

The app works perfectly offline:

1. undefinedGo Offline: Disconnect from the internet
2. undefinedCreate/Edit: Make changes to todos and lists
3. undefinedLocal Storage: Changes are saved immediately to localStorage
4. undefinedReload: Page reloads show cached data with no flash
5. undefinedReconnect: Automatic sync to server when back online

Theme Switching

Click the Sun/Moon icon in the header to toggle between:

• Light mode
• Dark mode
• System preference

🏗️ Architecture

Data Flow

User Action
    ↓
Zustand Store (Optimistic Update)
    ↓
LocalStorage (Offline Persistence)
    ↓
API Route (if online)
    ↓
MongoDB (Server Persistence)
    ↓
Sync & Merge (on reconnect)

Project Structure

fasttodo/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── auth/[...path]/    # Auth endpoints
│   │   │   ├── lists/             # List CRUD
│   │   │   └── todos/             # Todo CRUD
│   │   ├── login/                 # Login page
│   │   ├── signup/                # Signup page
│   │   ├── layout.tsx             # Root layout with ThemeProvider
│   │   └── page.tsx               # Main dashboard
│   ├── components/
│   │   ├── ui/                    # shadcn/ui components
│   │   ├── header.tsx             # App header with theme toggle
│   │   ├── todo-list.tsx          # Main todo list view
│   │   ├── todo-card.tsx          # Individual todo card
│   │   ├── todo-dialog.tsx        # Create/edit dialog
│   │   ├── create-list-dialog.tsx # List creation
│   │   └── ...
│   ├── lib/
│   │   ├── db.ts                  # MongoDB connection
│   │   └── auth.ts                # JWT utilities
│   ├── models/
│   │   ├── Todo.ts                # Todo Mongoose schema
│   │   ├── List.ts                # List Mongoose schema
│   │   └── User.ts                # User Mongoose schema
│   ├── store/
│   │   └── use-todo-store.ts      # Zustand store with sync logic
│   └── proxy.ts                   # Route protection middleware
└── package.json

Key Features Implementation

Offline-First Sync

The app uses a sophisticated sync engine in use-todo-store.ts:

1. undefinedPush Deletions: Sync deleted items to server
2. undefinedPush Updates: Sync created/modified items
3. undefinedPull & Merge: Fetch server data and merge with local changes
4. undefinedConflict Resolution: Unsynced local changes always take precedence

Authentication Flow

• Login → JWT signed → HTTP-only cookie set
• Every API request → Cookie validated → User identified
• Protected routes → proxy.ts checks auth → Redirect if needed

🧪 Testing

Manual Testing Checklist

• Signup and login
• Create multiple lists
• Switch between lists
• Create todos with different statuses/categories/priorities
• Edit todos
• Delete todos
• Rename list
• Delete list (verify cascading delete)
• Go offline, create todo, reconnect (verify sync)
• Reload page offline (verify no data loss)
• Toggle theme (light/dark/system)
• Logout and login again

🐛 Troubleshooting

MongoDB Connection Issues

If you get connection errors:

1. Ensure MongoDB is running: mongod --version
2. Check your MONGODB_URI in .env.local
3. For MongoDB Atlas, ensure IP whitelist includes your IP

JWT Errors

If you see JWT-related errors:

1. Verify JWT_SECRET is set in .env.local
2. Clear cookies and try logging in again
3. Regenerate JWT_SECRET with a strong random string

Hydration Errors

If you see hydration warnings:

1. Check that suppressHydrationWarning is on <html> tag
2. Ensure ThemeProvider is wrapping the app
3. Clear browser cache and reload

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Next.js - The React Framework
• shadcn/ui - Beautiful UI components
• Zustand - Lightweight state management
• MongoDB - Database platform
• Tailwind CSS - Utility-first CSS framework

---

undefinedBuilt with ❤️ using Next.js and TypeScriptundefined