Vehicle Manager Documentation

Welcome to the official documentation for Vehicle Manager - a comprehensive, self-hosted platform for tracking every aspect of vehicle ownership. Whether you manage a single car or a whole fleet of motorcycles, vans, and trucks, this guide will walk you through everything from initial setup to the deepest corners of the API.

Introduction

Vehicle Manager was built with a simple philosophy: you should own your data. There are no cloud subscriptions, no third-party analytics, and no telemetry. You host it yourself, and everything - every fuel receipt, every MOT advisory, every depreciation calculation - lives on your own infrastructure.

The platform covers fuel costs, service history, MOT records, insurance policies, road tax, parts, consumables, vehicle specifications, depreciation tracking, receipt OCR, report generation, and much more. It's built as three interlocking components:

Everything is open-source, free forever, and licensed permissively. The project lives on GitHub and contributions are always welcome.

Prerequisites

Before you begin, make sure your machine has the following installed. If you're deploying to a server, these same requirements apply there.

Docker Setup

The entire application runs inside Docker containers. Clone the repository, bring the containers up, and you're ready to go - no manual PHP, MySQL, or Redis installation required.

1. Clone the Repository

git clone https://github.com/peteclarke-del/vehicle.git
cd vehicle

2. Start the Containers

docker-compose up -d

This spins up five services. Here's what each one does and where it listens:

3. Wait for Readiness

MySQL has a health check configured. The PHP entrypoint script waits for the database to be ready and then automatically runs Doctrine migrations. You can follow the logs to watch for completion:

docker-compose logs -f php

Once you see the FPM "ready to handle connections" message, you're good.

4. Environment Variables

The default .env file ships with sensible development defaults. For production, you'll want to configure these key variables:

First Run

Once the containers are up and MySQL migrations have completed, you need to seed the reference data that powers the application's dropdowns and category systems.

Seed Lookup Data

docker-compose exec php bin/console doctrine:fixtures:load --no-interaction

This populates vehicle types (Motorcycle, Car, Van, Truck, EV), makes, models, consumable types, part categories, and security features from the bundled JSON data files in backend/data/.

Seed Feature Flags

docker-compose exec php bin/console app:seed-feature-flags

This creates the 49 default feature flags that control which parts of the application are available to each user. By default, all flags are enabled for everyone. Admins can override them per-user later.

Access the Application

Creating an Account

Head to the web frontend at http://localhost:3000 and click Register. You'll need to provide your name, email address, and a password. The password must meet the security policy (minimum 8 characters with a mix of upper-case, lower-case, digits, and special characters).

Alternatively, you can register via the API directly:

curl -X POST http://localhost:8081/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "SecureP@ss1",
    "firstName": "Jane",
    "lastName": "Doe"
  }'

Becoming an Admin

The first user you create will have standard ROLE_USER permissions. To promote yourself to an administrator - which unlocks user management, feature flag control, and vehicle assignment features - run this SQL against your database:

UPDATE users SET roles = '["ROLE_USER","ROLE_ADMIN"]' WHERE id = 1;

Architecture Overview

Vehicle Manager follows a clean API-first architecture. The backend exposes a RESTful JSON API that both the web and mobile front-ends consume identically. There is no server-side rendering - the backend is purely an API server, and the front-ends are fully decoupled single-page applications.

Authentication uses the Lexik JWT Authentication Bundle. Tokens have a one-hour time-to-live and can be extracted from both the Authorization: Bearer header and a ?token= query parameter (the latter is used for SSE notification streams). Refresh tokens are stored in the database with a 30-day expiry, and users can explicitly revoke them.

Caching runs through Redis 7 with tag-based invalidation. Five named cache pools cover different data types, each with a TTL tuned for how frequently the underlying data changes:

Backend Architecture

The backend is a Symfony 6.4 application running on PHP 8.4. It uses attribute-based routing on controller methods, Doctrine ORM for database access, and Symfony's autowiring container for dependency injection. The codebase is organised into these key layers:

