williamlo90/ai-document-ops-system

Purpose and entry points

Invoice Review is a human-controlled AP workflow: upload invoice PDFs, extract fields, validate, review/correct, approve or reject, then export only approved records. The deployed API entry point is backend/app/main.py; the asynchronous document worker starts through backend/app/worker.py and backend/app/worker_loop.py. The browser client begins at frontend/src/main.tsx and routes through frontend/src/App.tsx.

HTTP application and composition

FastAPI exposes domain-oriented endpoints for documents, workflow commands, review, exports, operations, evaluation, integrations, and agent functions under backend/app/api/. Dependency composition is centralized in backend/app/bootstrap/container.py, with domain-specific wiring in files such as backend/app/bootstrap/documents.py and backend/app/bootstrap/persistence.py. API handlers should remain a boundary layer over services/repositories rather than own workflow state.

Document intake and asynchronous extraction

PDF intake persists private source material and creates a document/job lifecycle. The document domain owns status, leases, processing policy, state writes, retention, and workflow transitions in backend/app/documents/. backend/app/documents/worker.py consumes leased jobs and drives backend/app/documents/extraction_pipeline.py. This separates request-time upload from potentially slow OCR/extraction and supports retry/operations visibility.

Provider and validation boundary

Extraction providers propose structured fields; they do not authorize business decisions. Provider contracts and runtime selection reside in backend/app/providers/contracts.py, backend/app/providers/factory.py, and backend/app/providers/llm_json.py, with mock and Mistral implementations available. Provider egress/security is isolated in backend/app/core/provider_egress.py. Proposed extraction then crosses into deterministic invoice/document validation in backend/app/validation/invoice.py and backend/app/validation/document.py, producing blocking issues independently of model confidence.

Human review, lifecycle, and auditability

Review services preserve the original extraction and apply field-level corrections, reviewer decisions, and reasoned history through backend/app/review/services.py, backend/app/review/corrections.py, and backend/app/review/repositories.py. The frontend review surface is frontend/src/pages/ReviewWorkspacePage.tsx, backed by frontend/src/features/review/. Approval is gated by validation and role/state rules, rather than delegated to providers or UI-only checks.

Approval-gated exports and operational control

Exports are eligibility-checked and execution is idempotency-oriented via backend/app/exports/eligibility.py, backend/app/exports/execution.py, and backend/app/exports/batch_service.py. Operations, metrics, invoice queries, and overview dashboards expose workflow health through backend/app/operations/, backend/app/metrics/, and backend/app/overview/dashboard.py. The administrative UI is represented by frontend/src/pages/SystemPage.tsx and frontend/src/pages/EvaluationPage.tsx.

Persistence, runtime, and external services

Local runtime uses Python/FastAPI, a React/TypeScript/Vite frontend, SQLite, and private local file storage. SQLite persistence is implemented by domain repositories such as backend/app/documents/sqlite_store.py and backend/app/review/sqlite_repositories.py; PostgreSQL schema support exists at backend/migrations/postgres/001_initial.sql. Docker starts API and worker via Dockerfile, docker-compose.yml, and docker-compose.production.yml. Default mocks avoid paid dependencies; provider-backed runs use Mistral OCR and an OpenAI structured-extraction model.

Quality and agent/back-office extensions

Evaluation measures extraction and validation against labeled datasets using backend/app/evaluation/ and backend/app/benchmark/. Agent and back-office capabilities are distinct orchestration domains, with request routing/services in backend/app/agent/service.py and controlled scenario/planning/execution in backend/app/backoffice/planning_service.py and backend/app/backoffice/execution.py; they should consume established document/workflow boundaries rather than bypass approval controls.