Context
Vehicle appraisal was a chain of human document reading, spreadsheet pricing, and PDF assembly. Banks needed a repeatable valuation with an audit trail, not a desk process that drifted per operator.
System boundary
In scope
- document intake
- OCR
- VIN validation
- market comparables
- valuation
- generated reports
- bank handoff
Out of scope
- physical inspection hardware
- lender underwriting decisions
Architecture
A FastAPI service owns ingestion and valuation. OCR and VIN checks are isolated stages so a document failure does not contaminate pricing. Generated PDFs are artifacts, not the source of truth; the valuation record is.
- Market source
- Ingestion
- OCR
- VIN validation
- Valuation
- Documents
- Banking API
- Source → transform → sink
- Last node is the handoff
- Market source
- Ingestion
- OCR
- VIN validation
- Valuation
- Documents
- Banking API
Counts from the published record. They describe structure, not a measured result.
Where does validation become a report?
inputs
- externalMarket source
pipeline
- serviceIngestion
- processOCR
- processVIN validation
- processValuation
records
- storeDocuments
handoff
- interfaceBanking API
- Market sourceIngestion
- IngestionOCR
- OCRVIN validation
- VIN validationValuation
- ValuationDocuments
- DocumentsBanking API
Critical flows
A document pack arrives
pages are classified
OCR extracts identity fields
VIN is validated against registry rules
comparables are scored
a valuation is written
a report is generated
the bank API receives a signed payload.
Stages
Decisions
Stage the pipeline
Each stage writes an explicit record. Replay and audit are cheaper than a single opaque job.
Keep valuation deterministic
Market adapters are versioned. A valuation cites the data vintage used, not “whatever the API returned today”.
Treat PDFs as exports
The report is a projection of the valuation record. Correcting a number means regenerating the artifact, not editing a file.
When it fails
| Condition | Detection | Response |
|---|---|---|
| Unreadable or mixed-language documents | OCR confidence + required-field presence | Hold for operator review; do not price |
| VIN checksum or registry mismatch | Validation stage reject | Stop pipeline; flag identity exception |
| Stale or missing market comparables | Adapter freshness window | Degrade to manual pricing queue |
| Bank API timeout or schema reject | Handoff status + retry budget | Retry with backoff; keep local valuation intact |
Infrastructure
- Linux hosts
- reverse proxy
- object storage for packs and reports
- worker queue for OCR and generation
- structured logs per stage
Outcome
End-to-end appraisal runs as a recorded pipeline. Banks receive a generated pack tied to a valuation record rather than a one-off PDF.
Current state
In production. New document types and lender schemas are added as stages, not as forks of the valuation core.