# shreesha1-ux/spark-fnol-multiagent architecture

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

- Interactive diagram: https://gitdiagram.com/shreesha1-ux/spark-fnol-multiagent
- Repository: https://github.com/shreesha1-ux/spark-fnol-multiagent

## Overview

Spark FNOL is an insurance-claims triage product: an adjuster or claimant submits a statement and photos, the system assesses coverage, damage and consistency, then routes the claim for fast-track handling or human review. The Streamlit cockpit and FastAPI/static cockpit are distinct user-facing entry points. Core processing, deterministic decisioning, JSON-backed state and surveyor recommendations are represented; some feature relationships are documented in the README rather than visible in the sampled source. The graph omits uncertain internal call details where excerpts do not establish them.

Main entry points: [`agents_crew.py`](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/agents_crew.py) (Agent Pipeline), [`state_manager.py`](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/state_manager.py) (State Manager), [`server.py`](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/server.py) (Claims API), [`app.py`](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/app.py) (Adjuster Cockpit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake & Cockpits"]
  node_streamlit["Adjuster Cockpit<br/>[app.py]"]
  node_api["Claims API<br/>[server.py]"]
  node_webui["Cockpit Web UI<br/>[index.html]"]
end

subgraph group_assessment["Claims Assessment"]
  node_pipeline["Agent Pipeline<br/>[agents_crew.py]"]
  node_statement["Statement Extraction<br/>[tools.py]"]
  node_vision["Photo Appraisal<br/>[tools.py]"]
  node_coverage["Policy Verification<br/>[tools.py]"]
  node_fraud["Fraud &amp; Weather Checks<br/>[tools.py]"]
end

subgraph group_governance["Decision &amp; Oversight"]
  node_decision["Tier Decision Gate<br/>[decision_gate.py]"]
  node_surveyor["Surveyor Recommendation<br/>[agents_crew.py]"]
end

subgraph group_state["Claim State"]
  node_models["Claim Data Models<br/>[schemas.py]"]
  node_state_manager["State Manager<br/>[state_manager.py]"]
  node_claims[("Claims Store<br/>[db1_claims.json]")]
  node_policies[("Policy Records<br/>[db2_policies.json]")]
  node_repair_costs[("Repair Cost Table<br/>[repair_costs.json]")]
  node_config["Runtime Configuration<br/>[config.py]"]
end

subgraph group_integrations["External Services"]
  node_gemini{{"Google Gemini"}}
  node_meteo{{"Open-Meteo"}}
end

node_adjuster(("Adjuster / Claimant"))

node_adjuster -->|"submits claims"| node_streamlit
node_adjuster -->|"submits claims"| node_api
node_streamlit -->|"advances claims"| node_pipeline
node_streamlit -->|"reads and updates"| node_state_manager
node_api -->|"serves UI"| node_webui
node_api -->|"runs processing"| node_pipeline
node_api -->|"reads and updates"| node_state_manager
node_pipeline -->|"extracts facts"| node_statement
node_pipeline -->|"assesses photos"| node_vision
node_pipeline -->|"checks coverage"| node_coverage
node_pipeline -->|"checks consistency"| node_fraud
node_pipeline -->|"routes claims"| node_decision
node_pipeline -->|"persists stages"| node_state_manager
node_pipeline -->|"recommends surveyor"| node_surveyor
node_decision -->|"produces decision fields"| node_models
node_state_manager -->|"loads and saves"| node_models
node_state_manager -->|"reads and writes"| node_claims
node_state_manager -->|"reads"| node_policies
node_state_manager -->|"reads"| node_repair_costs
node_coverage -->|"verifies schedule"| node_policies
node_vision -->|"estimates repairs"| node_repair_costs
node_vision -->|"analyzes images"| node_gemini
node_statement -->|"extracts narrative facts"| node_gemini
node_fraud -->|"checks historical weather"| node_meteo
node_config -->|"configures models"| node_gemini

click node_streamlit "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/app.py"
click node_api "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/server.py"
click node_webui "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/static/index.html"
click node_pipeline "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/agents_crew.py"
click node_statement "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/tools.py"
click node_vision "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/tools.py"
click node_coverage "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/tools.py"
click node_fraud "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/tools.py"
click node_decision "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/decision_gate.py"
click node_surveyor "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/agents_crew.py"
click node_models "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/schemas.py"
click node_state_manager "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/state_manager.py"
click node_claims "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/data/db1_claims.json"
click node_policies "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/data/db2_policies.json"
click node_repair_costs "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/data/repair_costs.json"
click node_config "https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/config.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_streamlit,node_api,node_webui toneBlue
class node_pipeline,node_statement,node_vision,node_coverage,node_fraud toneAmber
class node_decision,node_surveyor toneMint
class node_models,node_state_manager,node_claims,node_policies,node_repair_costs,node_config toneRose
class node_gemini,node_meteo,node_adjuster toneIndigo
```

## Components

### Intake & Cockpits

- [Adjuster Cockpit](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/app.py): `app.py`
- [Claims API](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/server.py): `server.py`
- [Cockpit Web UI](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/static/index.html): `static/index.html`

### Claims Assessment

- [Agent Pipeline](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/agents_crew.py): `agents_crew.py`
- [Statement Extraction](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/tools.py): `tools.py`
- [Photo Appraisal](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/tools.py): `tools.py`
- [Policy Verification](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/tools.py): `tools.py`
- [Fraud & Weather Checks](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/tools.py): `tools.py`

### Decision & Oversight

- [Tier Decision Gate](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/decision_gate.py): `decision_gate.py`
- [Surveyor Recommendation](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/agents_crew.py): `agents_crew.py`

### Claim State

- [Claim Data Models](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/schemas.py): `schemas.py`
- [State Manager](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/state_manager.py): `state_manager.py`
- [Claims Store](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/data/db1_claims.json): `data/db1_claims.json`
- [Policy Records](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/data/db2_policies.json): `data/db2_policies.json`
- [Repair Cost Table](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/data/repair_costs.json): `data/repair_costs.json`
- [Runtime Configuration](https://github.com/shreesha1-ux/spark-fnol-multiagent/blob/main/config.py): `config.py`

### External Services

- **Google Gemini**
- **Open-Meteo**

### Other components

- **Adjuster / Claimant**

## Connections

- Adjuster / Claimant → Adjuster Cockpit: submits claims (evidence: `README.md`)
- Adjuster / Claimant → Claims API: submits claims (evidence: `README.md`)
- Adjuster Cockpit → Agent Pipeline: advances claims (evidence: `app.py`)
- Adjuster Cockpit → State Manager: reads and updates (evidence: `app.py`)
- Claims API → Cockpit Web UI: serves UI (evidence: `server.py`)
- Claims API → Agent Pipeline: runs processing (evidence: `server.py`)
- Claims API → State Manager: reads and updates (evidence: `server.py`)
- Agent Pipeline → Statement Extraction: extracts facts (evidence: `agents_crew.py`)
- Agent Pipeline → Photo Appraisal: assesses photos (evidence: `agents_crew.py`)
- Agent Pipeline → Policy Verification: checks coverage (evidence: `agents_crew.py`)
- Agent Pipeline → Fraud & Weather Checks: checks consistency (evidence: `agents_crew.py`)
- Agent Pipeline → Tier Decision Gate: routes claims (evidence: `agents_crew.py`)
- Agent Pipeline → State Manager: persists stages (evidence: `agents_crew.py`)
- Agent Pipeline → Surveyor Recommendation: recommends surveyor (evidence: `README.md`)
- Tier Decision Gate → Claim Data Models: produces decision fields (evidence: `decision_gate.py`)
- State Manager → Claim Data Models: loads and saves (evidence: `state_manager.py`)
- State Manager → Claims Store: reads and writes (evidence: `state_manager.py`)
- State Manager → Policy Records: reads (evidence: `state_manager.py`)
- State Manager → Repair Cost Table: reads (evidence: `state_manager.py`)
- Policy Verification → Policy Records: verifies schedule (evidence: `tools.py`)
- Photo Appraisal → Repair Cost Table: estimates repairs (evidence: `tools.py`)
- Photo Appraisal → Google Gemini: analyzes images (evidence: `README.md`)
- Statement Extraction → Google Gemini: extracts narrative facts (evidence: `README.md`)
- Fraud & Weather Checks → Open-Meteo: checks historical weather (evidence: `tools.py`)
- Runtime Configuration → Google Gemini: configures models (evidence: `config.py`)