• Controllers (32 files) - Handle HTTP requests, validate input, enforce authorisation, and return JSON responses. Seven reusable traits provide common functionality like ownership verification, JSON validation, and entity hydration.
• Services (16+ files) - Encapsulate business logic: cost calculation, depreciation, OCR, report generation, URL scraping (with adapters for eBay, Amazon, Shopify, and generic sites), VIN decoding, DVLA/DVSA integration, and import/export.
• Entities (27 files) - Doctrine ORM entities mapping to MySQL tables. Rich relationships: User → Vehicles → all sub-records. Vehicle → Specification (OneToOne). InsurancePolicy ↔ Vehicles (ManyToMany).
• Event Subscribers (3 files) - FeatureFlagSubscriber enforces per-user feature flags on API routes. TestAuthSubscriber enables mock authentication in test environments. PreventFixturesLoadSubscriber blocks fixture loading in production.
• Commands (5 files) - Console commands for seeding feature flags, importing consumables/parts, migrating attachments, and normalising MOT advisories.
• Data Fixtures (8 files) - Seed lookup data from bundled JSON files covering vehicle types, makes, models, consumable types, part categories, and security features.

Controller Traits

Seven traits keep controllers DRY:

Frontend Architecture

The web frontend is a React 18 single-page application bootstrapped with Create React App. It uses MUI 5 (Material UI) for the component library, React Router v6 for client-side routing, and Axios for HTTP communication with the backend.

The app is wrapped in a layered provider hierarchy: ThemeContext (MUI light/dark theming) → AuthContext (JWT token management, login/logout, user state) → UserPreferencesContext (default vehicle, distance unit, currency, rows per page) → VehicleContext (global vehicle list with 30-second caching) → PermissionsContext (feature-flag and assignment-based access control).

The main layout is an AppBar with a collapsible drawer. Navigation items in the drawer are drag-and-drop reorderable (via @dnd-kit) and their order is persisted to user preferences. The drawer can be pinned open or collapsed to a mini-rail (48 px icons only).

Charts are powered by @mui/x-charts - PieChart for cost breakdowns, BarChart for monthly spend, and LineChart for depreciation curves. Reports use 13 JSON template definitions and can be previewed in-browser via SheetJS (XLSX) or downloaded as PDF.

Mobile Architecture

The mobile app is built with React Native 0.73 and TypeScript. It uses React Native Paper (Material Design 3) for the UI layer and React Navigation for stack and tab-based navigation.

The defining feature of the mobile app is its dual-mode architecture. On first launch, the user is presented with a choice: connect to a remote Vehicle Manager server (web mode) or use the app entirely offline (standalone mode). In standalone mode, a LocalApiAdapter provides full CRUD operations backed by AsyncStorage, so the app works without any server at all.

In web mode, a SyncContext manages an offline change queue. When the device loses connectivity, mutations are queued in AsyncStorage and automatically replayed when the connection returns - with a 2-second debounce, up to 5 retries per operation, and automatic discard of 4xx errors (which indicate permanently invalid data). The useOfflineData hook provides cache-first loading with a 24-hour TTL, so the app always shows data even when offline.

Database Schema

The database is MySQL 8.0 with 27 Doctrine ORM entities. The central entity is Vehicle, which has cascade-remove relationships to almost everything else - deleting a vehicle automatically removes all of its fuel records, service records, parts, consumables, MOT records, road tax, todos, images, status history, and specification.

Key relationships to understand:

• User → Vehicles - A user owns many vehicles (OneToMany)
• Vehicle → Sub-records - Each vehicle has many fuel records, service records, parts, consumables, MOT records, road tax records, todos, images, and status history entries (all OneToMany with cascade remove)
• Vehicle → Specification - Each vehicle has at most one specification entity (OneToOne with cascade remove), covering ~40 fields for engine, drivetrain, chassis, and dimensions
• InsurancePolicy ↔ Vehicles - Policies can cover multiple vehicles, and a vehicle can be on multiple policies (ManyToMany via a join table)
• ServiceRecord → ServiceItems - A service record contains multiple line items, each of which may link to a Part or Consumable
• VehicleAssignment - Allows sharing vehicles between users with granular permissions (canView, canEdit, canAddRecords, canDelete)
• FeatureFlag ↔ UserFeatureOverride ↔ User - 49 feature flags with per-user overrides

