Skip to content

VarozXYZ/how-to-do-list

BranchesTags

Repository files navigation

[How] ToDoList – AI-Enhanced Task Management Application

A modern, full-stack task management application with AI-powered features for creating, organizing, and improving your tasks. Built with React and Node.js, featuring intelligent task suggestions, custom tagging system, and a beautiful responsive UI with dark mode support.

📋 Overview

[How] ToDoList is a comprehensive task management application that combines traditional to-do list functionality with AI-powered enhancements. It helps users organize their tasks efficiently while providing intelligent suggestions to improve task descriptions and structure.

What Problem Does It Solve?

  • Task Organization: Manage tasks with custom tags, priorities, and due dates
  • AI-Powered Assistance: Get intelligent suggestions to improve task descriptions and clarity
  • User-Friendly Interface: Clean, modern UI with dark mode and responsive design
  • Personalization: Custom tags with color coding, notification preferences, and user profiles

What This Project Is

  • ✅ Educational Project: Built for learning full-stack development practices
  • ✅ Full-Stack Application: Demonstrates React frontend + Node.js backend integration
  • ✅ AI Integration: Showcases API integration with DeepSeek AI for task enhancement
  • ✅ Modern Stack: Uses current best practices (React 19, Vite, Express, JWT auth)

What This Project Is NOT

  • ❌ Production-Ready: This is an educational project, not optimized for production scale
  • ❌ Real Database: Uses JSON file storage for simplicity (not suitable for production)
  • ❌ Enterprise Solution: Designed for learning, not enterprise deployment

🛠️ Technologies Used

Frontend

  • Framework: React 19.2.0 with Vite 7.2.4
  • Routing: React Router DOM 7.11.0
  • Styling:
    • Bootstrap 5.3.8
    • React Bootstrap 2.10.10
    • Custom CSS with dark mode support
  • Key Libraries:
    • Axios 1.13.2 (HTTP client)
    • React Markdown 10.1.0 (Markdown rendering)
    • React Datepicker 9.1.0 (Date/time selection)

Backend

  • Runtime: Node.js
  • Framework: Express 4.18.2
  • Database: JSON file storage (data.json) - simple file-based database
  • Authentication:
    • JWT (jsonwebtoken 9.0.2)
    • bcryptjs 2.4.3 (password hashing)
  • API Integration:
    • OpenAI SDK 6.15.0 (DeepSeek AI integration)
  • Other:
    • CORS 2.8.5
    • dotenv 16.3.1 (environment variables)

Development Tools

  • Build Tool: Vite (with React SWC plugin for fast refresh)
  • Code Quality: ESLint 9.39.1
  • Development Server: Nodemon 3.0.2
  • Package Manager: npm

🏗️ Architecture

The application follows a client-server architecture with clear separation of concerns:

┌─────────────────┐         HTTP/REST API         ┌─────────────────┐
│                 │◄──────────────────────────────►│                 │
│   React Client  │                                 │  Express Server │
│   (Port 5173)   │                                 │   (Port 3001)   │
│                 │                                 │                 │
│  - Components   │                                 │  - Controllers │
│  - Context API │                                 │  - Routes      │
│  - Services     │                                 │  - Middleware  │
└─────────────────┘                                 └────────┬────────┘
                                                              │
                                                              ▼
                                                      ┌─────────────────┐
                                                      │   data.json     │
                                                      │  (JSON Database)│
                                                      └─────────────────┘
                                                              │
                                                              ▼
                                                      ┌─────────────────┐
                                                      │  DeepSeek API   │
                                                      │  (AI Service)   │
                                                      └─────────────────┘

Data Flow

  1. User Authentication: Frontend sends credentials → Backend validates → Returns JWT token
  2. Task Management: Frontend requests tasks → Backend queries JSON DB → Returns user-specific tasks
  3. AI Features: Frontend sends task data → Backend calls DeepSeek API → Returns improved suggestions
  4. Real-time Updates: Context API manages state → Components re-render → UI updates

📁 Project Structure

