# biegalski-llc/nhtsa-vehicle-api architecture

> Architecture diagram of the GitHub repository biegalski-llc/nhtsa-vehicle-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/biegalski-llc/nhtsa-vehicle-api
- Repository: https://github.com/biegalski-llc/nhtsa-vehicle-api

## Overview

1. **What this repository is**
   - This is a **PHP Composer library**, not a standalone app.
   - Its job is to provide a small, typed-ish facade over the **NHTSA Vehicle API** for:
     - VIN decoding
     - listing vehicle years
     - listing makes
     - listing models by make/year

2. **Primary public entrypoint**
   - The main consumer-facing class is `src/VehicleApi.php`.
   - The README shows the intended usage pattern: instantiate `VehicleApi`, then call methods like `listYears()`, `listAllMakes()`, `listModelsByMake()`, and `decodeVin()`.
   - This class is the API boundary for package users; the rest of the code is internal implementation detail.

3. **Internal service split**
   - The implementation is organized into small service classes under `src/Services`:
     - `Listing/Years.php`
     - `Listing/Makes.php`
     - `Listing/Models.php`
     - `Decode/Vin.php`
   - `src/Services/Service.php` is the shared base layer, likely holding common setup and/or shared helpers for the concrete services.

4. **Main data-flow pattern**
   - Most methods follow the same flow:
     1. accept a simple input such as a year, make ID, VIN, or a list of IDs
     2. call the NHTSA API or read local configuration data
     3. normalize and sort the output
     4. return an array of vehicle records
   - The README explicitly says all methods return an **alphabetized array of data**.

5. **External integration boundary**
   - The package integrates with the **NHTSA Vehicles API** over HTTP.
   - `src/Traits/HttpRequestTrait.php` strongly suggests HTTP request logic is centralized there instead of duplicated across services.
   - `config/nhtsa.php` likely contains API base URL and endpoint configuration, keeping the remote service boundary isolated from the business logic.

6. **Listing years: mostly local generation**
   - `listYears()` is different from the other calls: it does not need remote lookup for the year values themselves.
   - The README indicates it generates a range from a provided starting year up to two years beyond the current year.
   - That means the years subsystem is mostly a **local data generator** with no external dependency.

7. **Listing makes: live vs curated**
   - `Makes.php` supports multiple source strategies:
     - `listAllMakes()` pulls the full live make list from NHTSA
     - `listPreloadedMakes()` reads from curated local config lists
     - `listAcceptedListMakes([...])` filters based on caller-supplied NHTSA make IDs
   - The curated lists live under `config/VehicleMakes/`, with separate files for:
     - default mixed list
     - car/truck list
     - motorcycle/scooter list
   - This is a key architectural boundary: **remote completeness vs local curated subsets**.

8. **Listing models: dependent on make and year**
   - `Models.php` builds model results from NHTSA data using upstream identifiers:
     - by make ID only
     - by make ID plus year
   - The returned records include both make and model metadata, so this layer is responsible for joining/structuring the API response into a consumer-friendly shape.

9. **VIN decoding**
   - `src/Services/Decode/Vin.php` handles VIN lookups.
   - This is the most direct external-call use case: the caller provides a VIN string, and the service returns decoded vehicle details from NHTSA.
   - Architecturally, it is separate from the listing flows, but likely reuses the same request and normalization infrastructure.

10. **Shared traits**
   - `DataSortTrait.php` likely centralizes result ordering and/or array shaping so every service returns consistently sorted output.
   - `HttpRequestTrait.php` centralizes HTTP behavior, reducing duplication and making the NHTSA integration consistent across services.
   - These traits are part of the package’s internal plumbing, not the public API.

11. **Static configuration as a data source**
   - The repository includes several config/data files rather than a database or cache layer.
   - The preloaded make lists are stored as PHP arrays, which means the package can work offline for those curated make subsets.
   - There is no persistence layer, queue, or background worker; all work appears to be request/response and in-memory transformation.