Authentication API

All authenticated endpoints require a Bearer token in the Authorization header. Tokens are issued on login, last one hour, and can be refreshed using a long-lived refresh token (30 days). The authentication flow is entirely stateless - there are no server-side sessions.

{ "token": "eyJ0eXAiOiJKV1Qi..." }

{ "message": "User registered successfully", "userId": 1 }

{
  "id": 1,
  "email": "you@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "roles": ["ROLE_USER"],
  "country": "GB",
  "isActive": true,
  "isVerified": false,
  "passwordChangeRequired": false,
  "features": { "dashboard": true, "fuel_records": true, ... },
  "vehicleAssignments": [ ... ]
}

{ "refreshToken": "a1b2c3d4e5..." }

{ "refreshToken": "a1b2c3d4e5..." }

{ "token": "eyJ0eXAiOiJKV1Qi..." }

{ "currentPassword": "OldP@ss1", "newPassword": "NewP@ss2" }

Admin API

Every endpoint in this section requires ROLE_ADMIN. Administrators can manage user accounts, control feature flags on a per-user basis, and assign vehicles between users with granular permissions.

{ "roles": ["ROLE_USER", "ROLE_ADMIN"] }

{ "overrides": { "fuel_records": true, "mot_records": false, "reports": true } }

{ "assignments": [
  { "vehicleId": 5, "canView": true, "canEdit": true, "canAddRecords": true, "canDelete": false }
] }

Vehicles API

The vehicle endpoints form the core of the application. Vehicles are the top-level entity that everything else hangs off - fuel records, services, parts, MOT history, and more. Admin users see all vehicles across all users; regular users see only their own vehicles plus any that have been assigned to them.

Fuel Records API

Fuel records track every fill-up: date, litres, cost, mileage, fuel type, and station. The system automatically calculates MPG, price per litre, and cost per mile from the raw data. You can optionally attach a receipt photograph for OCR extraction.

Service Records API

Service records capture maintenance work - oil changes, brake replacements, tyre fitting, and anything else done to the vehicle. Each record can have multiple service items, each typed as a part, consumable, or labour charge. Items can be linked to existing Part or Consumable entities.

Parts API

Parts represent physical components purchased for a vehicle - brake pads, filters, spark plugs, bulbs, and so on. Each part can be linked to a service record, MOT record, or todo. The URL scraper endpoint lets you pull product details directly from online retailers.

{ "url": "https://www.ebay.co.uk/itm/123456789" }

{
  "name": "NGK Spark Plug BKR6E-11",
  "price": 4.99,
  "description": "...",
  "imageUrl": "https://...",
  "partNumber": "BKR6E-11"
}

Consumables API

Consumables are items that need regular replacement - engine oil, coolant, brake fluid, tyres, chain lubricant, and so on. Unlike parts, consumables have replacement tracking: you can record the replacement interval (in miles), when it was last changed, and the mileage at change. The system uses this data to trigger notifications when a consumable is due for replacement.

MOT Records API

MOT records track the annual roadworthiness test required for vehicles in the UK. Each record captures the test result (Pass, Fail, or Advisory), costs, mileage, structured advisory and failure items, and repair details. The system integrates with the DVSA API to automatically import historical MOT data.

{ "vehicleId": 1, "registration": "AB12CDE" }

Insurance API

Insurance is modelled with two levels. Insurance policies represent the actual policy documents from providers - these can cover multiple vehicles via a ManyToMany relationship. There are also vehicle-specific insurance records for simpler per-vehicle tracking. Both approaches are supported and you can use whichever fits your situation.

Policy Endpoints

{ "vehicleId": 5 }

Vehicle Insurance Endpoints

Road Tax API

Road tax records track vehicle excise duty (VED) payments. The system knows that vehicles aged 30 years or older are automatically road tax exempt in the UK, and will reject attempts to create road tax records for exempt vehicles. SORN (Statutory Off Road Notification) is also supported.

Todos API

