How aditi931/travel_reimbursement_agent works
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: graph.py Workflow Graph · nodes.py Stage Nodes · settings.py Runtime Config · database.py Claim Store
Components 21
Entry Points
Interactive and batch front doors into the shared workflow
- Streamlit UI · Interactive claim submission and review front end
app.py - CLI Runner · Batch or single-claim command-line execution
main.py
Claim Workflow
Typed LangGraph orchestration and domain nodes
- Workflow Graph · Defines the claim state machine and run_workflow path
agents/graph.py - Stage Nodes · Intake, OCR, validation, policy, fraud, and decision logic
agents/nodes.py - Claim Schemas · Typed claim input, workflow state, and final decision models
models/schemas.py - Intake · Checks timing, duplicates, and trip purpose
- OCR · Extracts receipt text when image evidence is needed
- Validator · Verifies receipt completeness against thresholds
- Policy · Applies caps and date-based reimbursement math
- Fraud · Combines rule checks with LLM fraud signal
- Decision · Synthesizes the final structured approval result
Supporting Services
OCR, database, configuration, and external provider dependencies
- Runtime Config · Environment-driven configuration and logging setup
config/settings.py - Claim Store · Async repository for history and duplicate detection
db/database.py - Receipt Extractor · Gemini Vision first, Tesseract fallback
ocr/extractor.py
Data Assets
Policy and sample/runtime data used by the workflow
- Policy Data · Reimbursement thresholds and category caps
data/travel_policy.json - Sample Claims · Local sample claims for development and batch runs
data/sample_claims.json - Claims DB · Default local database file for stored claim records
data/claims.db
Quality & Deployment
Tests and container packaging
- Workflow Tests · Deterministic workflow coverage without live LLM calls
tests/test_all.py - CI Pipeline · Runs tests and verifies Docker build
.github/workflows/ci.yml - Container Build · Container image definition for deployment
Dockerfile - Compose Setup · Containerized local runtime wiring
docker-compose.yml
Connections 25
- 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