# rithesh24/risk-intelligence-system architecture

> Architecture diagram of the GitHub repository rithesh24/risk-intelligence-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rithesh24/risk-intelligence-system
- Repository: https://github.com/rithesh24/risk-intelligence-system

## Overview

1. This repo is a two-tier decision-intelligence system: a Python/FastAPI backend that runs the risk-analysis pipeline, and a separate Next.js frontend that renders both the business-facing dashboard and the developer monitor view.

2. The backend entrypoint is `app/main.py`, which wires the API layer in `api/routes/*` to the analysis and monitoring subsystems. The main externally visible capabilities are: run an analysis, inspect system state, and inspect agent execution/monitoring data.

3. The core runtime architecture is orchestrated in `orchestrator/graph.py` and `orchestrator/nodes/*`. This is the control plane for the multi-agent workflow: execute agents, aggregate results, detect conflicts, run a challenge phase, and break ties when agent outputs diverge.

4. The analysis pipeline is stateful. `orchestrator/state/state_schema.py` defines the shared analysis state passed between nodes and agents, so each step can add structured outputs without losing prior context. That state is the main boundary between orchestration and domain logic.

5. Domain intelligence is split across agent groups under `agents/`. The `llm_agents` infer business context and narrative meaning, the `signal_agents` evaluate specific risk dimensions like currency, commodities, demand, and policy, and `agents/impact/impact_translation_agent.py` converts upstream risk signals into business outcomes such as revenue, cost, and margin pressure.

6. The system is explicitly hybrid: LLM reasoning is combined with deterministic models. Deterministic support lives in `services/risk_engine.py`, `risk/amplification_engine.py`, and `knowledge/knowledge_base.py`, which provide score adjustment, fragility amplification, and curated mappings used when live data is incomplete.

7. External data enters through two main paths. First, `ingestion/sources/rss_feed.py` and `ingestion/pipeline/event_builder.py` turn RSS/news content into structured events in `events/models/news_event.py` and publish them via `events/bus/event_bus.py`. Second, `data/market_data_service.py` fetches live market inputs such as FX and commodity prices for the specific exposures identified by the analysis.

8. The analysis flow is therefore: business description in, business profile extraction, exposure mapping, market-data enrichment, specialized risk-agent execution, narrative/news interpretation, impact translation, then aggregation into a final score and explanation. The backend is designed to produce both the composite risk result and per-agent contributions for explainability.

9. Observability is a first-class subsystem. `observability/agent_monitor.py` tracks execution order, timestamps, confidence, errors, and agent-level scores, and the FastAPI routes expose that data for inspection. This monitoring layer is separate from the analysis logic so the pipeline can be debugged without changing risk behavior.

10. The frontend is a dedicated presentation boundary under `frontend/`. `frontend/lib/api.ts` connects the UI to the backend, while `frontend/app/page.tsx` serves the business dashboard and `frontend/app/monitor/page.tsx` serves the operator/debug dashboard. The components are mostly visualization and explanation surfaces rather than business logic.

11. The business dashboard emphasizes the final answer: risk score, confidence, driver explanations, agent contribution charts, and mitigation guidance. The monitor dashboard emphasizes the pipeline itself: execution flow, conflict detection, radar comparisons, low-confidence warnings, and per-agent output panels.

12. In deployment terms, this is not a monolith despite being in one repository. The backend is a Python service meant to run independently, and the frontend is a separate Next.js app. The main external integrations that materially affect architecture are the Groq LLM API for reasoning, Alpha Vantage-style market data for live signals, and RSS/news sources for event ingestion.

13. For an architecture diagram, the key boundaries are: user input/UI, API layer, orchestrator, agent groups, deterministic scoring/knowledge services, market/news ingestion, observability, and frontend visualization. The most important dataflow is one-way from raw business text and external signals into stateful agent execution, then out to explainable risk outputs and monitoring data.

