Messenger Vehicle Automation

Phase 1 implementation for vehicle document OCR and field extraction.

Current Scope

• Upload a local OR/CR or vehicle document.
• Run Azure Document Intelligence prebuilt-read OCR.
• Extract vehicle fields with rule-based matching (new/old CR and OR), with an optional OpenAI-compatible LLM fallback for weak OCR/rule results.
• Merge OR + CR attachments from one message into a single vehicle record.
• Save document metadata, OCR JSON, and extracted vehicle data to SQLite.
• List recent extracted vehicle records.
• Correct and approve extracted vehicle records through an API endpoint.
• Serve a public privacy policy at /privacy-policy from editable markdown in docs/PRIVACY_POLICY.md.

Messenger webhooks and emission web app automation are planned for later phases.

Docker Deployment (single VM)

cp .env.example .env   # fill in credentials (Azure, Meta, domain)
docker compose up -d --build

• app container: uvicorn on :8000, SQLite + uploads in the app-data volume, migrations applied automatically at startup (fresh DB = zero manual steps)
• caddy container: reverse proxy with automatic HTTPS (Let's Encrypt)
• Optional Litestream continuous replication of SQLite to S3-compatible storage when LITESTREAM_BUCKET is set in .env

See docs/DEPLOYMENT.md for backups/restore, updates, troubleshooting, and the full environment reference.

Local Development Setup

1. Create a virtual environment.

python -m venv .venv
source .venv/bin/activate

2. Install dependencies.

If venv is unavailable on Ubuntu/Debian, install it first:

sudo apt install python3-venv

pip install -e ".[dev]"

3. Configure environment variables.

cp .env.example .env

Set:

• AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT
• AZURE_DOCUMENT_INTELLIGENCE_KEY
• APP_DATABASE_PATH
• APP_STORAGE_DIR

The app automatically loads .env from the project root when it starts.

4. Run the app.

uvicorn app.main:app --reload

5. Upload a document.

Open http://127.0.0.1:8000/docs and use POST /documents/upload.

6. Review or approve extracted data.

Use GET /vehicles/recent to list extracted records, then PATCH /vehicles/{vehicle_id}/review to correct fields and mark a record as approved.

7. Reprocess saved OCR after extractor changes.

Use POST /documents/{document_id}/reprocess to run extraction again from saved OCR without calling Azure again.

8. Upload multiple documents for one vehicle.

Use POST /documents/upload-batch with multiple files (e.g. OR + CR together). Each image is processed one-by-one, then the extractions are merged and verified into a single vehicle record. Conflicting values between OR and CR force needs_review.

Verification

Run tests:

pytest

Roadmap

See docs/ROADMAP.md: multi-user + SSO via Authentik (next ~2 months), browser automation of the emission web app, full external API automation, and operational polish.