# moseskakuno/ai-workflow-automation architecture

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

- Interactive diagram: https://gitdiagram.com/moseskakuno/ai-workflow-automation
- Repository: https://github.com/moseskakuno/ai-workflow-automation

## Overview

This Streamlit application takes a user-uploaded PDF invoice through text extraction, AI-based field extraction, deterministic financial validation and risk flagging, then presents results for human approval or clarification. The app also persists invoice records and timestamped workflow events in SQLite, displays the archive and history, and offers a JSON report download. The sampled code shows the processing and persistence calls; approval routing is partly handled in the UI. Other README capabilities are represented where documented, but no external OCR or separate routing service is evidenced.

Main entry points: [`workflow.py`](https://github.com/moseskakuno/ai-workflow-automation/blob/main/workflow.py) (PDF processing), [`database.py`](https://github.com/moseskakuno/ai-workflow-automation/blob/main/database.py) (Persistence operations), [`app.py`](https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py) (Streamlit workflow UI), [`ai_processor.py`](https://github.com/moseskakuno/ai-workflow-automation/blob/main/ai_processor.py) (AI field extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Invoice interface"]
  node_app["Streamlit workflow UI<br/>[app.py]"]
  node_upload["PDF upload<br/>[app.py]"]
  node_results["Review and decisions<br/>[app.py]"]
  node_history_view["History and archive views<br/>[app.py]"]
  node_report["JSON report export<br/>[app.py]"]
  node_human_decision["Human approval<br/>[app.py]"]
end

subgraph group_processing["Invoice processing"]
  node_orchestrator["PDF processing<br/>[workflow.py]"]
  node_pdf_text["PDF text extraction<br/>[workflow.py]"]
  node_extractor["AI field extraction<br/>[ai_processor.py]"]
  node_validator["Financial validation<br/>[validators.py]"]
  node_risk["Risk assessment<br/>[validators.py]"]
  node_routing["Approval routing<br/>[app.py]"]
end

subgraph group_records["Workflow records"]
  node_database_api["Persistence operations<br/>[database.py]"]
  node_sqlite[("SQLite archive and history<br/>[database.py]")]
end

node_reviewer(("Invoice user"))
node_openai{{"OpenAI API"}}

node_reviewer -->|"uses"| node_app
node_app -->|"presents"| node_upload
node_upload -->|"submits PDF"| node_orchestrator
node_orchestrator -->|"extracts text"| node_pdf_text
node_orchestrator -->|"requests extraction"| node_extractor
node_extractor -->|"sends invoice text"| node_openai
node_orchestrator -->|"validates data"| node_validator
node_validator -->|"flags threshold"| node_risk
node_orchestrator -->|"returns results"| node_results
node_results -->|"uses validation"| node_routing
node_routing -->|"allows review"| node_human_decision
node_app -->|"initializes and records"| node_database_api
node_results -->|"saves status"| node_database_api
node_history_view -->|"queries records"| node_database_api
node_report -->|"downloads report"| node_reviewer
node_database_api -->|"reads and writes"| node_sqlite
node_human_decision -->|"updates status"| node_database_api
node_reviewer -->|"decides"| node_human_decision

click node_app "https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py"
click node_upload "https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py"
click node_results "https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py"
click node_history_view "https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py"
click node_report "https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py"
click node_orchestrator "https://github.com/moseskakuno/ai-workflow-automation/blob/main/workflow.py"
click node_pdf_text "https://github.com/moseskakuno/ai-workflow-automation/blob/main/workflow.py"
click node_extractor "https://github.com/moseskakuno/ai-workflow-automation/blob/main/ai_processor.py"
click node_validator "https://github.com/moseskakuno/ai-workflow-automation/blob/main/validators.py"
click node_risk "https://github.com/moseskakuno/ai-workflow-automation/blob/main/validators.py"
click node_routing "https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py"
click node_human_decision "https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py"
click node_database_api "https://github.com/moseskakuno/ai-workflow-automation/blob/main/database.py"
click node_sqlite "https://github.com/moseskakuno/ai-workflow-automation/blob/main/database.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_app,node_upload,node_results,node_history_view,node_report,node_human_decision,node_reviewer toneBlue
class node_orchestrator,node_pdf_text,node_extractor,node_validator,node_risk,node_routing toneAmber
class node_database_api,node_sqlite,node_openai toneMint
```

## Components

### Invoice interface

- [Streamlit workflow UI](https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py): `app.py`
- [PDF upload](https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py): `app.py`
- [Review and decisions](https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py): `app.py`
- [History and archive views](https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py): `app.py`
- [JSON report export](https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py): `app.py`
- [Human approval](https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py): `app.py`

### Invoice processing

- [PDF processing](https://github.com/moseskakuno/ai-workflow-automation/blob/main/workflow.py): `workflow.py`
- [PDF text extraction](https://github.com/moseskakuno/ai-workflow-automation/blob/main/workflow.py): `workflow.py`
- [AI field extraction](https://github.com/moseskakuno/ai-workflow-automation/blob/main/ai_processor.py): `ai_processor.py`
- [Financial validation](https://github.com/moseskakuno/ai-workflow-automation/blob/main/validators.py): `validators.py`
- [Risk assessment](https://github.com/moseskakuno/ai-workflow-automation/blob/main/validators.py): `validators.py`
- [Approval routing](https://github.com/moseskakuno/ai-workflow-automation/blob/main/app.py): `app.py`

### Workflow records

- [Persistence operations](https://github.com/moseskakuno/ai-workflow-automation/blob/main/database.py): `database.py`
- [SQLite archive and history](https://github.com/moseskakuno/ai-workflow-automation/blob/main/database.py): `database.py`

### Other components

- **Invoice user**
- **OpenAI API**

## Connections

- Invoice user → Streamlit workflow UI: uses (evidence: `README.md`)
- Streamlit workflow UI → PDF upload: presents (evidence: `app.py`)
- PDF upload → PDF processing: submits PDF (evidence: `app.py`)
- PDF processing → PDF text extraction: extracts text (evidence: `workflow.py`)
- PDF processing → AI field extraction: requests extraction (evidence: `workflow.py`)
- AI field extraction → OpenAI API: sends invoice text (evidence: `ai_processor.py`)
- PDF processing → Financial validation: validates data (evidence: `workflow.py`)
- Financial validation → Risk assessment: flags threshold (evidence: `validators.py`)
- PDF processing → Review and decisions: returns results (evidence: `workflow.py`)
- Review and decisions → Approval routing: uses validation (evidence: `app.py`)
- Approval routing → Human approval: allows review (evidence: `app.py`)
- Streamlit workflow UI → Persistence operations: initializes and records (evidence: `app.py`)
- Review and decisions → Persistence operations: saves status (evidence: `app.py`)
- History and archive views → Persistence operations: queries records (evidence: `app.py`)
- JSON report export → Invoice user: downloads report (evidence: `app.py`)
- Persistence operations → SQLite archive and history: reads and writes (evidence: `database.py`)
- Human approval → Persistence operations: updates status (evidence: `app.py`)
- Invoice user → Human approval: decides (evidence: `README.md`)