# Local Time Tracker - Design Document

**Date:** 2026-02-17
**Status:** Approved

---

## 1. Overview

A portable desktop time tracking application for freelancers and small teams. Replaces cloud-based services like Toggl Track, Harvest, and Clockify with a fully local-first solution that stores all data next to the executable.

**Target Users:** Freelancers, small teams (2-10), independent contractors
**Platform:** Windows (Tauri v2 + Vue 3)

---

## 2. Architecture

### Tech Stack
- **Framework:** Tauri v2 (Rust backend)
- **Frontend:** Vue 3 + TypeScript + Vite
- **UI Library:** shadcn-vue v2.4.3 + Tailwind CSS v4
- **State Management:** Pinia
- **Database:** SQLite (rusqlite)
- **Charts:** Chart.js
- **PDF Generation:** jsPDF
- **Icons:** Lucide Vue

### Data Storage (Portable)
All data stored in `./data/` folder next to the executable:
- `./data/timetracker.db` - SQLite database
- `./data/exports/` - CSV and PDF exports
- `./data/logs/` - Application logs
- `./data/config.json` - User preferences

**No registry, no AppData, no cloud dependencies.**

---

## 3. UI/UX Design

### Window Model
- **Main Window:** Frameless with custom title bar (1200x800 default, resizable, min 800x600)
- **Title Bar:** Integrated menu + window controls (minimize, maximize, close)
- **Timer Bar:** Always visible below title bar

### Layout Structure
```
┌─────────────────────────────────────────────────────────┐
│ [Logo] LocalTimeTracker   [File Edit View Help]  [─][□][×] │ ← Custom Title Bar
├─────────────────────────────────────────────────────────┤
│ [▶ START]  00:00:00  [Project ▼]  [Task ▼]            │ ← Timer Bar
├────────────┬────────────────────────────────────────────┤
│            │                                            │
│  Dashboard │           Main Content Area                │
│  Timer     │                                            │
│  Projects  │     - Dashboard: Overview charts           │
│  Entries   │     - Timer: Active timer view             │
│  Reports   │     - Projects: Project/client list       │
│  Invoices  │     - Entries: Time entry table           │
│  Settings  │     - Reports: Charts and summaries        │
│            │     - Invoices: Invoice builder            │
│            │     - Settings: Preferences                │
│            │                                            │
└────────────┴────────────────────────────────────────────┘
```

### Visual Design

**Color Palette (Dark Mode + Amber):**
| Role | Color | Usage |
|------|-------|-------|
| Background | `#0F0F0F` | Page background |
| Surface | `#1A1A1A` | Cards, panels |
| Surface Elevated | `#242424` | Hover states, modals |
| Border | `#2E2E2E` | Subtle separation |
| Text Primary | `#FFFFFF` (87%) | Headings, body |
| Text Secondary | `#A0A0A0` (60%) | Labels, hints |
| Accent (Amber) | `#F59E0B` | Primary actions, active states |
| Accent Hover | `#D97706` | Button hover |
| Accent Light | `#FCD34D` | Highlights |
| Success | `#22C55E` | Positive status |
| Warning | `#F59E0B` | Warnings |
| Error | `#EF4444` | Errors |

**Typography:**
- **Headings/Body:** IBM Plex Sans
- **Timer/Data:** IBM Plex Mono
- **Scale:** 1.250 (Major Third)

**Spacing:**
- Base unit: 4px
- Comfortable density (16px standard padding)

**Border Radius:** 8px (cards, buttons, inputs)

### Components

**Navigation:**
- Sidebar (220px fixed)
- Items: Dashboard, Timer, Projects, Entries, Reports, Invoices, Settings
- Active state: Amber highlight + left border accent

**Timer Bar:**
- Start/Stop button (amber when active)
- Running time display (mono font, large)
- Project selector dropdown
- Task selector dropdown

**Buttons:**
- Primary: Amber fill
- Secondary: Outlined
- Ghost: Text only

**Cards:**
- Dark surface (`#1A1A1A`)
- Subtle border (`#2E2E2E`)
- Rounded corners (8px)

**Forms:**
- Dark background
- Amber focus ring

---

## 4. Functional Requirements

### 4.1 Timer
- One-click start/stop timer
- Project and task assignment
- Optional notes/description
- Manual time entry for forgotten sessions
- Idle detection with prompt to keep/discard idle time
- Reminder notifications

### 4.2 Projects & Clients
- Create/edit/delete projects
- Group projects by client
- Set hourly rate per project
- Archive projects

### 4.3 Time Entries
- List all time entries with filtering
- Edit existing entries
- Delete entries
- Bulk actions (delete, export)

### 4.4 Reports
- Weekly/monthly summaries
- Bar charts for time distribution
- Pie charts for project breakdown
- Filter by date range, project, client
- Export to CSV

### 4.5 Invoices
- Generate from tracked time
- Customizable line items
- Client details
- Tax rates, discounts
- Payment terms
- PDF export

### 4.6 Settings
- Theme preferences (dark mode only initially)
- Default hourly rate
- Idle detection settings
- Reminder intervals
- Data export/import
- Clear all data

### 4.7 System Integration
- System tray residence
- Compact floating timer window (optional)
- Global hotkey to start/stop
- Auto-start on login (optional)
- Native notifications

---

## 5. Data Model

### Tables
- `clients` - Client information
- `projects` - Projects linked to clients
- `tasks` - Tasks within projects
- `time_entries` - Individual time entries
- `invoices` - Generated invoices
- `invoice_items` - Line items for invoices
- `settings` - User preferences

---

## 6. Motion & Interactions

**Animation Style:** Moderate/Purposeful (200-300ms transitions)

**Key Interactions:**
- Timer: Subtle amber glow when running
- Cards: Soft lift on hover
- Buttons: Scale/color change on press
- View transitions: Fade + slight slide
- Empty states: Animated illustrations

---

## 7. Acceptance Criteria

1. ✅ App launches without errors
2. ✅ Timer starts/stops and tracks time correctly
3. ✅ Projects and clients can be created/edited/deleted
4. ✅ Time entries are persisted to SQLite
5. ✅ Reports display accurate charts
6. ✅ Invoices generate valid PDFs
7. ✅ All data stored in ./data/ folder (portable)
8. ✅ Custom title bar with working window controls
9. ✅ System tray integration works
10. ✅ Dark mode with amber accent throughout