Todos let you track upcoming work for a vehicle - "replace front tyre", "book MOT", "order new battery". Each todo can be linked to parts and consumables, and when you mark a todo as done, the completion timestamp is recorded. Overdue todos trigger notifications.

Attachments API

Attachments handle file uploads - primarily receipt photographs for OCR, but also general documentation, user manuals, and service manuals. Files are organised on disk into uploads/vehicles/{registration}/{category}/ for clean file management. The system validates MIME types and enforces a configurable size limit (default 200 MB).

When an admin user uploads an attachment for a vehicle they don't own, the attachment is automatically attributed to the vehicle's owner - not the admin.

Reports API

The reporting system is template-driven. There are 13 built-in report templates covering fuel costs, service costs, part costs, consumable tracking, insurance and MOT expiry, road tax, and comprehensive vehicle reports. Reports can be downloaded as XLSX, PDF, or CSV.

Notifications API

The notification system checks for items that need attention - MOT tests expiring soon, road tax renewals, overdue service dates, insurance expiry, consumables due for replacement, and todo deadlines. The web app uses Server-Sent Events (SSE) for real-time updates, with a fallback to polling.

Lookups API

Lookup endpoints provide the reference data that populates dropdowns and selection lists throughout the application. All lookup data is cached for one hour. Vehicle types, makes, models, part categories, consumable types, and security features are seeded from the bundled JSON fixtures.

External API Integrations

Vehicle Manager integrates with several external APIs for UK vehicle data and product scraping. These require API keys configured via environment variables. All external calls include retry logic and graceful error handling.

DVLA - Vehicle Registration Lookup

DVSA - MOT History

VIN Decoding

VIN decoding is available via GET /api/vehicles/{id}/vin-decode (documented under Vehicles API). It uses the API Ninjas service to decode 17-character VINs into make, model, year, country, and vehicle class.

Vehicle Specifications Scraping

Specification scraping is available via POST /api/vehicles/{id}/specifications/scrape (documented under Vehicles API). It uses an adapter pipeline with DVLA, API Ninjas Motorcycles, and API Ninjas Cars adapters.

Import & Export API

The import/export system lets you back up your entire vehicle collection and restore it elsewhere. Exports include all sub-records (fuel, service, parts, consumables, MOT, insurance, road tax, todos, specifications, images). ZIP exports also include the actual attachment files.

System API

A handful of utility endpoints for health checking, diagnostics, and third-party integrations.

Cost Calculator Service

The CostCalculator is the engine behind every cost display in the application. It queries across all record types - fuel, parts, consumables, service, insurance, road tax, and MOT - to compute total costs, per-category breakdowns, cost per mile, average fuel consumption (in both MPG and L/100km), and comprehensive vehicle statistics. It depends on the Entity Manager for database queries and the Depreciation Calculator for current-value computations.

The dashboard totals endpoint, individual vehicle stats, and cost breakdown pages all delegate to this service. Results are cached at the controller level (2-minute TTL in the dashboard pool) to avoid expensive re-computation on every page load.

Depreciation Calculator Service

The DepreciationCalculator implements four depreciation methods and generates year-by-year schedules showing the vehicle's value over time:

• automotive_standard (default) - Mimics real-world vehicle depreciation: 20% in the first year, then 15% per year thereafter. This is the most realistic for most vehicles.
• straight_line - Equal depreciation each year: purchase cost divided by the number of years.
• declining_balance - A fixed percentage of the remaining value each year (the rate is configurable, default 20%).
• double_declining - An accelerated method: double the straight-line rate applied to the remaining value each year.

The schedule output includes the value at the start of each year, the depreciation amount, and the cumulative depreciation. This powers the depreciation LineChart on the vehicle details page.

DVLA API Service

The DvlaApiService integrates with the UK Driver and Vehicle Licensing Agency API for vehicle registration lookups. It supports two authentication modes: OAuth2 client-credentials flow (using client ID and secret) and direct API key authentication.

The service implements exponential backoff retry logic for 429 (rate limited) and 504 (gateway timeout) responses. If all retries are exhausted, it throws a DvlaBusyException. Successful responses are cached to avoid repeated API calls for the same registration.

DVSA API Service

