218 lines
6.6 KiB
Markdown
218 lines
6.6 KiB
Markdown
# 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
|