# DriverVault — Web App

Maintenance tracker for your cars: a **Vue 3 + Vite + Tailwind CSS v4** SPA served
by a small **Go backend-for-frontend (BFF)**. The BFF serves the built SPA and
reverse-proxies `/api/*` to the API Server, so the browser is always same-origin
and all data access still flows through the API Server (never PocketBase directly).

```
Browser ─► Web App BFF (:8090) ──/api/*──► API Server (:8080) ─► PocketBase
   │              └── serves embedded Vue SPA
   └──────────────────────────────────────► API Server at another site ─► its PocketBase
                              (added in the app, called straight from the browser)
```

## Layout

```
server/           Go BFF: embeds web/dist, proxies /api -> API_BASE
  main.go
  Run-WebApp.ps1  build frontend, then serve
  .env.example
  dist/           built SPA (generated; embedded at compile time)
web/              Vue 3 + Vite + Tailwind v4 source
  src/
    main.js         app bootstrap
    router.js       /login, / (dashboard), /charging, /cars/:id, /settings
    api.js          the only place that calls the API Server (base URL resolution)
    servers.js      the server list + a session per server; which one is active
    auth.js         token/profile state for the active server, isAdmin
    prefs.js        theme/locale/date/font preferences -> <html>
    i18n/           en / pl / da translation files + loader
    lib/format.js   date/km formatting + next-service status badges
    lib/attachment.js  upload / fetch / open a record's attached file
    style.css       Tailwind v4 entry (+ dark custom-variant)
    App.vue         layout shell + nav (Garage, Charging, Settings)
    components/     Modal, AttachmentField, CarFormModal, ServiceFormModal,
                    TechnicalCheckFormModal, MaintenanceFormModal, FuelFormModal,
                    ChargingFormModal,
                    DocumentFormModal, ReminderFormModal, PartFormModal, ShareModal,
                    OrgManager, AdminUsers, Logo, ServerSwitcher,
                    ServerConnectModal
    views/          Login, Dashboard, CarDetail, Charging, Settings
```

## Requirements

- **Node 20.19+ or 22.12+** (Vite 8's floor — Node 18 is end-of-life and will not
  build) and **Go 1.26+** (the `go.mod` directive). The Docker image builds on
  `node:22-alpine`.
- A running **API Server** (see `../API Server`)

## Develop

Two terminals:

```powershell
# terminal 1 — API Server (see ../API Server/README.md)
cd "../API Server"; .\bin\api-server.exe

# terminal 2 — Vite dev server with hot reload (proxies /api -> :8080)
cd web; npm install; npm run dev      # http://localhost:5173
```

The dev server proxies `/api/*` to the API Server (default `http://localhost:8080`,
override with `VITE_API_TARGET`), so the client uses same-origin relative URLs and
avoids CORS. It also listens on all interfaces (`host: true`) so it's reachable on
the LAN (e.g. `http://10.2.1.101:5173`).

The base URL each call goes to comes from the active server (see **More than one
server** below); with only the built-in one, that resolves to `VITE_API_BASE` →
`/api`.

## Build & run (production-style)

```powershell
./server/Run-WebApp.ps1               # builds frontend, then serves on :8090
# or manually:
cd web; npm run build                 # outputs to ../server/dist
cd ../server; go run .                # http://localhost:8090
```

Config (`server/.env`, copy from `.env.example`):

| Variable | Purpose | Default |
|---|---|---|
| `WEB_ADDR` | Listen address | `:8090` |
| `API_BASE` | API Server base URL | `http://localhost:8080` |

## Features

- **Dashboard** — one card per car: last service, odometer, next-due date/km, and
  a status badge (OK / due soon ≤30d / overdue) from the Excel formulas. Add a
  car by hand, or **import from service** — pick a vehicle off a connected
  manufacturer account and have its details filled in (the button appears only
  once an account is connected). Shared cars are labelled and gated by your access
  level. **Drag a card** to rearrange the garage: the order is saved per user (so
  it covers shared cars and never reorders anybody else's garage) and applied by
  the API on every list. Pointer-only — the native drag events it uses don't fire
  on touch.
- **What a car shows** — the gear button in a car's header picks both the
  sections that car's page shows (connected service, service history, technical
  checks, maintenance, fuel cost, charging cost, documents, parts, reminders —
  Fuel cost off on an EV and Charging cost off on a petrol car) and which of the
  14 Information rows it lists (no Differential oil on a car without one) and
  which columns the Service history table shows (no File column for somebody who
  keeps no receipts). It belongs to the car, so everyone it is shared with sees
  the same page; setting it needs write access. Stored as the *hidden* sets, so
  anything added in a later release is on by default. Two things can't be
  switched off: the Information tab, and the service Date — a history with the
  day taken out stops being one.
