# raghavs16/insurance_claim_intake architecture

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

- Interactive diagram: https://gitdiagram.com/raghavs16/insurance_claim_intake
- Repository: https://github.com/raghavs16/insurance_claim_intake

## Overview

#### Purpose and Entry Points
This repository implements an AI-assisted claims-processing application: a browser form submits a claim, a Python backend runs it through an agent graph, persists claim data, and can use object storage for supporting files. The user-facing entry point is the Next.js page at `frontend/src/app/page.tsx`; backend HTTP startup is `backend/src/api/main.py`.

#### Frontend Client
The frontend is a Next.js/React application with the primary claim-submission UI in `frontend/src/components/ClaimForm.tsx`. `frontend/src/services/claims.ts` forms the client/server boundary, encapsulating requests from the UI to the backend. `frontend/src/app/layout.tsx` provides the application shell, while `frontend/src/app/page.tsx` composes the primary workflow.

#### API and Application Boundary
`backend/src/api/main.py` is the backend API layer and should own HTTP request validation, response shaping, and orchestration handoff. It separates browser-facing transport concerns from the claim-processing workflow implemented under `backend/src/agents/`. The backend is packaged as a container through `backend/Dockerfile`.

#### Agentic Claims Pipeline
The core processing architecture is an explicit graph-based agent workflow:
- `backend/src/agents/graph.py` defines graph topology and stage sequencing.
- `backend/src/agents/state.py` defines the shared workflow state passed between stages.
- `backend/src/agents/nodes.py` contains the processing nodes that inspect, enrich, assess, or route a claim.

Control flows from an API-submitted claim into graph initialization, across stateful nodes, and back to the API as a result. The graph/state split is the main boundary for extending decision stages without coupling them to HTTP or persistence code.

#### Persistence Layer
Database access is isolated under `backend/src/database/`. `backend/src/database/models.py` defines persistent domain entities, and `backend/src/database/session.py` owns database session/connection lifecycle. Schema bootstrapping, migration, seed, and verification assets are centralized in `database/schema.sql`, `database/migrate.sql`, and `database/init.sql`, making the relational database an infrastructure dependency rather than an agent-owned concern.

#### Document/Object Storage Boundary
`backend/src/utils/s3.py` provides the integration boundary for S3-compatible object storage, likely for claim attachments or evidence. Agent and API code should use this abstraction rather than directly embedding storage-client operations. `backend/test_s3.py` indicates this is a material external-service integration.

#### Deployment and Runtime Topology
The application has two containerized runtimes: Next.js frontend (`frontend/Dockerfile`) and Python backend (`backend/Dockerfile`). `docker-compose.yml` is the local multi-service composition point and likely coordinates these runtimes with the database and required environment configuration. Python dependencies are declared in `backend/requirements.txt`; frontend runtime dependencies are in `frontend/package.json`.

