# cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent architecture

> Architecture diagram of the GitHub repository cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent
- Repository: https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent

## Overview

Northwind FNOL Agent supports a claimant’s loss report through evidence capture, claim progression, and next-step planning, with staff taking over ambiguity or high-impact decisions using shared claim context. The backend separates HTTP transport, domain rules, application services, persistence ports, and replaceable adapters. Claimants, claims professionals, operations, and administrators use distinct frontends; administration governs runtime configuration, knowledge, integrations, evaluation, and operations. Edges rely on README architecture and workflow statements or shown frontend routing and calls; unsampled backend wiring is not inferred.

Main entry points: [`backend/services`](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/tree/main/backend/services) (Use-case services), [`admin/src/App.jsx`](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/admin/src/App.jsx) (Control Plane), [`backend/api`](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/tree/main/backend/api) (HTTP transport), [`customer/src/App.jsx`](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/customer/src/App.jsx) (Claimant app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_claimant["Claimant experience"]
  node_customer_ui["Claimant app<br/>[App.jsx]"]
  node_claim_api["Claim API<br/>[api.js]"]
end

subgraph group_staff["Staff workbench"]
  node_workbench_ui["Claims workbench<br/>[App.jsx]"]
end

subgraph group_backend["Claim runtime"]
  node_claim_workflow["Claim workflow<br/>[agent.py]"]
  node_claim_domain["Claim state<br/>[models.py]"]
  node_evidence["Evidence handling<br/>[evidence.py]"]
  node_backend_http["HTTP transport"]
  node_app_runtime["Application runtime<br/>[app.py]"]
  node_service_layer["Use-case services"]
  node_persistence_ports["Persistence ports<br/>[protocols.py]"]
  node_mongodb[("MongoDB storage<br/>[mongodb.py]")]
  node_evidence_storage["Evidence storage"]
  node_external_services["External services"]
  node_claims_adapter["Claims adapter<br/>[claims_service.py]"]
  node_knowledge["Knowledge retrieval<br/>[retrieval.py]"]
end

subgraph group_governance["Control plane"]
  node_admin_ui["Control Plane<br/>[App.jsx]"]
  node_admin_api["Admin API<br/>[admin.py]"]
  node_operations["Operations and audit<br/>[audit.py]"]
  node_evaluations["Evaluations<br/>[evaluation.py]"]
end

node_claimant(("Claimant"))
node_staff(("Claims professional"))
node_admin(("Administrator"))

node_claimant -->|"reports loss"| node_customer_ui
node_customer_ui -->|"requests claim data"| node_claim_api
node_claim_api -->|"sends requests"| node_backend_http
node_backend_http -->|"routes HTTP"| node_app_runtime
node_app_runtime -->|"coordinates use cases"| node_service_layer
node_service_layer -.->|"runs agent"| node_claim_workflow
node_claim_workflow -.->|"progresses claim"| node_claim_domain
node_service_layer -->|"uses persistence"| node_persistence_ports
node_persistence_ports -.->|"persists state"| node_mongodb
node_service_layer -.->|"stores evidence"| node_evidence_storage
node_service_layer -->|"coordinates handoff"| node_external_services
node_external_services -->|"dispatches service"| node_claims_adapter
node_service_layer -.->|"retrieves knowledge"| node_knowledge
node_staff -->|"reviews work"| node_workbench_ui
node_workbench_ui -->|"uses shared claim state"| node_backend_http
node_admin -->|"governs runtime"| node_admin_ui
node_admin_ui -->|"manages configuration"| node_admin_api
node_admin_ui -->|"manages knowledge"| node_knowledge
node_admin_ui -->|"reviews evaluations"| node_evaluations
node_admin_ui -->|"inspects operations"| node_operations

click node_customer_ui "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/customer/src/App.jsx"
click node_claim_api "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/customer/src/api.js"
click node_claim_workflow "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/services/agent.py"
click node_claim_domain "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/models.py"
click node_evidence "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/evidence.py"
click node_backend_http "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/tree/main/backend/api"
click node_app_runtime "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/app.py"
click node_service_layer "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/tree/main/backend/services"
click node_persistence_ports "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/repositories/protocols.py"
click node_mongodb "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/repositories/mongodb.py"
click node_evidence_storage "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/adapters/evidence_storage.py"
click node_external_services "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/services/external_services.py"
click node_claims_adapter "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/adapters/claims_service.py"
click node_workbench_ui "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/workbench/src/App.jsx"
click node_admin_ui "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/admin/src/App.jsx"
click node_admin_api "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/api/admin.py"
click node_knowledge "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/retrieval.py"
click node_operations "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/audit.py"
click node_evaluations "https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/evaluation.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_customer_ui,node_claim_api toneBlue
class node_workbench_ui toneAmber
class node_claim_workflow,node_claim_domain,node_evidence,node_backend_http,node_app_runtime,node_service_layer,node_persistence_ports,node_mongodb,node_evidence_storage,node_external_services,node_claims_adapter,node_knowledge toneMint
class node_admin_ui,node_admin_api,node_operations,node_evaluations toneRose
class node_claimant,node_staff,node_admin toneIndigo
```

## Components

### Claimant experience

- [Claimant app](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/customer/src/App.jsx): `customer/src/App.jsx`
- [Claim API](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/customer/src/api.js): `customer/src/api.js`

### Staff workbench

- [Claims workbench](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/workbench/src/App.jsx): `workbench/src/App.jsx`

### Claim runtime

- [Claim workflow](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/services/agent.py): `backend/services/agent.py`
- [Claim state](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/models.py): `backend/domain/models.py`
- [Evidence handling](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/evidence.py): `backend/domain/evidence.py`
- [HTTP transport](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/tree/main/backend/api): `backend/api`
- [Application runtime](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/app.py): `backend/app.py`
- [Use-case services](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/tree/main/backend/services): `backend/services`
- [Persistence ports](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/repositories/protocols.py): `backend/repositories/protocols.py`
- [MongoDB storage](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/repositories/mongodb.py): `backend/repositories/mongodb.py`
- [Evidence storage](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/adapters/evidence_storage.py): `backend/adapters/evidence_storage.py`
- [External services](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/services/external_services.py): `backend/services/external_services.py`
- [Claims adapter](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/adapters/claims_service.py): `backend/adapters/claims_service.py`
- [Knowledge retrieval](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/retrieval.py): `backend/domain/retrieval.py`

### Control plane

- [Control Plane](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/admin/src/App.jsx): `admin/src/App.jsx`
- [Admin API](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/api/admin.py): `backend/api/admin.py`
- [Operations and audit](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/audit.py): `backend/domain/audit.py`
- [Evaluations](https://github.com/cs778-s2-2026-aws-challenge/scenario-08-northwind-fnol-agent/blob/main/backend/domain/evaluation.py): `backend/domain/evaluation.py`

### Other components

- **Claimant**
- **Claims professional**
- **Administrator**

## Connections

- Claimant → Claimant app: reports loss (evidence: `README.md`)
- Claimant app → Claim API: requests claim data (evidence: `customer/src/App.jsx`)
- Claim API → HTTP transport: sends requests (evidence: `README.md`)
- HTTP transport → Application runtime: routes HTTP (evidence: `README.md`)
- Application runtime → Use-case services: coordinates use cases (evidence: `README.md`)
- Use-case services → Claim workflow: runs agent (evidence: `backend/services/turn_reducer.py`)
- Claim workflow → Claim state: progresses claim
- Use-case services → Persistence ports: uses persistence (evidence: `README.md`)
- Persistence ports → MongoDB storage: persists state
- Use-case services → Evidence storage: stores evidence (evidence: `backend/services/integrations.py`)
- Use-case services → External services: coordinates handoff (evidence: `backend/services/external_services.py`)
- External services → Claims adapter: dispatches service (evidence: `backend/services/external_services.py`)
- Use-case services → Knowledge retrieval: retrieves knowledge (evidence: `backend/services/integrations.py`)
- Claims professional → Claims workbench: reviews work (evidence: `README.md`)
- Claims workbench → HTTP transport: uses shared claim state (evidence: `README.md`)
- Administrator → Control Plane: governs runtime (evidence: `README.md`)
- Control Plane → Admin API: manages configuration (evidence: `admin/src/App.jsx`)
- Control Plane → Knowledge retrieval: manages knowledge (evidence: `admin/src/App.jsx`)
- Control Plane → Evaluations: reviews evaluations (evidence: `admin/src/App.jsx`)
- Control Plane → Operations and audit: inspects operations (evidence: `admin/src/App.jsx`)
