# Time Tracker

A browser-based time-tracking app: log daily work against projects, review totals in weekly and
monthly views, and track project budgets with automatic cost calculation and soft breach warnings.

**Stack:** React 19 + Vite 6 (TypeScript strict) — Spring Boot 3.4 (Java 21) — PostgreSQL 17 via
Docker Compose — Flyway for schema migrations — Tailwind CSS v4 — Biome 1.9 — Vitest.

## Features

- **Daily time entries** — date, project, duration (entered as h:mm), automatic cost from hourly rate
- **Weekly view** — navigate by ISO week; see total hours per day and a running week total
- **Monthly view** — per-project summary with time and cost progress bars; red banner when a budget is exceeded
- **Project management** — create projects with time and cost budgets; set a project-level hourly rate or fall back to the user's default
- **Multi-user** — pick any seeded user from the dropdown; cost is calculated using that user's rate when no project rate is set
- **Soft budget enforcement** — entries always save; over-budget projects are highlighted with a warning banner and colored bars

## Quick start

> **Requires a full JDK** (not just JRE) for Maven compilation. `mise install` below handles this.
> Without mise: `sudo apt install openjdk-21-jdk`.

```bash
# 1. Pin toolchain — installs Java 21 JDK, Node 22, Maven, lefthook, gitleaks
mise install

# 2. Install deps and git hooks (or run the four commands manually)
mise run setup

# 3. Start the database
docker compose up -d
```

Open two terminals:

```bash
# Backend → http://localhost:8080
mvn -f backend/pom.xml spring-boot:run

# Frontend → http://localhost:5173  (proxies /api → :8080)
cd frontend && npm run dev
```

## Verify everything

```bash
mise run check       # format-check + lint + test (both stacks)
```

Without mise:

```bash
mvn -f backend/pom.xml spotless:check -q
cd frontend && npx biome check src
mvn -f backend/pom.xml test -q
cd frontend && npx vitest run
```

## Design notes

**Money and duration** are stored as integers (cents and minutes respectively) to avoid floating-point
drift. Cost for a time entry is computed at read time: `duration_minutes × effective_rate_cents / 60`,
where the effective rate is the project's `hourly_rate_cents` if set, otherwise the user's
`default_hourly_rate_cents`. This means changing a rate retroactively updates all historical cost
totals — a deliberate trade-off for simplicity (see `NEXT_STEPS.md` for a snapshot-based alternative).

**Budget warnings** are soft: any entry saves regardless of budget status. Breach is detected in the
reporting layer by comparing aggregated totals to the project's `time_budget_minutes` and
`cost_budget_cents`. The monthly view renders a red warning banner and saturated progress bars for
any over-budget project.

**Schema migrations** are managed exclusively by Flyway (`V1__init.sql` for schema, `V2__seed_demo_data.sql`
for demo users and projects). Hibernate is set to `validate` — it never modifies the schema.

**API shape** — aggregation is done server-side via two dedicated endpoints:
`GET /api/reports/weekly?userId=&week=YYYY-Www` and `GET /api/reports/monthly?userId=&month=YYYY-MM`.
All other CRUD endpoints follow standard REST conventions under `/api/`.

## Environment

`.env.example` documents all env vars. `mise run setup` copies it to `.env` automatically on first run.