# williamlo90/ai-document-ops-system architecture

> Architecture diagram of the GitHub repository williamlo90/ai-document-ops-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/williamlo90/ai-document-ops-system
- Repository: https://github.com/williamlo90/ai-document-ops-system

## Overview

#### 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.

Main entry points: [`backend/app/bootstrap/container.py`](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/bootstrap/container.py) (Dependency container), [`backend/app/documents/extraction_pipeline.py`](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/documents/extraction_pipeline.py) (Extraction pipeline), [`backend/app/review/services.py`](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/review/services.py) (Review and corrections), [`backend/app/main.py`](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/main.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser client"]
  node_browser_entry["React application<br/>frontend entry<br/>[main.tsx]"]
  node_review_ui["Review workspace<br/>review UI"]
  node_admin_ui["Operations and evaluation UI<br/>admin UI<br/>[SystemPage.tsx]"]
end

subgraph group_api["API and composition"]
  node_api_entry["FastAPI application<br/>API entry<br/>[main.py]"]
  node_api_routes["Domain API routes<br/>HTTP boundary"]
  node_container["Dependency container<br/>composition root<br/>[container.py]"]
end

subgraph group_workflow["Document workflow"]
  node_document_domain["Document lifecycle<br/>workflow domain"]
  node_worker["Async document worker<br/>worker runtime<br/>[worker.py]"]
  node_pipeline["Extraction pipeline<br/>job processor"]
end

subgraph group_providers["Extraction boundary"]
  node_provider_factory["Provider selection<br/>provider factory<br/>[factory.py]"]
  node_provider_egress["Provider egress control<br/>security boundary<br/>[provider_egress.py]"]
  node_external_models{{"OCR and structured models<br/>external providers"}}
end

subgraph group_control["Review and control"]
  node_validation["Deterministic validation<br/>validation rules<br/>[invoice.py]"]
  node_review_services["Review and corrections<br/>review service<br/>[services.py]"]
  node_exports["Approval-gated exports<br/>export service<br/>[execution.py]"]
  node_operations["Workflow operations<br/>operational read models"]
  node_agent_backoffice["Agent and back-office orchestration<br/>controlled orchestration<br/>[service.py]"]
end

subgraph group_runtime["Storage and external services"]
  node_sqlite[("SQLite repositories<br/>persistence<br/>[sqlite_store.py]")]
  node_file_storage[("Private PDF storage<br/>file storage")]
end

node_browser_entry -->|"renders"| node_review_ui
node_browser_entry -->|"renders"| node_admin_ui
node_review_ui -->|"HTTP"| node_api_entry
node_admin_ui -->|"HTTP"| node_api_entry
node_api_entry -->|"serves"| node_api_routes
node_api_routes -->|"resolves services"| node_container
node_container -->|"wires"| node_document_domain
node_container -->|"wires"| node_review_services
node_container -->|"wires"| node_exports
node_document_domain -->|"stores PDFs"| node_file_storage
node_document_domain -->|"persists jobs and state"| node_sqlite
node_worker -->|"leases jobs"| node_document_domain
node_worker -->|"runs"| node_pipeline
node_pipeline -->|"requests extraction"| node_provider_factory
node_provider_factory -->|"uses"| node_provider_egress
node_provider_egress -->|"controlled calls"| node_external_models
node_pipeline -->|"validates proposals"| node_validation
node_validation -->|"records blocking issues"| node_document_domain
node_review_services -->|"applies decisions"| node_document_domain
node_review_services -->|"persists history"| node_sqlite
node_exports -->|"checks approval eligibility"| node_document_domain
node_operations -->|"reads workflow health"| node_document_domain
node_agent_backoffice -->|"orchestrates through domain"| node_document_domain

click node_browser_entry "https://github.com/williamlo90/ai-document-ops-system/blob/main/frontend/src/main.tsx"
click node_review_ui "https://github.com/williamlo90/ai-document-ops-system/blob/main/frontend/src/pages/ReviewWorkspacePage.tsx"
click node_admin_ui "https://github.com/williamlo90/ai-document-ops-system/blob/main/frontend/src/pages/SystemPage.tsx"
click node_api_entry "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/main.py"
click node_container "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/bootstrap/container.py"
click node_worker "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/worker.py"
click node_pipeline "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/documents/extraction_pipeline.py"
click node_provider_factory "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/providers/factory.py"
click node_provider_egress "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/core/provider_egress.py"
click node_validation "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/validation/invoice.py"
click node_review_services "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/review/services.py"
click node_exports "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/exports/execution.py"
click node_agent_backoffice "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/agent/service.py"
click node_sqlite "https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/documents/sqlite_store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser_entry,node_review_ui,node_admin_ui toneBlue
class node_api_entry,node_api_routes,node_container toneAmber
class node_document_domain,node_worker,node_pipeline toneMint
class node_provider_factory,node_provider_egress,node_external_models toneRose
class node_validation,node_review_services,node_exports,node_operations,node_agent_backoffice toneIndigo
class node_sqlite,node_file_storage toneTeal
```

## Components

### Browser client

- [React application](https://github.com/williamlo90/ai-document-ops-system/blob/main/frontend/src/main.tsx): frontend entry · `frontend/src/main.tsx`
- [Review workspace](https://github.com/williamlo90/ai-document-ops-system/blob/main/frontend/src/pages/ReviewWorkspacePage.tsx): review UI · `frontend/src/pages/ReviewWorkspacePage.tsx`
- [Operations and evaluation UI](https://github.com/williamlo90/ai-document-ops-system/blob/main/frontend/src/pages/SystemPage.tsx): admin UI · `frontend/src/pages/SystemPage.tsx`

### API and composition

- [FastAPI application](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/main.py): API entry · `backend/app/main.py`
- **Domain API routes**: HTTP boundary · Documents, workflow, review, exports, operations, evaluation, integrations, and agents.
- [Dependency container](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/bootstrap/container.py): composition root · `backend/app/bootstrap/container.py`

### Document workflow

- **Document lifecycle**: workflow domain · Owns intake, job leases, status, retention, and transitions.
- [Async document worker](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/worker.py): worker runtime · `backend/app/worker.py`
- [Extraction pipeline](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/documents/extraction_pipeline.py): job processor · `backend/app/documents/extraction_pipeline.py`

### Extraction boundary

- [Provider selection](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/providers/factory.py): provider factory · `backend/app/providers/factory.py`
- [Provider egress control](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/core/provider_egress.py): security boundary · `backend/app/core/provider_egress.py`
- **OCR and structured models**: external providers · Mocks are default; Mistral OCR and OpenAI can be enabled.

### Review and control

- [Deterministic validation](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/validation/invoice.py): validation rules · Produces blocking issues independently of extraction confidence. · `backend/app/validation/invoice.py`
- [Review and corrections](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/review/services.py): review service · Preserves original extraction, corrections, decisions, and history. · `backend/app/review/services.py`
- [Approval-gated exports](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/exports/execution.py): export service · Checks eligibility and executes idempotently. · `backend/app/exports/execution.py`
- **Workflow operations**: operational read models
- [Agent and back-office orchestration](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/agent/service.py): controlled orchestration · Uses established workflow boundaries rather than bypassing approval. · `backend/app/agent/service.py`

### Storage and external services

- [SQLite repositories](https://github.com/williamlo90/ai-document-ops-system/blob/main/backend/app/documents/sqlite_store.py): persistence · `backend/app/documents/sqlite_store.py`
- **Private PDF storage**: file storage

## Connections

- React application → Review workspace: renders
- React application → Operations and evaluation UI: renders
- Review workspace → FastAPI application: HTTP
- Operations and evaluation UI → FastAPI application: HTTP
- FastAPI application → Domain API routes: serves
- Domain API routes → Dependency container: resolves services
- Dependency container → Document lifecycle: wires
- Dependency container → Review and corrections: wires
- Dependency container → Approval-gated exports: wires
- Document lifecycle → Private PDF storage: stores PDFs
- Document lifecycle → SQLite repositories: persists jobs and state
- Async document worker → Document lifecycle: leases jobs
- Async document worker → Extraction pipeline: runs
- Extraction pipeline → Provider selection: requests extraction
- Provider selection → Provider egress control: uses
- Provider egress control → OCR and structured models: controlled calls
- Extraction pipeline → Deterministic validation: validates proposals
- Deterministic validation → Document lifecycle: records blocking issues
- Review and corrections → Document lifecycle: applies decisions
- Review and corrections → SQLite repositories: persists history
- Approval-gated exports → Document lifecycle: checks approval eligibility
- Workflow operations → Document lifecycle: reads workflow health
- Agent and back-office orchestration → Document lifecycle: orchestrates through domain