FocusFlow 🎯

A local-first, offline-first Kanban + Pomodoro "deep work operating system" that runs as an installable PWA—no account, no cloud, no tracking.

🌟 Overview

FocusFlow is a privacy-first productivity application that combines Kanban task management with Pomodoro time tracking to create a complete "deep work operating system." It runs entirely in your browser with full offline support, requiring no account, no cloud service, and no tracking.

What Makes FocusFlow Different?

• 🔒 Privacy First: No account required, no cloud sync, no tracking—your data stays on your device
• 📴 Offline First: Works completely offline after installation, powered by PWA technology
• ⏱️ Task × Time Coupling: Every card tracks focus sessions, making time a first-class citizen
• 💾 Portable Data: Reversible JSON export/import and readable Markdown export
• 🎨 Executable Templates: Pre-built workflows with WIP guidance and Definition of Done
• ⚡ App-Like Experience: Install as a progressive web app, launches offline, feels native

🚀 Key Features

Core Functionality

✅ Boards, Lists & Cards

• Unlimited boards with drag-and-drop organization
• Rich card details: description (markdown), due dates, priority, labels
• Multi-item checklists with progress tracking
• Activity log for every card action

✅ Integrated Pomodoro Timer

• Start/pause/resume/stop with configurable durations
• Attach timer sessions to specific cards
• Automatic session logging and statistics
• Timer state persists across refreshes
• Browser notifications on completion

✅ Global Search & Filters

• Search across titles, descriptions, labels, and checklists
• Filter by board, labels, priority, due dates
• Quick access to overdue and today's tasks

✅ Focus Dashboard

• Daily and weekly pomodoro trends
• Cards completed today/this week
• Overdue task alerts
• Activity overview

✅ Data Portability

• Export to JSON (full fidelity, reversible)
• Export to Markdown (human-readable sharing)
• Import with schema validation and migration
• Backup and restore your entire workspace

✅ Keyboard Shortcuts

• Fast card creation and navigation
• Quick search (non-conflicting with browser shortcuts)
• Timer controls
• Board switching

Templates

15+ professional templates including:

• Personal: Personal Goals, Habit Tracker, Life Planning
• Work: OKR Template, Team Goal Setting, Agile Sprint Planning
• Design: Design Project, Game Design, Web Design & Development
• Education: Teaching Planning, Academic Research
• Engineering: Engineering Project, Product Development
• Writing: Short Story Kanban, Book Outline, Content Calendar
• Marketing: Marketing Campaign, Social Media Content
• Business: Business Overview, Business Plan, Grant Tracking

Each template includes pre-configured lists, example cards, and workflow guidance.

🛠️ Technology Stack

• Framework: Next.js 15.5 (App Router)
• UI Library: React 18.3
• Language: TypeScript 5
• Styling: Tailwind CSS 3.4
• State: TanStack React Query v5
• Drag & Drop: react-dnd 16
• Database: IndexedDB (idb library)
• PWA: next-pwa (service worker, manifest)
• Icons: Lucide React
• Notifications: react-hot-toast + Browser Notifications API

📦 Installation & Setup

Prerequisites

• Node.js 18 or higher
• npm, yarn, or pnpm

Development Setup

# Clone the repository
git clone https://github.com/yourusername/focusflow.git
cd focusflow

# Install dependencies
npm install

# Run development server
npm run dev

# Open in browser
# Navigate to http://localhost:3000

Build for Production

# Create optimized production build
npm run build

# Test production build locally
npm run start

# Production build will be in .next/ directory

🌐 Deployment

Recommended: Vercel (Zero Config)

1. Push code to GitHub
2. Import project to Vercel
3. Deploy automatically
4. PWA will be available at your-domain.vercel.app

Alternative: Static Export (Netlify, GitHub Pages, etc.)

# Build static export
npm run build

# Deploy the 'out' directory to any static host

Important Deployment Settings

• Ensure service worker caching strategy is configured
• Set proper cache headers for static assets
• Enable HTTPS (required for PWA installation)
• Configure correct basePath if not deploying to root domain

🎮 Usage Guide

First Time Setup

1. Install the PWA (optional but recommended)

   • Open FocusFlow in your browser
   • Click "Install" button or use browser's install prompt
   • App will launch in standalone window

2. Choose a Template

   • Select from 15+ professional templates
   • Or create a blank board to start fresh

3. Start Your First Pomodoro

   • Open a board
   • Click on a priority card
   • Start the timer in the top-right corner

