PMVIC Uploader

Internal web application for PMVIC vehicle lookup, emission-result validation, synchronous LTMS upload, and transaction tracking.

Getting started

1. Start PostgreSQL:

docker compose up -d postgres

2. Apply migrations with Goose:

go run github.com/pressly/goose/v3/cmd/goose@latest -dir migrations postgres "$DATABASE_URL" up

For a local PostgreSQL install using peer/socket authentication, this project was verified with:

createdb eney
goose -dir migrations postgres "postgres:///eney?host=/var/run/postgresql" up
DATABASE_URL="postgres:///eney?host=/var/run/postgresql" go run ./cmd/web

3. Run the web app:

go run ./cmd/web

4. Open http://localhost:8080.

Development users:

• [email protected] / password123
• [email protected] / password123

Mock lookup values:

• GAS123 or any normal value returns a gasoline SUV.
• DIESEL returns a diesel utility vehicle.
• MOTO, MOTORCYCLE, TRICYCLE, or MOP returns a motorcycle.
• NOTFOUND returns no vehicle.
• TEMPFAIL returns a temporary lookup failure.
• REJECT returns a vehicle but the mock upload is rejected.
• UNKNOWN returns a vehicle but the mock upload outcome is unknown.

LTMS modes

The app defaults to deterministic mock mode for development:

LTMS_MODE=mock go run ./cmd/web

Direct LTO mode is intended only when the web server runs from an LTO-authorized IP and production upload settings are configured:

LTMS_MODE=direct \
PMVIC_CENTER="Configured Center" \
ITP_CODE="configured-itp-code" \
INSPECTOR_USERNAME="configured-inspector" \
go run ./cmd/web

Optional direct-mode settings:

• LTMS_SEARCH_URL, defaulting to the documented get_vehicleinfo endpoint.
• LTMS_UPLOAD_URL, defaulting to the documented store_testresults endpoint.
• LTMS_SEARCH_TIMEOUT, default 60s.
• LTMS_UPLOAD_TIMEOUT, default 600s.

TLS certificate verification remains enabled. Failed or uncertain uploads are not retried automatically.

Uploader Agent

Remote uploader agents wrap the LTMS lookup and upload API from an LTO-authorized site. The web app calls agents synchronously over the private Netbird/WireGuard network and requires a per-agent bearer token.

Run an agent on an authorized site:

UPLOADER_AGENT_TOKEN="change-this-token" \
HTTP_ADDR=":8090" \
go run ./cmd/uploader

Register the agent as an admin or manager in /admin/uploaders with its Netbird HTTP URL, token, priority, and daily allocation. Lower priority numbers are used first. Successful uploads count against allocation; unresolved UNKNOWN uploads hold allocation until reconciled. Vehicle lookup remains direct from the main app by default, but agents expose /agent/v1/lookup and have a lookup-enabled switch for future fallback use.

Development Commands

sqlc generate
gofmt -w cmd internal
go test ./...
go build ./...

Project documentation

• AGENTS.md: Instructions for AI coding agents
• docs/PROJECT.md: Goals, users, scope, and constraints
• docs/ARCHITECTURE.md: Components and data flow
• docs/DECISIONS.md: Architectural decision records
• docs/CURRENT_STATE.md: Continuation notes for future sessions
• docs/TESTING.md: Test commands and strategy
• docs/BACKLOG.md: Deferred and upcoming work

OpenCode subagents

• @review: Read-only review of current changes
• @project-docs: Updates project documentation after implementation