# alysibak/carinfo architecture

> Architecture diagram of the GitHub repository alysibak/carinfo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alysibak/carinfo
- Repository: https://github.com/alysibak/carinfo

## Overview

CarInfo is a specs-first vehicle discovery and comparison platform. Shoppers browse or search vehicles, inspect a vehicle dossier, compare candidates, and explore estimated value and ownership costs; garages, VIN decoding, and account features provide separate supporting journeys. The server exposes vehicle, VIN, account, billing, and statistics APIs. The README documents major capabilities beyond the sampled source, so those are represented at their documented module paths; uncertain internal wiring is omitted.

Main entry points: [`client/src/App.tsx`](https://github.com/alysibak/carinfo/blob/main/client/src/App.tsx) (Web app routes), [`client/src/services/api.ts`](https://github.com/alysibak/carinfo/blob/main/client/src/services/api.ts) (API client), [`server/src/services/car.service.ts`](https://github.com/alysibak/carinfo/blob/main/server/src/services/car.service.ts) (Vehicle catalog service), [`server/src/controllers/billing.controller.ts`](https://github.com/alysibak/carinfo/blob/main/server/src/controllers/billing.controller.ts) (Billing controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Vehicle discovery"]
  node_app["Web app routes<br/>[App.tsx]"]
  node_browse["Browse and search<br/>[Browse.tsx]"]
  node_smartsearch["Smart search<br/>[SmartSearch.tsx]"]
  node_dossier["Vehicle dossier<br/>[CarDetail.tsx]"]
  node_compare["Vehicle comparison<br/>[Compare.tsx]"]
  node_collections["Curated collections<br/>[Collection.tsx]"]
  node_value["Value matrix<br/>[ValueMatrix.tsx]"]
  node_garageui["Garage and sharing<br/>[DreamGarage.tsx]"]
  node_vinui["VIN decoder<br/>[VinDecoder.tsx]"]
end

subgraph group_vehicledata["Vehicle data and analytics"]
  node_carservice["Vehicle catalog service<br/>[car.service.ts]"]
  node_dashboard["Dossier analytics"]
  node_enrichment["Vehicle enrichment"]
  node_normalization["Record normalization<br/>[car-normalize.ts]"]
  node_valuation["Ownership valuation"]
  node_nhtsa["NHTSA service<br/>[nhtsa.service.ts]"]
end

subgraph group_accounts["Garage and accounts"]
  node_accountapi["Account API client<br/>[accountApi.ts]"]
  node_me_routes["Account API routes<br/>[me.routes.ts]"]
  node_mecontroller["Account controller<br/>[me.controller.ts]"]
  node_userstore[("User and garage store<br/>[user-store.ts]")]
  node_auth["Authentication middleware<br/>[auth.ts]"]
  node_billingroutes["Billing routes<br/>[billing.routes.ts]"]
  node_billing["Billing controller"]
end

subgraph group_platform["API and integrations"]
  node_clientapi["API client<br/>[api.ts]"]
  node_carapi["Vehicle API routes<br/>[car.routes.ts]"]
  node_carcontroller["Vehicle controllers<br/>[car.controller.ts]"]
  node_vinroutes["VIN API routes<br/>[vin.routes.ts]"]
  node_vincontroller["VIN controller<br/>[vin.controller.ts]"]
end

node_shopper(("Shopper"))
node_clerk["Clerk"]
node_stripe["Stripe"]
node_epa[("EPA vehicle data")]
node_browser(("Browser session"))

node_shopper -->|"uses"| node_app
node_app -->|"routes to"| node_browse
node_app -->|"routes to"| node_smartsearch
node_app -->|"routes to"| node_dossier
node_app -->|"routes to"| node_compare
node_app -->|"routes to"| node_collections
node_app -->|"routes to"| node_value
node_app -->|"routes to"| node_garageui
node_app -->|"routes to"| node_vinui
node_browse -->|"requests data"| node_clientapi
node_smartsearch -->|"requests data"| node_clientapi
node_dossier -->|"requests data"| node_clientapi
node_compare -->|"requests data"| node_clientapi
node_value -->|"requests data"| node_clientapi
node_vinui -->|"requests decode"| node_clientapi
node_garageui -->|"syncs garage"| node_accountapi
node_clientapi -->|"calls"| node_carapi
node_carapi -->|"dispatches"| node_carcontroller
node_carcontroller -->|"queries"| node_carservice
node_carcontroller -->|"requests analytics"| node_dashboard
node_dashboard -->|"loads vehicles"| node_carservice
node_carservice -->|"enriches records"| node_enrichment
node_carservice -->|"normalizes records"| node_normalization
node_dashboard -->|"calculates ownership"| node_valuation
node_vinui -->|"submits VIN"| node_vinroutes
node_vinroutes -->|"dispatches"| node_vincontroller
node_vincontroller -->|"decodes VIN"| node_nhtsa
node_enrichment -.->|"uses enrichment data"| node_epa
node_accountapi -->|"calls"| node_me_routes
node_me_routes -->|"guards requests"| node_auth
node_me_routes -->|"dispatches"| node_mecontroller
node_mecontroller -->|"reads and writes"| node_userstore
node_mecontroller -->|"loads garage cars"| node_carservice
node_clerk -.->|"provides identity"| node_auth
node_billingroutes -->|"dispatches"| node_billing
node_billing -->|"updates account"| node_userstore
node_billing -.->|"creates sessions"| node_stripe
node_stripe -.->|"sends webhooks"| node_billing
node_browser -->|"renders"| node_app

click node_app "https://github.com/alysibak/carinfo/blob/main/client/src/App.tsx"
click node_browse "https://github.com/alysibak/carinfo/blob/main/client/src/pages/Browse.tsx"
click node_smartsearch "https://github.com/alysibak/carinfo/blob/main/client/src/pages/SmartSearch.tsx"
click node_dossier "https://github.com/alysibak/carinfo/blob/main/client/src/pages/CarDetail.tsx"
click node_compare "https://github.com/alysibak/carinfo/blob/main/client/src/pages/Compare.tsx"
click node_collections "https://github.com/alysibak/carinfo/blob/main/client/src/pages/Collection.tsx"
click node_value "https://github.com/alysibak/carinfo/blob/main/client/src/pages/ValueMatrix.tsx"
click node_garageui "https://github.com/alysibak/carinfo/blob/main/client/src/pages/DreamGarage.tsx"
click node_vinui "https://github.com/alysibak/carinfo/blob/main/client/src/pages/VinDecoder.tsx"
click node_clientapi "https://github.com/alysibak/carinfo/blob/main/client/src/services/api.ts"
click node_accountapi "https://github.com/alysibak/carinfo/blob/main/client/src/services/accountApi.ts"
click node_carapi "https://github.com/alysibak/carinfo/blob/main/server/src/routes/car.routes.ts"
click node_carcontroller "https://github.com/alysibak/carinfo/blob/main/server/src/controllers/car.controller.ts"
click node_carservice "https://github.com/alysibak/carinfo/blob/main/server/src/services/car.service.ts"
click node_dashboard "https://github.com/alysibak/carinfo/blob/main/server/src/services/dashboard.service.ts"
click node_enrichment "https://github.com/alysibak/carinfo/blob/main/server/src/services/content-enrichment.ts"
click node_normalization "https://github.com/alysibak/carinfo/blob/main/server/src/utils/car-normalize.ts"
click node_valuation "https://github.com/alysibak/carinfo/blob/main/server/src/utils/vehicle-valuation.ts"
click node_vinroutes "https://github.com/alysibak/carinfo/blob/main/server/src/routes/vin.routes.ts"
click node_vincontroller "https://github.com/alysibak/carinfo/blob/main/server/src/controllers/vin.controller.ts"
click node_nhtsa "https://github.com/alysibak/carinfo/blob/main/server/src/services/nhtsa.service.ts"
click node_me_routes "https://github.com/alysibak/carinfo/blob/main/server/src/routes/me.routes.ts"
click node_mecontroller "https://github.com/alysibak/carinfo/blob/main/server/src/controllers/me.controller.ts"
click node_userstore "https://github.com/alysibak/carinfo/blob/main/server/src/db/user-store.ts"
click node_auth "https://github.com/alysibak/carinfo/blob/main/server/src/middleware/auth.ts"
click node_billingroutes "https://github.com/alysibak/carinfo/blob/main/server/src/routes/billing.routes.ts"
click node_billing "https://github.com/alysibak/carinfo/blob/main/server/src/controllers/billing.controller.ts"

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_app,node_browse,node_smartsearch,node_dossier,node_compare,node_collections,node_value,node_garageui,node_vinui,node_browser toneBlue
class node_carservice,node_dashboard,node_enrichment,node_normalization,node_valuation,node_nhtsa,node_epa toneAmber
class node_accountapi,node_me_routes,node_mecontroller,node_userstore,node_auth,node_billingroutes,node_billing toneMint
class node_clientapi,node_carapi,node_carcontroller,node_vinroutes,node_vincontroller toneRose
class node_shopper,node_clerk,node_stripe toneIndigo
```

## Components

### Vehicle discovery

- [Web app routes](https://github.com/alysibak/carinfo/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Browse and search](https://github.com/alysibak/carinfo/blob/main/client/src/pages/Browse.tsx): `client/src/pages/Browse.tsx`
- [Smart search](https://github.com/alysibak/carinfo/blob/main/client/src/pages/SmartSearch.tsx): `client/src/pages/SmartSearch.tsx`
- [Vehicle dossier](https://github.com/alysibak/carinfo/blob/main/client/src/pages/CarDetail.tsx): `client/src/pages/CarDetail.tsx`
- [Vehicle comparison](https://github.com/alysibak/carinfo/blob/main/client/src/pages/Compare.tsx): `client/src/pages/Compare.tsx`
- [Curated collections](https://github.com/alysibak/carinfo/blob/main/client/src/pages/Collection.tsx): `client/src/pages/Collection.tsx`
- [Value matrix](https://github.com/alysibak/carinfo/blob/main/client/src/pages/ValueMatrix.tsx): `client/src/pages/ValueMatrix.tsx`
- [Garage and sharing](https://github.com/alysibak/carinfo/blob/main/client/src/pages/DreamGarage.tsx): `client/src/pages/DreamGarage.tsx`
- [VIN decoder](https://github.com/alysibak/carinfo/blob/main/client/src/pages/VinDecoder.tsx): `client/src/pages/VinDecoder.tsx`

### Vehicle data and analytics

- [Vehicle catalog service](https://github.com/alysibak/carinfo/blob/main/server/src/services/car.service.ts): `server/src/services/car.service.ts`
- [Dossier analytics](https://github.com/alysibak/carinfo/blob/main/server/src/services/dashboard.service.ts): `server/src/services/dashboard.service.ts`
- [Vehicle enrichment](https://github.com/alysibak/carinfo/blob/main/server/src/services/content-enrichment.ts): `server/src/services/content-enrichment.ts`
- [Record normalization](https://github.com/alysibak/carinfo/blob/main/server/src/utils/car-normalize.ts): `server/src/utils/car-normalize.ts`
- [Ownership valuation](https://github.com/alysibak/carinfo/blob/main/server/src/utils/vehicle-valuation.ts): `server/src/utils/vehicle-valuation.ts`
- [NHTSA service](https://github.com/alysibak/carinfo/blob/main/server/src/services/nhtsa.service.ts): `server/src/services/nhtsa.service.ts`

### Garage and accounts

- [Account API client](https://github.com/alysibak/carinfo/blob/main/client/src/services/accountApi.ts): `client/src/services/accountApi.ts`
- [Account API routes](https://github.com/alysibak/carinfo/blob/main/server/src/routes/me.routes.ts): `server/src/routes/me.routes.ts`
- [Account controller](https://github.com/alysibak/carinfo/blob/main/server/src/controllers/me.controller.ts): `server/src/controllers/me.controller.ts`
- [User and garage store](https://github.com/alysibak/carinfo/blob/main/server/src/db/user-store.ts): `server/src/db/user-store.ts`
- [Authentication middleware](https://github.com/alysibak/carinfo/blob/main/server/src/middleware/auth.ts): `server/src/middleware/auth.ts`
- [Billing routes](https://github.com/alysibak/carinfo/blob/main/server/src/routes/billing.routes.ts): `server/src/routes/billing.routes.ts`
- [Billing controller](https://github.com/alysibak/carinfo/blob/main/server/src/controllers/billing.controller.ts): `server/src/controllers/billing.controller.ts`

### API and integrations

- [API client](https://github.com/alysibak/carinfo/blob/main/client/src/services/api.ts): `client/src/services/api.ts`
- [Vehicle API routes](https://github.com/alysibak/carinfo/blob/main/server/src/routes/car.routes.ts): `server/src/routes/car.routes.ts`
- [Vehicle controllers](https://github.com/alysibak/carinfo/blob/main/server/src/controllers/car.controller.ts): `server/src/controllers/car.controller.ts`
- [VIN API routes](https://github.com/alysibak/carinfo/blob/main/server/src/routes/vin.routes.ts): `server/src/routes/vin.routes.ts`
- [VIN controller](https://github.com/alysibak/carinfo/blob/main/server/src/controllers/vin.controller.ts): `server/src/controllers/vin.controller.ts`

### Other components

- **Shopper**
- **Clerk**
- **Stripe**
- **EPA vehicle data**
- **Browser session**

## Connections

- Shopper → Web app routes: uses
- Web app routes → Browse and search: routes to
- Web app routes → Smart search: routes to
- Web app routes → Vehicle dossier: routes to
- Web app routes → Vehicle comparison: routes to
- Web app routes → Curated collections: routes to
- Web app routes → Value matrix: routes to
- Web app routes → Garage and sharing: routes to
- Web app routes → VIN decoder: routes to
- Browse and search → API client: requests data
- Smart search → API client: requests data
- Vehicle dossier → API client: requests data
- Vehicle comparison → API client: requests data
- Value matrix → API client: requests data
- VIN decoder → API client: requests decode
- Garage and sharing → Account API client: syncs garage
- API client → Vehicle API routes: calls
- Vehicle API routes → Vehicle controllers: dispatches
- Vehicle controllers → Vehicle catalog service: queries
- Vehicle controllers → Dossier analytics: requests analytics
- Dossier analytics → Vehicle catalog service: loads vehicles
- Vehicle catalog service → Vehicle enrichment: enriches records
- Vehicle catalog service → Record normalization: normalizes records
- Dossier analytics → Ownership valuation: calculates ownership
- VIN decoder → VIN API routes: submits VIN
- VIN API routes → VIN controller: dispatches
- VIN controller → NHTSA service: decodes VIN
- Vehicle enrichment → EPA vehicle data: uses enrichment data
- Account API client → Account API routes: calls
- Account API routes → Authentication middleware: guards requests
- Account API routes → Account controller: dispatches
- Account controller → User and garage store: reads and writes
- Account controller → Vehicle catalog service: loads garage cars
- Clerk → Authentication middleware: provides identity
- Billing routes → Billing controller: dispatches
- Billing controller → User and garage store: updates account
- Billing controller → Stripe: creates sessions
- Stripe → Billing controller: sends webhooks
- Browser session → Web app routes: renders