# codebykarthik/natwest-case-investigation-agent architecture

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

- Interactive diagram: https://gitdiagram.com/codebykarthik/natwest-case-investigation-agent
- Repository: https://github.com/codebykarthik/natwest-case-investigation-agent

## Overview

NatWest Case Investigation Agent is a staff-facing investigation assistant spanning an authenticated frontend, backend agent, MCP business-tool layer, and shared domain services. The main workflow is staff sign-in, chat submission, agent routing and investigation, governed business operations, and a grounded response. The README documents customer/case review, timelines, vulnerability signals, case updates, and evaluation hooks; unsampled implementations are represented only at supported directory paths. Relationships are limited to README statements and SOURCE INDEX references, so some internal workflow links remain unverified.

Main entry points: [`natwest-backend/src/natwest_backend/agent/service.py`](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/service.py) (Agent service), [`natwest-backend/src/natwest_backend/agent/graph_builder.py`](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/graph_builder.py) (Agent graph), [`natwest-frontend/src/natwest_frontend/app.py`](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/app.py) (Staff UI), [`natwest-mcp/src/natwest_mcp/mcp/tools/business_tools.py`](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-mcp/src/natwest_mcp/mcp/tools/business_tools.py) (Case operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Staff experience"]
  node_frontend["Staff UI<br/>[app.py]"]
  node_login["Sign-in session<br/>[session.py]"]
  node_oauth["OAuth client<br/>[oauth.py]"]
  node_assistant["Assistant chat<br/>[assistant.py]"]
  node_api_client["Backend client<br/>[api_client.py]"]
end

subgraph group_backend["API and agent"]
  node_api["Backend API<br/>[app.py]"]
  node_chat_route["Chat endpoint<br/>[chat.py]"]
  node_agent_service["Agent service<br/>[service.py]"]
  node_graph["Agent graph<br/>[graph_builder.py]"]
  node_router["Intent router<br/>[router_node.py]"]
  node_investigation["Investigation flow"]
  node_guardrails["Input guardrails"]
  node_evaluation["Evaluation hooks"]
  node_mcp_client["MCP client"]
end

subgraph group_tools["Business tools"]
  node_mcp_server["MCP server<br/>[server.py]"]
  node_registry["Tool registry<br/>[tool_registry.py]"]
  node_business_tools["Case operations<br/>[business_tools.py]"]
end

subgraph group_domain["Shared domain"]
  node_auth_context["Auth context"]
  node_keycloak["Token verifier<br/>[keycloak.py]"]
  node_business_service["Business services"]
  node_read_repo["Case and customer reads"]
  node_write_repo["Case updates"]
  node_user_repo["Staff user records<br/>[user_repository.py]"]
end

subgraph group_state["Persistence and evaluation"]
  node_domain_db[("Domain database")]
  node_redis[("Redis cache<br/>[redis_client.py]")]
end

node_staff(("Operations staff"))
node_keycloak_service(("Keycloak"))
node_llm(("LLM provider"))

node_staff -->|"uses"| node_frontend
node_frontend -->|"authenticates"| node_login
node_login -->|"exchanges tokens"| node_oauth
node_oauth -->|"requests tokens"| node_keycloak_service
node_frontend -->|"renders"| node_assistant
node_assistant -->|"submits chat"| node_api_client
node_api_client -->|"posts chat"| node_api
node_api -->|"routes requests"| node_chat_route
node_chat_route -.->|"invokes agent"| node_agent_service
node_agent_service -->|"runs graph"| node_graph
node_graph -.->|"dispatches"| node_router
node_graph -.->|"runs workflow"| node_investigation
node_graph -.->|"checks input"| node_guardrails
node_agent_service -->|"connects tools"| node_mcp_client
node_mcp_client -->|"calls MCP"| node_mcp_server
node_mcp_server -->|"loads tools"| node_registry
node_registry -->|"registers"| node_business_tools
node_business_tools -->|"invokes operations"| node_business_service
node_business_tools -->|"gets authorization"| node_auth_context
node_auth_context -->|"verifies token"| node_keycloak
node_auth_context -->|"loads staff user"| node_user_repo
node_business_service -->|"queries domain"| node_read_repo
node_business_service -->|"updates domain"| node_write_repo
node_user_repo -.->|"reads users"| node_domain_db
node_read_repo -.->|"reads cases"| node_domain_db
node_write_repo -.->|"writes cases"| node_domain_db
node_agent_service -->|"stores conversation"| node_redis
node_agent_service -.->|"records runs"| node_evaluation
node_agent_service -.->|"generates response"| node_llm

click node_frontend "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/app.py"
click node_login "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/auth/session.py"
click node_oauth "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/auth/oauth.py"
click node_assistant "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/ui/assistant.py"
click node_api_client "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/client/api_client.py"
click node_api "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/api/app.py"
click node_chat_route "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/api/routes/chat.py"
click node_agent_service "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/service.py"
click node_graph "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/graph_builder.py"
click node_router "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/nodes/router_node.py"
click node_investigation "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/skills/investigation_workflow.py"
click node_guardrails "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/nodes/input_guardrail_node.py"
click node_evaluation "https://github.com/codebykarthik/natwest-case-investigation-agent/tree/main/natwest-backend/src/natwest_backend/agent/evaluation"
click node_mcp_client "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/mcp_client/client_connection.py"
click node_mcp_server "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-mcp/src/natwest_mcp/mcp/server.py"
click node_registry "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-mcp/src/natwest_mcp/mcp/tools/tool_registry.py"
click node_business_tools "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-mcp/src/natwest_mcp/mcp/tools/business_tools.py"
click node_auth_context "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/services/auth_context_service.py"
click node_keycloak "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/auth/keycloak.py"
click node_business_service "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/services/business_service.py"
click node_read_repo "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/db/repositories/business_read_repository.py"
click node_write_repo "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/db/repositories/business_write_repository.py"
click node_user_repo "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/db/repositories/user_repository.py"
click node_domain_db "https://github.com/codebykarthik/natwest-case-investigation-agent/tree/main/natwest-shared/src/natwest_shared/db"
click node_redis "https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/cache/redis_client.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_frontend,node_login,node_oauth,node_assistant,node_api_client toneBlue
class node_api,node_chat_route,node_agent_service,node_graph,node_router,node_investigation,node_guardrails,node_evaluation,node_mcp_client toneAmber
class node_mcp_server,node_registry,node_business_tools toneMint
class node_auth_context,node_keycloak,node_business_service,node_read_repo,node_write_repo,node_user_repo toneRose
class node_domain_db,node_redis,node_staff,node_keycloak_service,node_llm toneIndigo
```

## Components

### Staff experience

- [Staff UI](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/app.py): `natwest-frontend/src/natwest_frontend/app.py`
- [Sign-in session](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/auth/session.py): `natwest-frontend/src/natwest_frontend/auth/session.py`
- [OAuth client](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/auth/oauth.py): `natwest-frontend/src/natwest_frontend/auth/oauth.py`
- [Assistant chat](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/ui/assistant.py): `natwest-frontend/src/natwest_frontend/ui/assistant.py`
- [Backend client](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-frontend/src/natwest_frontend/client/api_client.py): `natwest-frontend/src/natwest_frontend/client/api_client.py`

### API and agent

- [Backend API](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/api/app.py): `natwest-backend/src/natwest_backend/api/app.py`
- [Chat endpoint](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/api/routes/chat.py): `natwest-backend/src/natwest_backend/api/routes/chat.py`
- [Agent service](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/service.py): `natwest-backend/src/natwest_backend/agent/service.py`
- [Agent graph](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/graph_builder.py): `natwest-backend/src/natwest_backend/agent/graph_builder.py`
- [Intent router](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/nodes/router_node.py): `natwest-backend/src/natwest_backend/agent/nodes/router_node.py`
- [Investigation flow](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/skills/investigation_workflow.py): `natwest-backend/src/natwest_backend/agent/skills/investigation_workflow.py`
- [Input guardrails](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/nodes/input_guardrail_node.py): `natwest-backend/src/natwest_backend/agent/nodes/input_guardrail_node.py`
- [Evaluation hooks](https://github.com/codebykarthik/natwest-case-investigation-agent/tree/main/natwest-backend/src/natwest_backend/agent/evaluation): `natwest-backend/src/natwest_backend/agent/evaluation`
- [MCP client](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/mcp_client/client_connection.py): `natwest-backend/src/natwest_backend/agent/mcp_client/client_connection.py`

### Business tools

- [MCP server](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-mcp/src/natwest_mcp/mcp/server.py): `natwest-mcp/src/natwest_mcp/mcp/server.py`
- [Tool registry](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-mcp/src/natwest_mcp/mcp/tools/tool_registry.py): `natwest-mcp/src/natwest_mcp/mcp/tools/tool_registry.py`
- [Case operations](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-mcp/src/natwest_mcp/mcp/tools/business_tools.py): `natwest-mcp/src/natwest_mcp/mcp/tools/business_tools.py`

### Shared domain

- [Auth context](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/services/auth_context_service.py): `natwest-shared/src/natwest_shared/services/auth_context_service.py`
- [Token verifier](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/auth/keycloak.py): `natwest-shared/src/natwest_shared/auth/keycloak.py`
- [Business services](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/services/business_service.py): `natwest-shared/src/natwest_shared/services/business_service.py`
- [Case and customer reads](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/db/repositories/business_read_repository.py): `natwest-shared/src/natwest_shared/db/repositories/business_read_repository.py`
- [Case updates](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/db/repositories/business_write_repository.py): `natwest-shared/src/natwest_shared/db/repositories/business_write_repository.py`
- [Staff user records](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-shared/src/natwest_shared/db/repositories/user_repository.py): `natwest-shared/src/natwest_shared/db/repositories/user_repository.py`

### Persistence and evaluation

- [Domain database](https://github.com/codebykarthik/natwest-case-investigation-agent/tree/main/natwest-shared/src/natwest_shared/db): `natwest-shared/src/natwest_shared/db`
- [Redis cache](https://github.com/codebykarthik/natwest-case-investigation-agent/blob/main/natwest-backend/src/natwest_backend/agent/cache/redis_client.py): `natwest-backend/src/natwest_backend/agent/cache/redis_client.py`

### Other components

- **Operations staff**
- **Keycloak**
- **LLM provider**

## Connections

- Operations staff → Staff UI: uses (evidence: `README.md`)
- Staff UI → Sign-in session: authenticates (evidence: `natwest-frontend/src/natwest_frontend/app.py`)
- Sign-in session → OAuth client: exchanges tokens (evidence: `natwest-frontend/src/natwest_frontend/auth/session.py`)
- OAuth client → Keycloak: requests tokens (evidence: `natwest-frontend/src/natwest_frontend/auth/oauth.py`)
- Staff UI → Assistant chat: renders (evidence: `natwest-frontend/src/natwest_frontend/app.py`)
- Assistant chat → Backend client: submits chat (evidence: `natwest-frontend/src/natwest_frontend/ui/assistant.py`)
- Backend client → Backend API: posts chat (evidence: `natwest-frontend/src/natwest_frontend/client/api_client.py`)
- Backend API → Chat endpoint: routes requests (evidence: `natwest-backend/src/natwest_backend/api/app.py`)
- Chat endpoint → Agent service: invokes agent
- Agent service → Agent graph: runs graph (evidence: `natwest-backend/src/natwest_backend/agent/service.py`)
- Agent graph → Intent router: dispatches
- Agent graph → Investigation flow: runs workflow
- Agent graph → Input guardrails: checks input
- Agent service → MCP client: connects tools (evidence: `natwest-backend/src/natwest_backend/agent/service.py`)
- MCP client → MCP server: calls MCP (evidence: `natwest-backend/src/natwest_backend/agent/mcp_client/client_connection.py`)
- MCP server → Tool registry: loads tools (evidence: `natwest-mcp/src/natwest_mcp/mcp/server.py`)
- Tool registry → Case operations: registers (evidence: `natwest-mcp/src/natwest_mcp/mcp/tools/tool_registry.py`)
- Case operations → Business services: invokes operations (evidence: `natwest-mcp/src/natwest_mcp/mcp/tools/business_tools.py`)
- Case operations → Auth context: gets authorization
- Auth context → Token verifier: verifies token (evidence: `natwest-shared/src/natwest_shared/services/auth_context_service.py`)
- Auth context → Staff user records: loads staff user (evidence: `natwest-shared/src/natwest_shared/services/auth_context_service.py`)
- Business services → Case and customer reads: queries domain (evidence: `natwest-shared/src/natwest_shared/services/business_service.py`)
- Business services → Case updates: updates domain (evidence: `natwest-shared/src/natwest_shared/services/business_service.py`)
- Staff user records → Domain database: reads users (evidence: `natwest-shared/src/natwest_shared/db/repositories/user_repository.py`)
- Case and customer reads → Domain database: reads cases (evidence: `natwest-shared/src/natwest_shared/db/repositories/business_read_repository.py`)
- Case updates → Domain database: writes cases (evidence: `natwest-shared/src/natwest_shared/db/repositories/business_write_repository.py`)
- Agent service → Redis cache: stores conversation (evidence: `natwest-backend/src/natwest_backend/agent/service.py`)
- Agent service → Evaluation hooks: records runs
- Agent service → LLM provider: generates response
