# hardikdhawan2904/ai-dispute-investigation-system architecture

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

- Interactive diagram: https://gitdiagram.com/hardikdhawan2904/ai-dispute-investigation-system
- Repository: https://github.com/hardikdhawan2904/ai-dispute-investigation-system

## Overview

The platform accepts customer disputes, persists and validates cases, runs a staged multi-agent investigation, stores structured findings, and exposes customer tracking and analyst review. The README documents the agent sequence and customer communication; source-index references and excerpts establish selected API, service, persistence, and workflow links. Several route and agent details are unsampled, so their internal connections are omitted rather than inferred.

Main entry points: [`backend/workflows/dispute_workflow.py`](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/workflows/dispute_workflow.py) (Investigation workflow), [`backend/services/dispute_service.py`](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/dispute_service.py) (Case lifecycle), [`backend/api/main.py`](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/api/main.py) (FastAPI application), [`backend/api/routes/disputes.py`](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/api/routes/disputes.py) (Dispute endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_submission["Dispute submission<br/>[page.tsx]"]
  node_tracking["Case tracking<br/>[page.tsx]"]
  node_review["Internal review<br/>[page.tsx]"]
end

subgraph group_api["API and case services"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_dispute_route["Dispute endpoint<br/>[disputes.py]"]
  node_case_service["Case lifecycle<br/>[dispute_service.py]"]
  node_validation["Document rules<br/>[document_rules.py]"]
end

subgraph group_investigation["Investigation agents"]
  node_workflow["Investigation workflow"]
  node_aria["Dispute understanding<br/>[pipeline.py]"]
  node_iia["Investigation planning<br/>[pipeline.py]"]
  node_woa["Workflow orchestration<br/>[pipeline.py]"]
  node_fria["Fraud reasoning<br/>[pipeline.py]"]
  node_fraud_tools["Fraud intelligence tools<br/>[tools.py]"]
  node_eia["Evidence assessment<br/>[pipeline.py]"]
end

subgraph group_operations["Operations and communications"]
  node_priority["Priority scoring<br/>[priority_engine.py]"]
  node_manual_review["Manual review rules"]
  node_communications["Customer communications"]
end

subgraph group_persistence["Persistence"]
  node_database[("Case database<br/>[models.py]")]
end

node_customer(("Customer"))
node_analyst(("Operations analyst"))
node_email["Email provider"]

node_customer -->|"submits dispute"| node_submission
node_submission -->|"sends submission"| node_api_app
node_analyst -->|"reviews cases"| node_review
node_tracking -.->|"requests status"| node_api_app
node_review -.->|"requests case data"| node_api_app
node_api_app -->|"routes requests"| node_dispute_route
node_dispute_route -->|"delegates case handling"| node_case_service
node_dispute_route -->|"checks documents"| node_validation
node_case_service -->|"starts investigation"| node_workflow
node_workflow -->|"runs first"| node_aria
node_workflow -->|"runs planning"| node_iia
node_workflow -->|"routes investigation"| node_woa
node_workflow -->|"runs fraud analysis"| node_fria
node_workflow -->|"runs evidence assessment"| node_eia
node_fria -->|"invokes tools"| node_fraud_tools
node_workflow -->|"saves findings"| node_database
node_case_service -->|"calculates priority"| node_priority
node_case_service -->|"checks review need"| node_manual_review
node_case_service -->|"requests notifications"| node_communications
node_communications -.->|"sends email"| node_email
node_case_service -->|"reads and writes cases"| node_database

click node_submission "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/frontend/src/app/submit-dispute/page.tsx"
click node_tracking "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/frontend/src/app/track/%5BcaseId%5D/page.tsx"
click node_review "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/frontend/src/app/internal-review/%5BcaseId%5D/page.tsx"
click node_api_app "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/api/main.py"
click node_dispute_route "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/api/routes/disputes.py"
click node_case_service "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/dispute_service.py"
click node_validation "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/document_rules.py"
click node_workflow "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/workflows/dispute_workflow.py"
click node_aria "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/dispute_agent/nodes/pipeline.py"
click node_iia "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/investigation_agent/nodes/pipeline.py"
click node_woa "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/orchestration_agent/nodes/pipeline.py"
click node_fria "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/fraud_reasoning_agent/nodes/pipeline.py"
click node_fraud_tools "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/fraud_reasoning_agent/tools.py"
click node_eia "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/evidence_agent/nodes/pipeline.py"
click node_priority "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/priority_engine.py"
click node_manual_review "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/manual_review_service.py"
click node_communications "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/communication_service.py"
click node_database "https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/database/models.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_submission,node_tracking,node_review toneBlue
class node_api_app,node_dispute_route,node_case_service,node_validation toneAmber
class node_workflow,node_aria,node_iia,node_woa,node_fria,node_fraud_tools,node_eia toneMint
class node_priority,node_manual_review,node_communications toneRose
class node_database,node_customer,node_analyst,node_email toneIndigo
```

## Components

### User experience

- [Dispute submission](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/frontend/src/app/submit-dispute/page.tsx): `frontend/src/app/submit-dispute/page.tsx`
- [Case tracking](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/frontend/src/app/track/%5BcaseId%5D/page.tsx): `frontend/src/app/track/[caseId]/page.tsx`
- [Internal review](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/frontend/src/app/internal-review/%5BcaseId%5D/page.tsx): `frontend/src/app/internal-review/[caseId]/page.tsx`

### API and case services

- [FastAPI application](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/api/main.py): `backend/api/main.py`
- [Dispute endpoint](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/api/routes/disputes.py): `backend/api/routes/disputes.py`
- [Case lifecycle](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/dispute_service.py): `backend/services/dispute_service.py`
- [Document rules](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/document_rules.py): `backend/services/document_rules.py`

### Investigation agents

- [Investigation workflow](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/workflows/dispute_workflow.py): `backend/workflows/dispute_workflow.py`
- [Dispute understanding](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/dispute_agent/nodes/pipeline.py): `backend/agents/dispute_agent/nodes/pipeline.py`
- [Investigation planning](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/investigation_agent/nodes/pipeline.py): `backend/agents/investigation_agent/nodes/pipeline.py`
- [Workflow orchestration](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/orchestration_agent/nodes/pipeline.py): `backend/agents/orchestration_agent/nodes/pipeline.py`
- [Fraud reasoning](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/fraud_reasoning_agent/nodes/pipeline.py): `backend/agents/fraud_reasoning_agent/nodes/pipeline.py`
- [Fraud intelligence tools](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/fraud_reasoning_agent/tools.py): `backend/agents/fraud_reasoning_agent/tools.py`
- [Evidence assessment](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/agents/evidence_agent/nodes/pipeline.py): `backend/agents/evidence_agent/nodes/pipeline.py`

### Operations and communications

- [Priority scoring](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/priority_engine.py): `backend/services/priority_engine.py`
- [Manual review rules](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/manual_review_service.py): `backend/services/manual_review_service.py`
- [Customer communications](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/services/communication_service.py): `backend/services/communication_service.py`

### Persistence

- [Case database](https://github.com/hardikdhawan2904/ai-dispute-investigation-system/blob/main/backend/database/models.py): `backend/database/models.py`

### Other components

- **Customer**
- **Operations analyst**
- **Email provider**

## Connections

- Customer → Dispute submission: submits dispute (evidence: `README.md`)
- Dispute submission → FastAPI application: sends submission (evidence: `README.md`)
- Operations analyst → Internal review: reviews cases (evidence: `README.md`)
- Case tracking → FastAPI application: requests status
- Internal review → FastAPI application: requests case data
- FastAPI application → Dispute endpoint: routes requests (evidence: `backend/api/main.py`)
- Dispute endpoint → Case lifecycle: delegates case handling (evidence: `backend/api/routes/disputes.py`)
- Dispute endpoint → Document rules: checks documents (evidence: `backend/api/routes/disputes.py`)
- Case lifecycle → Investigation workflow: starts investigation (evidence: `backend/services/dispute_service.py`)
- Investigation workflow → Dispute understanding: runs first (evidence: `backend/workflows/dispute_workflow.py`)
- Investigation workflow → Investigation planning: runs planning (evidence: `backend/workflows/dispute_workflow.py`)
- Investigation workflow → Workflow orchestration: routes investigation (evidence: `backend/workflows/dispute_workflow.py`)
- Investigation workflow → Fraud reasoning: runs fraud analysis (evidence: `backend/workflows/dispute_workflow.py`)
- Investigation workflow → Evidence assessment: runs evidence assessment (evidence: `backend/workflows/dispute_workflow.py`)
- Fraud reasoning → Fraud intelligence tools: invokes tools (evidence: `backend/agents/fraud_reasoning_agent/nodes/pipeline.py`)
- Investigation workflow → Case database: saves findings (evidence: `backend/workflows/dispute_workflow.py`)
- Case lifecycle → Priority scoring: calculates priority (evidence: `backend/services/dispute_service.py`)
- Case lifecycle → Manual review rules: checks review need (evidence: `backend/services/dispute_service.py`)
- Case lifecycle → Customer communications: requests notifications (evidence: `backend/services/dispute_service.py`)
- Customer communications → Email provider: sends email
- Case lifecycle → Case database: reads and writes cases (evidence: `backend/services/dispute_service.py`)