Main entry points: [`backend/src/agents/graph.py`](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/agents/graph.py) (Claims workflow), [`backend/src/agents/nodes.py`](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/agents/nodes.py) (Processing nodes), [`backend/src/api/main.py`](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/api/main.py) (Backend API), [`backend/src/database/session.py`](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/database/session.py) (Database session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_page["Claims page<br/>Next.js page<br/>[page.tsx]"]
  node_layout["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_claim_form["Claim form<br/>React component<br/>[ClaimForm.tsx]"]
  node_claims_client["Claims client<br/>API client<br/>[claims.ts]"]
end

subgraph group_backend["Backend"]
  node_api{{"Backend API<br/>Python HTTP API<br/>[main.py]"}}
  node_agent_graph["Claims workflow<br/>Agent graph<br/>[graph.py]"]
  node_workflow_state["Workflow state<br/>Shared state<br/>[state.py]"]
  node_agent_nodes["Processing nodes<br/>Agent stages<br/>[nodes.py]"]
end

subgraph group_data["Data services"]
  node_db_session["Database session<br/>Connection lifecycle<br/>[session.py]"]
  node_claim_models["Claim models<br/>Persistent entities<br/>[models.py]"]
  node_relational_db[("Relational database<br/>[schema.sql]")]
  node_object_storage["Object storage adapter<br/>S3 integration<br/>[s3.py]"]
end

subgraph group_runtime["Local runtime"]
  node_frontend_container["Frontend container<br/>Next.js runtime"]
  node_backend_container["Backend container<br/>Python runtime"]
  node_compose["Service composition<br/>Docker Compose<br/>[docker-compose.yml]"]
end

node_layout -->|"wraps"| node_page
node_page -->|"composes"| node_claim_form
node_claim_form -->|"submits through"| node_claims_client
node_claims_client -->|"HTTP claim request"| node_api
node_api -->|"starts workflow"| node_agent_graph
node_agent_graph -->|"initializes and passes"| node_workflow_state
node_agent_graph -->|"sequences"| node_agent_nodes
node_agent_nodes -->|"reads and updates"| node_workflow_state
node_agent_nodes -->|"persists via"| node_db_session
node_db_session -->|"maps"| node_claim_models
node_db_session -->|"connects to"| node_relational_db
node_agent_nodes -->|"uses attachments"| node_object_storage
node_agent_graph -->|"returns result"| node_api
node_compose -->|"runs"| node_frontend_container
node_compose -->|"runs"| node_backend_container
node_frontend_container -.->|"calls backend"| node_api
node_backend_container -.->|"depends on"| node_relational_db
node_backend_container -.->|"accesses"| node_object_storage

click node_page "https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/src/app/page.tsx"
click node_layout "https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/src/app/layout.tsx"
click node_claim_form "https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/src/components/ClaimForm.tsx"
click node_claims_client "https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/src/services/claims.ts"
click node_api "https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/api/main.py"
click node_agent_graph "https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/agents/graph.py"
click node_workflow_state "https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/agents/state.py"
click node_agent_nodes "https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/agents/nodes.py"
click node_db_session "https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/database/session.py"
click node_claim_models "https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/database/models.py"
click node_relational_db "https://github.com/raghavs16/insurance_claim_intake/blob/main/database/schema.sql"
click node_object_storage "https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/utils/s3.py"
click node_frontend_container "https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/Dockerfile"
click node_backend_container "https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/Dockerfile"
click node_compose "https://github.com/raghavs16/insurance_claim_intake/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_page,node_layout,node_claim_form,node_claims_client toneBlue
class node_api,node_agent_graph,node_workflow_state,node_agent_nodes toneAmber
class node_db_session,node_claim_models,node_relational_db,node_object_storage toneMint
class node_frontend_container,node_backend_container,node_compose toneRose
```

## Components

### Frontend

Next.js browser client.

- [Claims page](https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/src/app/page.tsx): Next.js page · Primary user entry point. · `frontend/src/app/page.tsx`
- [App shell](https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/src/app/layout.tsx): Next.js layout · `frontend/src/app/layout.tsx`
- [Claim form](https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/src/components/ClaimForm.tsx): React component · Collects claim submissions. · `frontend/src/components/ClaimForm.tsx`
- [Claims client](https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/src/services/claims.ts): API client · Encapsulates browser-to-backend requests. · `frontend/src/services/claims.ts`

### Backend

Python API and agent workflow.

- [Backend API](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/api/main.py): Python HTTP API · Validates requests and shapes workflow responses. · `backend/src/api/main.py`
- [Claims workflow](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/agents/graph.py): Agent graph · Defines claim-processing topology and sequencing. · `backend/src/agents/graph.py`
- [Workflow state](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/agents/state.py): Shared state · State passed across processing stages. · `backend/src/agents/state.py`
- [Processing nodes](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/agents/nodes.py): Agent stages · Inspect, enrich, assess, and route claims. · `backend/src/agents/nodes.py`

### Data services

Relational persistence and object storage.

- [Database session](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/database/session.py): Connection lifecycle · Owns database sessions and connections. · `backend/src/database/session.py`
- [Claim models](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/database/models.py): Persistent entities · `backend/src/database/models.py`
- [Relational database](https://github.com/raghavs16/insurance_claim_intake/blob/main/database/schema.sql): Database · Schema is initialized and migrated by SQL assets. · `database/schema.sql`
- [Object storage adapter](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/src/utils/s3.py): S3 integration · Abstraction for claim attachments and evidence. · `backend/src/utils/s3.py`

### Local runtime

Containerized service composition.

- [Frontend container](https://github.com/raghavs16/insurance_claim_intake/blob/main/frontend/Dockerfile): Next.js runtime · `frontend/Dockerfile`
- [Backend container](https://github.com/raghavs16/insurance_claim_intake/blob/main/backend/Dockerfile): Python runtime · `backend/Dockerfile`
- [Service composition](https://github.com/raghavs16/insurance_claim_intake/blob/main/docker-compose.yml): Docker Compose · Coordinates local application services. · `docker-compose.yml`

## Connections

- App shell → Claims page: wraps
- Claims page → Claim form: composes
- Claim form → Claims client: submits through
- Claims client → Backend API: HTTP claim request
- Backend API → Claims workflow: starts workflow
- Claims workflow → Workflow state: initializes and passes
- Claims workflow → Processing nodes: sequences
- Processing nodes → Workflow state: reads and updates
- Processing nodes → Database session: persists via
- Database session → Claim models: maps
- Database session → Relational database: connects to
- Processing nodes → Object storage adapter: uses attachments
- Claims workflow → Backend API: returns result
- Service composition → Frontend container: runs
- Service composition → Backend container: runs
- Frontend container → Backend API: calls backend
- Backend container → Relational database: depends on
- Backend container → Object storage adapter: accesses