Main entry points: [`orchestrator/nodes/agent_executor.py`](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/agent_executor.py) (Agent exec), [`agents/signal_agents/currency_agent.py`](https://github.com/rithesh24/risk-intelligence-system/blob/master/agents/signal_agents/currency_agent.py) (Signal agents), [`orchestrator/state/state_schema.py`](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/state/state_schema.py) (Analysis state), [`app/main.py`](https://github.com/rithesh24/risk-intelligence-system/blob/master/app/main.py) (Main app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Python backend"]
  node_app_main["Main app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_api_analyze["Analyze API<br/>route<br/>[analyze.py]"]
  node_api_state["State API<br/>route<br/>[system_state.py]"]
  node_api_monitor["Monitor API<br/>route<br/>[agent_monitor.py]"]
  node_agent_monitor["Agent monitor<br/>observability<br/>[agent_monitor.py]"]
end

subgraph group_intelligence["Decision engine"]
  node_orch_graph{{"Workflow graph<br/>orchestrator<br/>[graph.py]"}}
  node_orch_state["Analysis state<br/>state schema<br/>[state_schema.py]"]
  node_orch_exec["Agent exec<br/>orchestrator node<br/>[agent_executor.py]"]
  node_orch_conflict["Conflict detect<br/>orchestrator node"]
  node_orch_challenge["Challenge phase<br/>orchestrator node<br/>[challenge_phase.py]"]
  node_orch_tiebreak["Tie breaker<br/>orchestrator node<br/>[tie_breaker.py]"]
  node_orch_agg["Aggregator<br/>orchestrator node<br/>[aggregator.py]"]
  node_llm_agents["LLM agents<br/>agent group"]
  node_signal_agents["Signal agents<br/>agent group<br/>[currency_agent.py]"]
  node_impact_agent["Impact translate<br/>agent"]
  node_risk_engine["Risk engine<br/>deterministic service<br/>[risk_engine.py]"]
  node_amplification["Amplify model<br/>deterministic model"]
  node_knowledge_base[("Knowledge base<br/>curated mappings<br/>[knowledge_base.py]")]
end

subgraph group_ingestion["Data inputs"]
  node_rss_feed["RSS feed<br/>news source<br/>[rss_feed.py]"]
  node_event_builder["Event builder<br/>ingestion pipeline<br/>[event_builder.py]"]
  node_news_event["News event<br/>event model<br/>[news_event.py]"]
  node_event_bus["Event bus<br/>event transport<br/>[event_bus.py]"]
  node_market_data[("Market data<br/>external data service")]
end

subgraph group_frontend["Next.js frontend"]
  node_frontend_api["Frontend API<br/>client adapter<br/>[api.ts]"]
  node_dashboard["Dashboard<br/>page<br/>[page.tsx]"]
  node_monitor_page["Monitor page<br/>[page.tsx]"]
  node_risk_gauge(("Risk gauge<br/>visualization<br/>[RiskGauge.tsx]"))
  node_monitor_graph(("Exec graph<br/>visualization<br/>[ExecutionGraph.tsx]"))
end

node_api_analyze -->|"start analysis"| node_orch_graph
node_api_state -->|"read state"| node_orch_state
node_api_monitor -->|"read telemetry"| node_agent_monitor
node_app_main -->|"mount"| node_api_analyze
node_app_main -->|"mount"| node_api_state
node_app_main -->|"mount"| node_api_monitor
node_orch_graph -->|"share state"| node_orch_state
node_orch_graph -->|"run"| node_orch_exec
node_orch_exec -->|"invoke"| node_llm_agents
node_orch_exec -->|"invoke"| node_signal_agents
node_orch_exec -->|"invoke"| node_impact_agent
node_llm_agents -->|"write outputs"| node_orch_state
node_signal_agents -->|"enrich"| node_market_data
node_signal_agents -->|"fallbacks"| node_knowledge_base
node_signal_agents -->|"adjust"| node_amplification
node_impact_agent -->|"write impact"| node_orch_state
node_orch_exec -->|"check divergence"| node_orch_conflict
node_orch_conflict -->|"challenge"| node_orch_challenge
node_orch_challenge -->|"resolve"| node_orch_tiebreak
node_orch_tiebreak -->|"finalize"| node_orch_agg
node_orch_agg -->|"score"| node_risk_engine
node_risk_engine -->|"store result"| node_orch_state
node_orch_exec -->|"log run"| node_agent_monitor
node_rss_feed -->|"source items"| node_event_builder
node_event_builder -->|"shape"| node_news_event
node_event_builder -->|"publish"| node_event_bus
node_event_bus -->|"news context"| node_signal_agents
node_frontend_api -->|"request analysis"| node_api_analyze
node_frontend_api -->|"fetch state"| node_api_state
node_frontend_api -->|"fetch telemetry"| node_api_monitor
node_dashboard -->|"render"| node_risk_gauge
node_monitor_page -->|"render"| node_monitor_graph
node_monitor_page -->|"inspect"| node_agent_monitor

click node_app_main "https://github.com/rithesh24/risk-intelligence-system/blob/master/app/main.py"
click node_api_analyze "https://github.com/rithesh24/risk-intelligence-system/blob/master/api/routes/analyze.py"
click node_api_state "https://github.com/rithesh24/risk-intelligence-system/blob/master/api/routes/system_state.py"
click node_api_monitor "https://github.com/rithesh24/risk-intelligence-system/blob/master/api/routes/agent_monitor.py"
click node_orch_graph "https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/graph.py"
click node_orch_state "https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/state/state_schema.py"
click node_orch_exec "https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/agent_executor.py"
click node_orch_conflict "https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/conflict_detector.py"
click node_orch_challenge "https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/challenge_phase.py"
click node_orch_tiebreak "https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/tie_breaker.py"
click node_orch_agg "https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/aggregator.py"
click node_llm_agents "https://github.com/rithesh24/risk-intelligence-system/blob/master/agents/llm_agents/business_profile_agent.py"
click node_signal_agents "https://github.com/rithesh24/risk-intelligence-system/blob/master/agents/signal_agents/currency_agent.py"
click node_impact_agent "https://github.com/rithesh24/risk-intelligence-system/blob/master/agents/impact/impact_translation_agent.py"
click node_risk_engine "https://github.com/rithesh24/risk-intelligence-system/blob/master/services/risk_engine.py"
click node_amplification "https://github.com/rithesh24/risk-intelligence-system/blob/master/risk/amplification_engine.py"
click node_knowledge_base "https://github.com/rithesh24/risk-intelligence-system/blob/master/knowledge/knowledge_base.py"
click node_rss_feed "https://github.com/rithesh24/risk-intelligence-system/blob/master/ingestion/sources/rss_feed.py"
click node_event_builder "https://github.com/rithesh24/risk-intelligence-system/blob/master/ingestion/pipeline/event_builder.py"
click node_news_event "https://github.com/rithesh24/risk-intelligence-system/blob/master/events/models/news_event.py"
click node_event_bus "https://github.com/rithesh24/risk-intelligence-system/blob/master/events/bus/event_bus.py"
click node_market_data "https://github.com/rithesh24/risk-intelligence-system/blob/master/data/market_data_service.py"
click node_agent_monitor "https://github.com/rithesh24/risk-intelligence-system/blob/master/observability/agent_monitor.py"
click node_frontend_api "https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/lib/api.ts"
click node_dashboard "https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/app/page.tsx"
click node_monitor_page "https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/app/monitor/page.tsx"
click node_risk_gauge "https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/components/RiskGauge.tsx"
click node_monitor_graph "https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/components/monitor/ExecutionGraph.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_main,node_api_analyze,node_api_state,node_api_monitor,node_agent_monitor toneBlue
class node_orch_graph,node_orch_state,node_orch_exec,node_orch_conflict,node_orch_challenge,node_orch_tiebreak,node_orch_agg,node_llm_agents,node_signal_agents,node_impact_agent,node_risk_engine,node_amplification,node_knowledge_base toneAmber
class node_rss_feed,node_event_builder,node_news_event,node_event_bus,node_market_data toneMint
class node_frontend_api,node_dashboard,node_monitor_page,node_risk_gauge,node_monitor_graph toneRose
```

## Components

### Python backend

FastAPI service that runs analysis, orchestration, and monitoring

- [Main app](https://github.com/rithesh24/risk-intelligence-system/blob/master/app/main.py): FastAPI entrypoint · Wires the backend API to analysis and monitoring subsystems · `app/main.py`
- [Analyze API](https://github.com/rithesh24/risk-intelligence-system/blob/master/api/routes/analyze.py): route · Starts a risk analysis request · `api/routes/analyze.py`
- [State API](https://github.com/rithesh24/risk-intelligence-system/blob/master/api/routes/system_state.py): route · Exposes current system and analysis state · `api/routes/system_state.py`
- [Monitor API](https://github.com/rithesh24/risk-intelligence-system/blob/master/api/routes/agent_monitor.py): route · Serves agent execution and monitoring data · `api/routes/agent_monitor.py`
- [Agent monitor](https://github.com/rithesh24/risk-intelligence-system/blob/master/observability/agent_monitor.py): observability · Tracks execution order, timing, confidence, errors, and scores · `observability/agent_monitor.py`

### Decision engine

Agent groups, deterministic scoring, and shared analysis state

- [Workflow graph](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/graph.py): orchestrator · Controls the multi-agent analysis flow · `orchestrator/graph.py`
- [Analysis state](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/state/state_schema.py): state schema · Shared state passed between orchestration steps and agents · `orchestrator/state/state_schema.py`
- [Agent exec](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/agent_executor.py): orchestrator node · Runs the active agents against the shared state · `orchestrator/nodes/agent_executor.py`
- [Conflict detect](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/conflict_detector.py): orchestrator node · Finds divergence between agent outputs · `orchestrator/nodes/conflict_detector.py`
- [Challenge phase](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/challenge_phase.py): orchestrator node · Re-runs reasoning to challenge uncertain conclusions · `orchestrator/nodes/challenge_phase.py`
- [Tie breaker](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/tie_breaker.py): orchestrator node · Resolves disagreement when agent outputs diverge · `orchestrator/nodes/tie_breaker.py`
- [Aggregator](https://github.com/rithesh24/risk-intelligence-system/blob/master/orchestrator/nodes/aggregator.py): orchestrator node · Combines per-agent results into the final explanation and score · `orchestrator/nodes/aggregator.py`
- [LLM agents](https://github.com/rithesh24/risk-intelligence-system/blob/master/agents/llm_agents/business_profile_agent.py): agent group · Business-context and narrative reasoning agents · `agents/llm_agents/business_profile_agent.py`
- [Signal agents](https://github.com/rithesh24/risk-intelligence-system/blob/master/agents/signal_agents/currency_agent.py): agent group · Specialized risk agents for market and policy dimensions · `agents/signal_agents/currency_agent.py`
- [Impact translate](https://github.com/rithesh24/risk-intelligence-system/blob/master/agents/impact/impact_translation_agent.py): agent · Converts upstream risks into business outcomes like revenue and margin pressure · `agents/impact/impact_translation_agent.py`
- [Risk engine](https://github.com/rithesh24/risk-intelligence-system/blob/master/services/risk_engine.py): deterministic service · Performs score adjustment and hybrid risk calculation · `services/risk_engine.py`
- [Amplify model](https://github.com/rithesh24/risk-intelligence-system/blob/master/risk/amplification_engine.py): deterministic model · Raises scores for fragile or high-sensitivity situations · `risk/amplification_engine.py`
- [Knowledge base](https://github.com/rithesh24/risk-intelligence-system/blob/master/knowledge/knowledge_base.py): curated mappings · Provides fallback mappings and domain knowledge when live data is incomplete · `knowledge/knowledge_base.py`

### Data inputs

News and market-data paths that feed the analysis pipeline

- [RSS feed](https://github.com/rithesh24/risk-intelligence-system/blob/master/ingestion/sources/rss_feed.py): news source · Ingests external news content · `ingestion/sources/rss_feed.py`
- [Event builder](https://github.com/rithesh24/risk-intelligence-system/blob/master/ingestion/pipeline/event_builder.py): ingestion pipeline · Turns news items into structured events · `ingestion/pipeline/event_builder.py`
- [News event](https://github.com/rithesh24/risk-intelligence-system/blob/master/events/models/news_event.py): event model · Structured event representation used by the pipeline · `events/models/news_event.py`
- [Event bus](https://github.com/rithesh24/risk-intelligence-system/blob/master/events/bus/event_bus.py): event transport · Publishes and distributes news events · `events/bus/event_bus.py`
- [Market data](https://github.com/rithesh24/risk-intelligence-system/blob/master/data/market_data_service.py): external data service · Fetches live FX and commodity inputs for exposed risks · `data/market_data_service.py`

### Next.js frontend

Dashboard and operator UI that visualize results and pipeline behavior

- [Frontend API](https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/lib/api.ts): client adapter · Connects the UI to backend endpoints · `frontend/lib/api.ts`
- [Dashboard](https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/app/page.tsx): page · Business-facing risk summary and guidance view · `frontend/app/page.tsx`
- [Monitor page](https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/app/monitor/page.tsx): page · Operator view for pipeline execution and debugging · `frontend/app/monitor/page.tsx`
- [Risk gauge](https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/components/RiskGauge.tsx): visualization · Shows final score and confidence · `frontend/components/RiskGauge.tsx`
- [Exec graph](https://github.com/rithesh24/risk-intelligence-system/blob/master/frontend/components/monitor/ExecutionGraph.tsx): visualization · Displays execution flow and conflict handling · `frontend/components/monitor/ExecutionGraph.tsx`

## Connections

- Analyze API → Workflow graph: start analysis · Routes a user request into the workflow controller
- State API → Analysis state: read state · Returns the shared analysis state for inspection
- Monitor API → Agent monitor: read telemetry · Exposes monitoring records to the API layer
- Main app → Analyze API: mount · Registers analysis routes
- Main app → State API: mount · Registers system-state routes
- Main app → Monitor API: mount · Registers monitoring routes
- Workflow graph → Analysis state: share state · All steps operate on the same evolving analysis state
- Workflow graph → Agent exec: run · Drives the agent execution step
- Agent exec → LLM agents: invoke · Calls business-context and narrative agents
- Agent exec → Signal agents: invoke · Calls specialized risk agents
- Agent exec → Impact translate: invoke · Translates upstream risks into business impact
- LLM agents → Analysis state: write outputs · Adds extracted business profile and narrative context
- Signal agents → Market data: enrich · Uses live market inputs when available
- Signal agents → Knowledge base: fallbacks · Uses curated mappings when data is missing
- Signal agents → Amplify model: adjust · Applies fragility amplification to signals
- Impact translate → Analysis state: write impact · Stores business-outcome interpretation in shared state
- Agent exec → Conflict detect: check divergence · Compares agent outputs for disagreement
- Conflict detect → Challenge phase: challenge · Escalates uncertain or conflicting conclusions
- Challenge phase → Tie breaker: resolve · Breaks ties after the challenge phase
- Tie breaker → Aggregator: finalize · Hands resolved outputs to the aggregator
- Aggregator → Risk engine: score · Combines results into the composite risk score
- Risk engine → Analysis state: store result · Writes final score and explanation back to shared state
- Agent exec → Agent monitor: log run · Records execution order, timestamps, confidence, and errors
- RSS feed → Event builder: source items · Feeds raw news content into the builder
- Event builder → News event: shape · Produces structured news events
- Event builder → Event bus: publish · Publishes events for downstream consumers
- Event bus → Signal agents: news context · Supplies external news signals to analysis
- Frontend API → Analyze API: request analysis · Business dashboard submits analysis requests
- Frontend API → State API: fetch state · UI reads the current system state
- Frontend API → Monitor API: fetch telemetry · Monitor page reads agent telemetry
- Dashboard → Risk gauge: render · Shows the final risk summary
- Monitor page → Exec graph: render · Shows execution flow and pipeline behavior
- Monitor page → Agent monitor: inspect · Surfaces monitoring data in the operator UI