motovaultpro/docs/README.md

# MotoVaultPro Documentation

Project documentation hub for the 5-container single-tenant architecture with integrated platform feature.

## Navigation

- Architecture: `docs/PLATFORM-SERVICES.md`
- Security: `docs/SECURITY.md`
- Vehicles API (authoritative): `docs/VEHICLES-API.md`
- Database schema: `docs/DATABASE-SCHEMA.md`
- Testing (containers only): `docs/TESTING.md`
- Database Migration: `docs/DATABASE-MIGRATION.md`
- Development commands: `Makefile`, `docker-compose.yml`
- Application features (start at each README):
  - `backend/src/features/platform/README.md`
  - `backend/src/features/vehicles/README.md`
  - `backend/src/features/fuel-logs/README.md`
  - `backend/src/features/maintenance/README.md`
  - `backend/src/features/stations/README.md`
  - `backend/src/features/documents/README.md`

## Notes

- Canonical URLs: Frontend `https://motovaultpro.com`, Backend health `http://localhost:3001/health`.
- Feature test coverage: Basic test structure exists for vehicles and documents features; other features have placeholder tests.


## Cleanup Notes
> Documentation Audit

  - Documented commands make test/make test-frontend appear across README.md:12-17, backend/README.md:20-38, docs/TESTING.md:24-49, AI-INDEX.md:8, and frontend/
  README.md:8-28; the Makefile only advertises them in help (Makefile:11-12) with no corresponding targets, so the instructions currently break.
  - README.md:27 and AI-INDEX.md:19 point folks to http://localhost:3001/health, but docker-compose.yml:77-135 never exposes that port, meaning the reachable
  probe is https://motovaultpro.com/api/health via Traefik.
  - docs/TESTING.md:11-99,169-175 commit to full per-feature suites and fixtures such as vehicles.fixtures.json, yet backend/src/features/fuel-logs/tests and
  backend/src/features/maintenance/tests contain no files (see find output), and backend/src/features/vehicles/tests/fixtures is empty.
  - Backend fuel-log docs still describe the legacy contract (gallons, pricePerGallon, mpg field) in backend/src/features/fuel-logs/README.md:20-78, but the
  code now accepts/returns dateTime, fuelUnits, costPerUnit, efficiency, etc. (backend/src/features/fuel-logs/domain/fuel-logs.service.ts:17-320).

  Security & Platform

  - docs/VEHICLES-API.md:35-36 and 149-151 still require an API key, while the platform routes enforce Auth0 JWTs via fastify.authenticate (backend/src/
  features/platform/api/platform.routes.ts:20-42); there’s no API key configuration in the repo.
  - docs/VEHICLES-API.md:38-41 promises 1-hour Redis TTLs, but PlatformCacheService stores dropdown data for six hours and successful VIN decodes for seven days
  (backend/src/features/platform/domain/platform-cache.service.ts:27-110).
  - docs/SECURITY.md:15-16 claims “Unauthenticated Endpoints – None,” yet /health and /api/health are open (backend/src/app.ts:69-86); docs/SECURITY.md:25-
  29 also states Postgres connections are encrypted even though the pool uses a plain postgresql:// URL without SSL options (backend/src/core/config/config-
  loader.ts:213-218; backend/src/core/config/database.ts:1-16).
  - docs/SECURITY.md:21-23 references the old FastAPI VIN service, but VIN decoding now lives entirely in TypeScript (backend/src/features/platform/domain/vin-
  decode.service.ts:1-114).

  Feature Guides

  - backend/src/features/vehicles/README.md:15-108 still references an implemented dropdown proxy, a platform-vehicles client folder, and a platform-
  vehicles.client.test.ts, yet the service methods remain TODO stubs returning empty arrays (backend/src/features/vehicles/domain/vehicles.service.ts:165-193)
  and there is no such client or test file in the tree.
  - docs/VEHICLES-API.md:58-97 says the frontend consumes /api/vehicles/dropdown/*, but the current client hits /platform/* and expects raw arrays (frontend/
  src/features/vehicles/api/vehicles.api.ts:35-69) while the backend responds with wrapped objects like { makes: [...] } (backend/src/features/platform/api/
  platform.controller.ts:48-94), so either the docs or the code path needs realignment.
  - backend/src/features/fuel-logs/README.md:150-153 advertises a fuel-stats:vehicle:{vehicleId} Redis cache and response fields like totalLogs/averageMpg, but
  getVehicleStats performs fresh queries and returns { logCount, totalFuelUnits, totalCost, averageCostPerUnit, totalDistance, averageEfficiency, unitLabels }
  with no caching (backend/src/features/fuel-logs/domain/fuel-logs.service.ts:226-320).
  - backend/src/features/documents/README.md:4,23-25 describes S3-compatible storage and a core/middleware/user-context dependency; in reality uploads go to
  the filesystem adapter (backend/src/core/storage/storage.service.ts:1-48; backend/src/core/storage/adapters/filesystem.adapter.ts:1-86) and there is no user-
  context module in backend/src/core.
  - docs/DATABASE-SCHEMA.md:109-111 asserts station caching happens in Redis, but Station data is persisted in Postgres tables such as station_cache
  (backend/src/features/stations/data/stations.repository.ts:11-115), and docs/DATABASE-SCHEMA.md:155-157 mentions “RESTRICT on delete” even though
  migrations use ON DELETE CASCADE (backend/src/features/fuel-logs/migrations/001_create_fuel_logs_table.sql:18-21; backend/src/features/maintenance/
  migrations/002_recreate_maintenance_tables.sql:21-43).

  Questions

  - Do we want to add the missing make test / make test-frontend automation (so the documented workflow survives), or should the documentation be rewritten to
  direct people to the existing docker compose exec ... npm test commands?
  - For the vehicles dropdown flow, should the docs be updated to call out the current TODOs, or is finishing the proxy implementation (and aligning the
  frontend/client responses) a higher priority?

  Suggested next steps: decide on the build/test command strategy, refresh the security/platform documentation to match the Auth0 setup and real cache
  behaviour, and schedule a pass over the feature READMEs (vehicles, fuel logs, documents) so they match the implemented API contracts.