TaskFlow

A modern, full-stack productivity and task management platform with algorithmic priority scoring, dual-mode storage, and built-in focus tools.

Live Demo: https://task-flow-psi-silk.vercel.app
Repository: https://github.com/dhanesh-hub/TaskFlow

Overview

TaskFlow is a production-grade web application designed for knowledge workers, developers, and students to manage complex workloads without decision fatigue.

Traditional task lists quickly become disorganized backlogs. TaskFlow solves this by combining:

Deterministic Priority Scoring (0–100) to dynamically highlight the next best task to work on.
Dual-Mode Persistence offering instant offline exploration via LocalStorage or cloud synchronization via Google Cloud Firestore.
Integrated Focus & Planning Tools including daily timeblocking, Pomodoro focus timers, real-time analytics, and an offline-grounded AI assistant.

Key Features

Authentication & User Management: Firebase Email/Password login, Google Authentication, and a 1-Click Demo mode with pre-seeded data.
Dual Storage Architecture: Automatic switching between Cloud Firestore (for authenticated users) and LocalStorage (for demo/offline mode).
Task CRUD & Organization: Create, edit, delete, duplicate, archive, and unarchive tasks with rich metadata.
Interactive Views: Switch seamlessly between a structured List View and an interactive Kanban Board (To Do, In Progress, Completed).
Subtasks & Progress Tracking: Manage granular subtasks with live percentage completion bars.
Search, Filtering & Sorting: Real-time multi-criteria filtering by category, priority, status, completion, and keyword search.
Algorithmic Priority Engine: Computes a transparent 0–100 priority score with factor breakdown tooltips.
Today Focus Workspace: Filter out workspace noise to focus strictly on tasks due today with batch overdue rescheduling.
Deep Focus & Pomodoro Timer: Stopwatch and countdown timer to track estimated vs. actual minutes worked.
Daily Planner: Structured hourly timeblocking grid (07:00 to 22:00) to map goals into dedicated focus slots.
Productivity Analytics & Streaks: Visual completion velocity, creation trends, category breakdown, and daily streak tracking via Recharts.
Milestone Achievements: Automatically unlocks tiered badges based on task completion milestones and consistency.
In-App Notifications: Alerts for overdue deadlines, daily streaks, and milestone achievements.
Data Export & Import: Complete workspace JSON backup and restore capabilities.
AI Productivity Assistant: Generates structured task breakdowns and answers workspace questions in offline/demo mode without data leakage.
Light-Mode Only UI: Clean, distraction-free interface built with Tailwind CSS and responsive design for mobile and desktop.

Technology Stack

Layer	Technology	Purpose
Frontend	React 18, TypeScript 5.6, Vite 6	Core Single-Page Application (SPA) & build tool
Styling & UI	Tailwind CSS 3.4, Lucide Icons	Responsive layout, design tokens, and iconography
Routing	React Router DOM 6.28	Code-split client-side routing with `React.lazy`
Validation	Zod 3.23, React Hook Form	Schema validation for forms and entity storage
Data Visualization	Recharts 2.13	Interactive analytics charts (Area, Bar, Pie)
Cloud Backend	Firebase Auth, Cloud Firestore	User authentication and cloud data persistence
Testing	Vitest 2.1, Happy-DOM	Automated unit and integration testing
Deployment	Vercel, Docker / Nginx	Frontend web hosting and containerized deployment

System Architecture

flowchart TD
    UI[React 18 UI Layer<br/>Dashboard / Tasks / Today / Planner / Analytics / AI] --> Context[React Context Providers<br/>AuthContext / TaskContext / ToastContext / NotificationContext]
    Context --> Adapter[Storage Adapter Manager<br/>storageAdapter.getAdapter]
    
    Adapter -->|Authenticated Firebase User| FirestoreRepo[Firestore Repository]
    Adapter -->|Demo / Guest User| LocalRepo[Local Repository]
    
    FirestoreRepo --> FirestoreDB[(Cloud Firestore<br/>users/uid/...)]
    LocalRepo --> BrowserStorage[(LocalStorage<br/>taskflow_tasks_uid)]

AI Assistant Architecture

flowchart TD
    AI_UI[AI Assistant Page / Goal Breakdown Modal] --> AIService[AI Service Interface]
    AIService --> MockProvider[Mock AI Provider]
    MockProvider --> OfflineResponse[Offline Heuristics & Local Workspace Context]

Note on AI Architecture: Gemini Cloud AI proxy integration exists in the codebase but is currently disabled in the live production deployment. The deployed application runs exclusively in Offline / Demo AI Mode with zero external API dependencies or key requirements.

Firebase Cloud Data Structure

When connected to Firebase, user data is strictly isolated within the authenticated user's document path:

users/{uid}
  ├── tasks/{taskId}               # Task entities, subtasks, priority scores
  ├── categories/{categoryId}     # Custom user categories
  ├── activity/{activityId}       # Historical audit logs
  └── achievements/{achievementId} # Unlocked badges and streak data

Data Isolation: Firestore Security Rules enforce request.auth != null && request.auth.uid == userId across all subcollections. Users cannot read, write, or delete another user's records.

Deterministic Priority Scoring Engine

TaskFlow uses an algorithmic, deterministic scoring engine (0 to 100 points) to eliminate task paralysis without black-box AI:

$$\text{Priority Score} = \min\Big(100, \text{User Priority} + \text{Deadline Proximity} + \text{Effort Ratio} + \text{Subtask Momentum} + \text{Stagnation}\Big)$$

