Collision VIN Decoder API

A deployable FastAPI service for Precision Auto Body's VIN decoder workflow. It demonstrates typed AI outputs, deterministic fallback behavior, SQLite audit persistence, production-style JSON logging, Docker packaging, CI, Railway deployment notes, and synthetic public demo data.

This service is an assistive workflow tool. It does not make final safety, repair, insurance, financial, or outbound communication decisions.

Portfolio Status

• Local validation: complete
• GitHub remote: published at https://github.com/dkdejesus/collision-vin-decoder-api
• Railway deployment: pending dashboard deployment
• Demo data policy: synthetic only

Live demo

Add Railway URLs after deployment:

• API health: https://<railway-domain>/health
• Swagger docs: https://<railway-domain>/docs

Case study

Business problem

Vehicle identity drives estimate, parts, OEM procedure, and calibration workflows, so VIN data must be normalized early.

Workflow context

This service validates VIN-like input and returns a synthetic normalized vehicle profile for demo use. The public version is synthetic-first: every fixture is made-up and safe to publish.

Architecture

flowchart LR
    Client["Client / workflow tool"] --> API["FastAPI service"]
    API --> Validation["Pydantic validation"]
    Validation --> Model["OpenAI structured output or deterministic fallback"]
    Model --> Assessment["Typed VinDecodeAssessment"]
    Assessment --> Store["SQLite audit database"]
    Store --> Response["JSON response and retrievable record"]

Loading

What it returns

• normalized_vin
• year
• make
• model
• trim_placeholder
• validation_warnings
• confidence

Measurable impact hypothesis

A production version could reduce manual review time for this workflow by turning scattered notes into structured handoffs, missing-item checks, and human-approved next actions.

API endpoints

• POST /v1/vin-decodes creates a workflow assessment.
• GET /v1/vin-decodes lists recent assessment summaries.
• GET /v1/vin-decodes/{request_id} retrieves a stored assessment.
• GET /health supports deployment health checks.

Example request

curl -X POST http://localhost:8000/v1/vin-decodes \
  -H 'Content-Type: application/json' \
  -d @sample_data/sample_request.json

Example response

{
  "request_id": "demo-request-001",
  "assessment": {
    "normalized_vin": "4T3RWRFV0MU000000",
    "year": "2021",
    "make": "Toyota",
    "model": "RAV4",
    "trim_placeholder": "To Validate",
    "validation_warnings": [
      "Synthetic demo VIN; confirm with an authoritative decoder before production use"
    ],
    "confidence": 0.68
  },
  "model": "rule-based-fallback"
}

Run locally

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

Open Swagger UI at http://localhost:8000/docs.

Run with Docker

docker build -t collision-vin-decoder-api .
docker run --rm -p 8000:8000 --env-file .env collision-vin-decoder-api

Deploy on Railway

1. Push this repository to GitHub.
2. Create a Railway project from the GitHub repository.
3. Railway will detect the Dockerfile and use railway.toml for the /health deployment check.
4. Add service variables:

APP_ENV=production
LOG_LEVEL=INFO
OPENAI_API_KEY=<your key>
OPENAI_MODEL=gpt-5-mini
REQUEST_TIMEOUT_SECONDS=30
DATABASE_PATH=/data/vin_decode.db

5. Add a volume mounted at /data so saved records survive redeploys.
6. Generate a public domain from the service Networking settings.

Test

pytest -q
ruff check .
ruff format --check .
docker build -t collision-vin-decoder-api:ci .

Production considerations

• Keep customer, VIN, claim, phone, email, insurer, and photo data out of public demos.
• Put the container behind HTTPS and an authenticated gateway.
• Add rate limiting before public production traffic.
• Human review remains required for safety, repair, insurance, financial, and outbound communication decisions.
• Validate CCC ONE, Gmail, Google Calendar, Google Drive, QuickBooks, vendor, and carrier access before live integrations.

Portfolio talking points

• Designed a typed AI workflow API around a real collision repair operating process.
• Used synthetic fixtures so the project is public-safe.
• Implemented deterministic fallback behavior so demos and tests work without an API key.
• Added request IDs, JSON logs, persistence, health checks, validation, tests, Docker, and Railway deployment notes.