The DvsaApiService connects to the UK Driver and Vehicle Standards Agency API for MOT history retrieval. Like the DVLA service, it supports both OAuth2 and API key authentication.

Key methods:

• getMotHistory(registration) - Full MOT test history
• parseFailureItems(data) - Extracts structured failure items from raw data
• parseAdvisoryItems(data) - Extracts structured advisory items
• getCurrentMotStatus(data) - Derives the current MOT status
• getPassRate(data) - Calculates the vehicle's overall MOT pass rate

Feature Flag Service

The FeatureFlagService manages the 49 feature flags that control which parts of the application are available to each user. The service resolves effective flags by merging the system-wide defaults with any per-user overrides. Admin users automatically get all features enabled, regardless of overrides.

Key methods:

• getEffectiveFlags(user) - Returns the resolved flag map for a user
• isFeatureEnabled(user, featureKey) - Check a single flag
• setFeatureOverride(user, featureKey, enabled) - Set one override
• bulkSetFeatureOverrides(user, overrides) - Set many overrides at once
• resetFeatureOverrides(user) - Remove all overrides, revert to defaults
• seedDefaults() - Create or update the 49 default flags
• getAllFlagsGrouped() - Returns flags organised by category for the admin UI

The FeatureFlagSubscriber event subscriber enforces these flags on every API request. If a user tries to access a route that requires a disabled feature, they receive a 403 response. Routes for authentication, admin, and lookups are always allowed regardless of flags.

Receipt OCR Service

The ReceiptOcrService uses Tesseract OCR to extract structured data from photographs of receipts. When you upload a receipt and trigger OCR, the service analyses the image and returns field values that can pre-fill forms automatically.

Supported receipt types:

• Fuel receipts - Extracts date, total cost, litres, station name, and fuel type
• Part receipts - Extracts product name, part number, price, quantity, and supplier
• Consumable receipts - Same as part receipts
• Service receipts - Extracts work description, labour cost, parts cost, and date

Report Engine

The ReportEngine is a template-driven report generation system. Each report is defined by a JSON template that specifies data sources, calculations, layout, and styling. The engine reads these templates, queries the database for the relevant data, performs calculations, and outputs the result as XLSX (via PhpSpreadsheet) or PDF (via TCPDF).

The system supports unit conversion - distances can be rendered in miles or kilometres based on user preference. There are 13 built-in templates (listed in the Reports API section above), and the template format is extensible for custom reports.

URL Scraper Service

The UrlScraperService extracts product information from retail URLs. When you paste a product URL into the parts or consumables form, this service attempts to pull the product name, price, description, images, and part numbers automatically.

It uses an adapter pipeline - each adapter is tried in order until one succeeds:

1. eBay Browse API - Fast path for eBay links using the official API (client credentials flow)
2. Shopify Adapter - Parses Shopify product JSON and HTML
3. Amazon Adapter - Uses the Amazon product API (API key required)
4. eBay HTML Adapter - Fallback HTML parsing for eBay when the API isn't available
5. Generic DOM Adapter - Last resort: parses OpenGraph meta tags, JSON-LD, and DOM elements

The service handles bot detection, retries on transient failures, and gracefully returns partial results when not all fields can be extracted.

Vehicle Export Service

The VehicleExportService serialises vehicles and all their sub-records into JSON format. It processes vehicles in batches of 25 with a 1 GB memory limit to handle large collections. The ZIP mode additionally packages all attachment files into the archive, preserving the directory structure.

Vehicle Import Service

The VehicleImportService is approximately 2,800 lines of import logic that handles every entity type. Imports are fully transactional - if any part of the import fails, the entire operation is rolled back. The service creates vehicles and all sub-entities (fuel records, service records with items, parts, consumables, MOT records, insurance policies, road tax, todos, attachments, and specifications). It handles duplicate detection, ID remapping, and relationship reconstruction.

Specification Scraper Service

The VehicleSpecificationScraperService fetches vehicle specifications from external sources using an adapter pattern. Three adapters are registered:

