Initial commit
This commit is contained in:
Your Name
217
docs/plans/2026-02-17-local-time-tracker-design.md
Normal file
217
docs/plans/2026-02-17-local-time-tracker-design.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user