A modern, full-stack todo application built with Next.js 15, TypeScript, ConvexDB, and Clerk authentication. Features real-time synchronization, category organization, and a beautiful responsive UI.

• ✅ Real-time Synchronization - Changes sync instantly across all devices
• ✅ Secure Authentication - Powered by Clerk.js with social login support
• ✅ Category Organization - Organize todos with customizable categories
• ✅ Progress Tracking - Visual progress bars and completion statistics
• ✅ Responsive Design - Works perfectly on desktop, tablet, and mobile
• ✅ TypeScript - Full type safety throughout the application
• ✅ Modern UI - Built with Tailwind CSS and shadcn/ui components
• ✅ Database - Real-time database with ConvexDB
• ✅ API - RESTful API with comprehensive documentation

• Node.js 18.0 or higher
• npm, bun, or yarn package manager
• Git

1. Clone the repository

   git clone <repository-url> cd todo-app

2. Install dependencies

   npm install # or bun install

3. Set up environment variables

   cp .env.example .env.local

   Edit .env.local with your credentials:

   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_key CLERK_SECRET_KEY=sk_test_your_secret NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud NEXT_PUBLIC_APP_URL=http://localhost:3000

4. Set up Clerk Authentication

   • Create account at Clerk Dashboard
   • Create a new application
   • Copy API keys to your .env.local

5. Set up Convex Database

   npx convex dev --once npx convex deploy

6. Run the development server

   npm run dev # or bun dev

7. Open your browser

   • Navigate to http://localhost:3000
   • Sign up for a new account or sign in

• User Guide - Complete user manual with screenshots and examples
• Setup Guide - Step-by-step setup instructions for development and production
• Deployment Guide - Deploy to Vercel, Netlify, AWS, and more

• API Documentation - Complete API reference with examples
• Best Practices - Development guidelines and patterns
• Troubleshooting - Common issues and solutions

• Product Requirements - Product vision and requirements
• Research Notes - Technical research and decisions
• Calendar Sync - Calendar integration documentation

• Next.js 15 - React framework with App Router
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework
• shadcn/ui - Modern UI components
• Lucide Icons - Beautiful icon library

• ConvexDB - Real-time database
• Clerk - Authentication and user management
• Next.js API Routes - Server-side functionality

• ESLint - Code linting
• Prettier - Code formatting
• Jest - Unit testing
• Playwright - End-to-end testing
• Vitest - Fast unit testing

todo-app/ ├── app/ # Next.js app router pages │ ├── api/ # API routes │ ├── profile/ # User profile page │ ├── sign-in/ # Authentication pages │ ├── sign-up/ │ └── todos/ # Main todos page ├── components/ # Reusable React components │ ├── ui/ # shadcn/ui components │ └── AuthGuard.tsx # Authentication guard ├── convex/ # ConvexDB backend │ ├── todos.ts # Todo operations │ ├── categories.ts # Category operations │ ├── schema.ts # Database schema │ └── auth.config.js # Authentication config ├── docs/ # Documentation ├── lib/ # Utility functions ├── public/ # Static assets └── tests/ # Test files 

# Development npm run dev # Start development server npm run build # Build for production npm run start # Start production server npm run lint # Run ESLint # Testing npm test # Run unit tests npm run test:ui # Run tests with UI npm run test:coverage # Generate coverage report # Database npx convex dev # Start Convex development npx convex deploy # Deploy Convex functions npx convex dashboard # Open Convex dashboard # Verification node verify-auth-setup.js # Verify authentication setup

1. Connect your repository to Vercel
2. Add environment variables in Vercel dashboard
3. Deploy automatically on every push to main

• Netlify
• Railway
• AWS
• Docker

The app uses Clerk for authentication with the following features:

• Email/Password authentication
• Social login (Google, GitHub, etc.)
• User profiles with avatars
• Session management
• Secure API access

{ _id: Id<"users"> clerkId: string email: string name?: string createdAt: number }

{ _id: Id<"categories"> userId: Id<"users"> name: string color: string createdAt: number }

{ _id: Id<"todos"> userId: Id<"users"> categoryId?: Id<"categories"> title: string description?: string completed: boolean createdAt: number updatedAt: number }

npm test

npx playwright test

npm run test:coverage

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Commit your changes: git commit -m 'Add your feature'
6. Push to the branch: git push origin feature/your-feature
7. Open a Pull Request

• Follow the existing code style
• Write comprehensive tests
• Update documentation as needed
• Use TypeScript for all new code
• Follow conventional commit messages

• Lighthouse Score: 95+ on all metrics
• First Contentful Paint: < 1.5s
• Time to Interactive: < 3s
• Bundle Size: < 200KB gzipped

• HTTPS Only: All communications encrypted
• Secure Headers: CSP, HSTS, and other security headers
• Input Validation: All inputs validated and sanitized
• Authentication: JWT-based secure authentication
• Authorization: Row-level security with ConvexDB

• Vercel Analytics: Built-in performance monitoring
• Convex Dashboard: Database monitoring and logs
• Clerk Dashboard: Authentication monitoring
• Error Tracking: Sentry integration for error monitoring

1. Authentication not working

   • Check Clerk configuration
   • Verify environment variables
   • Clear browser cache

2. Database connection issues

   • Verify Convex URL
   • Check network connectivity
   • Review Convex dashboard

3. Build failures

   • Check Node.js version (18+)
   • Clear node_modules and reinstall
   • Check for TypeScript errors

See Troubleshooting Guide for detailed solutions.

• Next.js Documentation
• ConvexDB Documentation
• Clerk Documentation
• Tailwind CSS
• shadcn/ui

This project is licensed under the MIT License - see the LICENSE file for details.

• Next.js Team for the amazing framework
• Convex for the real-time database
• Clerk for authentication
• shadcn for the beautiful UI components
• Tailwind CSS for the styling system

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Happy todo-ing! 🎉