Daily Workflow

1. Review Dashboard: Check today's tasks and overdue items
2. Use Search: Find tasks with Ctrl/Cmd+K
3. Start Timer: Begin pomodoro on selected task
4. Track Progress: Move cards through lists as you complete them
5. Review Stats: Check Focus Dashboard for productivity insights

Backup & Device Migration

# Export your workspace
Dashboard → Settings → Export → Download JSON

# Import on another device/browser
New Device → Settings → Import → Upload JSON file

# Your boards, cards, labels, checklists, and pomodoro stats will be restored

Keyboard Shortcuts

Shortcut	Action
N	New card
↑/↓	Navigate cards
Enter	Open card details
/ or Ctrl+K	Global search
Space	Start/pause timer
R	Reset timer
Esc	Close modal

📂 Project Structure

focusflow/
├── public/
│   ├── manifest.json          # PWA manifest
│   ├── icons/                 # PWA icons (192x192, 512x512)
│   └── sw.js                  # Service worker
├── src/
│   ├── app/
│   │   ├── layout.tsx         # Root layout with PWA setup
│   │   ├── page.tsx           # Dashboard/home page
│   │   ├── globals.css        # Global styles
│   │   └── board/[id]/
│   │       └── page.tsx       # Board detail page
│   ├── components/
│   │   ├── KanbanBoard/       # Kanban components
│   │   │   ├── KanbanBoard.tsx
│   │   │   ├── ListComponent.tsx
│   │   │   ├── TaskComponent.tsx
│   │   │   ├── AddListForm.tsx
│   │   │   └── PomodoroTimer.tsx
│   │   ├── CardDetailModal.tsx    # Card details with checklist
│   │   ├── NewBoardModal.tsx      # Board creation
│   │   ├── Navbar.tsx             # Navigation with search
│   │   └── ...
│   ├── hooks/
│   │   └── useData.ts         # React Query hooks
│   ├── lib/
│   │   ├── db.ts              # IndexedDB operations
│   │   ├── migrations.ts      # Schema migrations
│   │   └── export.ts          # Export/import logic
│   └── types.ts               # TypeScript types
├── package.json
├── next.config.mjs            # Next.js config with PWA
├── tsconfig.json
└── tailwind.config.ts

🧪 Testing

# Run linter
npm run lint

# Type checking
npx tsc --noEmit

# Test PWA offline
# 1. npm run build && npm run start
# 2. Open DevTools → Application → Service Workers
# 3. Check "Offline" and reload

🔒 Privacy & Security

• No Telemetry: Zero tracking or analytics by default
• No Network Calls: Core features work without internet
• Local Storage: All data stays in IndexedDB on your device
• No Third-Party Scripts: No external dependencies at runtime
• Future Sync: If cloud sync is added, it will be 100% opt-in

📊 Performance

• Smooth drag/drop: Handles 500+ cards without lag
• Fast search: Results in <200ms for typical datasets
• Optimized rendering: Virtual scrolling for large lists
• Small bundle: <200KB gzipped JavaScript
• Offline launch: <1s load time after PWA install

🗺️ Roadmap

✅ Phase 1 (Current - MVP for Public Release)

• PWA installation & offline support
• Boards/Lists/Cards with rich details
• Pomodoro timer integration
• Global search & filters
• Export/Import (JSON + Markdown)
• Keyboard shortcuts
• Focus Dashboard
• IndexedDB schema versioning

🚧 Phase 2 (Growth)

• Advanced analytics (weekly review, heatmaps)
• Enhanced templates & template marketplace
• Cross-device import (QR code/file share)
• Optional BYO cloud sync (self-hosted)
• Browser extension

🔮 Phase 3 (Future)

• Team workspaces (optional collaboration)
• Shared templates & public boards
• Plugin system
• Mobile app (React Native)

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow TypeScript and ESLint conventions
4. Test offline functionality
5. Commit with clear messages
6. Open a Pull Request

Development Guidelines

• Offline First: All features must work without network
• No Required Cloud: Cloud features must be opt-in
• Privacy Preserving: No default telemetry
• Accessible: Keyboard usable, ARIA roles, focus states
• Portable: Don't break export/import compatibility

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Inspired by the need for privacy-first productivity tools
• Built with the amazing Next.js and React ecosystems
• Thanks to the open-source community

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See PRD.md for detailed specifications

---

Built with ❤️ for focused, private productivity

No account. No cloud. No tracking. Just you and your work.