- **Locking the layout** — the padlock in the sidebar, above the theme toggle,
  holds every arrangement still at once: the garage, a car's tabs, its
  Information rows, the provider's readings. It is a guard against nudging a
  layout while reading it, not a permission — it is the user's own setting
  (`dragLocked` on the profile, so it follows them to the next device) and says
  nothing about what they may edit. Unlocked by default; while locked the drag
  cursor and the hints go too.
- **Arranging the tabs** — the tabs themselves drag into any order, saved on
  drop. A property of the car like the choice of which tabs show, so everyone it
  is shared with sees the same bar, and it needs write access. It covers the
  hidden tabs too, so switching one back on returns it to where it was, and
  Information is arrangeable even though it can't be switched off. The page then
  opens on whichever tab now leads the bar — see below.
- **Which tab a page opens on** — a bar the user dragged says what they want to
  see first, so every tabbed page (Charging, a car, Settings) opens on the tab
  that now leads it rather than on a fixed one. Settings › Appearance overrides
  that per page for the case where the reading order and the landing tab are two
  different wishes; "First in the bar" is the default and means no override.
  Stored as `defaultTabs` on the profile ({"charging": "home", …}), so it
  follows the user to the next device, and a saved tab that no longer has a
  button — one switched off for that car, a Users tab on a non-admin — falls
  back to the front of the bar. `/settings?tab=` still wins over both.
- **Arranging the Information rows** — the rows on a car's Information tab drag
  into any order, saved on drop. Also a property of the car, and it covers the
  hidden rows too, so switching one back on returns it to where it was. Same
  native drag events as the garage, so also pointer-only.
- **A build date nobody fully knows** — the Build date field picks its own
  precision: a full date, a month and year, or a year on its own. A car's build
  date is often only half known — the VIN plate carries a month, the papers a
  day, a grey import neither — and it is stored as the ISO prefix ("2015",
  "2015-03") and printed back at exactly that precision rather than padded out
  to a day nobody supplied. Narrowing the precision keeps what is still true;
  widening clears the field, since there is nothing to widen it with. First
  registration still asks for a full date.
- **Changed parts** — every part a service can record sits in one column, not one
  column each: they are a growing list and a column apiece would widen the table
  without end. The cell names what was changed (past two, the first and a tally)
  and opens a panel listing every part with a yes or a no — a dropdown rather
  than a dialog, so the rows you are comparing it against stay on screen. Both
  the column and the form's Changed parts section are driven by one list in
  `lib/serviceParts.js`, so adding a part is one entry there plus its boolean on
  the API's `service_records` collection.

  **Which parts a car records is the car's** too, under the same picker. An EV
  changes no oil, and a checkbox nobody will ever tick is one more thing to read
  past on every service. A part switched off leaves the form, the column's
  summary and the panel together — "I don't record this" means it stops taking
  up room, not that it takes up room saying nothing. Nothing is written to the
  records: an edit sends a hidden part's stored boolean straight back, because
  the API rewrites all of them from the body, so switching the part on again
  brings the old services' chips back with it.
- **Arranging the Service history columns** — the column headings on that tab
  drag into any order, saved on drop, and it covers the hidden columns too. Date
  is arrangeable although it can't be switched off, the same rule Information
  follows in the tab bar.
- **Arranging the connected service's readings** — the headline readings on that
  tab drag the same way. Only what the provider reported can be arranged, so a
  reading that turns up later (an EV range on a car that was parked unplugged)
  joins the end rather than displacing the arrangement.
- **Car detail** — all car spec fields (engine / transmission / differential oil,
  brake fluid, coolant, VIN, fuel type, …) plus tabbed histories, each with an
  optional file attachment and add/edit/delete gated by your access level:
  - **The connected service** (e.g. **MyToyota**) — the first tab, present for a
    car linked to a manufacturer account: live readings (odometer, fuel, battery,
    range, position), the vehicle record, and every section the plugin can fetch
    with its raw response. Offers the provider's odometer when it is ahead of the
    stored one. Every card below the live readings — the vehicle record and each
    provider section — folds away, and which ones you folded is remembered per
    device in localStorage. On an unlinked car the tab instead offers to connect
    it to a vehicle on your account. Read under *your* account, so a car shared
    from someone else shows data only if that vehicle is on your account too.
  - **Service history** — date, km, computed next date/km, and changed-parts flags.
  - **Technical checks** — roadworthiness inspections; result, cost, station and
    the certificate's valid-until, which drives the next-due date.
  - **Maintenance** — workshop visits and repairs (type/status, workshop, parts,
    labour + parts cost, invoice, warranty-until).
  - **Fuel cost** — refills with a summary panel (average / best / worst
    consumption, cost per km, price per litre), measured between full tanks.
  - **Charging cost** — the same log for an electric car: charges in kWh with
    consumption in kWh/100km, km per kWh, cost per km and price per kWh,
    measured between charges to the car's usual full point. Partial charges
    still count towards the cost and roll into the next full one, and a charge
    taken without logging it (flagged on the next session) leaves that window
    uncomputed rather than reporting an implausible figure.
  - **Documents** — insurance, registration, road tax, … with a renewal badge.
  - **Parts** — the per-car parts catalog.
  - **Reminders** — date/odometer, one-off or recurring; server-derived ones are
    read-only.

  Also **share** the car with other users (read/write, owner only); edit/delete
  controls are hidden for read-only shares.
- **Charging** — the EV charging screen for connected Anker Solix chargers:
  live status and, in own/proxy control mode, start/stop and charge-limit
  controls driven by the API Server's OCPP Central System.
- **Settings** — split into tabs: *Personal settings* — account (name / email
  verification / password), appearance (theme light/dark/system, locale, date
  format, currency, font size), profile (avatar, bio), data **export/import**,
  and the account-deletion state machine; *Integrations* (Toyota, Anker Solix);
  *Users* for admins; and *Organization* (create your own — which makes you its
  admin — or rename/delete the one you administer).
- **Users** — user management (list / create / role / reset password / delete)
  as the admin-only Settings tab; `/admin` redirects there for old links.
- **Theming** — light/dark/system app-wide (Tailwind v4 class strategy); `prefs.js`
  toggles `.dark` on `<html>` and applies the saved theme/locale/date/font.

## More than one server

Two sites, two full DriverVault stacks — and one browser tab. The server picker
sits at the bottom of the app rail (after signing in, not on the login screen):
it names the server you are reading right now, and switches between them in a
click.

- **The home server** is the one that served the app, reached same-origin through
  the BFF's `/api` proxy. It is always in the list and can't be removed.
- **Any other server** is added by address — `https://garage.example.com`; the
  `/api` is appended for you if you leave the path off — and is called **straight
  from the browser**, not relayed through the BFF. That server therefore has to be
  reachable from wherever the browser is, which it already is if the phone app
  talks to it.
- **A session per server.** Each server is its own PocketBase with its own users,
  so a token can't be carried across: you sign into each one once, and after that
  switching needs no password. Sessions live in `localStorage` under
  `cc_session_<id>`, the list under `cc_servers`, the active one under
  `cc_active_server`.
- **Switching goes back to the garage**, because record ids belong to the server
  that issued them — a car page can't survive the change.
- **An expiring remote session doesn't sign you out of the app**: that server's
  token is dropped, the app falls back to the home server, and the entry stays in
  the list to sign into again. Only *Log out* clears every server at once.

The remote server must allow the Web App's origin in **`CORS_ALLOW_ORIGINS`**
(API Server setting, `*` by default — so this works out of the box, and only
needs attention on a server whose list has been narrowed). Nothing needs to be
configured on the server you are browsing *from*.

## Auth & access

Login proxies to the API Server, which relays PocketBase's own token — there is
no JWT the server mints and no server-side session list. The token is stored
client-side, per server, and sent as `Authorization` on every call; each request
is pinned to the server that was active when it went out, so one server's `401`
can never drop another's session. `auth.js` exposes
`isAdmin` and the current profile; the router guards `public` / `admin` routes.
Cars are per-user (owned + shared), and the UI mirrors the server's read / write
/ owner access levels.
