233 lines
10 KiB
Markdown
233 lines
10 KiB
Markdown
# Wotra — Working Time Tracker: Implementation Plan
|
|
|
|
## 1. High-Level Architecture
|
|
|
|
```
|
|
┌─────────────────────────┐ ┌──────────────────────────┐
|
|
│ Svelte PWA (client) │ ◄─────► │ Go service (API) │
|
|
│ - IndexedDB cache │ HTTPS │ - REST/JSON endpoints │
|
|
│ - Service Worker │ JSON │ - Business logic │
|
|
│ - Sync queue │ │ - SQLite (modernc) │
|
|
└─────────────────────────┘ └──────────────────────────┘
|
|
```
|
|
|
|
Single-user, self-hosted. One Go binary serves the Svelte SPA and the API.
|
|
|
|
## 2. Backend (Go)
|
|
|
|
### Stack
|
|
|
|
- `net/http` + `chi` for routing
|
|
- `modernc.org/sqlite` (pure Go, no CGO) with `database/sql`
|
|
- SQLite WAL mode, foreign keys on, busy timeout 5s
|
|
- `golang-migrate` or hand-rolled migrations
|
|
- Structured logging via `slog`
|
|
|
|
### Project Layout
|
|
|
|
```
|
|
cmd/wotra/main.go
|
|
internal/
|
|
config/ # timezone, token, port
|
|
domain/ # Entry, ClosedDay, ClosedWeek, Settings types
|
|
store/ # sqlite repos + migrations
|
|
handler/ # HTTP handlers, middleware
|
|
service/ # business rules (close day/week, merge, overtime)
|
|
migrations/ # SQL migration files
|
|
web/ # SvelteKit app (embedded in binary at build time)
|
|
Makefile
|
|
PLAN.md
|
|
```
|
|
|
|
### Database Schema
|
|
|
|
```sql
|
|
-- Raw tracking events (source of truth for open days)
|
|
CREATE TABLE entries (
|
|
id TEXT PRIMARY KEY, -- UUIDv7 (client-generated, sync-friendly)
|
|
start_time INTEGER NOT NULL, -- unix epoch ms, UTC
|
|
end_time INTEGER, -- NULL while running
|
|
auto_stopped INTEGER NOT NULL DEFAULT 0, -- 1 = stopped at midnight automatically
|
|
note TEXT,
|
|
day_key TEXT NOT NULL, -- 'YYYY-MM-DD' in configured local tz
|
|
updated_at INTEGER NOT NULL,
|
|
deleted_at INTEGER -- soft delete for sync
|
|
);
|
|
CREATE INDEX idx_entries_day ON entries(day_key);
|
|
|
|
-- Closed days: merged result, effectively immutable
|
|
CREATE TABLE closed_days (
|
|
day_key TEXT PRIMARY KEY, -- 'YYYY-MM-DD'
|
|
start_time INTEGER, -- min(entries.start_time), NULL for non-work kinds
|
|
end_time INTEGER, -- max(entries.end_time), NULL for non-work kinds
|
|
worked_ms INTEGER NOT NULL, -- sum of entry durations (breaks excluded)
|
|
kind TEXT NOT NULL, -- 'work' | 'holiday' | 'vacation' | 'sick'
|
|
closed_at INTEGER NOT NULL,
|
|
updated_at INTEGER NOT NULL
|
|
);
|
|
|
|
-- Closed weeks: snapshot of expectations at close time
|
|
CREATE TABLE closed_weeks (
|
|
week_key TEXT PRIMARY KEY, -- 'YYYY-Www' ISO week
|
|
expected_ms INTEGER NOT NULL, -- frozen at close
|
|
worked_ms INTEGER NOT NULL, -- sum of closed_days.worked_ms for the week
|
|
delta_ms INTEGER NOT NULL, -- worked_ms - expected_ms (signed)
|
|
closed_at INTEGER NOT NULL,
|
|
updated_at INTEGER NOT NULL
|
|
);
|
|
|
|
-- Settings with effective-from semantics so past weeks aren't retroactively changed
|
|
CREATE TABLE settings_history (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
effective_from TEXT NOT NULL, -- 'YYYY-MM-DD'
|
|
hours_per_week REAL NOT NULL,
|
|
workdays_mask INTEGER NOT NULL DEFAULT 31, -- bits Mon=1..Sun=64; Mon-Fri = 31
|
|
timezone TEXT NOT NULL DEFAULT 'UTC',
|
|
created_at INTEGER NOT NULL
|
|
);
|
|
|
|
-- Sync event log (last-write-wins per entity row)
|
|
CREATE TABLE sync_log (
|
|
entity TEXT NOT NULL, -- 'entries' | 'closed_days' | 'closed_weeks'
|
|
entity_id TEXT NOT NULL,
|
|
op TEXT NOT NULL, -- 'upsert' | 'delete'
|
|
version INTEGER NOT NULL, -- monotonic server-assigned
|
|
payload TEXT NOT NULL, -- JSON snapshot
|
|
PRIMARY KEY (entity, entity_id, version)
|
|
);
|
|
```
|
|
|
|
### API Surface (REST/JSON)
|
|
|
|
```
|
|
# Entries
|
|
POST /api/entries/start { note? } -> Entry
|
|
POST /api/entries/{id}/stop -> Entry
|
|
GET /api/entries?from=YYYY-MM-DD&to=YYYY-MM-DD
|
|
PUT /api/entries/{id} { start_time?, end_time?, note? }
|
|
DELETE /api/entries/{id} (soft delete)
|
|
|
|
# Days
|
|
GET /api/days?from=YYYY-MM-DD&to=YYYY-MM-DD
|
|
POST /api/days/{day_key}/close -> ClosedDay
|
|
POST /api/days/{day_key}/mark { kind } # holiday|vacation|sick
|
|
DELETE /api/days/{day_key}/close (reopen day)
|
|
|
|
# Weeks
|
|
GET /api/weeks?from=YYYY-Www&to=YYYY-Www
|
|
POST /api/weeks/{week_key}/close -> ClosedWeek
|
|
DELETE /api/weeks/{week_key}/close (reopen week)
|
|
|
|
# Settings
|
|
GET /api/settings # current effective settings
|
|
PUT /api/settings { effective_from, hours_per_week, workdays_mask, timezone }
|
|
GET /api/settings/history
|
|
|
|
# Sync
|
|
POST /api/sync/pull { since_version } -> { changes[], server_version }
|
|
POST /api/sync/push { changes[] } -> { applied[], conflicts[] }
|
|
|
|
# Health
|
|
GET /healthz (unauthenticated)
|
|
```
|
|
|
|
### Key Business Rules
|
|
|
|
- **day_key assignment**: based on `start_time` in the configured timezone.
|
|
- **Midnight enforcement**: `end_time` must be on the same calendar day as `start_time`. Server auto-stops any running entry at 23:59:59 local time via a background goroutine. Client warns the user.
|
|
- **Close day**: requires all entries for that day to have `end_time != NULL` (409 otherwise). Computes `worked_ms = sum(end_time - start_time)` across non-deleted entries. Entries are preserved but the day is now locked.
|
|
- **Mark day**: writes a `closed_days` row with `kind != 'work'`; `worked_ms` = expected daily ms (hours_per_week * 3600000 / popcount(workdays_mask)) for workdays, 0 for non-workdays.
|
|
- **Close week**: all workdays in the week must have a `closed_days` row. Sums `worked_ms`, snapshots `expected_ms` from settings effective at the week start, stores signed `delta_ms`.
|
|
- **Settings change**: new row in `settings_history` with `effective_from`. Past closed weeks are unaffected because they store a frozen snapshot.
|
|
|
|
### Auth
|
|
|
|
- `AUTH_TOKEN` environment variable on the server.
|
|
- All `/api/*` routes require `Authorization: Bearer <token>`.
|
|
- Client stores token in `localStorage` after a one-time setup screen.
|
|
- `/healthz` is unauthenticated.
|
|
|
|
## 3. Frontend (Svelte PWA)
|
|
|
|
### Stack
|
|
|
|
- SvelteKit (static adapter for embedding in Go binary)
|
|
- TypeScript
|
|
- `vite-plugin-pwa` + Workbox for service worker and manifest
|
|
- `dexie` for typed IndexedDB access
|
|
|
|
### Screens
|
|
|
|
| Screen | Purpose |
|
|
|--------|---------|
|
|
| **Today** | Start/Stop button with live timer, list of today's entries, quick-mark actions |
|
|
| **Week** | 7-day grid: worked vs expected per day, running totals, "Close week" CTA |
|
|
| **History** | Month/week list of closed days and weeks with overtime indicators |
|
|
| **Settings** | hours/week, workdays mask, timezone, effective-from, token setup |
|
|
|
|
### Offline Strategy
|
|
|
|
1. App shell precached by Workbox.
|
|
2. All reads come from Dexie (IndexedDB); a sync worker reconciles with the server in the background.
|
|
3. All mutations create a local Dexie record with a client-generated UUIDv7 and an entry in a local `outbox` table.
|
|
4. When online, the outbox is flushed via `/api/sync/push`; responses update the local cache.
|
|
5. `/api/sync/pull` fetches any server-side changes since `last_pulled_version`.
|
|
|
|
## 4. Sync Protocol
|
|
|
|
- Every mutable row carries `updated_at` (ms) on the client and `version` (server monotonic int) once accepted.
|
|
- **Pull**: `POST /api/sync/pull { since_version: N }` → rows with `version > N` + `server_version`.
|
|
- **Push**: client sends batched upsert/delete events with `updated_at`. Server applies last-write-wins per row. Conflicts returned to client, which re-pulls those rows.
|
|
|
|
## 5. Build & Deployment
|
|
|
|
```makefile
|
|
# Single-binary production build
|
|
make build
|
|
# 1. pnpm build (inside web/)
|
|
# 2. go build -tags production ./cmd/wotra
|
|
# -> embeds web/build via go:embed
|
|
```
|
|
|
|
Dev mode: Go on `:8080`, Vite dev server on `:5173` with `/api` proxied to Go.
|
|
|
|
Environment variables:
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `AUTH_TOKEN` | required | Bearer token for API access |
|
|
| `PORT` | `8080` | Server port |
|
|
| `DB_PATH` | `wotra.db` | SQLite file path |
|
|
| `TZ` | `UTC` | Server timezone for day-key calculation |
|
|
|
|
## 6. Milestones
|
|
|
|
### M1 — Backend MVP
|
|
Repo scaffold, Go module, SQLite with migrations, entries CRUD, start/stop with same-day validation (midnight guard), auth middleware, service-layer tests.
|
|
|
|
### M2 — Day Management
|
|
Settings with effective-from history, close day (running-entry guard, entry merging), holiday/vacation/sick marking.
|
|
|
|
### M3 — Week Close & Overtime
|
|
Close week, expected/worked/delta computation with frozen settings snapshot, reopen day/week.
|
|
|
|
### M4 — Svelte UI (online-only)
|
|
Today view, Week view, History view, Settings screen, all consuming the API directly.
|
|
|
|
### M5 — PWA + Offline
|
|
Service worker, manifest, Dexie store, outbox pattern, `/api/sync/pull` and `/api/sync/push` endpoints, last-write-wins reconciliation.
|
|
|
|
### M6 — Polish
|
|
CSV/JSON export, monthly summary view, single-binary build with embedded assets, Makefile, README.
|
|
|
|
## 7. Decisions & Rationale
|
|
|
|
| Decision | Choice | Reason |
|
|
|----------|--------|--------|
|
|
| Midnight crossing | Disallow; auto-stop at 23:59:59 | Keeps day-boundary logic simple and lossless |
|
|
| Running entry at close | Refuse with 409 | Explicit is better than implicit |
|
|
| Expected hours split | Even across workdays | Simplest correct model; per-day config out of scope |
|
|
| Auth v1 | Single shared bearer token | Single-user self-hosted; minimal friction |
|
|
| Deployment | Single Go binary embeds SPA | Simplest self-hosting story |
|
|
| SQLite driver | modernc.org/sqlite (pure Go) | No CGO; easy cross-compilation |
|
|
| Breaks in closed day | Not included in worked_ms | Sum of entry durations only; gaps between entries are breaks |
|