# aditi931/travel_reimbursement_agent architecture

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

- Interactive diagram: https://gitdiagram.com/aditi931/travel_reimbursement_agent
- Repository: https://github.com/aditi931/travel_reimbursement_agent

## Overview

1. **What this repository is**
   - This is a travel reimbursement approval system built as a **GenAI-driven workflow**, not a generic CRUD app.
   - The core architecture is a **LangGraph state machine** that evaluates claims through a sequence of agent-like nodes, then emits a structured approval decision.

2. **Primary entry points**
   - `app.py` is the **interactive Streamlit UI** for submitting and reviewing claims.
   - `main.py` is the **CLI batch runner** for processing sample or individual claims.
   - Both entry points converge on the same backend workflow, so the UI and CLI are just different front doors into the same claim-processing pipeline.

3. **Central workflow orchestration**
   - `agents/graph.py` defines the **workflow graph** and the `run_workflow()` execution path.
   - The graph coordinates the claim through the ordered stages described in the README: **intake → OCR → validator → policy → fraud → decision**.
   - Conditional routing is important: some claims can **short-circuit directly to decision** if they are duplicates, late, personal travel, or otherwise hard-rejected early.

4. **Agent node responsibilities**
   - `agents/nodes.py` contains the actual stage logic.
   - The nodes are domain-specific, not generic agent tools:
     - **Intake**: validates submission timing, duplicate detection, and trip purpose.
     - **OCR**: extracts receipt text when needed.
     - **Validator**: checks receipt completeness against required thresholds.
     - **Policy**: applies per-category reimbursement caps and date-based math.
     - **Fraud**: combines rule-based checks with an LLM fraud signal.
     - **Decision**: synthesizes all intermediate results into the final structured outcome.

5. **Data model boundary**
   - `models/schemas.py` is the schema boundary for the whole system.
   - It uses **Pydantic** models to validate incoming claim data, represent workflow state, and format the final decision object.
   - This is a key architectural constraint: the workflow passes **typed structured objects**, not ad hoc dictionaries.

6. **Persistence layer**
   - `db/database.py` provides the database abstraction, using **SQLAlchemy 2.0 async ORM** and a `ClaimRepository`.
   - The README indicates **SQLite by default**, with **PostgreSQL support** via `DATABASE_URL`.
   - Persistence is used mainly for **duplicate detection** and claim history, so the database is part of the intake and fraud boundaries rather than the final output path.

7. **OCR and document handling**
   - `ocr/extractor.py` handles receipt text extraction.
   - The system supports **Gemini Vision** first, with **Tesseract as fallback**.
   - Architecturally, OCR is an optional enrichment step: structured claim data can still flow through the system, but receipt verification becomes stronger when image extraction is available.

8. **Configuration and runtime setup**
   - `config/settings.py` centralizes environment-driven configuration using **pydantic-settings** and also sets up logging.
   - `.env.example` shows the runtime dependency on provider selection and API keys.
   - The system is designed to swap LLM providers with configuration rather than code changes, which matters for deployment boundaries.

9. **Policy and sample data**
   - `data/travel_policy.json` holds the reimbursement rules and thresholds used by the policy node.
   - `data/sample_claims.json` and `data/claims.db` support local/demo execution and testing.
   - This makes the policy logic data-driven, with rule values separated from the workflow code.

10. **External service dependency**
   - The main external dependency is the **LLM provider** used for OCR support and final decision synthesis, with support for **Gemini, OpenAI, and Anthropic**.
   - The architecture is provider-agnostic at the workflow level, but provider choice affects OCR capability and decision generation quality.

11. **Decision and rejection model**
   - The decision endpoint is not just approve/reject; it produces a **structured `ClaimDecision`** object.
   - Early rejection is a first-class path in the graph, especially for duplicates, lateness, personal travel, and high fraud scores.
   - That means the system is optimized for **fast branching**, not linear “always process everything” execution.

