Your Personal Progress Tracking Companion
FlowState is a modern, comprehensive tracking application designed to help you manage and monitor your progress across all areas of interest - from the books you're reading and courses you're taking, to the movies you're watching and activities you're pursuing.
In our busy lives, we often start multiple projects, books, courses, and activities but struggle to keep track of our progress. FlowState solves this by providing:
- Centralized Tracking: One place for all your ongoing interests
- Visual Progress: See how far you've come with intuitive progress bars and analytics
- Rich Context: Add notes, ratings, tags, and detailed metadata
- Motivation: Visual feedback and completion statistics keep you motivated
- Organization: Smart categorization and filtering to manage large collections
- Insights: Understand your habits and preferences through detailed analytics
Perfect for students, lifelong learners, content consumers, and anyone who wants to be more intentional about their personal growth and entertainment choices.
- Media: Movies, TV shows, documentaries, games
- Reading: Books, articles, research papers, blogs
- Learning: Online courses, tutorials, skill development
- Activities: Sports, hobbies, personal projects
- Custom Categories: Create your own tracking categories
- Visual Progress Bars: See completion percentage at a glance
- Flexible Metrics: Track pages, episodes, chapters, hours, or custom units
- Status Management: Not started, in progress, paused, completed, or dropped
- Priority Levels: Organize by importance (low, medium, high)
- Time Tracking: Monitor time spent on each item
- Detailed Information: Author/creator, year, genre, tags
- Personal Notes: Add descriptions, reviews, and thoughts
- Rating System: 5-star rating system for completed items
- Custom Fields: Extend with your own metadata fields
- Cover Images: Visual identification (coming soon)
- Responsive Design: Perfect on desktop, tablet, and mobile
- Dark/Light Themes: Automatic system detection + manual toggle
- Intuitive Interface: Clean, modern design with shadcn/ui components
- Fast Performance: Optimized with Next.js 15 and modern web standards
- Keyboard Shortcuts: Power-user friendly navigation (coming soon)
- Firebase Authentication: Secure email/password authentication
- Real-time Sync: All data synced across devices instantly
- Offline Support: Basic offline functionality (coming soon)
- Data Privacy: Your data belongs to you, stored securely in Firebase
- Export/Import: Backup and migrate your data (coming soon)
- Progress Analytics: Completion rates, time spent, trends over time
- Category Breakdown: See which areas you're most active in
- Monthly Statistics: Track your productivity and habits
- Achievement System: Celebrate your progress milestones (coming soon)
- User Authentication - Secure signup/login with Firebase
- Real-time Sync - Firebase Firestore for instant data synchronization
- Data Privacy - Secure user data isolation with Firestore security rules
- Modern Sidebar Navigation - Collapsible sidebar with mobile bottom navigation
- Responsive Design - Mobile-first design that works on all devices
- Enhanced Color Themes - Professional warm off-white and deep gray themes
- Professional Skeletons - Loading states that match actual content layouts
- Larger Buttons - Improved mobile experience with bigger touch targets
- Toast Notifications - User feedback with Sonner toast system
- Dashboard - Overview of your progress with statistics cards
- Items Management - View, filter, and manage your collection
- Progress Tracking - Visual progress bars and percentage tracking
- Priority System - Mark items as low, medium, or high priority
- Status Management - Track items through different lifecycle stages
- Search & Filtering - Find items quickly with powerful filters
- Grid/List Views - Choose how you want to view your items
- Dynamic Form Fields - Category-specific form fields that adapt to selection
- Default Category Templates - Pre-built templates for Media, Reading, Learning, Activity
- Custom User Categories - Create and manage your own category templates
- Category-Specific Fields - Unique fields for each category (director, author, instructor, etc.)
- Custom Field Storage - All dynamic fields properly stored in Firestore
- Form Validation - Comprehensive validation with Zod schemas
- Analytics Dashboard - Detailed insights into your tracking habits
- Category Breakdown - Visual distribution of items across categories
- Status Analytics - Progress tracking across different completion states
- Monthly Statistics - Track your productivity and habits over time
- Lazy Loading - User categories loaded on-demand for better performance
- Optimized Skeletons - Loading states that exactly match real content
- Smart State Management - Efficient data loading and caching with Zustand
- Bundle Optimization - Code splitting and dynamic imports for faster loading
- Item Detail Pages - Dedicated pages for viewing and editing items
- Progress Updates - Quick progress update functionality
- Settings Page - User preferences and account management
- Cover Image Upload - Visual identification for your items
- Advanced Analytics - Trends, predictions, and deeper insights
- Data Export/Import - Backup and migrate your data
- Sharing Features - Share your lists and progress with friends
- External Integrations - Import from Goodreads, Letterboxd, etc.
- Mobile App - Native mobile experience with React Native
- Offline Support - Work without internet connection
- Achievement System - Gamification with badges and milestones
- Custom Themes - Create your own color schemes
- Collaboration - Share and collaborate on lists with others
- API Access - REST API for third-party integrations
- Browser Extension - Quick add functionality from any website
- Framework: Next.js 15 with App Router
- Language: TypeScript for type safety
- UI Library: React 18 with modern hooks
- Styling: Tailwind CSS v3 for responsive design
- Components: shadcn/ui for consistent, accessible components
- Icons: Lucide React for beautiful, consistent icons
- Themes: next-themes for dark/light mode switching
- Authentication: Firebase Auth with email/password
- Database: Firestore (NoSQL) for real-time data sync
- Storage: Firebase Storage for file uploads (future)
- Security: Firestore security rules for data protection
- State Management: Zustand for lightweight global state
- Form Handling: React Hook Form for performant forms
- Validation: Zod for runtime type checking and validation
- Notifications: Sonner for beautiful toast notifications
- Build Tool: Next.js built-in bundler with SWC
- Linting: ESLint with TypeScript rules
- Code Style: Prettier for consistent formatting
- Deployment: Optimized for Vercel deployment
- Environment: Node.js 18+ with modern JavaScript features
- Node.js 18+
- npm or yarn
- Firebase project
-
Clone the repository:
git clone <your-repo-url> cd flowstate
-
Install dependencies:
npm install
-
Set up Firebase:
- Create a new Firebase project at Firebase Console
- Enable Authentication and Firestore Database
- Copy your Firebase config
-
Set up environment variables:
cp .env.local.example .env.local
Fill in your Firebase configuration in
.env.local:NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key_here NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project_id.firebaseapp.com NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id_here NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project_id.appspot.com NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id_here NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id_here
-
Run the development server:
npm run dev
-
Open http://localhost:3000 in your browser.
-
Authentication:
- Go to Authentication > Sign-in method
- Enable Email/Password authentication
-
Firestore Database:
- Create a Firestore database in production mode
- Set up security rules (basic rules provided below)
-
Security Rules (Firestore):
rules_version = '2'; service cloud.firestore { match /databases/{database}/documents { // Users can only access their own user document match /users/{userId} { allow read, write: if request.auth != null && request.auth.uid == userId; } // Users can only access their own items match /items/{itemId} { allow read, write: if request.auth != null && request.auth.uid == resource.data.userId; allow create: if request.auth != null && request.auth.uid == request.resource.data.userId; } // Users can only access their own custom categories match /categories/{categoryId} { allow read, write: if request.auth != null && request.auth.uid == resource.data.userId; allow create: if request.auth != null && request.auth.uid == request.resource.data.userId; // Allow collection queries for authenticated users allow list: if request.auth != null; } } }
src/
├── app/ # Next.js 15 App Router
│ ├── dashboard/ # Protected dashboard pages
│ ├── items/ # Item management pages
│ │ ├── new/ # Add new item page
│ │ └── page.tsx # Items listing page
│ ├── analytics/ # Analytics dashboard
│ └── globals.css # Global styles with enhanced themes
├── components/ # Reusable components
│ ├── auth/ # Authentication components
│ ├── forms/ # Dynamic form components
│ │ └── dynamic-fields.tsx # Category-based dynamic fields
│ ├── layout/ # Layout components
│ │ ├── sidebar.tsx # Modern collapsible sidebar
│ │ └── dashboard-layout.tsx # Main layout wrapper
│ ├── skeletons/ # Loading skeleton components
│ │ ├── dashboard-skeleton.tsx
│ │ ├── items-skeleton.tsx
│ │ └── analytics-skeleton.tsx
│ └── ui/ # shadcn/ui components
│ ├── skeleton.tsx # Base skeleton component
│ └── loading-wrapper.tsx # Lazy loading wrapper
├── contexts/ # React contexts
│ └── auth-context.tsx # Authentication context
├── lib/ # Utilities and configurations
│ ├── auth.ts # Authentication functions
│ ├── firebase.ts # Firebase configuration
│ ├── items.ts # Item CRUD operations
│ └── categories.ts # Category management functions
├── store/ # Zustand stores
│ ├── auth.ts # Authentication state
│ ├── items.ts # Items state management
│ └── categories.ts # Categories and templates store
└── types/ # TypeScript type definitions
└── index.ts # Core type definitions
- Create Account: Sign up with your email and password
- Explore Dashboard: Get familiar with your progress overview
- Add Your First Item: Click "Add Item" to start tracking something
- Set Up Categories: Organize your items by media, reading, learning, etc.
- Quick Progress Updates: Update your current progress (pages read, episodes watched)
- Add New Items: Continuously add new things you want to track
- Review & Organize: Use filters and search to manage your collection
- Check Analytics: Monitor your progress patterns and completion rates
- Use Tags: Add descriptive tags to make items easier to find later
- Set Priorities: Mark important items as high priority to focus on them
- Write Reviews: Add notes and ratings to remember your thoughts
- Regular Updates: Update progress frequently to maintain momentum
- Explore Analytics: Use insights to understand your habits and improve
📚 Book Reader:
- Add book with total pages and current page
- Update progress as you read
- Add notes about favorite quotes or thoughts
- Rate and review when finished
- Use analytics to track reading habits
🎬 Movie Enthusiast:
- Add movies to your watchlist with priority levels
- Mark as "in-progress" when you start watching
- Add ratings and reviews after watching
- Use tags to organize by genre or director
- Track completion rates and favorite genres
🎓 Lifelong Learner:
- Add online courses with total lessons/hours
- Track progress through course modules
- Add notes about key learnings
- Set target completion dates
- Monitor learning velocity and topics
interface Item {
id: string;
userId: string;
title: string;
description?: string;
category: string; // Now supports custom categories
customCategory?: string;
status: 'not-started' | 'in-progress' | 'paused' | 'completed' | 'dropped';
priority: 'low' | 'medium' | 'high';
progress: {
current: number;
total?: number;
percentage: number;
timeSpent: number;
};
metadata: {
author?: string;
year?: number;
genre?: string[];
tags: string[];
rating?: number;
review?: string;
coverImage?: string;
externalId?: string;
};
customFields: Record<string, unknown>; // Dynamic fields based on category
startDate?: Timestamp;
targetDate?: Timestamp;
completionDate?: Timestamp;
createdAt: Timestamp;
updatedAt: Timestamp;
}interface Category {
id: string;
name: string;
userId?: string; // undefined for default categories
icon?: string;
color?: string;
fields: CategoryField[];
createdAt?: Date;
updatedAt?: Date;
}
interface CategoryField {
id: string;
name: string;
type: 'text' | 'number' | 'select' | 'date' | 'boolean' | 'textarea';
label: string;
placeholder?: string;
required?: boolean;
options?: string[]; // For select type
defaultValue?: string | number | boolean;
}- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Item Detail Pages - Dedicated pages for viewing and editing items
- Quick Progress Updates - One-click progress increment buttons
- Settings Page - User preferences and account management
- Cover Image Upload - Visual identification for items
- Advanced Search - Full-text search across all item fields
- Keyboard Shortcuts - Power-user navigation and actions
- Data Export/Import - JSON/CSV export and import functionality
- External Integrations - Import from Goodreads, Letterboxd, Steam, etc.
- Achievement System - Badges and milestones for motivation
- Advanced Analytics - Trends, predictions, and deeper insights
- Sharing Features - Public profiles and shareable lists
- Browser Extension - Quick add from any website
- Mobile App - React Native app for iOS and Android
- Offline Support - Full offline functionality with sync
- Collaboration - Shared lists and team tracking
- API Access - REST API for third-party integrations
- Custom Themes - User-created color schemes
- AI Recommendations - Smart suggestions based on your preferences
- Social Features - Follow friends and see their progress
- Performance Optimization - Faster loading and better caching
- Accessibility - WCAG 2.1 AA compliance
- Internationalization - Multi-language support
- Advanced Security - Two-factor authentication, audit logs
- Monitoring - Error tracking and performance monitoring
FlowState is ready for deployment to Vercel with optimized configuration.
- Connect to Vercel: Import your repository to Vercel
- Set Environment Variables: Add your Firebase configuration in Vercel dashboard
- Deploy: Vercel will automatically deploy on push to main branch
Add these to your Vercel project settings:
NEXT_PUBLIC_FIREBASE_API_KEY=your_firebase_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
# Development
npm run dev # Start development server
npm run build # Production build
npm run start # Start production server
npm run type-check # TypeScript validation
npm run lint # Code linting
npm run lint:fix # Auto-fix linting issues
# Utilities
npm run analyze # Bundle size analysis
npm run clean # Clean build artifactsIf you have any questions or need help, please open an issue on GitHub.