how-to-do-list/
├── src/                          # Frontend source code
│   ├── components/
│   │   ├── auth/                 # Login, Register components
│   │   ├── cards/                # CardItem, CardDetail, CardView
│   │   ├── common/               # Shared components (modals, notifications)
│   │   └── layout/               # Sidebar, Navbar, Layout
│   ├── context/                  # React Context providers
│   │   ├── AuthContext.jsx       # Authentication state
│   │   ├── CardsContext.jsx      # Tasks/cards state management
│   │   └── ThemeContext.jsx      # Dark/light theme
│   ├── hooks/                    # Custom React hooks
│   │   ├── useDebounce.js        # Search debouncing
│   │   └── useNotifications.js   # Notification management
│   ├── pages/                    # Route pages
│   │   ├── Dashboard.jsx         # Main tasks view
│   │   ├── Completed.jsx         # Completed tasks
│   │   ├── Settings.jsx          # User settings
│   │   ├── Pricing.jsx           # Pricing page
│   │   └── LoginPage.jsx         # Authentication pages
│   ├── services/                 # API service layer
│   │   ├── api.js                # Axios instance with interceptors
│   │   ├── auth.js               # Authentication API calls
│   │   ├── cards.js              # Tasks CRUD operations
│   │   ├── tags.js               # Tags management
│   │   ├── ai.js                 # AI service integration
│   │   └── notifications.js      # Notifications API
│   ├── utils/                    # Utility functions
│   │   ├── storage.js            # localStorage helpers
│   │   └── cardHelpers.js        # Card utility functions
│   ├── App.jsx                   # Main app component with routing
│   ├── main.jsx                  # Entry point
│   └── index.css                 # Global styles
│
├── server/                        # Backend source code
│   ├── config/
│   │   ├── db.js                 # JSON database read/write operations
│   │   └── ai.js                 # AI service configuration
│   ├── controllers/              # Request handlers
│   │   ├── authController.js     # Authentication logic
│   │   ├── cardsController.js    # Tasks CRUD logic
│   │   ├── tagsController.js     # Tags management
│   │   ├── aiController.js       # AI request handling
│   │   └── notificationsController.js  # Notifications logic
│   ├── middleware/
│   │   └── auth.js               # JWT verification middleware
│   ├── routes/                   # API route definitions
│   │   ├── auth.js               # /api/auth endpoints
│   │   ├── cards.js              # /api/cards endpoints
│   │   ├── tags.js               # /api/tags endpoints
│   │   ├── ai.js                 # /api/ai endpoints
│   │   └── notifications.js      # /api/notifications endpoints
│   ├── utils/
│   │   ├── logger.js             # Logging utility
│   │   ├── cardHelpers.js        # Card helper functions
│   │   └── notificationsHelper.js # Notification utilities
│   ├── data.json                 # JSON database file
│   ├── index.js                  # Express server entry point
│   └── package.json              # Backend dependencies
│
├── dist/                         # Production build output
├── .gitignore                    # Git ignore rules
├── vite.config.js                # Vite configuration
└── package.json                  # Frontend dependencies

Key Components Explained

  • Context API: Manages global state (auth, tasks, theme) without prop drilling
  • Services Layer: Abstracts API calls, handles errors, manages tokens
  • Controllers: Business logic separated from routes for maintainability
  • Middleware: JWT authentication protects all private routes
  • JSON Database: Simple file-based storage (suitable for learning, not production)

🚀 Installation & Setup

Prerequisites

  • Node.js >= 18.x
  • npm >= 9.x (or yarn/pnpm)
  • Git (for cloning)

Installation Steps

  1. Clone the repository

    git clone https://github.com/VarozXYZ/how-to-do-list.git
cd how-to-do-list

  2. Install frontend dependencies

    npm install

  3. Install backend dependencies

    cd server
npm install
cd ..

Environment Variables

Create a .env file in the server/ directory:

# Server Configuration
PORT=3001
NODE_ENV=development

# Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# AI Service (DeepSeek)
DEEPSEEK_API_KEY=your-deepseek-api-key-here

Important Notes:

  • JWT_SECRET: Use a strong, random string for production
  • DEEPSEEK_API_KEY: Get your API key from DeepSeek
  • The .env file is already in .gitignore and won't be committed

Running the Application

  1. Start the backend server (Terminal 1)

    cd server
npm run dev

    Server will run on http://localhost:3001

  2. Start the frontend development server (Terminal 2)

    npm run dev

    Frontend will run on http://localhost:5173

  3. Open your browser Navigate to http://localhost:5173

The Vite proxy is configured to forward /api requests to the backend automatically.

Production Build

# Build frontend
npm run build

# The built files will be in the dist/ directory
# Serve with any static file server or deploy to hosting service

✨ Main Features

Task Management

  • ✅ Create, Edit, Delete Tasks: Full CRUD operations for tasks
  • ✅ Task Details: Title, description (Markdown support), due date/time, priority
  • ✅ Task Status: Active, completed, and expired states
  • ✅ Task Filtering: Filter by tags, priority, status, and search by text
  • ✅ Task Sorting: Sort by date, priority, or title

Tag System

  • ✅ Custom Tags: Create tags with custom names and colors
  • ✅ Color Coding: 8 color presets for visual organization
  • ✅ Default Tags: Pre-configured tags (Marketing, Personal, Design, Work, Research)
  • ✅ Tag Favorites: Mark tags as favorites for quick access

AI Features

  • ✅ Task Improvement: AI suggests better task descriptions
  • ✅ Basic & Advanced Modes: Choose between quick suggestions or detailed improvements
  • ✅ Personality Settings: Adjust formality and creativity levels
  • ✅ Usage Tracking: Monitor AI usage with per-user limits
  • ✅ Markdown Preview: View AI-generated content with full Markdown rendering

User Experience

  • ✅ Authentication: Secure JWT-based login and registration
  • ✅ User Profiles: Customize name, email, and preferences
  • ✅ Dark Mode: Toggle between light and dark themes (persistent)
  • ✅ Notifications: In-app notification system for task events
  • ✅ Responsive Design: Works on desktop, tablet, and mobile devices

