# sanchitkumar18/risklens architecture

> Architecture diagram of the GitHub repository sanchitkumar18/risklens, 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/sanchitkumar18/risklens
- Repository: https://github.com/sanchitkumar18/risklens

## Overview

RiskLens is a market-risk analytics platform with a Streamlit dashboard and FastAPI service. Users ingest market data, create portfolios, and request valuation, risk metrics, stress tests, anomaly scans, and alerts; the API-backed dashboard presents the results. A grounded assistant retrieves analytical results through service-wrapping tools and explains them. The graph preserves the documented ingestion stages and analytics branches. Some route and assistant internals were not sampled, so those links rely on README statements or are omitted where wiring is uncertain.

Main entry points: [`app/main.py`](https://github.com/sanchitkumar18/risklens/blob/main/app/main.py) (FastAPI app), [`app/services/risk_service.py`](https://github.com/sanchitkumar18/risklens/blob/main/app/services/risk_service.py) (Risk service), [`app/services/anomaly_service.py`](https://github.com/sanchitkumar18/risklens/blob/main/app/services/anomaly_service.py) (Anomaly service), [`app/services/portfolio_service.py`](https://github.com/sanchitkumar18/risklens/blob/main/app/services/portfolio_service.py) (Portfolio service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_dashboard["Dashboard<br/>[app.py]"]
  node_dashboard_views["Dashboard views"]
  node_http_client["HTTP client<br/>[api_client.py]"]
end

subgraph group_api["API layer"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_dependencies["Service wiring<br/>[dependencies.py]"]
  node_market_routes["Market-data routes<br/>[market_data.py]"]
  node_portfolio_routes["Portfolio routes<br/>[portfolios.py]"]
  node_risk_routes["Risk routes<br/>[risk.py]"]
  node_stress_routes["Stress routes<br/>[stress.py]"]
  node_anomaly_routes["Anomaly routes<br/>[anomalies.py]"]
  node_alert_routes["Alert routes<br/>[alerts.py]"]
  node_assistant_route["Assistant route<br/>[assistant.py]"]
end

subgraph group_market["Market data"]
  node_market_service["Market-data service"]
  node_ingestion["Ingestion pipeline<br/>[ingestion.py]"]
  node_validation["Validation and cleaning<br/>[validation.py]"]
  node_transformation["Feature transformation<br/>[transformation.py]"]
end

subgraph group_portfolio["Portfolio and storage"]
  node_portfolio_service["Portfolio service"]
  node_database[("Relational database<br/>[database.py]")]
  node_market_repo["Market-data repository"]
end

subgraph group_analytics["Risk analytics"]
  node_risk_service["Risk service<br/>[risk_service.py]"]
  node_risk_engine["Risk calculations"]
  node_stress_service["Stress service<br/>[stress_service.py]"]
  node_stress_engine["Stress engine<br/>[stress_testing.py]"]
  node_anomaly_service["Anomaly service<br/>[anomaly_service.py]"]
  node_anomaly_detector["Anomaly detection"]
  node_alert_service["Alert service<br/>[alert_service.py]"]
  node_alert_rules["Alert rules<br/>[alert_rules.py]"]
end

subgraph group_assistant["Grounded assistant"]
  node_assistant_service["Assistant service"]
  node_assistant_graph["Assistant graph<br/>[graph.py]"]
  node_assistant_tools["Grounded tools<br/>[tools.py]"]
  node_assistant_retrieve["Tool retrieval<br/>[retrieve.py]"]
  node_assistant_explain["Answer explanation<br/>[explain.py]"]
  node_assistant_validate["Grounding validation<br/>[validate.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_dashboard_views
node_dashboard -->|"creates"| node_http_client
node_dashboard_views -->|"requests data"| node_http_client
node_http_client -->|"HTTP requests"| node_api_app
node_api_app -->|"registers"| node_market_routes
node_api_app -->|"registers"| node_portfolio_routes
node_api_app -->|"registers"| node_risk_routes
node_api_app -->|"registers"| node_stress_routes
node_api_app -->|"registers"| node_anomaly_routes
node_api_app -->|"registers"| node_alert_routes
node_api_app -->|"registers"| node_assistant_route
node_market_routes -->|"gets service"| node_dependencies
node_portfolio_routes -->|"gets service"| node_dependencies
node_risk_routes -->|"gets service"| node_dependencies
node_market_routes -->|"calls"| node_market_service
node_portfolio_routes -->|"calls"| node_portfolio_service
node_risk_routes -->|"calls"| node_risk_service
node_market_service -->|"ingests"| node_ingestion
node_market_service -->|"validates"| node_validation
node_market_service -->|"upserts bars"| node_market_repo
node_portfolio_service -->|"reads prices"| node_market_repo
node_portfolio_service -.->|"stores portfolio data"| node_database
node_risk_service -->|"values portfolio"| node_portfolio_service
node_risk_service -->|"loads prices"| node_market_repo
node_risk_service -->|"builds features"| node_transformation
node_risk_service -->|"computes metrics"| node_risk_engine
node_stress_routes -.->|"runs tests"| node_stress_service
node_stress_service -->|"values portfolio"| node_portfolio_service
node_stress_service -->|"applies shocks"| node_stress_engine
node_anomaly_routes -->|"scans"| node_anomaly_service
node_anomaly_service -->|"gets holdings"| node_portfolio_service
node_anomaly_service -->|"loads bars"| node_market_repo
node_anomaly_service -->|"engineers features"| node_transformation
node_anomaly_service -->|"detects anomalies"| node_anomaly_detector
node_alert_routes -->|"evaluates"| node_alert_service
node_alert_service -->|"computes risk"| node_risk_service
node_alert_service -->|"scans anomalies"| node_anomaly_service
node_alert_service -->|"runs scenarios"| node_stress_service
node_alert_service -->|"grades breaches"| node_alert_rules
node_assistant_route -.->|"handles query"| node_assistant_service
node_assistant_service -.->|"runs graph"| node_assistant_graph
node_assistant_graph -.->|"retrieves"| node_assistant_retrieve
node_assistant_retrieve -->|"invokes tools"| node_assistant_tools
node_assistant_tools -->|"queries risk"| node_risk_service
node_assistant_tools -->|"queries portfolio"| node_portfolio_service
node_assistant_tools -->|"runs stress"| node_stress_service
node_assistant_tools -->|"queries anomalies"| node_anomaly_service

click node_dashboard "https://github.com/sanchitkumar18/risklens/blob/main/dashboard/app.py"
click node_dashboard_views "https://github.com/sanchitkumar18/risklens/tree/main/dashboard/views"
click node_http_client "https://github.com/sanchitkumar18/risklens/blob/main/dashboard/api_client.py"
click node_api_app "https://github.com/sanchitkumar18/risklens/blob/main/app/main.py"
click node_dependencies "https://github.com/sanchitkumar18/risklens/blob/main/app/api/dependencies.py"
click node_market_routes "https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/market_data.py"
click node_portfolio_routes "https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/portfolios.py"
click node_risk_routes "https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/risk.py"
click node_stress_routes "https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/stress.py"
click node_anomaly_routes "https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/anomalies.py"
click node_alert_routes "https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/alerts.py"
click node_assistant_route "https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/assistant.py"
click node_market_service "https://github.com/sanchitkumar18/risklens/blob/main/app/services/market_data_service.py"
click node_ingestion "https://github.com/sanchitkumar18/risklens/blob/main/app/pipelines/ingestion.py"
click node_validation "https://github.com/sanchitkumar18/risklens/blob/main/app/pipelines/validation.py"
click node_transformation "https://github.com/sanchitkumar18/risklens/blob/main/app/pipelines/transformation.py"
click node_portfolio_service "https://github.com/sanchitkumar18/risklens/blob/main/app/services/portfolio_service.py"
click node_database "https://github.com/sanchitkumar18/risklens/blob/main/app/db/database.py"
click node_market_repo "https://github.com/sanchitkumar18/risklens/blob/main/app/db/repositories/market_data_repo.py"
click node_risk_service "https://github.com/sanchitkumar18/risklens/blob/main/app/services/risk_service.py"
click node_risk_engine "https://github.com/sanchitkumar18/risklens/tree/main/app/risk"
click node_stress_service "https://github.com/sanchitkumar18/risklens/blob/main/app/services/stress_service.py"
click node_stress_engine "https://github.com/sanchitkumar18/risklens/blob/main/app/risk/stress_testing.py"
click node_anomaly_service "https://github.com/sanchitkumar18/risklens/blob/main/app/services/anomaly_service.py"
click node_anomaly_detector "https://github.com/sanchitkumar18/risklens/blob/main/app/analytics/anomaly_detection.py"
click node_alert_service "https://github.com/sanchitkumar18/risklens/blob/main/app/services/alert_service.py"
click node_alert_rules "https://github.com/sanchitkumar18/risklens/blob/main/app/analytics/alert_rules.py"
click node_assistant_service "https://github.com/sanchitkumar18/risklens/blob/main/app/services/assistant_service.py"
click node_assistant_graph "https://github.com/sanchitkumar18/risklens/blob/main/app/llm/graph.py"
click node_assistant_tools "https://github.com/sanchitkumar18/risklens/blob/main/app/llm/tools.py"
click node_assistant_retrieve "https://github.com/sanchitkumar18/risklens/blob/main/app/llm/nodes/retrieve.py"
click node_assistant_explain "https://github.com/sanchitkumar18/risklens/blob/main/app/llm/nodes/explain.py"
click node_assistant_validate "https://github.com/sanchitkumar18/risklens/blob/main/app/llm/nodes/validate.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_dashboard,node_dashboard_views,node_http_client,node_user toneBlue
class node_api_app,node_dependencies,node_market_routes,node_portfolio_routes,node_risk_routes,node_stress_routes,node_anomaly_routes,node_alert_routes,node_assistant_route toneAmber
class node_market_service,node_ingestion,node_validation,node_transformation toneMint
class node_portfolio_service,node_database,node_market_repo toneRose
class node_risk_service,node_risk_engine,node_stress_service,node_stress_engine,node_anomaly_service,node_anomaly_detector,node_alert_service,node_alert_rules toneIndigo
class node_assistant_service,node_assistant_graph,node_assistant_tools,node_assistant_retrieve,node_assistant_explain,node_assistant_validate toneTeal
```

## Components

### User experience

- [Dashboard](https://github.com/sanchitkumar18/risklens/blob/main/dashboard/app.py): `dashboard/app.py`
- [Dashboard views](https://github.com/sanchitkumar18/risklens/tree/main/dashboard/views): `dashboard/views`
- [HTTP client](https://github.com/sanchitkumar18/risklens/blob/main/dashboard/api_client.py): `dashboard/api_client.py`

### API layer

- [FastAPI app](https://github.com/sanchitkumar18/risklens/blob/main/app/main.py): `app/main.py`
- [Service wiring](https://github.com/sanchitkumar18/risklens/blob/main/app/api/dependencies.py): `app/api/dependencies.py`
- [Market-data routes](https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/market_data.py): `app/api/routes/market_data.py`
- [Portfolio routes](https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/portfolios.py): `app/api/routes/portfolios.py`
- [Risk routes](https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/risk.py): `app/api/routes/risk.py`
- [Stress routes](https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/stress.py): `app/api/routes/stress.py`
- [Anomaly routes](https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/anomalies.py): `app/api/routes/anomalies.py`
- [Alert routes](https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/alerts.py): `app/api/routes/alerts.py`
- [Assistant route](https://github.com/sanchitkumar18/risklens/blob/main/app/api/routes/assistant.py): `app/api/routes/assistant.py`

### Market data

- [Market-data service](https://github.com/sanchitkumar18/risklens/blob/main/app/services/market_data_service.py): `app/services/market_data_service.py`
- [Ingestion pipeline](https://github.com/sanchitkumar18/risklens/blob/main/app/pipelines/ingestion.py): `app/pipelines/ingestion.py`
- [Validation and cleaning](https://github.com/sanchitkumar18/risklens/blob/main/app/pipelines/validation.py): `app/pipelines/validation.py`
- [Feature transformation](https://github.com/sanchitkumar18/risklens/blob/main/app/pipelines/transformation.py): `app/pipelines/transformation.py`

### Portfolio and storage

- [Portfolio service](https://github.com/sanchitkumar18/risklens/blob/main/app/services/portfolio_service.py): `app/services/portfolio_service.py`
- [Relational database](https://github.com/sanchitkumar18/risklens/blob/main/app/db/database.py): `app/db/database.py`
- [Market-data repository](https://github.com/sanchitkumar18/risklens/blob/main/app/db/repositories/market_data_repo.py): `app/db/repositories/market_data_repo.py`

### Risk analytics

- [Risk service](https://github.com/sanchitkumar18/risklens/blob/main/app/services/risk_service.py): `app/services/risk_service.py`
- [Risk calculations](https://github.com/sanchitkumar18/risklens/tree/main/app/risk): `app/risk`
- [Stress service](https://github.com/sanchitkumar18/risklens/blob/main/app/services/stress_service.py): `app/services/stress_service.py`
- [Stress engine](https://github.com/sanchitkumar18/risklens/blob/main/app/risk/stress_testing.py): `app/risk/stress_testing.py`
- [Anomaly service](https://github.com/sanchitkumar18/risklens/blob/main/app/services/anomaly_service.py): `app/services/anomaly_service.py`
- [Anomaly detection](https://github.com/sanchitkumar18/risklens/blob/main/app/analytics/anomaly_detection.py): `app/analytics/anomaly_detection.py`
- [Alert service](https://github.com/sanchitkumar18/risklens/blob/main/app/services/alert_service.py): `app/services/alert_service.py`
- [Alert rules](https://github.com/sanchitkumar18/risklens/blob/main/app/analytics/alert_rules.py): `app/analytics/alert_rules.py`

### Grounded assistant

- [Assistant service](https://github.com/sanchitkumar18/risklens/blob/main/app/services/assistant_service.py): `app/services/assistant_service.py`
- [Assistant graph](https://github.com/sanchitkumar18/risklens/blob/main/app/llm/graph.py): `app/llm/graph.py`
- [Grounded tools](https://github.com/sanchitkumar18/risklens/blob/main/app/llm/tools.py): `app/llm/tools.py`
- [Tool retrieval](https://github.com/sanchitkumar18/risklens/blob/main/app/llm/nodes/retrieve.py): `app/llm/nodes/retrieve.py`
- [Answer explanation](https://github.com/sanchitkumar18/risklens/blob/main/app/llm/nodes/explain.py): `app/llm/nodes/explain.py`
- [Grounding validation](https://github.com/sanchitkumar18/risklens/blob/main/app/llm/nodes/validate.py): `app/llm/nodes/validate.py`

### Other components

- **User**

## Connections

- User → Dashboard: uses (evidence: `README.md`)
- Dashboard → Dashboard views: renders (evidence: `dashboard/app.py`)
- Dashboard → HTTP client: creates (evidence: `dashboard/app.py`)
- Dashboard views → HTTP client: requests data (evidence: `dashboard/views/alerts.py`)
- HTTP client → FastAPI app: HTTP requests (evidence: `dashboard/api_client.py`)
- FastAPI app → Market-data routes: registers (evidence: `app/main.py`)
- FastAPI app → Portfolio routes: registers (evidence: `app/main.py`)
- FastAPI app → Risk routes: registers (evidence: `app/main.py`)
- FastAPI app → Stress routes: registers (evidence: `app/main.py`)
- FastAPI app → Anomaly routes: registers (evidence: `app/main.py`)
- FastAPI app → Alert routes: registers (evidence: `app/main.py`)
- FastAPI app → Assistant route: registers (evidence: `app/main.py`)
- Market-data routes → Service wiring: gets service (evidence: `app/api/routes/market_data.py`)
- Portfolio routes → Service wiring: gets service (evidence: `app/api/routes/portfolios.py`)
- Risk routes → Service wiring: gets service (evidence: `app/api/routes/risk.py`)
- Market-data routes → Market-data service: calls (evidence: `app/api/routes/market_data.py`)
- Portfolio routes → Portfolio service: calls (evidence: `app/api/routes/portfolios.py`)
- Risk routes → Risk service: calls (evidence: `app/api/routes/risk.py`)
- Market-data service → Ingestion pipeline: ingests (evidence: `app/services/market_data_service.py`)
- Market-data service → Validation and cleaning: validates (evidence: `app/services/market_data_service.py`)
- Market-data service → Market-data repository: upserts bars (evidence: `app/services/market_data_service.py`)
- Portfolio service → Market-data repository: reads prices (evidence: `app/services/portfolio_service.py`)
- Portfolio service → Relational database: stores portfolio data (evidence: `README.md`)
- Risk service → Portfolio service: values portfolio (evidence: `app/services/risk_service.py`)
- Risk service → Market-data repository: loads prices (evidence: `app/services/risk_service.py`)
- Risk service → Feature transformation: builds features (evidence: `app/services/risk_service.py`)
- Risk service → Risk calculations: computes metrics (evidence: `app/services/risk_service.py`)
- Stress routes → Stress service: runs tests (evidence: `README.md`)
- Stress service → Portfolio service: values portfolio (evidence: `app/services/stress_service.py`)
- Stress service → Stress engine: applies shocks (evidence: `app/services/stress_service.py`)
- Anomaly routes → Anomaly service: scans (evidence: `app/api/routes/anomalies.py`)
- Anomaly service → Portfolio service: gets holdings (evidence: `app/services/anomaly_service.py`)
- Anomaly service → Market-data repository: loads bars (evidence: `app/services/anomaly_service.py`)
- Anomaly service → Feature transformation: engineers features (evidence: `app/services/anomaly_service.py`)
- Anomaly service → Anomaly detection: detects anomalies (evidence: `app/services/anomaly_service.py`)
- Alert routes → Alert service: evaluates (evidence: `app/api/routes/alerts.py`)
- Alert service → Risk service: computes risk (evidence: `app/services/alert_service.py`)
- Alert service → Anomaly service: scans anomalies (evidence: `app/services/alert_service.py`)
- Alert service → Stress service: runs scenarios (evidence: `app/services/alert_service.py`)
- Alert service → Alert rules: grades breaches (evidence: `app/services/alert_service.py`)
- Assistant route → Assistant service: handles query (evidence: `README.md`)
- Assistant service → Assistant graph: runs graph
- Assistant graph → Tool retrieval: retrieves
- Tool retrieval → Grounded tools: invokes tools (evidence: `app/llm/nodes/retrieve.py`)
- Grounded tools → Risk service: queries risk (evidence: `app/llm/tools.py`)
- Grounded tools → Portfolio service: queries portfolio (evidence: `app/llm/tools.py`)
- Grounded tools → Stress service: runs stress (evidence: `app/llm/tools.py`)
- Grounded tools → Anomaly service: queries anomalies (evidence: `app/llm/tools.py`)