User Priority (10–40 pts): Low (10), Medium (20), High (30), Urgent (40).
Deadline Proximity (0–35 pts): Overdue (+20 to +35 pts, +3 pts/day overdue), Due Today (+25 pts), Tomorrow (+18 pts), This Week (+12 pts).
Effort Ratio (0–12 pts): Quick wins ($\le 20$m) get +12 pts; manageable tasks ($\le 45$m) get +8 pts.
Subtask Momentum (0–8 pts): Awarded proportionally to completed subtask percentage.
Stagnation Age (0–7 pts): Incremental penalty for active tasks pending $>3$ days without updates.

AI Assistant (Offline / Demo Mode)

Grounded Workspace Responses: Directly references your real tasks, overdue items, streaks, and categories to answer queries (e.g., "What should I work on today?", "Which tasks are overdue?").
Goal Decomposition: Breaks complex goals into 4–5 actionable subtasks with time estimates and actionable execution tips.
Zero Privacy Leakage: All computations are performed locally in the browser; no private workspace data or credentials leave your device.

Security

Authentication: Firebase Authentication manages user tokens and session lifecycle.
Granular Security Rules: Cloud Firestore rules strictly enforce individual user ownership.
Input Validation: All task, category, and profile mutations are validated against Zod schemas.
Credential Protection: Private credentials, service account keys, and .env.local files are excluded via .gitignore. No Gemini API keys or private tokens exist in the client bundle.

Automated Testing & Quality Assurance

Unit & Integration Tests: 45 passed (5 test suites) via Vitest.
Type Checking: Clean (tsc --noEmit passed with 0 errors).
Production Build: Clean bundle generated with manual vendor chunking (tsc -b && vite build).
Route Smoke Tests: 15 / 15 application routes verified for HTTP 200 and DOM hydration.

# Run automated test suite
npm test

# Run TypeScript linter
npm run lint

# Build production bundle
npm run build

Deployment

Frontend Hosting: Deployed on Vercel with single-page application routing (vercel.json).
Backend Services: Google Cloud Firestore and Firebase Authentication handle cloud data and authentication.
Production URL: https://task-flow-psi-silk.vercel.app

Local Development

1. Clone & Install

git clone https://github.com/dhanesh-hub/TaskFlow.git
cd TaskFlow
npm install

2. Configure Environment (Optional)

TaskFlow runs out-of-the-box in Demo Mode without any configuration. To connect your own Firebase project:

Copy .env.example to .env.local:
```
cp .env.example .env.local
```

Add your Firebase Web SDK keys into .env.local:

VITE_APP_MODE=production
VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project_id.firebasestorage.app
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id

3. Start Development Server

npm run dev

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

Project Structure

TaskFlow/
├── src/
│   ├── components/         # Reusable UI, layout, and auth components
│   ├── context/            # React Context stores (Auth, Task, Toast, Notification)
│   ├── features/           # Feature views (Tasks, Kanban, Planner, Focus, AI)
│   ├── pages/              # Route pages (Dashboard, Tasks, Today, Analytics, etc.)
│   ├── services/           # Firebase SDK, StorageAdapter, AuthService, AIService
│   ├── types/              # TypeScript interfaces and type definitions
│   ├── utils/              # Priority engine, streak calculator, Zod schemas
│   ├── App.tsx             # Root component and code-split route definitions
│   └── main.tsx            # Application entry point
├── functions/              # Firebase Cloud Functions (backend reference)
├── scripts/                # Verification and smoke testing scripts
├── firestore.rules         # Cloud Firestore security rules
├── storage.rules           # Firebase Storage security rules
├── firebase.json           # Firebase project configuration
├── vercel.json             # Vercel SPA rewrite configuration
├── Dockerfile              # Production Nginx container configuration
├── docker-compose.yml      # Docker container orchestration
├── .env.example            # Safe environment template
├── CONTRIBUTING.md         # Contribution guidelines
├── SECURITY.md             # Security policy and data isolation model
├── LICENSE                 # MIT License
└── package.json            # Dependencies and npm scripts

Contributing

Contributions, issues, and feature requests are welcome. Please read CONTRIBUTING.md for development guidelines.

Security Policy

Please review SECURITY.md for vulnerability reporting and security details.

License

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

Navigation Menu

Repository files navigation

TaskFlow

Overview

Key Features

Technology Stack

System Architecture

AI Assistant Architecture

Firebase Cloud Data Structure

Deterministic Priority Scoring Engine

AI Assistant (Offline / Demo Mode)

Security

Automated Testing & Quality Assurance

Deployment

Local Development

1. Clone & Install

2. Configure Environment (Optional)

3. Start Development Server

Project Structure

Contributing

Security Policy

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
functions		functions
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
firebase.json		firebase.json
firestore.rules		firestore.rules
index.html		index.html
nginx.conf		nginx.conf
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
storage.rules		storage.rules
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vercel.json		vercel.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation

TaskFlow

Overview

Key Features

Technology Stack

System Architecture

AI Assistant Architecture

Firebase Cloud Data Structure

Deterministic Priority Scoring Engine

AI Assistant (Offline / Demo Mode)

Security

Automated Testing & Quality Assurance

Deployment

Local Development

1. Clone & Install

2. Configure Environment (Optional)

3. Start Development Server

Project Structure

Contributing

Security Policy

License

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages