TimeTracker Pro

A Progressive Web App (PWA) for time tracking built with React, TypeScript, and Tailwind CSS. Installable on desktop and mobile with full offline support. Built for freelancers, consultants, and professionals who need to track time, manage projects, and generate invoices.

---

Features

• Daily Time Tracking — start/stop your workday with clear daily boundaries
• Task Management — create, edit, and delete tasks with real-time duration tracking
• Projects & Clients — organize work by project with per-project hourly rates
• Revenue Tracking — automatic earnings calculation based on hourly rates
• Custom Categories — color-coded, billable/non-billable categorization
• Rich Text Notes — GitHub Flavored Markdown in task descriptions
• Archive & Export — permanent record with CSV, JSON, and invoice export formats
• CSV Import — bring in existing time data from other tools
• Weekly Report — AI-generated work summaries (standup, client, or retrospective tone)
• No Account Required — full functionality with local storage; optional cloud sync via Supabase
• PWA + Native iOS — installable on desktop/mobile; distributed as a native iOS app via Capacitor 8

---

Quick Start

git clone https://github.com/AdamJ/TimeTrackerPro.git
cd TimeTrackerPro
npm install
npm run dev

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

First run: click "Start Day" to begin tracking. No configuration required.

Optional — cloud sync: copy .env.example to .env and add your Supabase credentials (see Authentication & Storage).

---

Available Commands

# Development
npm run dev              # Start dev server (localhost:8080)
npm run build            # Production build
npm run preview          # Preview production build

# Code Quality
npm run lint             # ESLint
npm run test             # Vitest unit tests

# iOS / Capacitor
npm run build:ios        # Vite build for iOS (no PWA/auth UI)
npm run sync:ios         # build:ios + cap sync ios

# PWA Screenshots
npm run screenshots:install   # Install Playwright (first time)
npm run screenshots           # Capture screenshots (headless)

# CSV Import Testing
npm run test-csv-import
npm run test-full-import
npm run test-error-handling

---

Development Setup

Prerequisites: Node.js 18+ and npm. Supabase account is optional (guest mode works without it).

npm install
npm run dev

Before committing:

npm run lint && npm run build

See CLAUDE.md for code style requirements (tabs, double quotes, @/ imports). See README-EXT.md for full developer documentation.

---

For Developers

Detailed documentation lives in README-EXT.md:

• How to Use — daily workflow, project/category management, export/import, markdown
• Progressive Web App — install instructions and PWA feature details
• Authentication & Storage — storage modes, cloud sync setup, auth flow, security
• Technical Architecture — stack, patterns, data flow, project structure, conventions
• Development Workflow — git workflow, testing, adding features
• Documentation Index — links to all docs
• iOS Screenshots

---

Changelog

See CHANGELOG.md for the full history of changes.

Recent highlights:

• Native iOS app via Capacitor 8 with iOS-specific build mode (build:ios / sync:ios)
• PageLayout shared component standardizes page chrome across all pages
• Incomplete checklist items carry over as todo tasks when archiving a day
• Weekly Report distinguishes Gemini API failure modes (rate limit, quota, overload, key issues)
• Fixed Weekly Report for authenticated users (data sourced from Supabase)

---

License

MIT License — open source and free to use.

---

Credits

• Originally started with Lovable — learn more
• Badges from markdown-badges
• UI components from shadcn/ui on Radix UI
• Icons from Radix Icons and Lucide
• Built with React, Vite, and Supabase