CORTEX Invoice Processor

Lean local stack for AFIP invoice ingestion, AI extraction, human review, export, and KPI dashboards.

Stack

• FastAPI + SQLAlchemy + SQLite
• Prefect local server + worker
• React + Vite + Tailwind (single-page tab UI)
• Nginx reverse proxy
• Grafana sidecar (Prometheus endpoint + SQLite datasource)

Quick Start

1. Copy env file:

cp .env.example .env

2. Keep SURUS_MOCK_MODE=true for local testing without external API.

3. Start services:

docker compose up --build

4. Open:

• App: http://localhost
• FastAPI docs: http://localhost/api/docs
• Prefect UI: http://localhost:4200
• Grafana: http://localhost:3001

API Overview

• POST /api/invoices
• GET /api/artifacts/{invoice_id}/image
• GET /api/review/pending
• GET /api/review/{invoice_id}
• GET /api/review/{invoice_id}/anchors
• POST /api/review/{invoice_id}/anchors/recompute
• PUT /api/review/{invoice_id}/approve
• PUT /api/review/{invoice_id}/reject
• GET /api/export/approved
• GET /api/export/approved/{invoice_id}
• GET /api/export/approved.csv
• GET /api/data/extracted
• GET /api/metrics/latest
• GET /api/metrics/history
• POST /api/metrics/compute
• GET /api/invoices/recent
• GET /api/invoices/{invoice_id}
• GET /api/references
• GET /metrics

Running Tests

pip install -r backend/requirements.txt
pytest -q

Notes

• Main app DB: /data/invoices.db
• Uploaded artifacts: /data/artifacts
• Export CSVs can be generated from /api/export/approved.csv
• Dashboard references loaded from /data/references.json
• Review anchors provider behavior (including REVIEW_ANCHORS_PROVIDER=surus) is documented in backend/review_anchors/README.md

Inspect DB with DBeaver

1. Open DBeaver and create a new connection.
2. Choose SQLite.
3. Set database file path to your local project file: ./data/invoices.db.
4. Connect and inspect tables (invoices, extracted_data, approved_data, logs, metrics_snapshots).

Example query:

SELECT i.id, i.status, e.extracted_at, e.moneda, e.importe_bruto
FROM invoices i
LEFT JOIN extracted_data e ON e.invoice_id = i.id
ORDER BY i.received_at DESC
LIMIT 50;