# dominatingspirit/macroriskai_final architecture

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

## Overview

MacroRisk AI provides macroeconomic forecasts, company-level resilience analysis, scenario reports, portfolio and sector insights, retail calculators, and a chat assistant. The main company-analysis workflow combines macro forecasts and company financial history, models scenario impacts, then generates an executive report. A separate resilience-scoring path adjusts company metrics for macro conditions and ranks them. The graph also preserves documented API and supporting-model branches. Some frontend-to-endpoint wiring and unsampled subsystem internals are not shown, so those links are omitted or marked unverified.

Main entry points: [`main.py`](https://github.com/dominatingspirit/macroriskai_final/blob/main/main.py) (FastAPI application), [`services/resilience_score.py`](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/resilience_score.py) (Resilience scoring), [`langgraph_orchestrator.py`](https://github.com/dominatingspirit/macroriskai_final/blob/main/langgraph_orchestrator.py) (Analysis workflow), [`Agent_1/inflation_outlook_agent.py`](https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_1/inflation_outlook_agent.py) (Macro forecaster)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web["Product pages"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and orchestration"]
  node_api_server["FastAPI application<br/>[main.py]"]
  node_workflow["Analysis workflow"]
end

subgraph group_analysis["Company analysis"]
  node_macro["Macro forecaster"]
  node_macro_data["Macro data loader"]
  node_company_data["Company financial history"]
  node_scenario["Scenario forecasts"]
  node_report["Executive report"]
end

subgraph group_resilience["Resilience intelligence"]
  node_resilience_engine["Resilience scoring"]
  node_resilience_model["Statistical and ML model"]
  node_features["Feature engineering"]
  node_inflation_regimes["Inflation regimes"]
  node_sectors["Sector intelligence"]
end

subgraph group_capabilities["Additional capabilities"]
  node_portfolio["Portfolio analysis<br/>[portfolio.py]"]
  node_portfolio_upload["Portfolio upload"]
  node_retail["Retail calculators<br/>[retail_tools.py]"]
  node_narrative["Narrative generation<br/>[narrative.py]"]
  node_rag["Document chat RAG<br/>[MacroRiskAI_rag.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -.->|"requests data"| node_api_client
node_api_client -->|"sends HTTP requests"| node_api_server
node_api_server -.->|"runs analysis"| node_workflow
node_workflow -->|"runs forecast"| node_macro
node_workflow -->|"loads company history"| node_company_data
node_workflow -->|"builds scenarios"| node_scenario
node_workflow -->|"generates report"| node_report
node_macro -->|"loads current data"| node_macro_data
node_api_server -->|"runs forecast"| node_macro
node_api_server -->|"serves company data"| node_company_data
node_api_server -->|"computes leaderboard"| node_resilience_engine
node_api_server -->|"serves sector insights"| node_sectors
node_api_server -->|"computes retail tools"| node_retail
node_api_server -->|"analyzes portfolio"| node_portfolio
node_api_server -->|"handles uploads"| node_portfolio_upload
node_api_server -->|"generates narratives"| node_narrative
node_api_server -.->|"serves assistant"| node_rag
node_resilience_engine -->|"gets macro outlook"| node_macro
node_resilience_engine -->|"derives macro impacts"| node_scenario
node_resilience_engine -->|"scores panel"| node_resilience_model
node_resilience_engine -->|"uses metric definitions"| node_features
node_resilience_model -->|"builds features"| node_features
node_resilience_model -->|"finds shock years"| node_inflation_regimes
node_sectors -->|"uses resilience scores"| node_resilience_engine
node_portfolio -->|"uses resilience scores"| node_resilience_engine

click node_web "https://github.com/dominatingspirit/macroriskai_final/tree/main/frontend/app/(app)"
click node_api_client "https://github.com/dominatingspirit/macroriskai_final/blob/main/frontend/lib/api/client.ts"
click node_api_server "https://github.com/dominatingspirit/macroriskai_final/blob/main/main.py"
click node_workflow "https://github.com/dominatingspirit/macroriskai_final/blob/main/langgraph_orchestrator.py"
click node_macro "https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_1/inflation_outlook_agent.py"
click node_macro_data "https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_1/macro_api_service.py"
click node_company_data "https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_2/corporate_analysis_agent.py"
click node_scenario "https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_3/scenario_resilience_agent.py"
click node_report "https://github.com/dominatingspirit/macroriskai_final/blob/main/Executive_intelligence_agent.py"
click node_resilience_engine "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/resilience_score.py"
click node_resilience_model "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/ml_resilience_model.py"
click node_features "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/feature_engineering.py"
click node_inflation_regimes "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/inflation_regimes.py"
click node_sectors "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/sector_intelligence.py"
click node_portfolio "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/portfolio.py"
click node_portfolio_upload "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/portfolio_upload.py"
click node_retail "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/retail_tools.py"
click node_narrative "https://github.com/dominatingspirit/macroriskai_final/blob/main/services/narrative.py"
click node_rag "https://github.com/dominatingspirit/macroriskai_final/blob/main/MacroRiskAI_rag.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_web,node_api_client,node_user toneBlue
class node_api_server,node_workflow toneAmber
class node_macro,node_macro_data,node_company_data,node_scenario,node_report toneMint
class node_resilience_engine,node_resilience_model,node_features,node_inflation_regimes,node_sectors toneRose
class node_portfolio,node_portfolio_upload,node_retail,node_narrative,node_rag toneIndigo
```

## Components

### Web application

- [Product pages](https://github.com/dominatingspirit/macroriskai_final/tree/main/frontend/app/(app)): `frontend/app/(app)`
- [API client](https://github.com/dominatingspirit/macroriskai_final/blob/main/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`

### API and orchestration

- [FastAPI application](https://github.com/dominatingspirit/macroriskai_final/blob/main/main.py): `main.py`
- [Analysis workflow](https://github.com/dominatingspirit/macroriskai_final/blob/main/langgraph_orchestrator.py): `langgraph_orchestrator.py`

### Company analysis

- [Macro forecaster](https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_1/inflation_outlook_agent.py): `Agent_1/inflation_outlook_agent.py`
- [Macro data loader](https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_1/macro_api_service.py): `Agent_1/macro_api_service.py`
- [Company financial history](https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_2/corporate_analysis_agent.py): `Agent_2/corporate_analysis_agent.py`
- [Scenario forecasts](https://github.com/dominatingspirit/macroriskai_final/blob/main/Agent_3/scenario_resilience_agent.py): `Agent_3/scenario_resilience_agent.py`
- [Executive report](https://github.com/dominatingspirit/macroriskai_final/blob/main/Executive_intelligence_agent.py): `Executive_intelligence_agent.py`

### Resilience intelligence

- [Resilience scoring](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/resilience_score.py): `services/resilience_score.py`
- [Statistical and ML model](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/ml_resilience_model.py): `services/ml_resilience_model.py`
- [Feature engineering](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/feature_engineering.py): `services/feature_engineering.py`
- [Inflation regimes](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/inflation_regimes.py): `services/inflation_regimes.py`
- [Sector intelligence](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/sector_intelligence.py): `services/sector_intelligence.py`

### Additional capabilities

- [Portfolio analysis](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/portfolio.py): `services/portfolio.py`
- [Portfolio upload](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/portfolio_upload.py): `services/portfolio_upload.py`
- [Retail calculators](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/retail_tools.py): `services/retail_tools.py`
- [Narrative generation](https://github.com/dominatingspirit/macroriskai_final/blob/main/services/narrative.py): `services/narrative.py`
- [Document chat RAG](https://github.com/dominatingspirit/macroriskai_final/blob/main/MacroRiskAI_rag.py): `MacroRiskAI_rag.py`

### Other components

- **User**

## Connections

- User → Product pages: uses
- Product pages → API client: requests data
- API client → FastAPI application: sends HTTP requests (evidence: `frontend/lib/api/client.ts`)
- FastAPI application → Analysis workflow: runs analysis (evidence: `main.py`)
- Analysis workflow → Macro forecaster: runs forecast (evidence: `langgraph_orchestrator.py`)
- Analysis workflow → Company financial history: loads company history (evidence: `langgraph_orchestrator.py`)
- Analysis workflow → Scenario forecasts: builds scenarios (evidence: `langgraph_orchestrator.py`)
- Analysis workflow → Executive report: generates report (evidence: `langgraph_orchestrator.py`)
- Macro forecaster → Macro data loader: loads current data (evidence: `Agent_1/inflation_outlook_agent.py`)
- FastAPI application → Macro forecaster: runs forecast (evidence: `main.py`)
- FastAPI application → Company financial history: serves company data (evidence: `main.py`)
- FastAPI application → Resilience scoring: computes leaderboard (evidence: `main.py`)
- FastAPI application → Sector intelligence: serves sector insights (evidence: `main.py`)
- FastAPI application → Retail calculators: computes retail tools (evidence: `main.py`)
- FastAPI application → Portfolio analysis: analyzes portfolio (evidence: `main.py`)
- FastAPI application → Portfolio upload: handles uploads (evidence: `main.py`)
- FastAPI application → Narrative generation: generates narratives (evidence: `main.py`)
- FastAPI application → Document chat RAG: serves assistant (evidence: `main.py`)
- Resilience scoring → Macro forecaster: gets macro outlook (evidence: `services/resilience_score.py`)
- Resilience scoring → Scenario forecasts: derives macro impacts (evidence: `services/resilience_score.py`)
- Resilience scoring → Statistical and ML model: scores panel (evidence: `services/resilience_score.py`)
- Resilience scoring → Feature engineering: uses metric definitions (evidence: `services/resilience_score.py`)
- Statistical and ML model → Feature engineering: builds features (evidence: `services/ml_resilience_model.py`)
- Statistical and ML model → Inflation regimes: finds shock years (evidence: `services/ml_resilience_model.py`)
- Sector intelligence → Resilience scoring: uses resilience scores (evidence: `services/sector_intelligence.py`)
- Portfolio analysis → Resilience scoring: uses resilience scores (evidence: `services/portfolio.py`)
