# nirholas/carsearch architecture

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

- Interactive diagram: https://gitdiagram.com/nirholas/carsearch
- Repository: https://github.com/nirholas/carsearch

## Overview

carsearch searches vehicle listings across marketplaces, dealer inventories, auctions, and salvage sources, then turns them into deduplicated, normalized, searchable market data. The primary workflow is a shopper query through the API or web UI, source crawling, listing validation and enrichment, storage, and ranked results; plain-English queries can be parsed before search. Separate capabilities include VIN and recall information, sold-price comparisons, market trends, valuation, and source-status reporting. The README documents these capabilities; sampled excerpts confirm key pipeline and parser calls, but do not expose every route or enrichment connection.

Main entry points: [`src/api/server.ts`](https://github.com/nirholas/carsearch/blob/main/src/api/server.ts) (JSON API), [`src/pipeline.ts`](https://github.com/nirholas/carsearch/blob/main/src/pipeline.ts) (Crawl pipeline), [`src/store/store.ts`](https://github.com/nirholas/carsearch/blob/main/src/store/store.ts) (Store interface), [`src/store/open.ts`](https://github.com/nirholas/carsearch/blob/main/src/store/open.ts) (Store selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Listing collection"]
  node_pipeline["Crawl pipeline<br/>[pipeline.ts]"]
  node_source_adapters["Source adapters<br/>[index.ts]"]
  node_source_registry["Source registry<br/>[registry.ts]"]
  node_transports["Fetch and browser<br/>[fetcher.ts]"]
end

subgraph group_processing["Listing processing"]
  node_normalization["Normalize and validate<br/>[normalize.ts]"]
  node_vin_enrichment["VIN enrichment<br/>[vpic.ts]"]
  node_recalls["Recall lookup<br/>[recalls.ts]"]
  node_dedupe["VIN deduplication<br/>[dedupe.ts]"]
  node_ranking["Result ranking<br/>[rank.ts]"]
  node_facets["Facet filtering<br/>[facets.ts]"]
end

subgraph group_data_insights["Data and insights"]
  node_store_api["Store interface<br/>[store.ts]"]
  node_store_open["Store selection<br/>[open.ts]"]
  node_postgres[("Postgres store<br/>[postgres.ts]")]
  node_sqlite[("SQLite adapter<br/>[sqlite-adapter.ts]")]
  node_market["Market analytics<br/>[market.ts]"]
end

subgraph group_experience["Search experience"]
  node_cli["CLI<br/>[cli.ts]"]
  node_web_ui["Web UI<br/>[app.js]"]
  node_api["JSON API<br/>[server.ts]"]
  node_nl["Query interpretation<br/>[index.ts]"]
  node_pattern_parser["Pattern parser<br/>[parse.ts]"]
  node_llm_parser["Claude parser<br/>[llm.ts]"]
end

node_shopper(("Shopper"))
node_cli_user(("CLI user"))
node_external_sites["Listing sites"]
node_anthropic["Anthropic Claude"]
node_nhtsa["NHTSA"]
node_database[("Database")]

node_shopper -->|"searches"| node_web_ui
node_cli_user -->|"queries"| node_cli
node_web_ui -->|"requests"| node_api
node_api -->|"interprets ask"| node_nl
node_nl -->|"parses locally"| node_pattern_parser
node_nl -.->|"escalates query"| node_llm_parser
node_llm_parser -.->|"requests parse"| node_anthropic
node_api -->|"starts crawl"| node_pipeline
node_cli -->|"starts crawl"| node_pipeline
node_pipeline -->|"dispatches crawl"| node_source_adapters
node_source_adapters -->|"fetches pages"| node_transports
node_transports -->|"requests listings"| node_external_sites
node_pipeline -->|"enriches listings"| node_vin_enrichment
node_vin_enrichment -->|"decodes VINs"| node_nhtsa
node_api -->|"looks up recalls"| node_recalls
node_recalls -->|"requests campaigns"| node_nhtsa
node_pipeline -->|"validates listings"| node_normalization
node_pipeline -->|"groups listings"| node_dedupe
node_pipeline -->|"writes listings"| node_store_api
node_api -->|"searches listings"| node_store_api
node_store_api -->|"selects backend"| node_store_open
node_store_open -->|"opens Postgres"| node_postgres
node_store_open -->|"opens SQLite"| node_sqlite
node_postgres -->|"reads and writes"| node_database
node_sqlite -->|"reads and writes"| node_database
node_api -->|"ranks results"| node_ranking
node_api -->|"parses filters"| node_facets
node_api -->|"builds market report"| node_market
node_market -->|"uses listing data"| node_store_api
node_api -->|"reports source status"| node_source_registry

click node_cli "https://github.com/nirholas/carsearch/blob/main/src/cli.ts"
click node_web_ui "https://github.com/nirholas/carsearch/blob/main/web/app.js"
click node_api "https://github.com/nirholas/carsearch/blob/main/src/api/server.ts"
click node_nl "https://github.com/nirholas/carsearch/blob/main/src/nl/index.ts"
click node_pattern_parser "https://github.com/nirholas/carsearch/blob/main/src/nl/parse.ts"
click node_llm_parser "https://github.com/nirholas/carsearch/blob/main/src/nl/llm.ts"
click node_pipeline "https://github.com/nirholas/carsearch/blob/main/src/pipeline.ts"
click node_source_adapters "https://github.com/nirholas/carsearch/blob/main/src/sources/index.ts"
click node_source_registry "https://github.com/nirholas/carsearch/blob/main/src/sources/registry.ts"
click node_transports "https://github.com/nirholas/carsearch/blob/main/src/transport/fetcher.ts"
click node_normalization "https://github.com/nirholas/carsearch/blob/main/src/core/normalize.ts"
click node_vin_enrichment "https://github.com/nirholas/carsearch/blob/main/src/enrich/vpic.ts"
click node_recalls "https://github.com/nirholas/carsearch/blob/main/src/enrich/recalls.ts"
click node_dedupe "https://github.com/nirholas/carsearch/blob/main/src/core/dedupe.ts"
click node_store_api "https://github.com/nirholas/carsearch/blob/main/src/store/store.ts"
click node_store_open "https://github.com/nirholas/carsearch/blob/main/src/store/open.ts"
click node_postgres "https://github.com/nirholas/carsearch/blob/main/src/store/postgres.ts"
click node_sqlite "https://github.com/nirholas/carsearch/blob/main/src/store/sqlite-adapter.ts"
click node_ranking "https://github.com/nirholas/carsearch/blob/main/src/core/rank.ts"
click node_facets "https://github.com/nirholas/carsearch/blob/main/src/core/facets.ts"
click node_market "https://github.com/nirholas/carsearch/blob/main/src/analytics/market.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_pipeline,node_source_adapters,node_source_registry,node_transports,node_cli_user toneBlue
class node_normalization,node_vin_enrichment,node_recalls,node_dedupe,node_ranking,node_facets,node_database toneAmber
class node_store_api,node_store_open,node_postgres,node_sqlite,node_market toneMint
class node_cli,node_web_ui,node_api,node_nl,node_pattern_parser,node_llm_parser toneRose
class node_shopper,node_external_sites,node_anthropic,node_nhtsa toneIndigo
```

## Components

### Listing collection

- [Crawl pipeline](https://github.com/nirholas/carsearch/blob/main/src/pipeline.ts): `src/pipeline.ts`
- [Source adapters](https://github.com/nirholas/carsearch/blob/main/src/sources/index.ts): `src/sources/index.ts`
- [Source registry](https://github.com/nirholas/carsearch/blob/main/src/sources/registry.ts): `src/sources/registry.ts`
- [Fetch and browser](https://github.com/nirholas/carsearch/blob/main/src/transport/fetcher.ts): `src/transport/fetcher.ts`

### Listing processing

- [Normalize and validate](https://github.com/nirholas/carsearch/blob/main/src/core/normalize.ts): `src/core/normalize.ts`
- [VIN enrichment](https://github.com/nirholas/carsearch/blob/main/src/enrich/vpic.ts): `src/enrich/vpic.ts`
- [Recall lookup](https://github.com/nirholas/carsearch/blob/main/src/enrich/recalls.ts): `src/enrich/recalls.ts`
- [VIN deduplication](https://github.com/nirholas/carsearch/blob/main/src/core/dedupe.ts): `src/core/dedupe.ts`
- [Result ranking](https://github.com/nirholas/carsearch/blob/main/src/core/rank.ts): `src/core/rank.ts`
- [Facet filtering](https://github.com/nirholas/carsearch/blob/main/src/core/facets.ts): `src/core/facets.ts`

### Data and insights

- [Store interface](https://github.com/nirholas/carsearch/blob/main/src/store/store.ts): `src/store/store.ts`
- [Store selection](https://github.com/nirholas/carsearch/blob/main/src/store/open.ts): `src/store/open.ts`
- [Postgres store](https://github.com/nirholas/carsearch/blob/main/src/store/postgres.ts): `src/store/postgres.ts`
- [SQLite adapter](https://github.com/nirholas/carsearch/blob/main/src/store/sqlite-adapter.ts): `src/store/sqlite-adapter.ts`
- [Market analytics](https://github.com/nirholas/carsearch/blob/main/src/analytics/market.ts): `src/analytics/market.ts`

### Search experience

- [CLI](https://github.com/nirholas/carsearch/blob/main/src/cli.ts): `src/cli.ts`
- [Web UI](https://github.com/nirholas/carsearch/blob/main/web/app.js): `web/app.js`
- [JSON API](https://github.com/nirholas/carsearch/blob/main/src/api/server.ts): `src/api/server.ts`
- [Query interpretation](https://github.com/nirholas/carsearch/blob/main/src/nl/index.ts): `src/nl/index.ts`
- [Pattern parser](https://github.com/nirholas/carsearch/blob/main/src/nl/parse.ts): `src/nl/parse.ts`
- [Claude parser](https://github.com/nirholas/carsearch/blob/main/src/nl/llm.ts): `src/nl/llm.ts`

### Other components

- **Shopper**
- **CLI user**
- **Listing sites**
- **Anthropic Claude**
- **NHTSA**
- **Database**

## Connections

- Shopper → Web UI: searches
- CLI user → CLI: queries
- Web UI → JSON API: requests
- JSON API → Query interpretation: interprets ask
- Query interpretation → Pattern parser: parses locally
- Query interpretation → Claude parser: escalates query
- Claude parser → Anthropic Claude: requests parse
- JSON API → Crawl pipeline: starts crawl
- CLI → Crawl pipeline: starts crawl
- Crawl pipeline → Source adapters: dispatches crawl
- Source adapters → Fetch and browser: fetches pages
- Fetch and browser → Listing sites: requests listings
- Crawl pipeline → VIN enrichment: enriches listings
- VIN enrichment → NHTSA: decodes VINs
- JSON API → Recall lookup: looks up recalls
- Recall lookup → NHTSA: requests campaigns
- Crawl pipeline → Normalize and validate: validates listings
- Crawl pipeline → VIN deduplication: groups listings
- Crawl pipeline → Store interface: writes listings
- JSON API → Store interface: searches listings
- Store interface → Store selection: selects backend
- Store selection → Postgres store: opens Postgres
- Store selection → SQLite adapter: opens SQLite
- Postgres store → Database: reads and writes
- SQLite adapter → Database: reads and writes
- JSON API → Result ranking: ranks results
- JSON API → Facet filtering: parses filters
- JSON API → Market analytics: builds market report
- Market analytics → Store interface: uses listing data
- JSON API → Source registry: reports source status