• DvlaAdapter - Extracts specification data from DVLA vehicle records
• ApiNinjasMotorcycleAdapter - Queries the API Ninjas Motorcycles API for detailed specs
• ApiNinjasCarAdapter - Queries the API Ninjas Cars API

Adapters are tried in priority order. Results are merged to fill gaps - if one adapter returns engine specs but not chassis data, the next adapter can fill in the missing fields. Covers approximately 40 specification fields including engine, fluids, drivetrain, chassis, brakes, tyres, dimensions, weights, and performance data.

VIN Decoder Service

The VinDecoderService decodes Vehicle Identification Numbers via the API Ninjas VIN API. It validates the 17-character format (rejecting VINs containing I, O, or Q, which are never used in valid VINs), sends the query, and returns decoded information: make, model, year, country of manufacture, and vehicle class. Decoded data is cached on the vehicle entity to avoid repeated API calls.

Attachment Linking Service

The AttachmentLinkingService manages bidirectional links between attachments and entities. When you link a receipt to a fuel record, this service updates both the attachment's entity reference and the fuel record's receipt reference. It also handles file reorganisation - when an attachment is linked to a vehicle, the physical file is moved from the generic uploads directory to uploads/vehicles/{registration}/{category}/ for clean file management.

Entity Reference

This section documents every Doctrine entity in the system - the database tables, their fields, types, and relationships. Click on an entity card to expand its field list.

User

Vehicle

Fuel Record

Service Record & Service Item

Part

Consumable

MOT Record

Insurance Policy

Road Tax

Todo

Attachment

Specification

Vehicle Image

Vehicle Assignment

Lookup Entities

These are simple reference entities that power dropdowns and categorisation throughout the application. They are seeded from bundled JSON fixtures.

Feature Flag Entities

Frontend Overview

The web frontend is a React 18 single-page application built with Create React App. It uses MUI 5 for the component library (including @mui/x-charts for data visualisation), React Router v6 for client-side routing, Axios for HTTP, and react-i18next for internationalisation with 21 languages (including a Pirate Easter egg 🏴‍☠️).

The application wraps all pages in a layered context hierarchy: ThemeContext → AuthContext → UserPreferencesContext → VehicleContext → PermissionsContext. This means every page has access to the current theme, authentication state, user preferences, the global vehicle list, and feature-flag permissions - without prop drilling.

Key Pages

Dashboard

The dashboard is the landing page after login. It shows stat cards at the top summarising total spend across categories (fuel, parts, consumables, services) for a configurable period. Below that is a pie chart showing total cost per vehicle (vehicles beyond the top 9 are grouped into an "Other" slice), and two stacked bar charts showing monthly fuel and maintenance spend over 3/6/12/24/36 months. At the bottom, vehicle cards are displayed in status tabs (Live, Sold, Scrapped, Exported) with key metrics and a drag-to-reorder capability.

Vehicles & Vehicle Details

The Vehicles page supports both card and table view modes with a toggle. Vehicles can be filtered by status, sorted by various fields (with sort preference persisted), and paginated. The add/edit dialog supports registration lookup (which scrapes data from the DVLA), make/model/year selection, depreciation settings, and MOT/road-tax exempt toggles.

The Vehicle Details page has seven tabs. Overview shows basic info, VIN decoder, and license plate rendering. Statistics displays cost breakdowns in a pie chart. Depreciation shows a line chart with the year-by-year schedule. Specifications shows ~40 fields with a "Scrape from web" button. Pictures is an image gallery with upload, reorder, and primary selection. Documentation and Manuals handle PDF/document uploads per category.

Records & Forms

All record pages (Fuel, Service, Parts, Consumables, MOT, Insurance, Road Tax, Todos) follow a consistent pattern: a list view with a vehicle selector filter, action buttons for add/edit/delete, and a dialog-based form. Each form handles receipt photograph upload, URL scraping (for parts and consumables), and entity linking.

Service record forms are the most complex - they support inline addition of service items, each typed as a part, labour charge, or consumable, with the ability to link to existing Part or Consumable entities. MOT record forms include structured advisory and failure item entry. Insurance forms support multi-vehicle policy assignment.

Admin Panel

