# madhankumar98/clearset-ai architecture

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

- Interactive diagram: https://gitdiagram.com/madhankumar98/clearset-ai
- Repository: https://github.com/madhankumar98/clearset-ai

## Overview

ClearSet AI is a post-trade settlement operations copilot. Analysts review detected exceptions, inspect deterministic risk factors, run a procedural investigation with policy and historical evidence, and make the required human authorization decision. The React client uses a shared application context and API client; the Express backend provides Snowflake-backed data and reporting. README capabilities also include impact metrics, predictive risk, settlement-chain visualization, CoCo replay, and optional Slack notifications. Some links are documented rather than verified from source excerpts; those are marked accordingly.

Main entry points: [`src/App.tsx`](https://github.com/madhankumar98/clearset-ai/blob/main/src/App.tsx) (Application Shell), [`server/index.ts`](https://github.com/madhankumar98/clearset-ai/blob/main/server/index.ts) (Express API), [`src/services/apiClient.ts`](https://github.com/madhankumar98/clearset-ai/blob/main/src/services/apiClient.ts) (Frontend API Client), [`src/context/AppContext.tsx`](https://github.com/madhankumar98/clearset-ai/blob/main/src/context/AppContext.tsx) (Application State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Analyst Console"]
  node_app["Application Shell<br/>[App.tsx]"]
  node_exceptions["Exception Queue<br/>[ExceptionsView.tsx]"]
  node_dashboard["Operations Dashboard<br/>[DashboardView.tsx]"]
  node_investigation["Investigation Workspace"]
  node_cases["Cases Ledger<br/>[CasesView.tsx]"]
  node_copilot["Copilot View<br/>[CopilotView.tsx]"]
  node_policies["Policy Library View<br/>[PoliciesView.tsx]"]
  node_coco["CoCo Replay Panel"]
  node_chainviz["Settlement Chain View"]
  node_predictionpanel["Prediction Panel"]
  node_impacttile["Impact Metrics Tile"]
end

subgraph group_domain["Settlement Intelligence"]
  node_appctx["Application State<br/>[AppContext.tsx]"]
  node_settlement["Settlement Data Service"]
  node_risk["Deterministic Risk Engine<br/>[riskEngine.ts]"]
  node_orchestrator["Investigation Orchestrator"]
  node_policystore[("SOP Knowledge Base<br/>[knowledgeBase.ts]")]
  node_localdata[("Local Trade Data<br/>[syntheticData.ts]")]
  node_cortex["Cortex Service<br/>[cortexService.ts]"]
end

subgraph group_backend["Backend Services"]
  node_api["Frontend API Client<br/>[apiClient.ts]"]
  node_server["Express API<br/>[index.ts]"]
  node_predict["Prediction API<br/>[predict.ts]"]
  node_predictor["Predictive Engine"]
  node_metrics["Impact Metrics<br/>[metricsService.ts]"]
  node_report["Audit Reports"]
end

subgraph group_integrations["Data and Integrations"]
  node_snowflake[("Snowflake Client<br/>[snowflakeClient.ts]")]
  node_slack["Slack Notifications<br/>[slackService.ts]"]
  node_snowflake_service[("Snowflake Cortex")]
end

node_analyst(("Operations Analyst"))

node_analyst -->|"uses"| node_app
node_app -->|"routes to"| node_exceptions
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_investigation
node_app -->|"routes to"| node_cases
node_app -->|"routes to"| node_copilot
node_app -->|"routes to"| node_policies
node_app -->|"provides state"| node_appctx
node_appctx -->|"loads exceptions"| node_settlement
node_appctx -->|"runs investigation"| node_cortex
node_appctx -->|"checks status"| node_api
node_settlement -->|"fetches data"| node_api
node_settlement -->|"falls back to"| node_localdata
node_localdata -->|"scores trades"| node_risk
node_cortex -->|"delegates steps"| node_orchestrator
node_cortex -->|"requests Cortex"| node_api
node_orchestrator -->|"calculates score"| node_risk
node_orchestrator -->|"uses procedures"| node_policystore
node_exceptions -->|"reads queue"| node_appctx
node_investigation -->|"advances workflow"| node_appctx
node_investigation -->|"displays evidence"| node_orchestrator
node_investigation -->|"shows risk math"| node_risk
node_policies -->|"displays procedures"| node_policystore
node_cases -->|"loads cases"| node_api
node_dashboard -->|"renders metrics"| node_impacttile
node_dashboard -->|"renders forecasts"| node_predictionpanel
node_dashboard -->|"renders settlement chain"| node_chainviz
node_dashboard -->|"renders replay"| node_coco
node_api -->|"calls API"| node_server
node_server -->|"queries"| node_snowflake
node_server -.->|"uses Cortex"| node_snowflake_service
node_server -->|"computes metrics"| node_metrics
node_server -->|"generates reports"| node_report
node_server -->|"notifies optionally"| node_slack
node_server -->|"mounts routes"| node_predict
node_predict -->|"runs predictions"| node_predictor
node_impacttile -->|"fetches metrics"| node_api
node_predictionpanel -->|"requests predictions"| node_api
node_chainviz -->|"fetches chain data"| node_api

click node_app "https://github.com/madhankumar98/clearset-ai/blob/main/src/App.tsx"
click node_exceptions "https://github.com/madhankumar98/clearset-ai/blob/main/src/views/ExceptionsView.tsx"
click node_dashboard "https://github.com/madhankumar98/clearset-ai/blob/main/src/views/DashboardView.tsx"
click node_investigation "https://github.com/madhankumar98/clearset-ai/blob/main/src/views/InvestigationView.tsx"
click node_cases "https://github.com/madhankumar98/clearset-ai/blob/main/src/views/CasesView.tsx"
click node_copilot "https://github.com/madhankumar98/clearset-ai/blob/main/src/views/CopilotView.tsx"
click node_policies "https://github.com/madhankumar98/clearset-ai/blob/main/src/views/PoliciesView.tsx"
click node_appctx "https://github.com/madhankumar98/clearset-ai/blob/main/src/context/AppContext.tsx"
click node_settlement "https://github.com/madhankumar98/clearset-ai/blob/main/src/services/settlementService.ts"
click node_risk "https://github.com/madhankumar98/clearset-ai/blob/main/src/engine/riskEngine.ts"
click node_orchestrator "https://github.com/madhankumar98/clearset-ai/blob/main/src/engine/agentOrchestrator.ts"
click node_policystore "https://github.com/madhankumar98/clearset-ai/blob/main/src/data/knowledgeBase.ts"
click node_localdata "https://github.com/madhankumar98/clearset-ai/blob/main/src/data/syntheticData.ts"
click node_cortex "https://github.com/madhankumar98/clearset-ai/blob/main/src/services/cortexService.ts"
click node_api "https://github.com/madhankumar98/clearset-ai/blob/main/src/services/apiClient.ts"
click node_server "https://github.com/madhankumar98/clearset-ai/blob/main/server/index.ts"
click node_predict "https://github.com/madhankumar98/clearset-ai/blob/main/server/routes/predict.ts"
click node_predictor "https://github.com/madhankumar98/clearset-ai/blob/main/server/services/predictiveEngine.ts"
click node_metrics "https://github.com/madhankumar98/clearset-ai/blob/main/server/services/metricsService.ts"
click node_report "https://github.com/madhankumar98/clearset-ai/blob/main/server/services/auditReportService.ts"
click node_snowflake "https://github.com/madhankumar98/clearset-ai/blob/main/server/snowflakeClient.ts"
click node_slack "https://github.com/madhankumar98/clearset-ai/blob/main/server/services/slackService.ts"
click node_coco "https://github.com/madhankumar98/clearset-ai/blob/main/src/components/CocoReplayPanel.tsx"
click node_chainviz "https://github.com/madhankumar98/clearset-ai/blob/main/src/components/SettlementChainViz.tsx"
click node_predictionpanel "https://github.com/madhankumar98/clearset-ai/blob/main/src/components/PredictionPanel.tsx"
click node_impacttile "https://github.com/madhankumar98/clearset-ai/blob/main/src/components/ImpactMetricsTile.tsx"

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_app,node_exceptions,node_dashboard,node_investigation,node_cases,node_copilot,node_policies,node_coco,node_chainviz,node_predictionpanel,node_impacttile toneBlue
class node_appctx,node_settlement,node_risk,node_orchestrator,node_policystore,node_localdata,node_cortex toneAmber
class node_api,node_server,node_predict,node_predictor,node_metrics,node_report toneMint
class node_snowflake,node_slack,node_snowflake_service toneRose
class node_analyst toneIndigo
```

## Components

### Analyst Console

- [Application Shell](https://github.com/madhankumar98/clearset-ai/blob/main/src/App.tsx): `src/App.tsx`
- [Exception Queue](https://github.com/madhankumar98/clearset-ai/blob/main/src/views/ExceptionsView.tsx): `src/views/ExceptionsView.tsx`
- [Operations Dashboard](https://github.com/madhankumar98/clearset-ai/blob/main/src/views/DashboardView.tsx): `src/views/DashboardView.tsx`
- [Investigation Workspace](https://github.com/madhankumar98/clearset-ai/blob/main/src/views/InvestigationView.tsx): `src/views/InvestigationView.tsx`
- [Cases Ledger](https://github.com/madhankumar98/clearset-ai/blob/main/src/views/CasesView.tsx): `src/views/CasesView.tsx`
- [Copilot View](https://github.com/madhankumar98/clearset-ai/blob/main/src/views/CopilotView.tsx): `src/views/CopilotView.tsx`
- [Policy Library View](https://github.com/madhankumar98/clearset-ai/blob/main/src/views/PoliciesView.tsx): `src/views/PoliciesView.tsx`
- [CoCo Replay Panel](https://github.com/madhankumar98/clearset-ai/blob/main/src/components/CocoReplayPanel.tsx): `src/components/CocoReplayPanel.tsx`
- [Settlement Chain View](https://github.com/madhankumar98/clearset-ai/blob/main/src/components/SettlementChainViz.tsx): `src/components/SettlementChainViz.tsx`
- [Prediction Panel](https://github.com/madhankumar98/clearset-ai/blob/main/src/components/PredictionPanel.tsx): `src/components/PredictionPanel.tsx`
- [Impact Metrics Tile](https://github.com/madhankumar98/clearset-ai/blob/main/src/components/ImpactMetricsTile.tsx): `src/components/ImpactMetricsTile.tsx`

### Settlement Intelligence

- [Application State](https://github.com/madhankumar98/clearset-ai/blob/main/src/context/AppContext.tsx): `src/context/AppContext.tsx`
- [Settlement Data Service](https://github.com/madhankumar98/clearset-ai/blob/main/src/services/settlementService.ts): `src/services/settlementService.ts`
- [Deterministic Risk Engine](https://github.com/madhankumar98/clearset-ai/blob/main/src/engine/riskEngine.ts): `src/engine/riskEngine.ts`
- [Investigation Orchestrator](https://github.com/madhankumar98/clearset-ai/blob/main/src/engine/agentOrchestrator.ts): `src/engine/agentOrchestrator.ts`
- [SOP Knowledge Base](https://github.com/madhankumar98/clearset-ai/blob/main/src/data/knowledgeBase.ts): `src/data/knowledgeBase.ts`
- [Local Trade Data](https://github.com/madhankumar98/clearset-ai/blob/main/src/data/syntheticData.ts): `src/data/syntheticData.ts`
- [Cortex Service](https://github.com/madhankumar98/clearset-ai/blob/main/src/services/cortexService.ts): `src/services/cortexService.ts`

### Backend Services

- [Frontend API Client](https://github.com/madhankumar98/clearset-ai/blob/main/src/services/apiClient.ts): `src/services/apiClient.ts`
- [Express API](https://github.com/madhankumar98/clearset-ai/blob/main/server/index.ts): `server/index.ts`
- [Prediction API](https://github.com/madhankumar98/clearset-ai/blob/main/server/routes/predict.ts): `server/routes/predict.ts`
- [Predictive Engine](https://github.com/madhankumar98/clearset-ai/blob/main/server/services/predictiveEngine.ts): `server/services/predictiveEngine.ts`
- [Impact Metrics](https://github.com/madhankumar98/clearset-ai/blob/main/server/services/metricsService.ts): `server/services/metricsService.ts`
- [Audit Reports](https://github.com/madhankumar98/clearset-ai/blob/main/server/services/auditReportService.ts): `server/services/auditReportService.ts`

### Data and Integrations

- [Snowflake Client](https://github.com/madhankumar98/clearset-ai/blob/main/server/snowflakeClient.ts): `server/snowflakeClient.ts`
- [Slack Notifications](https://github.com/madhankumar98/clearset-ai/blob/main/server/services/slackService.ts): `server/services/slackService.ts`
- **Snowflake Cortex**

### Other components

- **Operations Analyst**

## Connections

- Operations Analyst → Application Shell: uses (evidence: `README.md`)
- Application Shell → Exception Queue: routes to (evidence: `src/App.tsx`)
- Application Shell → Operations Dashboard: routes to (evidence: `src/App.tsx`)
- Application Shell → Investigation Workspace: routes to (evidence: `src/App.tsx`)
- Application Shell → Cases Ledger: routes to (evidence: `src/App.tsx`)
- Application Shell → Copilot View: routes to (evidence: `src/App.tsx`)
- Application Shell → Policy Library View: routes to (evidence: `src/App.tsx`)
- Application Shell → Application State: provides state (evidence: `src/App.tsx`)
- Application State → Settlement Data Service: loads exceptions (evidence: `src/context/AppContext.tsx`)
- Application State → Cortex Service: runs investigation (evidence: `src/context/AppContext.tsx`)
- Application State → Frontend API Client: checks status (evidence: `src/context/AppContext.tsx`)
- Settlement Data Service → Frontend API Client: fetches data (evidence: `src/services/settlementService.ts`)
- Settlement Data Service → Local Trade Data: falls back to (evidence: `src/services/settlementService.ts`)
- Local Trade Data → Deterministic Risk Engine: scores trades (evidence: `src/data/syntheticData.ts`)
- Cortex Service → Investigation Orchestrator: delegates steps (evidence: `src/services/cortexService.ts`)
- Cortex Service → Frontend API Client: requests Cortex (evidence: `src/services/cortexService.ts`)
- Investigation Orchestrator → Deterministic Risk Engine: calculates score (evidence: `src/engine/agentOrchestrator.ts`)
- Investigation Orchestrator → SOP Knowledge Base: uses procedures (evidence: `src/engine/agentOrchestrator.ts`)
- Exception Queue → Application State: reads queue (evidence: `src/views/ExceptionsView.tsx`)
- Investigation Workspace → Application State: advances workflow (evidence: `src/views/InvestigationView.tsx`)
- Investigation Workspace → Investigation Orchestrator: displays evidence (evidence: `src/views/InvestigationView.tsx`)
- Investigation Workspace → Deterministic Risk Engine: shows risk math (evidence: `src/views/InvestigationView.tsx`)
- Policy Library View → SOP Knowledge Base: displays procedures (evidence: `src/views/PoliciesView.tsx`)
- Cases Ledger → Frontend API Client: loads cases (evidence: `src/views/CasesView.tsx`)
- Operations Dashboard → Impact Metrics Tile: renders metrics (evidence: `src/views/DashboardView.tsx`)
- Operations Dashboard → Prediction Panel: renders forecasts (evidence: `src/views/DashboardView.tsx`)
- Operations Dashboard → Settlement Chain View: renders settlement chain (evidence: `src/views/DashboardView.tsx`)
- Operations Dashboard → CoCo Replay Panel: renders replay (evidence: `src/views/DashboardView.tsx`)
- Frontend API Client → Express API: calls API (evidence: `src/services/apiClient.ts`)
- Express API → Snowflake Client: queries (evidence: `server/index.ts`)
- Express API → Snowflake Cortex: uses Cortex (evidence: `README.md`)
- Express API → Impact Metrics: computes metrics (evidence: `server/index.ts`)
- Express API → Audit Reports: generates reports (evidence: `server/index.ts`)
- Express API → Slack Notifications: notifies optionally (evidence: `server/index.ts`)
- Express API → Prediction API: mounts routes (evidence: `server/index.ts`)
- Prediction API → Predictive Engine: runs predictions (evidence: `server/routes/predict.ts`)
- Impact Metrics Tile → Frontend API Client: fetches metrics (evidence: `src/components/ImpactMetricsTile.tsx`)
- Prediction Panel → Frontend API Client: requests predictions (evidence: `src/components/PredictionPanel.tsx`)
- Settlement Chain View → Frontend API Client: fetches chain data (evidence: `src/components/SettlementChainViz.tsx`)