12. **Validation and quality gates**
   - `tests/test_all.py` covers the workflow without requiring live LLM calls, which suggests the system is built around deterministic validation of core behavior.
   - The repository also includes GitHub Actions in `.github/workflows/ci.yml` for **tests plus Docker build verification**.
   - This is important architecturally because the workflow is intended to be deployable and testable in isolation from cloud AI services.

13. **Deployment packaging**
   - `Dockerfile` and `docker-compose.yml` indicate containerized deployment.
   - The app can run in a local containerized environment with environment variables injected, which matches the separation between runtime config, workflow logic, and persistence.

14. **How to draw the architecture**
   - A good diagram would show:
     - **UI/CLI entry points** feeding a shared **typed claim ingestion layer**
     - that enters the **LangGraph workflow**
     - which consults **OCR**, **database**, **policy data**, and **LLM provider**
     - then outputs a **structured decision**
     - and optionally stores/reads claim records from **SQLite/PostgreSQL**.
   - The key boundary is that all business decisions flow through the graph, while UI, storage, OCR, and LLM services remain pluggable dependencies around it.

Main entry points: [`agents/graph.py`](https://github.com/aditi931/travel_reimbursement_agent/blob/main/agents/graph.py) (Workflow Graph), [`agents/nodes.py`](https://github.com/aditi931/travel_reimbursement_agent/blob/main/agents/nodes.py) (Stage Nodes), [`config/settings.py`](https://github.com/aditi931/travel_reimbursement_agent/blob/main/config/settings.py) (Runtime Config), [`db/database.py`](https://github.com/aditi931/travel_reimbursement_agent/blob/main/db/database.py) (Claim Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entry Points"]
  node_app_py["Streamlit UI<br/>ui entrypoint<br/>[app.py]"]
  node_main_py["CLI Runner<br/>cli entrypoint<br/>[main.py]"]
end

subgraph group_workflow["Claim Workflow"]
  node_graph_py{{"Workflow Graph<br/>langgraph orchestrator<br/>[graph.py]"}}
  node_nodes_py["Stage Nodes<br/>domain agents<br/>[nodes.py]"]
  node_schemas_py["Claim Schemas<br/>pydantic models<br/>[schemas.py]"]
  node_intake_node(("Intake<br/>submission gate"))
  node_ocr_node(("OCR<br/>receipt extraction"))
  node_validator_node(("Validator<br/>receipt checks"))
  node_policy_node(("Policy<br/>reimbursement rules"))
  node_fraud_node(("Fraud<br/>risk scoring"))
  node_decision_node(("Decision<br/>claim outcome"))
end

subgraph group_services["Supporting Services"]
  node_settings_py["Runtime Config<br/>settings and logging<br/>[settings.py]"]
  node_db_py[("Claim Store<br/>sqlalchemy async repo<br/>[database.py]")]
  node_ocr_py["Receipt Extractor<br/>ocr service<br/>[extractor.py]"]
end

subgraph group_data["Data Assets"]
  node_policy_json["Policy Data<br/>policy rules<br/>[travel_policy.json]"]
  node_sample_json["Sample Claims<br/>demo data<br/>[sample_claims.json]"]
  node_claims_db[("Claims DB<br/>sqlite data<br/>[claims.db]")]
end

subgraph group_quality["Quality & Deployment"]
  node_tests_py["Workflow Tests<br/>test suite<br/>[test_all.py]"]
  node_ci_yml["CI Pipeline<br/>github actions<br/>[ci.yml]"]
  node_dockerfile["Container Build<br/>docker packaging"]
  node_compose_yml["Compose Setup<br/>local deployment<br/>[docker-compose.yml]"]
end

node_app_py -->|"submits claims"| node_graph_py
node_main_py -->|"runs workflow"| node_graph_py
node_graph_py -->|"typed state"| node_schemas_py
node_graph_py -->|"routes stages"| node_nodes_py
node_nodes_py -->|"intake"| node_intake_node
node_nodes_py -->|"ocr"| node_ocr_node
node_nodes_py -->|"validate"| node_validator_node
node_nodes_py -->|"apply policy"| node_policy_node
node_nodes_py -->|"score fraud"| node_fraud_node
node_nodes_py -->|"finalize"| node_decision_node
node_graph_py -->|"lookup history"| node_db_py
node_db_py -->|"default store"| node_claims_db
node_db_py -->|"db url"| node_settings_py
node_ocr_node -->|"extracts text"| node_ocr_py
node_ocr_py -->|"provider config"| node_settings_py
node_policy_node -->|"reads rules"| node_policy_json
node_graph_py -->|"runtime config"| node_settings_py
node_settings_py -->|"connects"| node_db_py
node_settings_py -->|"model keys"| node_ocr_py
node_graph_py -.->|"demo input"| node_sample_json
node_tests_py -->|"validates"| node_graph_py
node_ci_yml -->|"runs"| node_tests_py
node_ci_yml -->|"verifies build"| node_dockerfile
node_dockerfile -->|"packages"| node_compose_yml
node_compose_yml -->|"env injection"| node_settings_py

click node_app_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/app.py"
click node_main_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/main.py"
click node_graph_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/agents/graph.py"
click node_nodes_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/agents/nodes.py"
click node_schemas_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/models/schemas.py"
click node_settings_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/config/settings.py"
click node_db_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/db/database.py"
click node_ocr_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/ocr/extractor.py"
click node_policy_json "https://github.com/aditi931/travel_reimbursement_agent/blob/main/data/travel_policy.json"
click node_sample_json "https://github.com/aditi931/travel_reimbursement_agent/blob/main/data/sample_claims.json"
click node_claims_db "https://github.com/aditi931/travel_reimbursement_agent/blob/main/data/claims.db"
click node_tests_py "https://github.com/aditi931/travel_reimbursement_agent/blob/main/tests/test_all.py"
click node_ci_yml "https://github.com/aditi931/travel_reimbursement_agent/blob/main/.github/workflows/ci.yml"
click node_dockerfile "https://github.com/aditi931/travel_reimbursement_agent/tree/main/Dockerfile"
click node_compose_yml "https://github.com/aditi931/travel_reimbursement_agent/blob/main/docker-compose.yml"

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_py,node_main_py toneBlue
class node_graph_py,node_nodes_py,node_schemas_py,node_intake_node,node_ocr_node,node_validator_node,node_policy_node,node_fraud_node,node_decision_node toneAmber
class node_settings_py,node_db_py,node_ocr_py toneMint
class node_policy_json,node_sample_json,node_claims_db toneRose
class node_tests_py,node_ci_yml,node_dockerfile,node_compose_yml toneIndigo
```

## Components

### Entry Points

Interactive and batch front doors into the shared workflow

- [Streamlit UI](https://github.com/aditi931/travel_reimbursement_agent/blob/main/app.py): ui entrypoint · Interactive claim submission and review front end · `app.py`
- [CLI Runner](https://github.com/aditi931/travel_reimbursement_agent/blob/main/main.py): cli entrypoint · Batch or single-claim command-line execution · `main.py`

### Claim Workflow

Typed LangGraph orchestration and domain nodes

- [Workflow Graph](https://github.com/aditi931/travel_reimbursement_agent/blob/main/agents/graph.py): langgraph orchestrator · Defines the claim state machine and run_workflow path · `agents/graph.py`
- [Stage Nodes](https://github.com/aditi931/travel_reimbursement_agent/blob/main/agents/nodes.py): domain agents · Intake, OCR, validation, policy, fraud, and decision logic · `agents/nodes.py`
- [Claim Schemas](https://github.com/aditi931/travel_reimbursement_agent/blob/main/models/schemas.py): pydantic models · Typed claim input, workflow state, and final decision models · `models/schemas.py`
- **Intake**: submission gate · Checks timing, duplicates, and trip purpose
- **OCR**: receipt extraction · Extracts receipt text when image evidence is needed
- **Validator**: receipt checks · Verifies receipt completeness against thresholds
- **Policy**: reimbursement rules · Applies caps and date-based reimbursement math
- **Fraud**: risk scoring · Combines rule checks with LLM fraud signal
- **Decision**: claim outcome · Synthesizes the final structured approval result

### Supporting Services

OCR, database, configuration, and external provider dependencies

- [Runtime Config](https://github.com/aditi931/travel_reimbursement_agent/blob/main/config/settings.py): settings and logging · Environment-driven configuration and logging setup · `config/settings.py`
- [Claim Store](https://github.com/aditi931/travel_reimbursement_agent/blob/main/db/database.py): sqlalchemy async repo · Async repository for history and duplicate detection · `db/database.py`
- [Receipt Extractor](https://github.com/aditi931/travel_reimbursement_agent/blob/main/ocr/extractor.py): ocr service · Gemini Vision first, Tesseract fallback · `ocr/extractor.py`

### Data Assets

Policy and sample/runtime data used by the workflow

- [Policy Data](https://github.com/aditi931/travel_reimbursement_agent/blob/main/data/travel_policy.json): policy rules · Reimbursement thresholds and category caps · `data/travel_policy.json`
- [Sample Claims](https://github.com/aditi931/travel_reimbursement_agent/blob/main/data/sample_claims.json): demo data · Local sample claims for development and batch runs · `data/sample_claims.json`
- [Claims DB](https://github.com/aditi931/travel_reimbursement_agent/blob/main/data/claims.db): sqlite data · Default local database file for stored claim records · `data/claims.db`

### Quality & Deployment

Tests and container packaging

- [Workflow Tests](https://github.com/aditi931/travel_reimbursement_agent/blob/main/tests/test_all.py): test suite · Deterministic workflow coverage without live LLM calls · `tests/test_all.py`
- [CI Pipeline](https://github.com/aditi931/travel_reimbursement_agent/blob/main/.github/workflows/ci.yml): github actions · Runs tests and verifies Docker build · `.github/workflows/ci.yml`
- [Container Build](https://github.com/aditi931/travel_reimbursement_agent/tree/main/Dockerfile): docker packaging · Container image definition for deployment · `Dockerfile`
- [Compose Setup](https://github.com/aditi931/travel_reimbursement_agent/blob/main/docker-compose.yml): local deployment · Containerized local runtime wiring · `docker-compose.yml`

## Connections

- Streamlit UI → Workflow Graph: submits claims · UI hands structured claim data to the shared workflow
- CLI Runner → Workflow Graph: runs workflow · CLI uses the same backend execution path
- Workflow Graph → Claim Schemas: typed state · Workflow is driven by structured Pydantic models
- Workflow Graph → Stage Nodes: routes stages · Graph invokes the domain stage implementations
- Stage Nodes → Intake: intake · Submission gating and early rejection checks
- Stage Nodes → OCR: ocr · Optional receipt text extraction step
- Stage Nodes → Validator: validate · Receipt completeness checks
- Stage Nodes → Policy: apply policy · Reimbursement calculation step
- Stage Nodes → Fraud: score fraud · Risk evaluation stage
- Stage Nodes → Decision: finalize · Produces the structured ClaimDecision outcome
- Workflow Graph → Claim Store: lookup history · Intake and fraud stages consult prior claims
- Claim Store → Claims DB: default store · SQLite is the local persistence target
- Claim Store → Runtime Config: db url · Database backend is chosen from runtime settings
- OCR → Receipt Extractor: extracts text · OCR stage delegates image-to-text handling
- Receipt Extractor → Runtime Config: provider config · OCR provider selection is environment-driven
- Policy → Policy Data: reads rules · Policy logic is data-driven from JSON rules
- Workflow Graph → Runtime Config: runtime config · Workflow behavior depends on centralized settings
- Runtime Config → Claim Store: connects · Settings supply database configuration
- Runtime Config → Receipt Extractor: model keys · OCR and LLM providers are configured centrally
- Workflow Graph → Sample Claims: demo input · Sample claims support local execution paths
- Workflow Tests → Workflow Graph: validates · Tests exercise workflow behavior deterministically
- CI Pipeline → Workflow Tests: runs · CI executes the test suite
- CI Pipeline → Container Build: verifies build · CI checks container image buildability
- Container Build → Compose Setup: packages · Compose uses the containerized application image
- Compose Setup → Runtime Config: env injection · Local deployment is driven by environment settings
