rithesh24/risk-intelligence-system

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.