12. **Testing and delivery**
   - Tests exist for the core listing behaviors: `MakesTest`, `ModelsTest`, and `YearsTest`.
   - The presence of `.travis.yml` indicates CI automation, and `phpunit.xml` confirms PHPUnit-based testing.
   - This repository is therefore a small, test-driven library with CI, a single public facade, internal services, and a clear external dependency on the NHTSA API.

Main entry points: [`src/Services/Listing/Makes.php`](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Listing/Makes.php) (Makes), [`src/Services/Listing/Models.php`](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Listing/Models.php) (Models), [`src/Services/Decode/Vin.php`](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Decode/Vin.php) (VIN Decode), [`src/VehicleApi.php`](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/VehicleApi.php) (Vehicle API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_vehicle_api["Vehicle API<br/>facade<br/>[VehicleApi.php]"]
end

subgraph group_services["Services"]
  node_service_base["Service Base<br/>shared base<br/>[Service.php]"]
  node_years_service["Years<br/>listing service<br/>[Years.php]"]
  node_makes_service["Makes<br/>listing service<br/>[Makes.php]"]
  node_models_service["Models<br/>listing service<br/>[Models.php]"]
  node_vin_service["VIN Decode<br/>decode service<br/>[Vin.php]"]
  node_http_trait["HTTP Request<br/>trait"]
  node_sort_trait["Data Sort<br/>trait<br/>[DataSortTrait.php]"]
end

subgraph group_config["Config Data"]
  node_nhtsa_config["NHTSA Config<br/>api config<br/>[nhtsa.php]"]
  node_preloaded_makes["Make List<br/>curated data"]
  node_preloaded_cars["Car List<br/>curated data"]
  node_preloaded_motos["Moto List<br/>curated data"]
end

subgraph group_external["External API"]
  node_nhtsa_api[("NHTSA API<br/>external service")]
end

node_vehicle_api -->|"listYears"| node_years_service
node_vehicle_api -->|"listMakes"| node_makes_service
node_vehicle_api -->|"listModels"| node_models_service
node_vehicle_api -->|"decodeVin"| node_vin_service
node_years_service -->|"sort"| node_sort_trait
node_makes_service -->|"extends"| node_service_base
node_makes_service -->|"http"| node_http_trait
node_makes_service -->|"sort"| node_sort_trait
node_makes_service -->|"curated"| node_preloaded_makes
node_makes_service -->|"curated"| node_preloaded_cars
node_makes_service -->|"curated"| node_preloaded_motos
node_makes_service -->|"live makes"| node_nhtsa_api
node_models_service -->|"extends"| node_service_base
node_models_service -->|"http"| node_http_trait
node_models_service -->|"sort"| node_sort_trait
node_models_service -->|"live models"| node_nhtsa_api
node_vin_service -->|"extends"| node_service_base
node_vin_service -->|"http"| node_http_trait
node_vin_service -->|"sort"| node_sort_trait
node_vin_service -->|"decode"| node_nhtsa_api
node_http_trait -->|"config"| node_nhtsa_config

click node_vehicle_api "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/VehicleApi.php"
click node_service_base "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Service.php"
click node_years_service "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Listing/Years.php"
click node_makes_service "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Listing/Makes.php"
click node_models_service "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Listing/Models.php"
click node_vin_service "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Decode/Vin.php"
click node_http_trait "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Traits/HttpRequestTrait.php"
click node_sort_trait "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Traits/DataSortTrait.php"
click node_nhtsa_config "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/config/nhtsa.php"
click node_preloaded_makes "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/config/VehicleMakes/preloadedMakeList.php"
click node_preloaded_cars "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/config/VehicleMakes/preloadedCarMakeList.php"
click node_preloaded_motos "https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/config/VehicleMakes/preloadedMotoMakeList.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vehicle_api toneBlue
class node_service_base,node_years_service,node_makes_service,node_models_service,node_vin_service,node_http_trait,node_sort_trait toneAmber
class node_nhtsa_config,node_preloaded_makes,node_preloaded_cars,node_preloaded_motos toneMint
class node_nhtsa_api toneRose
```

## Components

### Public API

Consumer-facing entrypoint for the package.

- [Vehicle API](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/VehicleApi.php): facade · Main consumer entrypoint for listing and decoding methods. · `src/VehicleApi.php`

### Services

Internal request and normalization logic for vehicle data.

- [Service Base](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Service.php): shared base · Common service layer used by concrete vehicle operations. · `src/Services/Service.php`
- [Years](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Listing/Years.php): listing service · Generates year ranges and returns sorted year lists. · `src/Services/Listing/Years.php`
- [Makes](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Listing/Makes.php): listing service · Lists all makes, curated makes, or accepted subsets. · `src/Services/Listing/Makes.php`
- [Models](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Listing/Models.php): listing service · Builds model records from make and year inputs. · `src/Services/Listing/Models.php`
- [VIN Decode](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Services/Decode/Vin.php): decode service · Decodes a VIN into vehicle details. · `src/Services/Decode/Vin.php`
- [HTTP Request](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Traits/HttpRequestTrait.php): trait · Centralized HTTP request behavior for NHTSA calls. · `src/Traits/HttpRequestTrait.php`
- [Data Sort](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/src/Traits/DataSortTrait.php): trait · Shared sorting and output normalization helpers. · `src/Traits/DataSortTrait.php`

### Config Data

Static configuration and curated make lists.

- [NHTSA Config](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/config/nhtsa.php): api config · Remote API base and endpoint configuration. · `config/nhtsa.php`
- [Make List](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/config/VehicleMakes/preloadedMakeList.php): curated data · Default curated make list for offline or narrowed lookup. · `config/VehicleMakes/preloadedMakeList.php`
- [Car List](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/config/VehicleMakes/preloadedCarMakeList.php): curated data · Curated car and truck make list. · `config/VehicleMakes/preloadedCarMakeList.php`
- [Moto List](https://github.com/biegalski-llc/nhtsa-vehicle-api/blob/master/config/VehicleMakes/preloadedMotoMakeList.php): curated data · Curated motorcycle and scooter make list. · `config/VehicleMakes/preloadedMotoMakeList.php`

### External API

Remote NHTSA Vehicle API boundary.

- **NHTSA API**: external service · Remote vehicle data source used for makes, models, and VIN decode.

## Connections

- Vehicle API → Years: listYears · Public facade delegates year listing to the years service.
- Vehicle API → Makes: listMakes · Public facade delegates make listing to the makes service.
- Vehicle API → Models: listModels · Public facade delegates model listing to the models service.
- Vehicle API → VIN Decode: decodeVin · Public facade delegates VIN decoding to the decode service.
- Years → Data Sort: sort · Years output is normalized and alphabetized.
- Makes → Service Base: extends · Make listing builds on the shared service base.
- Makes → HTTP Request: http · Live make listing uses shared request handling.
- Makes → Data Sort: sort · Make results are normalized and alphabetized.
- Makes → Make List: curated · Default curated makes are loaded from static config.
- Makes → Car List: curated · Car and truck curated makes are loaded from static config.
- Makes → Moto List: curated · Motorcycle and scooter curated makes are loaded from static config.
- Makes → NHTSA API: live makes · Full make lists are retrieved from the NHTSA API.
- Models → Service Base: extends · Model listing builds on the shared service base.
- Models → HTTP Request: http · Model lookup uses shared request handling.
- Models → Data Sort: sort · Model results are normalized and alphabetized.
- Models → NHTSA API: live models · Model lists are retrieved from the NHTSA API.
- VIN Decode → Service Base: extends · VIN decoding builds on the shared service base.
- VIN Decode → HTTP Request: http · VIN lookup uses shared request handling.
- VIN Decode → Data Sort: sort · Decoded output is normalized and alphabetized.
- VIN Decode → NHTSA API: decode · VIN decode requests are sent to the NHTSA API.
- HTTP Request → NHTSA Config: config · HTTP behavior reads base and endpoint configuration.