The admin panel is available to users with ROLE_ADMIN. The Admin Users page lists all registered users with their vehicle counts, last login times, and active status. Admins can create new users, toggle active status, force password changes, and manage roles.

The Admin User Details page has two sections: feature flags (categorised toggle switches for all 49 flags with bulk update and reset-to-defaults) and vehicle assignments (assign vehicles to the user with granular canView/canEdit/canAddRecords/canDelete permissions).

Reports

The Reports page lets you generate reports from 13 built-in templates. Select a template, optionally filter by vehicle and date range, and generate. The system shows an in-browser XLSX preview powered by SheetJS, so you can inspect the data before downloading. Downloads are available in XLSX, PDF, and CSV formats.

Contexts & Hooks

The frontend uses five React contexts:

• AuthContext - Manages JWT tokens (SafeStorage), login/logout, user profile, 401 interceptor
• ThemeContext - MUI light/dark theme, persisted to localStorage and user preferences
• UserPreferencesContext - Default vehicle, rows per page, distance unit, currency
• VehicleContext - Global vehicle list with 30-second cache, auto-fetch on mount
• PermissionsContext - Feature-flag and vehicle-assignment based access control; admin bypass

And seven custom hooks:

• useApi - Generic data fetching with loading/error state
• useDistance - Distance unit conversion (miles/km) based on user preference
• useFileDrop - Drag-and-drop file handling
• useNotifications - SSE stream with fallback polling, 90-day dismissed/snoozed cleanup
• useSortPreference - Persisted sort field/order
• usePagination - Pagination state with user-preferred default rows
• useVehicleSelection - Vehicle selection synced with user preferences

Internationalization

The web app supports 21 languages via react-i18next, loading translations from /public/locales/{lang}/translation.json. The languages are: Arabic, Czech, Danish, German, English, Spanish, Finnish, French, Hindi, Italian, Japanese, Korean, Dutch, Norwegian, Pirate 🏴‍☠️, Polish, Portuguese, Russian, Swedish, Turkish, and Chinese.

The language selector is in the user preferences dialog and persists the choice to both localStorage and the server. Currency is auto-mapped from the language/locale choice.

Mobile App Overview

