# Car Control Project

A car control & service tracking system. Built incrementally — starting with a
**car maintenance tracker** (modeled on `Car Service.xlsx`) and growing toward
live integration with the car via an ESP32 device.

## Architecture

All clients communicate with the database **only through the API Server** —
nothing talks to PocketBase directly.

```
                       ┌──────────────────┐
   Web App (Vue) ─────▶│                  │
   Phone App (Flutter)▶│   API Server     │────▶  PocketBase
   Home Assistant ────▶│   (Go, stdlib)   │       (10.2.1.10:8027)
   ESP32 device ──────▶│                  │
                       └──────────────────┘
```

| Component | Stack | Status | Docs |
|---|---|---|---|
| **API Server** | Go (stdlib) | ✅ built, running, verified | [API Server/README.md](API%20Server/README.md) |
| **Database** | PocketBase | ✅ running, schema + seed done | — |
| **Web App** | Vue 3 + Vite + Tailwind v4 | ✅ full feature set (below) | [Web App/README.md](Web%20App/README.md) |
| **Phone App** | Flutter (Android) | ✅ web parity + biometric login | [Phone App/README.md](Phone%20App/README.md) |
| **Home Assistant Plugin** | — | ⬜ later | — |
| **Car Agent Device** | ESP32 | ⬜ later | — |

The Web and Phone apps are at feature parity (the phone omits only data
export/import).

## Features

- **Maintenance tracking** — cars, service history (date/odometer + which parts
  were changed), and a per-car parts catalog, with next-due date/km status.
- **Accounts & sessions** — JWT login, per-device active sessions with remote
  logout, profile + appearance preferences (theme/locale/date/font), email
  verification, and account deletion.
- **Per-user ownership & sharing** — each car has an owner and can be shared with
  other users as read or write; the UI mirrors the server's access checks.
- **Admin** — role-gated user management (create / role / reset password / delete).
- **Phone biometric login & app lock** — fingerprint / face sign-in with an
  app-lock that requires an unlock on relaunch (with a short grace period for
  quick app-switches). See the Phone App README.

## Auth model

All three apps share one auth model: login via `POST /api/auth/login` returns a
JWT issued by the API Server (after verifying against PocketBase `users`), and
every other endpoint requires `Authorization: Bearer <token>`. Each login also
creates a server-side session whose id is embedded in the token, so sessions can
be listed and revoked. Access to cars/records/parts is gated by per-user
ownership and shares; admin endpoints require the admin role.

## Domain (from `Car Service.xlsx`)

- **Cars** — one per vehicle (was: one spreadsheet sheet), with spec fields
  (engine / transmission / differential oil, brake fluid, coolant, VIN, …) and
  configurable service intervals.
- **Service records** — date + odometer per service, plus which parts were
  changed (oil & oil filter, engine air filter, cabin air filter).
- **Parts** — per-car catalog of part numbers.

Key spreadsheet formulas, reproduced by the API Server on read:

```
Next Service Date = service date + serviceIntervalDays   (default 365; Excel: =A+365)
Next Service Km   = service km   + serviceIntervalKm      (default 15 000; Excel: =B+15000)
```

Intervals are configurable per car.

## Getting started

Bring up the stack in this order — each app's README has the details:

1. **[API Server](API%20Server/README.md)** — configure `.env`, run
   `setup-pocketbase.mjs`, start the server. This must be running for either app.
2. **[Web App](Web%20App/README.md)** — `npm install && npm run dev`
   (proxies `/api` to the server).
3. **[Phone App](Phone%20App/README.md)** — `flutter build apk` /
   `flutter run` with `--dart-define=API_BASE=http://<server-ip>:8080/api`.

## Layout

```
Car Control Project/
├── API Server/            # Go gateway to PocketBase (the only DB client)
├── Web App/               # Vue 3 + Vite + Tailwind v4
├── Phone App/             # Flutter (Android)
├── Home Assistant Plugin/ # later phase
└── Car Agent Device/      # ESP32, later phase
```