Additional Features

  • ✅ Completed Tasks View: Separate page for completed tasks
  • ✅ Settings Page: Manage profile, preferences, and notification settings
  • ✅ Pricing Page: Placeholder for future subscription plans
  • ✅ Search Functionality: Debounced search across all tasks

🔄 How It Works

User Flow

  1. Registration/Login

    • User registers with email and password
    • Backend hashes password with bcryptjs
    • JWT token generated and stored in localStorage
    • Token sent with every API request via Axios interceptor

  2. Task Creation

    • User creates task with title, description, tags, priority, due date
    • Frontend sends POST request to /api/cards
    • Backend saves to data.json with user ID association
    • Task appears in dashboard immediately

  3. AI Enhancement

    • User clicks AI button on a task
    • Frontend sends task data to /api/ai/improve
    • Backend calls DeepSeek API with configured prompts
    • AI returns improved description
    • Frontend displays result with Markdown preview

  4. Task Management

    • User filters, sorts, or searches tasks
    • Context API manages state updates
    • Changes sync with backend via API calls
    • UI updates reactively

  5. Notifications

    • Backend checks for expired tasks periodically
    • Creates notifications for task events (completion, expiry, etc.)
    • Frontend polls /api/notifications endpoint
    • Notifications displayed in dropdown menu

Data Persistence

  • JSON File Database: All data stored in server/data.json
  • User Isolation: Each user only sees their own tasks (filtered by userId)
  • Real-time Updates: Changes reflect immediately after API calls
  • No Migrations: Simple structure, easy to understand and modify

🎓 Educational Purpose

This project was created for educational purposes to practice and demonstrate:

Full-Stack Development

  • ✅ Frontend Architecture: React Context API, custom hooks, component composition
  • ✅ Backend Architecture: RESTful API design, middleware patterns, separation of concerns
  • ✅ API Integration: HTTP client setup, error handling, authentication flows

Modern Development Practices

  • ✅ State Management: Context API for global state, local state for components
  • ✅ Code Organization: Clear folder structure, reusable components, service layer
  • ✅ Performance: Debounced search, memoization, optimized re-renders

Real-World Features

  • ✅ Authentication: JWT tokens, password hashing, protected routes
  • ✅ AI Integration: External API consumption, error handling, usage limits
  • ✅ User Experience: Dark mode, responsive design, notifications

Learning Outcomes

  • Understanding React hooks and context patterns
  • Building RESTful APIs with Express
  • Implementing authentication and authorization
  • Integrating third-party APIs (AI services)
  • Managing application state effectively
  • Creating responsive, accessible UIs

🔮 Potential Improvements

High Priority

  • Database Migration: Replace JSON file with PostgreSQL or MongoDB
  • Real-time Updates: Implement WebSockets for live task updates
  • User Authentication: Add OAuth (Google, GitHub) login
  • Payment Integration: Implement Stripe for subscription plans
  • Email Notifications: Send email reminders for due tasks

Medium Priority

  • Unit Tests: Add Jest/Vitest tests for components and API endpoints
  • E2E Tests: Implement Cypress or Playwright for integration testing
  • Docker Support: Containerize application for easy deployment
  • CI/CD Pipeline: Set up GitHub Actions for automated testing and deployment
  • Internationalization: Add i18n support for multiple languages

Low Priority

  • Task Templates: Pre-defined task templates for common workflows
  • Task Dependencies: Link related tasks together
  • Time Tracking: Track time spent on tasks
  • Export/Import: Export tasks to CSV/JSON, import from other services
  • Mobile App: React Native version for iOS/Android

Technical Debt

  • TypeScript Migration: Convert JavaScript to TypeScript for type safety
  • Error Boundaries: Add React error boundaries for better error handling
  • API Documentation: Generate OpenAPI/Swagger documentation
  • Logging System: Implement structured logging (Winston, Pino)
  • Rate Limiting: Add rate limiting to prevent API abuse

📸 Screenshots & Demo

Dashboard View

The main dashboard displays all active tasks in a card-based grid layout with filtering and sorting options.

Task Creation

Modal interface for creating new tasks with rich options for tags, priorities, and due dates.

AI Enhancement

AI-powered task improvement with Markdown preview and customizable personality settings.

Dark Mode

Full dark mode support with consistent theming across all components.

Note: Screenshots can be added to a /screenshots directory and referenced here.

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025 [How] ToDoList

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

👤 Author

VarozXYZ

🙏 Acknowledgments

  • DeepSeek AI for providing the AI service used in this project
  • React Team for the amazing React framework
  • Vite Team for the fast build tool
  • Express.js for the robust backend framework
  • Bootstrap for the UI components

📝 Notes

  • This is an educational project and should not be used in production without significant improvements
  • The JSON file database is suitable for learning but should be replaced with a proper database for any real-world use
  • AI features require a valid DeepSeek API key to function
  • All user data is stored locally in the server/data.json file

Last Updated: December 2025

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages