tajniak81andClaude Opus 5
d4033dbcef
Two changes, both about showing what is actually known rather than a tidier version of it. The build date asked for a day. A car's build date is often only a year, or a month and a year - the VIN plate is stamped with a month, the papers carry a day, a grey import neither - so a field insisting on all three is answered either with an invented day or with nothing, and both throw away what the owner did know. The field now picks its own precision: a full date, a month and year, or a year, each with the control that suits it. A year is typed rather than picked, because a date picker that makes you walk back to 1998 is worse than four keystrokes. Stored as the ISO prefix - "2015", "2015-03", "2015-03-10" - which is ISO 8601 reduced precision, and printed back at exactly that precision. The three shapes sort and compare as strings in date order, which is why the prefix is stored rather than a date with a precision field beside it. The formatter takes the string apart rather than parsing it: "2015-03" read as a UTC instant and printed in local time hands back February west of Greenwich. Narrowing the precision keeps what is still true, so a day dropped from "2015-03-10" leaves "2015-03". Widening clears the field. That is the awkward half of the control and it is deliberate: there is nothing to widen a year with, and leaving "2015" behind an empty month box would store a date the screen is not showing. The column was free text with no validation at all, which was tolerable while only a date picker could write it and is not now that three shapes are legal. normalizeBuildDate parses rather than pattern-matches, so "2015-13" and "2015-02-31" are refused instead of stored as something no reader can print. The phone needed changing to avoid destroying this. It parsed buildDate with DateTime.tryParse, which returns null for "2015" - so a half-known date would have shown as a dash, and saving the car from the phone would have written "" back over it. It holds both date fields as the string they arrived as now, prints them at their own precision, and hands back anything it cannot set. Its picker still only makes full dates; a precision control there is a separate job. Separately: an empty cell of the service table had three different looks in one row. The dash under Notes was body-coloured, as though it were content; the one under File was 12px, having borrowed the size of the Download button that would otherwise be there; the one under Changed parts was muted at 14px. They are one constant now, muted at the row's own size, which is what Next date and Next km already did for a missing value. The Download link keeps its own styling - it is an action, not a value. Verified in a browser: a stored "2015-03" loads as month precision in a month picker, month to year narrows to "2015", year to day clears, "19x98abc" typed into the year box sanitises to "1998", saving sends buildDate:"1998" and the Information tab then reads "1998" - while a full first-registration date beside it still reads 06-08-2026. All five empty cells across the three columns now compute to the same size, colour and weight, with the filled ones unchanged. go vet and go test ./... pass with a new test over the three valid shapes and six rejects; flutter analyze is clean and 22 tests pass, one new, covering a half-known date in two date formats and the time zone that could shift it; npm run build is clean. Not verified: First registration still demands a full date. The same argument applies to it and the field is now a reusable component, but it was not asked for and is one line away. The web formatter's month-name paths - the DMY and MDY formats, which spell the month out - are covered only by the phone's mirror of the logic, the web app still having no test runner. A car created through the Toyota import bypasses the new validation; it only ever produces full dates, so nothing invalid gets in that way, but it is not guarded. Both apps need redeploying before any of this is visible. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
DriverVault — API Server
The central API Server for the DriverVault project. Written in Go (standard
library only, module drivervault/apiserver). It is the single gateway
between all clients (web app, phone app, Home Assistant plugin, ESP32 device)
and the PocketBase database — clients never talk to PocketBase directly. The
API Server authenticates to PocketBase as a superuser and all collection access
rules are left null, so data is only reachable through this server.
It also serves the superadmin web panel at the server root (/).
Layout
cmd/server/main.go # entry point
internal/
├── api/ # HTTP handlers + router (server.go)
│ ├── auth.go # PocketBase token proxy + role gates
│ ├── users.go # user management (role/org scoped)
│ ├── orgs.go # organization management
│ ├── settings.go # runtime PocketBase connection (pb-config)
│ ├── plugins.go # plugin management endpoints
│ ├── status.go # upstream health probes
│ ├── health.go respond.go panel.go
│ ├── cars.go records.go services.go parts.go shares.go me.go
│ ├── technical.go fuel.go charging.go maintenance.go documents.go
│ ├── reminders.go
│ ├── attachments.go # one optional file per record (shared handlers)
│ ├── integrations*.go # per-user Toyota / Anker Solix settings + OCPP control
│ └── dist/ # built panel, embedded via go:embed
├── config/config.go # env + .env load, .env write-back
├── models/models.go # domain types + derived-field computation
├── ocpp/ # OCPP 1.6J Central System (Anker Solix charging control)
├── pb/client.go # PocketBase superuser client (runtime-retargetable)
└── plugins/ # plugin system — see plugins/README.md
├── plugin.go manager.go external.go doc.go
└── builtin/ # built-in connectors: toyota, ankersolix
panel/ # Vue 3 + Tailwind panel source
scripts/ # Node/Python maintenance scripts
bin/api-server.exe # prebuilt binary the deployment runs
Auth & access control
Authentication is PocketBase's own. POST /api/auth/login is proxied to the
PocketBase users collection and the client keeps the token PocketBase minted;
this server does not issue its own JWT. Every protected request re-resolves that
token against PocketBase (auth-refresh), so a role change or a deletion takes
effect immediately rather than lingering until a token expires.
POST /api/auth/login { "email": "...", "password": "..." } -> PocketBase { token, record }
GET /api/auth/me (Authorization: <token>) -> { id, email, name, role }
GET /api/identity (Authorization: <token>) -> + organization
Both Authorization: Bearer <token> and a raw Authorization: <token> are
accepted (PocketBase's own SDKs send the latter).
Roles
users.role is user | admin | superadmin (empty is treated as user).
| Role | Can |
|---|---|
| user | their own cars, service records, parts, profile |
| admin | the above, plus manage users within their own organization |
| superadmin | everything, across all organizations, plus the PocketBase connection and plugins |
Guards worth knowing: an admin cannot create or edit a superadmin, cannot move users between organizations, and nobody can change their own role or delete their own account. An organization cannot be deleted while it still has members.
Organizations
organizations is the tenant collection; users.organization is the
membership. A superadmin spans all organizations; an admin is scoped by the
server to their own. Users may have no organization at all.
Creating one is self-service: any user who does not already belong to an
organization may POST /api/orgs, and becomes that organization's admin and
first member in the same request (if the promotion fails the new organization is
rolled back, so it is never left with nobody able to administer it). A user who
already belongs to one is refused — membership is a single relation, so creating
a second would mean silently abandoning the first.
A superadmin is the exception: they create organizations without joining them, since they already span every tenant.
From there an admin manages their own organization — rename it, or delete it
once they are its only member. Deleting it detaches and demotes them back to a
plain user before the record is removed, so the organization is empty when it
goes. A superadmin may rename or delete any organization, but still only once it
has no members at all.
Per-user car ownership + sharing
Cars are not a global list. cars.owner marks ownership and car_shares grants
other users read or write access. Every car/service/part handler is gated by
requireCarAccess:
- read — view the car, its service records and parts.
- write — edit the car and full service/part CRUD.
- owner only — delete the car and manage its shares.
Data model
| Collection | Purpose | Key fields |
|---|---|---|
cars |
one per car | name, make, model, year, registration, registrationCountry, vin, fuelType, buildDate, firstRegistrationDate, currentKm, serviceIntervalDays (365), serviceIntervalKm (15000), technicalCheckIntervalDays (365), oilSpec, transmissionOilSpec, differentialOilSpec, brakeFluidSpec, coolantSpec, owner |
service_records |
the service log | car, date, km, changed_oil, changed_engine_air_filter, changed_cabin_air_filter, notes |
technical_checks |
roadworthiness inspections (przegląd techniczny / MOT / TÜV) | car, date, result (passed | failed), cost, station, valid_until, notes |
parts |
per-car parts catalog | car, name, part_number, category, notes |
fuel_entries |
refuelling log (efficiency derived on read) | car, date, km, liters, cost, full_tank, missed_fill, station, notes |
charging_sessions |
EV charging log, the same shape as the refuelling one (kWh/100km derived on read) | car, date, km, kwh, cost, full_charge, missed_session, location, notes |
maintenance_entries |
workshop visits & repairs (outside routine service) | car, date, km, type, status, workshop, parts_used, labor_cost, parts_cost, invoice_number, warranty_until, notes |
car_documents |
paperwork (insurance, registration, road tax, …) | car, type, title, provider, reference, issue_date, expiry_date, cost, notes |
reminders |
date/odometer reminders (some auto-derived) | car, title, type, due_date, due_km, repeat_days, repeat_km, done, done_at, notes |
car_shares |
grants another user access to a car | car, user, permission (read | write) |
organizations |
tenants | name (unique) |
control_audit |
OCPP control-command audit trail | user, charger, action, result, timestamp |
users |
login + profile (built-in auth collection) | name, email, avatar, role (user | admin | superadmin), organization, bio, theme, locale, date_format, currency, font_size, deletion_requested_at |
Every record collection except car_shares / organizations / control_audit
carries one optional file attachment, served only through the API Server
(GET /api/{records}/{id}/file) — never a public PocketBase URL.
Spreadsheet formulas (from the original Car Service.xlsx), reproduced by
the API on read:
Next Service Date = service date + serviceIntervalDays (Excel: =A+365)
Next Service Km = service km + serviceIntervalKm (Excel: =B+15000)
These come back on each service record as nextServiceDate / nextServiceKm.
Endpoints
# public
GET /healthz
GET /api/health
GET /api/status # health of PocketBase + Web App, probed server-side
POST /api/auth/login
GET /api/auth/validate
# identity
GET /api/auth/me
GET /api/identity
# current user (profile / appearance / drag lock / garage order / avatar / data /
# account lifecycle)
GET /api/me PATCH /api/me DELETE /api/me
POST /api/me/password
POST /api/me/avatar GET /api/me/avatar DELETE /api/me/avatar
POST /api/me/verify/request
GET /api/me/export POST /api/me/import
POST /api/me/delete POST /api/me/delete/cancel
# users + organizations (admin or superadmin; POST /api/orgs is open to any user)
GET /api/users POST /api/users
PATCH /api/users/{id} DELETE /api/users/{id}
GET /api/orgs POST /api/orgs
PATCH /api/orgs/{id} DELETE /api/orgs/{id}
# superadmin — connection + plugin management
GET /api/admin/pb-config PUT /api/admin/pb-config POST /api/admin/pb-config/test
GET /api/admin/webapp-config PUT /api/admin/webapp-config POST /api/admin/webapp-config/test
GET /api/admin/server-config PUT /api/admin/server-config
GET /api/admin/plugins POST /api/admin/plugins
GET /api/admin/plugins/{name} PUT /api/admin/plugins/{name}
DELETE /api/admin/plugins/{name} POST /api/admin/plugins/{name}/health
# integrations (per-user plugin settings; superadmin → org admin → user cascade)
GET /api/integrations/toyota PUT /api/integrations/toyota POST /api/integrations/toyota/health
GET /api/integrations/toyota/vehicles
GET /api/integrations/anker-solix PUT /api/integrations/anker-solix POST /api/integrations/anker-solix/health
GET /api/integrations/anker-solix/chargers
# Anker Solix OCPP charging control (own/proxy mode + a live CSMS session)
GET /api/integrations/anker-solix/chargers/{sn}/control
POST /api/integrations/anker-solix/chargers/{sn}/control/token
DELETE /api/integrations/anker-solix/chargers/{sn}/control/token
POST /api/integrations/anker-solix/chargers/{sn}/{action}
GET /ocpp/{serial} # charger dials in here (OCPP Basic auth, not bearer)
# vehicle providers — create a car from a manufacturer service; per-car provider tab
GET /api/vehicle-providers
GET /api/vehicle-providers/{provider}/vehicles
POST /api/vehicle-providers/{provider}/import
# cars + sharing (GET /api/cars returns the garage in the user's saved order,
# which PATCH /api/me {carOrder} sets)
GET /api/cars POST /api/cars
GET /api/cars/{id} PATCH /api/cars/{id} DELETE /api/cars/{id}
PUT /api/cars/{id}/view # which tabs, Information rows and service-history
# columns this car shows, and the order of the tabs,
# the rows, the columns and the provider readings
GET /api/cars/{id}/provider POST /api/cars/{id}/provider
POST /api/cars/{id}/provider/sync
GET /api/cars/{id}/service-records GET /api/cars/{id}/technical-checks
GET /api/cars/{id}/parts GET /api/cars/{id}/fuel-entries GET /api/cars/{id}/fuel-stats
GET /api/cars/{id}/charging-sessions GET /api/cars/{id}/charging-stats
GET /api/cars/{id}/maintenance GET /api/cars/{id}/documents GET /api/cars/{id}/reminders
GET /api/cars/{id}/shares POST /api/cars/{id}/shares DELETE /api/cars/{id}/shares/{userId}
# per-record collections — each is GET(list) POST / GET PATCH DELETE {id}
/api/service-records /api/technical-checks /api/parts
/api/fuel-entries /api/charging-sessions /api/maintenance
/api/car-documents
/api/reminders (+ POST /api/reminders/{id}/complete)
# attachments — one optional file per record, on every collection that takes one.
# {records} = car-documents | service-records | technical-checks | maintenance
# | fuel-entries | charging-sessions | parts
POST /api/{records}/{id}/file GET /api/{records}/{id}/file DELETE /api/{records}/{id}/file
GET /api/cars returns the caller's owned cars plus any shared with them, each
annotated with an access field. The per-record list endpoints also accept a
?car={id} filter (e.g. GET /api/service-records?car={id}).
Gotcha:
updateCarrewrites all car columns from the payload, so aPATCH /api/cars/{id}must send the full car object — omitted spec fields get blanked. (The phone's odometer quick-edit sends the whole car for this reason.) The two exceptions areownerand the provider link (provider,provider_vehicle_id), whichcarPayloaddeliberately leaves out so an ordinary edit can neither reassign the car nor break its connected service.
Vehicle providers
internal/api/vehicleproviders.go turns a manufacturer-service plugin into a car
you can create from your own account with that service, plus a per-car tab showing
everything the service currently knows about it. Toyota (MyToyota) is the first
provider; adding the next one means writing a vehicleSource adapter and
appending it to vehicleSources() — no new endpoints and no Web App changes.
Two properties shape the design:
- Credentials are always the caller's. Every provider call resolves through the same global → org → user cascade as the integration settings, so a car shared with someone else shows them provider data only when that vehicle is on their manufacturer account. The owner's credentials are never borrowed.
- Upstream shapes are not modelled. These are unofficial APIs. Rather than hard-coding field paths, the layer searches payloads by key name for the handful of readings worth promoting (odometer, fuel, battery, range) and flattens the rest to dotted key/value pairs, shipping the raw payload alongside. A renamed field costs one blank value instead of a broken page.
POST .../import takes {vehicleId, name?, include?}, where include selects
which groups to pull (identity, fuelType, dates, odometer). Omitting it
means "everything available". POST /api/cars/{id}/provider/sync takes the same
selection, and only ever moves the odometer forward — a reading that appears to go
backwards is a stale provider, not a car driven in reverse.
The panel (/)
A Vue 3 + Tailwind app (source in panel/, built into internal/api/dist and
embedded at compile time). It is the superadmin console:
- Overview — live health of the API Server, PocketBase and the Web App.
- Users / Organizations — full management, scoped to the caller's role.
- PocketBase — retarget the database connection at runtime; test before
saving. Applied immediately and persisted to
.env, so it survives a restart. This is the escape hatch when the configured PocketBase is wrong or unreachable — the settings endpoints deliberately do not require a working service account. - Plugins — enable/disable/configure integrations, run health checks, register external plugins.
- API — the endpoint reference.
Log in with any DriverVault account; the sections you see depend on your role.
cd panel
npm install
npm run dev # localhost:5174, proxies /api to localhost:8080
npm run build # -> ../internal/api/dist (then rebuild the Go binary)
Editing panel source alone does nothing to the served panel — run npm run build
and then rebuild the Go binary, since dist is embedded.
Plugins
An extension system for integrating third-party services, managed by a
superadmin. Two kinds share one contract: built-in (Go, compiled in) and
external (any HTTP service, registered at runtime, no rebuild). Enable
state and global config persist to PocketBase, in the app_settings singleton —
the same place the per-org and per-user layers of the cascade live.
See internal/plugins/README.md for the full
guide. Two built-in connectors ship today — Toyota Connected (toyota,
read-only MyToyota vehicle data) and the Anker Solix V1 EV charger
(anker-solix) — and any number of external HTTP plugins can be registered at
runtime with no rebuild.
Integrations & charging control
Beyond the superadmin plugin registry, the built-in connectors are exposed
per-user through /api/integrations/* under a superadmin → org admin → user
cascade (each layer supplies defaults the next can override). For Anker Solix
chargers the server additionally runs an OCPP 1.6J Central System
(internal/ocpp): when the owner sets a control mode of own/proxy, the charger
dials back in at GET /ocpp/{serial} (authenticated with OCPP Basic auth using a
per-charger control token, not a bearer token) and the owner can start/stop and
set charge limits, with every command rate-limited and written to a
control_audit trail.
Configuration
Copy .env.example to .env and fill in. Summary:
| Variable | Default | Purpose |
|---|---|---|
API_ADDR |
:8080 |
listen address (bare port accepted) |
POCKETBASE_URL |
http://10.2.1.10:8027 |
PocketBase base URL |
POCKETBASE_ADMIN_EMAIL / _PASSWORD |
— | superuser service account |
CORS_ALLOW_ORIGINS |
* |
comma-separated browser origins |
WEBAPP_URL |
http://localhost:8090 |
probed by /api/status |
AUTH_USERS_COLLECTION |
users |
PocketBase auth collection |
OCPP_REQUIRE_TLS |
true |
reject chargers that did not connect over TLS |
OCPP_PUBLIC_URL |
— | canonical ws(s):// base to point chargers at |
PB_BOOTSTRAP |
true |
run the on-boot schema create/reconcile (leave on across upgrades) |
DRIVERVAULT_SUPERADMIN_EMAIL / _PASSWORD / _NAME |
— / — / Administrator |
first superadmin, created on boot when absent |
PB_URL, PB_ADMIN_EMAIL, PB_ADMIN_PASSWORD, PORT and CORS_ORIGINS are
still honoured for older deployments; the modern names win when both are set.
The server keeps no state on disk: plugin settings, like everything else it
owns, live in PocketBase. A .env in the working directory is read at startup as
a local-development convenience, and the panel writes back to it when a
superadmin retargets PocketBase or the Web App — but in Docker there is no volume
behind it, so those two screens apply for the life of the container only. Set the
environment variables to change them permanently; see Dockerfile
and ../Docker.
CORS_ALLOW_ORIGINS only matters for browser clients (the web app). Native
mobile apps are not subject to CORS.
The service account is optional at startup: without it the server still runs and a superadmin can log in and configure it from the panel, while management endpoints return 503.
Scripts (scripts/)
node scripts/setup-pocketbase.mjs # create/reconcile collections (idempotent)
node scripts/create-user.mjs <email> <pw> "Name" # create an app login
node scripts/set-role.mjs <email> user|admin|superadmin
node scripts/backfill-car-owners.mjs # one-off: assign owner to legacy cars
python scripts/seed_from_excel.py "C:/Users/jania/Desktop/Car Service.xlsx"
The Node scripts read POCKETBASE_URL / POCKETBASE_ADMIN_EMAIL /
POCKETBASE_ADMIN_PASSWORD (or the legacy PB_* names) from the environment.
PocketBase note: collections created by the setup script do not get automatic
created/updatedautodate fields in this PocketBase version — sorting oncreatedfails unless an explicitF.autodate(...)is added. When adding a new car spec field, extendDESIRED.carsinsetup-pocketbase.mjs, add it tomodels.Car+ the record mapping inrecords.go, then rebuild.
Startup bootstrap: the server also runs this same create/reconcile on boot (
internal/bootstrap, a Go mirror ofsetup-pocketbase.mjs) whenever a service account is configured, so the Docker prod stack needs no manual setup step. It is idempotent and gated byPB_BOOTSTRAP(defaulttrue; set tofalseto skip). WithDRIVERVAULT_SUPERADMIN_EMAIL+DRIVERVAULT_SUPERADMIN_PASSWORDset it also creates the firstsuperadminuser when absent. Keep the two schemas in sync: a change toDESIREDin the script must be mirrored ininternal/bootstrap/schema.go(guarded byTestSchemaConsistency).
First-time setup
-
Create the PocketBase collections (idempotent — safe to re-run on an existing deployment; it adds
organizations,users.organization, and growsusers.roleto includesuperadmin):$env:POCKETBASE_URL="http://10.2.1.10:8027" $env:POCKETBASE_ADMIN_EMAIL="you@example.com" $env:POCKETBASE_ADMIN_PASSWORD="secret" node scripts/setup-pocketbase.mjs -
Mint the first superadmin. The panel's management screens need one, and only a superadmin can promote another — so the first has to come from the script:
node scripts/create-user.mjs admin@example.com "a-long-password" "Admin" node scripts/set-role.mjs admin@example.com superadmin -
Run the server —
go run ./cmd/server, or build and run the binary. -
Open the panel at
http://localhost:8080/and sign in. -
(Optional) Seed from the spreadsheet with the server running (see scripts).
Build & run
go build -o bin/api-server.exe ./cmd/server
The deployment runs the prebuilt binary bin/api-server.exe (not go run),
started detached so it survives the shell:
Start-Process -FilePath ".\bin\api-server.exe" -WorkingDirectory "." `
-WindowStyle Hidden -RedirectStandardOutput api-server.out.log `
-RedirectStandardError api-server.err.log
Go's log package writes to stderr, so check api-server.err.log for
request logs and errors. After editing any Go source, rebuild and restart the
process — editing source alone does nothing until the binary is rebuilt.
Migrating from the JWT build
Earlier builds minted their own HS256 JWT and tracked a sessions collection
for "active devices" / remote logout. That is gone — the server now relays
PocketBase tokens. Consequences:
AUTH_SECRETis obsolete and ignored.- Login returns PocketBase's envelope —
{token, record}, not{token, user}. GET|DELETE /api/sessions*are gone. PocketBase tokens are stateless, so there is nothing to revoke per-device. To lock every device out of an account, change its password: PocketBase rotates the user's token key, which invalidates every token already issued.- User management moved from
/api/admin/users*to/api/users*, and the separate password-reset endpoint folded intoPATCH /api/users/{id}({"password": "..."}). Responses are enveloped:{users}/{user}. - Existing tokens are invalid — every client must log in once more.
- The
sessionscollection is left in PocketBase rather than dropped; delete it by hand if you want it gone.
The Web App and Phone App in this repo are already updated for all of the above.