# dyson-025/finintel architecture

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

- Interactive diagram: https://gitdiagram.com/dyson-025/finintel
- Repository: https://github.com/dyson-025/finintel

## Overview

FinIntel is a financial-intelligence terminal: users submit a financial question or configure a portfolio shock, then inspect market, news, historical, macro, correlation, risk, and evidence views. The backend endpoint delegates analysis planning and orchestration to agents, which use market-data tools, historical-event retrieval, macro context, and deterministic scenario calculations. The graph also preserves the frontend’s documented result panels. Some App request wiring and backend orchestration details were not excerpted, so uncertain connections are omitted.

Main entry points: [`frontend/src/App.jsx`](https://github.com/dyson-025/finintel/blob/main/frontend/src/App.jsx) (FinIntel terminal), [`backend/agents.py`](https://github.com/dyson-025/finintel/blob/main/backend/agents.py) (Analysis agents), [`backend/tools.py`](https://github.com/dyson-025/finintel/blob/main/backend/tools.py) (Market and news tools), [`frontend/src/ScenarioSimulator.jsx`](https://github.com/dyson-025/finintel/blob/main/frontend/src/ScenarioSimulator.jsx) (Scenario simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ui["FinIntel terminal<br/>[App.jsx]"]
  node_entry["React entry<br/>[main.jsx]"]
  node_scenario_ui["Scenario simulator"]
  node_news_ui["News panel<br/>[NewsPanel.jsx]"]
  node_macro_ui["Macro panel<br/>[MacroPanel.jsx]"]
  node_history_ui["Historical chart"]
  node_correlation_ui["Correlation panel"]
  node_risk_ui["Risk recommendation"]
  node_evidence_ui["Evidence panel<br/>[EvidencePanel.jsx]"]
end

subgraph group_orchestration["Analysis orchestration"]
  node_api["Analysis API<br/>[app.py]"]
  node_agents["Analysis agents<br/>[agents.py]"]
end

subgraph group_data["Financial data"]
  node_market_tools["Market and news tools<br/>[tools.py]"]
  node_history_tools["Historical price tools<br/>[tools.py]"]
  node_correlation_tools["Correlation tools<br/>[tools.py]"]
  node_historical_rag["Historical event search<br/>[rag.py]"]
  node_historical_events["Historical events dataset"]
  node_macro_data["Macro context<br/>[macro.py]"]
end

subgraph group_risk["Risk and evidence"]
  node_scenario_calc["Scenario calculations<br/>[analysis.py]"]
  node_provenance["Source metadata<br/>[provenance.py]"]
end

node_user(("Financial user"))
node_groq["Groq language model"]
node_yahoo["Yahoo Finance"]

node_user -->|"asks question"| node_ui
node_entry -->|"renders"| node_ui
node_ui -->|"renders"| node_news_ui
node_ui -->|"renders"| node_macro_ui
node_ui -->|"renders"| node_history_ui
node_ui -->|"renders"| node_correlation_ui
node_ui -->|"renders"| node_risk_ui
node_ui -->|"renders"| node_evidence_ui
node_ui -->|"renders"| node_scenario_ui
node_scenario_ui -->|"posts query"| node_api
node_api -->|"runs analysis"| node_agents
node_agents -->|"requests market data"| node_market_tools
node_agents -->|"requests price history"| node_history_tools
node_agents -->|"requests correlations"| node_correlation_tools
node_agents -->|"searches events"| node_historical_rag
node_agents -->|"gets macro context"| node_macro_data
node_agents -->|"calculates scenarios"| node_scenario_calc
node_historical_rag -->|"loads events"| node_historical_events
node_market_tools -->|"retrieves market data"| node_yahoo
node_history_tools -->|"retrieves prices"| node_yahoo
node_correlation_tools -->|"retrieves prices"| node_yahoo
node_agents -->|"invokes model"| node_groq
node_market_tools -->|"creates source metadata"| node_provenance
node_macro_data -->|"creates source metadata"| node_provenance

click node_ui "https://github.com/dyson-025/finintel/blob/main/frontend/src/App.jsx"
click node_entry "https://github.com/dyson-025/finintel/blob/main/frontend/src/main.jsx"
click node_scenario_ui "https://github.com/dyson-025/finintel/blob/main/frontend/src/ScenarioSimulator.jsx"
click node_news_ui "https://github.com/dyson-025/finintel/blob/main/frontend/src/NewsPanel.jsx"
click node_macro_ui "https://github.com/dyson-025/finintel/blob/main/frontend/src/MacroPanel.jsx"
click node_history_ui "https://github.com/dyson-025/finintel/blob/main/frontend/src/HistoricalChart.jsx"
click node_correlation_ui "https://github.com/dyson-025/finintel/blob/main/frontend/src/CorrelationPanel.jsx"
click node_risk_ui "https://github.com/dyson-025/finintel/blob/main/frontend/src/RiskRecommendation.jsx"
click node_evidence_ui "https://github.com/dyson-025/finintel/blob/main/frontend/src/EvidencePanel.jsx"
click node_api "https://github.com/dyson-025/finintel/blob/main/backend/app.py"
click node_agents "https://github.com/dyson-025/finintel/blob/main/backend/agents.py"
click node_market_tools "https://github.com/dyson-025/finintel/blob/main/backend/tools.py"
click node_history_tools "https://github.com/dyson-025/finintel/blob/main/backend/tools.py"
click node_correlation_tools "https://github.com/dyson-025/finintel/blob/main/backend/tools.py"
click node_historical_rag "https://github.com/dyson-025/finintel/blob/main/backend/rag.py"
click node_historical_events "https://github.com/dyson-025/finintel/blob/main/backend/data/historical_events.json"
click node_macro_data "https://github.com/dyson-025/finintel/blob/main/backend/macro.py"
click node_scenario_calc "https://github.com/dyson-025/finintel/blob/main/backend/analysis.py"
click node_provenance "https://github.com/dyson-025/finintel/blob/main/backend/provenance.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_ui,node_entry,node_scenario_ui,node_news_ui,node_macro_ui,node_history_ui,node_correlation_ui,node_risk_ui,node_evidence_ui,node_user toneBlue
class node_api,node_agents toneAmber
class node_market_tools,node_history_tools,node_correlation_tools,node_historical_rag,node_historical_events,node_macro_data toneMint
class node_scenario_calc,node_provenance toneRose
class node_groq,node_yahoo toneIndigo
```

## Components

### User interface

- [FinIntel terminal](https://github.com/dyson-025/finintel/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [React entry](https://github.com/dyson-025/finintel/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [Scenario simulator](https://github.com/dyson-025/finintel/blob/main/frontend/src/ScenarioSimulator.jsx): `frontend/src/ScenarioSimulator.jsx`
- [News panel](https://github.com/dyson-025/finintel/blob/main/frontend/src/NewsPanel.jsx): `frontend/src/NewsPanel.jsx`
- [Macro panel](https://github.com/dyson-025/finintel/blob/main/frontend/src/MacroPanel.jsx): `frontend/src/MacroPanel.jsx`
- [Historical chart](https://github.com/dyson-025/finintel/blob/main/frontend/src/HistoricalChart.jsx): `frontend/src/HistoricalChart.jsx`
- [Correlation panel](https://github.com/dyson-025/finintel/blob/main/frontend/src/CorrelationPanel.jsx): `frontend/src/CorrelationPanel.jsx`
- [Risk recommendation](https://github.com/dyson-025/finintel/blob/main/frontend/src/RiskRecommendation.jsx): `frontend/src/RiskRecommendation.jsx`
- [Evidence panel](https://github.com/dyson-025/finintel/blob/main/frontend/src/EvidencePanel.jsx): `frontend/src/EvidencePanel.jsx`

### Analysis orchestration

- [Analysis API](https://github.com/dyson-025/finintel/blob/main/backend/app.py): `backend/app.py`
- [Analysis agents](https://github.com/dyson-025/finintel/blob/main/backend/agents.py): `backend/agents.py`

### Financial data

- [Market and news tools](https://github.com/dyson-025/finintel/blob/main/backend/tools.py): `backend/tools.py`
- [Historical price tools](https://github.com/dyson-025/finintel/blob/main/backend/tools.py): `backend/tools.py`
- [Correlation tools](https://github.com/dyson-025/finintel/blob/main/backend/tools.py): `backend/tools.py`
- [Historical event search](https://github.com/dyson-025/finintel/blob/main/backend/rag.py): `backend/rag.py`
- [Historical events dataset](https://github.com/dyson-025/finintel/blob/main/backend/data/historical_events.json): `backend/data/historical_events.json`
- [Macro context](https://github.com/dyson-025/finintel/blob/main/backend/macro.py): `backend/macro.py`

### Risk and evidence

- [Scenario calculations](https://github.com/dyson-025/finintel/blob/main/backend/analysis.py): `backend/analysis.py`
- [Source metadata](https://github.com/dyson-025/finintel/blob/main/backend/provenance.py): `backend/provenance.py`

### Other components

- **Financial user**
- **Groq language model**
- **Yahoo Finance**

## Connections

- Financial user → FinIntel terminal: asks question (evidence: `frontend/src/App.jsx`)
- React entry → FinIntel terminal: renders (evidence: `frontend/src/main.jsx`)
- FinIntel terminal → News panel: renders (evidence: `frontend/src/App.jsx`)
- FinIntel terminal → Macro panel: renders (evidence: `frontend/src/App.jsx`)
- FinIntel terminal → Historical chart: renders (evidence: `frontend/src/App.jsx`)
- FinIntel terminal → Correlation panel: renders (evidence: `frontend/src/App.jsx`)
- FinIntel terminal → Risk recommendation: renders (evidence: `frontend/src/App.jsx`)
- FinIntel terminal → Evidence panel: renders (evidence: `frontend/src/App.jsx`)
- FinIntel terminal → Scenario simulator: renders (evidence: `frontend/src/App.jsx`)
- Scenario simulator → Analysis API: posts query (evidence: `frontend/src/ScenarioSimulator.jsx`)
- Analysis API → Analysis agents: runs analysis (evidence: `backend/app.py`)
- Analysis agents → Market and news tools: requests market data (evidence: `backend/agents.py`)
- Analysis agents → Historical price tools: requests price history (evidence: `backend/agents.py`)
- Analysis agents → Correlation tools: requests correlations (evidence: `backend/agents.py`)
- Analysis agents → Historical event search: searches events (evidence: `backend/agents.py`)
- Analysis agents → Macro context: gets macro context (evidence: `backend/agents.py`)
- Analysis agents → Scenario calculations: calculates scenarios (evidence: `backend/agents.py`)
- Historical event search → Historical events dataset: loads events (evidence: `backend/rag.py`)
- Market and news tools → Yahoo Finance: retrieves market data (evidence: `backend/tools.py`)
- Historical price tools → Yahoo Finance: retrieves prices (evidence: `backend/tools.py`)
- Correlation tools → Yahoo Finance: retrieves prices (evidence: `backend/tools.py`)
- Analysis agents → Groq language model: invokes model (evidence: `backend/agents.py`)
- Market and news tools → Source metadata: creates source metadata (evidence: `backend/tools.py`)
- Macro context → Source metadata: creates source metadata (evidence: `backend/macro.py`)
