Personal KPI Tracker

A modern, feature-rich personal KPI (Key Performance Indicator) tracking application for managing habits, goals, and tasks. Built with React, TypeScript, and a beautiful mobile-first UI.

✨ Features

📊 KPI Management

Multiple Metric Types: Checkbox, Counter, Timer, Number, Percentage, Currency, and Rating
Flexible Recurrence: Daily, Weekly, Monthly, Custom intervals, or One-time tasks
Categories: Organize as Habits, Goals, or Tasks
Priority Levels: Low, Medium, High, Urgent
Tags & Colors: Customize with icons, colors, and tags
Notes per Entry: Document thoughts and progress for each day

📅 Calendar View

Weekly Overview: See your KPIs organized by day
Heatmap Visualization: Track activity patterns over time
Quick Navigation: Jump to any date easily

🔥 Streaks & Motivation

Streak Tracking: Monitor consecutive completion days
Visual Streak Display: Fire icons and progress indicators
Daily Motivational Quotes: Inspiration to keep you going

⏱️ Focus Timer (Pomodoro)

Customizable Sessions: Work, short break, and long break durations
Session Tracking: Count completed focus sessions
Visual Progress: Circular timer with progress ring
Auto-break System: Automatic transitions between sessions

📈 Statistics & Analytics

Completion Rates: Daily, weekly, and monthly statistics
Performance Charts: Visual progress over time with Recharts
Category Breakdown: See performance by habit/goal/task
Historical Data: Track your journey over any time period

🏆 Achievements & Gamification

XP System: Earn experience points for completions
Levels: Progress through levels as you achieve more
Achievement Badges: Unlock achievements for milestones

🎨 Customization

Dark/Light Mode: System-aware theme switching
Week Start Day: Choose Sunday or Monday
Multi-language: English 🇬🇧, German 🇩🇪, Italian 🇮🇹

Share Progress: Generate beautiful shareable images
Daily/Weekly Summaries: Visual cards of your achievements

📱 Progressive Web App (PWA)

Install on Device: Works like a native app
Offline Support: Full functionality without internet
Local Storage: All data stored securely on your device

🛠️ Tech Stack

Technology	Purpose
React 18	UI Framework
TypeScript	Type Safety
Vite 7	Build Tool
Tailwind CSS 4	Styling
Shadcn/UI	UI Components
Zustand	State Management
Dexie (IndexedDB)	Local Database
Recharts	Charts & Visualizations
date-fns	Date Utilities
Lucide React	Icons

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Production Build

# Build and run with Docker Compose
docker compose up -d

# Or build manually
docker build -t app-docs .
docker run -d -p 8080:80 --name app-docs app-docs

The app will be available at http://localhost:8080

Development with Docker

For development with hot reload, you can mount the source code:

docker run -d -p 4321:4321 -v $(pwd):/app --name app-docs-dev node:18-alpine sh -c "cd /app && npm install && npm run dev -- --host 0.0.0.0"

Useful Docker Commands

# Stop the container
docker compose down

# Rebuild after changes
docker compose up -d --build

# View logs
docker compose logs -f app-docs

# Check container health
docker inspect --format='{{.State.Health.Status}}' app-docs

📁 Project Structure

src/
├── components/     # Reusable UI components
│   └── ui/        # Shadcn UI components
├── lib/           # Utilities, i18n, database
├── pages/         # Main view components
├── store/         # Zustand state management
└── types/         # TypeScript type definitions

🏗️ Architecture

Overview

flowchart TD
    A[Dashboard] --> B[Zustand Store]
    C[Calendar] --> B
    D[Streaks] --> B
    E[Focus] --> B
    B --> F[Dexie IndexedDB]
    
    subgraph "UI Layer"
        A
        C
        D
        E
    end
    
    subgraph "State Layer"
        B
    end
    
    subgraph "Data Layer"
        F
    end

Data Flow

flowchart LR
    A[User Action] --> B[Component]
    B --> C[Zustand Action]
    C --> D[Dexie DB]
    D --> E[State Update]
    E --> F[Re-render]

Core Components

Component	Responsibility
`useAppStore`	Central state management with Zustand. Handles all CRUD operations and syncs with IndexedDB
`db.ts`	Dexie database configuration with tables for KPIs, Entries, and Settings
`Layout.tsx`	Main app shell with navigation and theme provider
`KPICard.tsx`	Reusable card component for displaying and interacting with KPIs

Data Models

KPI
├── id: string
├── name: string
├── category: 'habit' | 'goal' | 'task'
├── metric: MetricConfig (type, target, unit)
├── recurrence: RecurrenceConfig (pattern, days)
├── priority: 'low' | 'medium' | 'high' | 'urgent'
└── startDate, tags, icon, color, archived

KPIEntry
├── id: string
├── kpiId: string (→ KPI)
├── date: string (YYYY-MM-DD)
├── value: number | boolean | string
├── notes?: string
└── timerSessions?: TimerSession[]

AppSettings
├── theme: 'light' | 'dark' | 'system'
├── language: 'en' | 'de' | 'it'
├── startOfWeek: 0-6 (day of week)
└── notifications, focusTimer config

Key Design Decisions

Offline-First: All data stored locally in IndexedDB via Dexie for instant access and offline capability
Single Store Pattern: One Zustand store manages all application state, simplifying data flow and debugging
Component Composition: Small, focused components composed together (e.g., MetricInput renders different inputs based on metric type)
Hook-Based i18n: Custom useTranslation hook reads from centralized translations object, no external i18n library needed
PWA Architecture: Service worker pre-caches assets for offline use, manifest enables “Add to Home Screen”