🧠 MindMate

An intelligent task companion to help you focus and reduce overwhelm.

---

MindMate is not just another to-do list. It's an intelligent task management app designed to help you focus and combat procrastination. By combining a clean, calming user interface with powerful AI features, it makes planning your day feel effortless. Instead of showing a long, overwhelming list, it suggests one task at a time based on your current energy level.

If a task feels too big, its AI can break it down into smaller, more manageable steps. With features like smart reminders, a conversational AI check-in, and a rich note-taking system, MindMate helps you stay organized, motivated, and in control.

✨ Key Features

Here is a summary of the key features implemented so far:

• 🤖 AI-Powered Task Suggestions: The home page intelligently suggests one task at a time based on your selected energy level.

• 🔮 Advanced AI Task Tools:

  • AI Task Breakdown: "Divide Task" feature breaks large tasks into smaller, actionable sub-tasks.
  • AI Task Enhancement: Automatically suggest a clearer title, write a description, and predict the best category and duration for a new task.
  • URL Summarization: Pasting a URL as a task title automatically generates a summary for the description.

• ✅ Comprehensive Task Management:

  • Full CRUD (Create, Read, Update, Delete) for tasks.
  • Sub-tasks: Create and manage nested sub-tasks for larger projects.
  • Reminders & Recurrence: Set due dates and create repeating tasks (daily, weekly, monthly).

• 📝 Rich Note-Taking System:

  • A flexible, grid-based layout for notes, inspired by Google Keep.
  • Rich Text Formatting: Includes bold, italics, lists, and adjustable font sizes.
  • Multimedia & Styling: Add images via URL and color-code your notes.
  • Search Functionality: A search bar to quickly find text within any of your notes.

• 💬 Conversational AI Check-in: A dedicated chat page where you can talk with an AI assistant that has context on your tasks to help you plan.

• 📊 History & Views:

  • Pending Tasks Page: A dedicated view to see all upcoming to-do items.
  • Completed History: A chronological view of all your accomplished tasks, grouped by day.
  • Detailed Task Page: A focused view for a single task and its sub-tasks.

• 🎨 Customization & Notifications:

  • Theme Picker: Personalize the app's look with different color themes and light/dark modes.
  • Custom Settings: Define your own task categories and default durations.
  • Smart Notifications: Get reminders for upcoming tasks right in your browser.

• 🎉 Milestones & Anniversary Tracking: Track one-time events and recurring milestones (birthdays, anniversaries, achievements). Includes a create/edit UI, dashboard card showing time-since and time-until, and scheduled push reminders (30d, 7d, 3d, 1d, on-the-day). Server-side logic stores notifications in Firestore and sends web-push via VAPID.

🚀 Newly Implemented & Advanced Features

• Advanced Calendar & Time Management

  • Drag-and-drop task scheduling
  • Time blocking interface
  • Multiple calendar views (day/week/month/agenda)
  • Pomodoro timer integration
  • Conflict detection and resolution for calendar sync
  • Mobile-optimized responsive design
  • Advanced task visualization
  • Session tracking and statistics

• External Calendar Sync

  • Google Calendar integration (sync, conflict resolution, two-way sync)
  • Outlook Calendar integration (framework present)
  • Sync token management for incremental sync

• Push Notification System

  • Comprehensive API for notifications (subscribe, unsubscribe, preferences, reminders)
  • Smart notification scheduling (quiet hours, customizable timing, multiple types)
  • Notification dashboard and history UI
  • Advanced user preferences (sound, vibration, priority, grouping, max daily, etc.)
  • Background sync for notifications and tasks (offline support via service worker)

• Task Management Enhancements

  • Recurring tasks (basic and advanced patterns)
  • Time-blocked tasks
  • Pomodoro session tracking
  • Task reminders and overdue notifications

• Sharing & Collaboration

  • Share tasks and notes via unique links
  • Permission management for shared items

• Notes System

  • Rich note-taking (grid layout, formatting, images, color-coding, search)

• Mobile & PWA Features

  • Offline support (service worker caches, background sync)
  • App install prompt
  • Responsive/mobile-first design

• User Customization

  • Theme picker (light/dark, color themes)
  • Custom notification settings
  • Custom task categories and durations

• Accessibility

  • Keyboard navigation
  • Screen reader support

🎉 Milestones feature overview

This project now includes a Milestones subsystem for tracking important dates (birthdays, anniversaries, achievements, purchases, etc.) with optional recurring anniversaries and push reminders.

Quick summary

• Milestones can be one-time or recurring (yearly/monthly). Recurring milestones compute the next anniversary and can trigger reminders at: 30 days, 7 days, 3 days, 1 day, and on the day.
• Notifications are saved to Firestore under users/{email}/notifications and sent as web-push to subscriptions saved in pushSubscriptions.

Core features

• Milestone data model (typed) with notification preferences, recurrence flags, and timestamps.
• UI: create / edit modal with conditional notification settings (shown only for recurring milestones) and a dashboard card that displays "time since" and "time until" next anniversary.
• Server: integrated scheduling in the comprehensive notification check. Prevents duplicate daily sends, respects quiet hours, and removes invalid push subscriptions.
• Utilities & service layer: date helpers for anniversary math and a Firestore-backed service that safely writes only defined fields (avoids undefined causing Firestore errors).