The mobile app is built with React Native 0.73 and TypeScript. It uses React Native Paper (Material Design 3) for the UI, React Navigation for navigation, and Axios for HTTP communication. The app supports 20 languages with bundled JSON translations (no Pirate - that's a web-only Easter egg).

The bottom tab navigation has five tabs: Dashboard, Vehicles, Fuel, Service, and More. The "More" tab provides access to MOT Records, Parts, Consumables, Vehicle Lookup, and Settings. All screens are feature-gated through the PermissionsContext.

Web & Standalone Modes

The defining feature of the mobile app is its dual-mode architecture. On first launch, the ServerConfigScreen presents two choices:

• Connect to Server - Enter your Vehicle Manager server URL. The app tests the connection before proceeding. All data is synced with the backend. The URL is auto-normalised (adds https:// if missing, appends /api if needed).
• Use Standalone - The app runs entirely offline. A LocalApiAdapter provides full CRUD operations backed by AsyncStorage. No server required. Data lives entirely on the device.

In standalone mode, the PermissionsContext grants all permissions, and authentication is handled locally with a simple email/password stored in AsyncStorage.

Dashboard

The mobile dashboard shows a sync status banner (online/offline with pending change count), stat cards (vehicles, fuel, service, mileage), and vehicle notifications with severity colours (danger for expired, warning for ≤30 days, info for ≤60 days). Notifications can be dismissed, cleared, or reset. The dashboard fires Android system notifications for critical items via the @notifee service.

Vehicles

The vehicle list supports search, status filter chips (All/Live/Sold/Scrapped), and a FAB button to add new vehicles. Each vehicle card shows the registration, make/model, mileage (with unit conversion), and an icon based on fuel type. Tapping a vehicle opens the detail screen with a header card, quick actions (Add Fuel / Add Service), cost summary grid, important dates with days-remaining indicators, key info list, and navigation to all record types.

Records & Forms

All record screens follow a consistent pattern: vehicle selector, card-based list with chips for metadata, and form screens for creating/editing. Each form supports receipt photo capture via camera or gallery (using react-native-image-picker). The QuickFuelScreen provides a streamlined one-tap fuel logging experience with auto-populated mileage.

The vehicle form has sections for Basic Info, Status (segmented buttons), Specifications, and Purchase Info. MOT forms include structured advisory and failure entry. The DVSA Vehicle Lookup screen lets you enter a registration and view specs plus full MOT history without creating any records.

Offline & Sync

The offline system is built around two core pieces: SyncContext and useOfflineData.

SyncContext monitors network connectivity via @react-native-community/netinfo. When the device is offline, mutations (create, update, delete) are queued in AsyncStorage. When connectivity returns, the queue is replayed with a 2-second debounce to avoid hammering the server. Each operation is retried up to 5 times. Operations that fail with a 4xx status code are automatically discarded (since the data is permanently invalid). Entity-to-endpoint mapping covers 10 entity types.

useOfflineData provides a cache-first data-fetching hook. On mount, it immediately returns cached data (if available and less than 24 hours old), then fetches fresh data from the network. If the network request fails, the cached data remains visible. This ensures the app always shows something, even in spotty connectivity.

Notifications

The NotificationService uses @notifee/react-native to create Android notification channels (vehicle-reminders and vehicle-urgent). It calculates notifications for live vehicles based on MOT expiry, insurance expiry, road tax expiry, and service due dates. Severity levels are: danger (expired or < 0 days), warning (≤ 30 days), and info (≤ 60 days). The top 5 most critical notifications are fired as system notifications.

Settings

The Settings screen provides comprehensive configuration:

• Sync status - Shows online/offline state with a "Sync Now" button and pending count
• Language selector - 20 languages with flag emojis and native names
• Theme - Light, System, or Dark (segmented buttons)
• Currency - 17 currencies (GBP, USD, EUR, JPY, etc.)
• Distance unit - Miles or kilometres
• Volume unit - Litres or gallons
• Notification toggles - Service, MOT, and insurance reminder switches
• Server info - Connected server URL
• Clear Data & Disconnect - Reset the app to ServerConfigScreen
• Logout

Administration

The admin panel is available to users with the ROLE_ADMIN role. It provides three main capabilities: user management, feature flag control, and vehicle assignment management. All admin operations are enforced server-side - the frontend simply hides the UI for non-admin users, but the API will reject unauthorised requests regardless.

User Management

From the Admin Users page, you can see every registered account along with their vehicle count, role, last login time, and active status. Available actions include:

• Create user - Set up a new account with email, password, name, and role. Useful for onboarding family members or fleet drivers.
• Toggle active - Disable or re-enable a user account. Disabled users cannot log in.
• Force password change - Sets a flag that forces the user to choose a new password on their next login. Use this if you suspect a compromised account.
• Manage roles - Promote a user to ROLE_ADMIN or demote back to ROLE_USER.

Feature Flags

Vehicle Manager has 49 feature flags organised by category. By default, all flags are enabled for everyone. Admins can override flags on a per-user basis - for example, disabling the Reports feature for a specific user, or restricting a user to only view fuel records and nothing else.

The Admin User Details page shows all 49 flags as categorised toggle switches. Changes are saved with a bulk update. You can also reset a user back to the system defaults with one click. Admin users always get all features enabled regardless of overrides.

The FeatureFlagSubscriber enforces these flags on every API request. If a disabled feature is accessed, the server returns 403 Forbidden. Authentication, admin, and lookup routes are exempted from flag checking.

Vehicle Assignments

Vehicle assignments let you share vehicles between users. This is useful in scenarios like:

• A family sharing access to household vehicles
• A fleet manager giving drivers read-only access to their assigned vehicles
• A mechanic needing to add service records to customer vehicles

Each assignment has four granular permissions:

A user can be assigned to the same vehicle only once (enforced by a unique constraint). Assignments are managed through the Admin User Details page or directly via the API.

FAQ & Troubleshooting

General Questions

Docker Issues

API Issues

Mobile App Issues

Import & Export Issues

Vehicle Manager Documentation · GitHub · Open source & free forever