zeroclock/docs/plans/2026-02-17-local-time-tracker-design.md

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