File locations (primary)

• Types: src/lib/types.ts
• Date utils: src/lib/milestone-utils.ts
• Firestore service (CRUD): src/services/milestone-service.ts
• Milestone form UI: src/components/milestone-form.tsx
• Dashboard card UI: src/components/milestone-dashboard-card.tsx
• Notification processing and web-push logic: src/app/api/notifications/comprehensive-check/route.ts

How to test notifications (single-run)

1. Ensure dev server is running and environment variables are set (VAPID keys, Firebase credentials).
2. Run a single notification check (this will log detailed milestone debug info):

PowerShell (from project root):

# Trigger a single run of the server-side notification check
Invoke-WebRequest -Uri "http://localhost:3000/api/notifications/comprehensive-check?mode=single" -Method POST

curl (alternative):

curl -X POST "http://localhost:3000/api/notifications/comprehensive-check?mode=single"

Debugging tips

• Check server logs for these markers added to the notification route:
  • 🔍 Processing milestone: shows milestone payload read from Firestore
  • 📅 Anniversary calculation: shows computed next anniversary and daysUntil
  • 📋 Notification settings for ... shows effective notification toggles
  • ✅ Should notify: or ❌ No notification rule matches: explains the decision
• Common causes for missed sends:
  1. isRecurring is false (one-time milestones do not calculate daysUntil).
  2. originalDate stored in Firestore as an unexpected type (ensure it's a timestamp/number or valid Date).
  3. The specific notification preference (oneWeekBefore, oneDayBefore, etc.) is disabled.
  4. User has no valid push subscriptions or notifications are disabled in notificationPreferences.
  5. Quiet hours are active for the user at check time.

What to check in Firestore

• users/{email}/milestones/{milestoneId}: fields isRecurring, originalDate, notificationSettings, and lastNotifiedAt.
• pushSubscriptions collection: verify valid subscription documents for the user.
• users/{email}/notifications: look for documents with data.type === 'milestone-reminder' to see if a notification was created and whether sentAt was updated.

If you'd like, I can run a single check locally and paste the server logs here or add an optional debug endpoint that forces a notification for a specific milestone id for safe testing.

🛠️ Tech Stack

• Framework: Next.js (App Router)
• Language: TypeScript
• AI Framework: Genkit (with Google Gemini)
• UI Library: React, ShadCN UI
• Styling: Tailwind CSS
• Database: Firebase Firestore
• State Management: React Context API

🚀 Getting Started

To get a local copy up and running, follow these simple steps.

Prerequisites

• Node.js (v18 or higher)
• npm

Installation

1. Clone the repository:

   git clone https://github.com/hamidijaz/MindMate.git
   cd MindMate

2. Install NPM packages:

   npm install

3. Set up Firebase:

   • Create a Firebase project at console.firebase.google.com.

   • Enable the Firestore Database.

   • Copy your Firebase project configuration credentials.

   • Create a .env.local file in the root of the project and add your credentials. Below is a full list of required and optional fields:

   # Firebase Configuration
   NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key_here
   NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
   NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
   NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.firebasestorage.app
   NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
   NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
   NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id
   
   # Google AI Configuration
   GOOGLE_AI_API_KEY=your_google_ai_api_key_here
   
   # External Calendar Integration - Google Calendar
   GOOGLE_CLIENT_ID=your_google_oauth_client_id
   GOOGLE_CLIENT_SECRET=your_google_oauth_client_secret
   GOOGLE_REDIRECT_URI=http://localhost:3000/api/calendar/google
   
   # External Calendar Integration - Microsoft Outlook
   OUTLOOK_CLIENT_ID=your_outlook_app_client_id
   OUTLOOK_CLIENT_SECRET=your_outlook_app_client_secret
   OUTLOOK_REDIRECT_URI=http://localhost:3000/api/calendar/outlook
   
   # Development Settings
   NEXT_PUBLIC_USE_FIREBASE_EMULATOR=false
   
   # Push Notification Configuration (VAPID Keys)
   NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_vapid_public_key_here
   VAPID_PRIVATE_KEY=your_vapid_private_key_here
   
   # Optional: Analytics
   NEXT_PUBLIC_GA_MEASUREMENT_ID=your_ga_measurement_id

   • Refer to FIREBASE_MIGRATION.md for details on the Firestore data structure.

4. Set up Genkit (for AI features):

   • Obtain a Gemini API key from Google AI Studio.
   • Add the API key to your .env.local file:

     GEMINI_API_KEY=your-gemini-api-key

Running the Application

1. Start the development server:

   npm run dev

   The application will be available at http://localhost:9002.

2. Start the Genkit server (for AI flows): In a separate terminal, run:

   npm run genkit:dev

   The Genkit development UI will be available at http://localhost:4000.

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
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

👤 Owner

This project is maintained by Hamid Ijaz.

• GitHub: @hamidijaz
• LinkedIn: Hamid Ijaz

📄 License

Distributed under the MIT License. See LICENSE for more information.