# MotorSignal Website/Admin Current State

Audited 2026-09-08 against the implementation plan and the deployed API at
`api.motorsignal.app`.

## Repository Boundary

This repository is the Flutter mobile application. It contains no separate
website frontend, no FastAPI source, and no Alembic migration directory. The
production FastAPI source currently lives on the VPS under
`/opt/motorsignal/current/app`; it is not available as local versioned source.

The production website at `motorsignal.app` is currently a placeholder static
page. It is not an admin panel.

## Verified API Surface

The deployed FastAPI application currently exposes:

- `GET /api/v1/health`
- `GET /api/v1/ready`
- `POST /api/v1/auth/register`
- `POST /api/v1/auth/login`
- `POST /api/v1/auth/refresh`
- `POST /api/v1/auth/logout`
- `GET /api/v1/me`

Authentication already has password hashing, access tokens, refresh-token
hashing/rotation, per-device sessions, and session validation for the current
user.

## Implemented Locally In This Checkpoint

The recovered backend now includes a reversible Alembic revision for:

- User roles with a default `user` role
- Email-verification and password-reset token persistence
- Audit-event persistence with actor/target, request metadata, and timestamps

The API now includes email verification request/consume flows, password reset
request/consume flows, session listing/revocation/logout-all, role dependencies,
and a support/admin audit-event read endpoint. It also includes role-protected
paginated admin CRUD for users and vehicles, plus ride CRUD with archive-on-delete
semantics. SMTP delivery is optional and configured only through environment
variables; tokens are never returned by the request endpoints.

User-scoped vehicle and ride list/read/create/update/delete-or-archive access is
also available under `/api/v1/vehicles` and `/api/v1/rides`, scoped from the
authenticated session rather than caller-supplied ownership.

Ride-linked telemetry persistence is available through bounded batch ingestion
at `/api/v1/rides/{ride_id}/telemetry`, owner-scoped reads, and support/admin
reads. Points are indexed by ride and timestamp.

Owner and support/admin telemetry summary endpoints expose point count, duration,
maximum speed, maximum lean angle, and maximum G-force without requiring raw
bundle transfer.

Subscription and entitlement baselines are available through authenticated
account reads and admin-controlled updates. Default subscription is `free`; no
payment provider or billing state is fabricated.

The account portal now exposes active sessions and supports revoking individual
non-current sessions or all sessions through secure server-side proxy routes.

Database-backed authentication rate limits now protect login, registration,
verification, and password-reset paths. Limit is 10 attempts per client IP per
15-minute window, with `Retry-After` responses.

## Still Missing Before Admin UI

These plan requirements are not present in the deployed API:

- Telemetry, subscriptions, and entitlement models
- Authentication rate limiting beyond the existing Nginx request limit

Production deployment remains pending review. Local runtime verification uses
the recovered lock and a Windows-compatible test lock.

## Local Verification Checkpoint

The exact production dependency set was recovered from the running production
virtualenv with `pip freeze` and saved as
`backend/motorsignal_api/requirements.lock`. Parity against a fresh production
freeze passed. Windows uses a separate test lock excluding only `uvloop`, which
does not support Windows.

Local PostgreSQL 16 runs in Docker on `127.0.0.1:55432`. Alembic upgrade from an
empty database passed at revision `d9e4f6012a35`. Repeatable API smoke tests pass
for registration, email verification, password reset, sessions, RBAC denial,
audit writes, and logout-all. No production migration or API deployment was
performed.

## Required Next Checkpoint

Obtain the FastAPI/Alembic source into a versioned local backend project before
editing authentication, authorization, schema, or production deployment. Do not
implement admin CRUD against the current API: it has no server-side admin
authorization or resource endpoints to secure the panel.