# higgsboson0906/financial-intelligence-terminal architecture

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

- Interactive diagram: https://gitdiagram.com/higgsboson0906/financial-intelligence-terminal
- Repository: https://github.com/higgsboson0906/financial-intelligence-terminal

## Overview

Financial Intelligence Terminal is an analysis-and-simulation product, not a trading system. Its main backend workflow accepts a natural-language query, orchestrates market, sentiment, macro/weather, historical-event and risk analysis, then synthesizes an answer and persists run data. The frontend presents terminal views and event intelligence; a separate historical-data pipeline acquires and prepares inputs. The README also describes predictive analytics and RAG capabilities. Some endpoints and UI modules are unsampled, so their internal links are omitted; the frontend-to-backend query connection is not asserted.

Main entry points: [`backend/app/agents/orchestrator.py`](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/orchestrator.py) (Analysis Orchestrator), [`backend/app/api/query.py`](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/api/query.py) (Query Endpoint), [`backend/app/services/historical_rag_service.py`](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/historical_rag_service.py) (Historical Event Retrieval), [`frontend/src/App.tsx`](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/App.tsx) (Financial Terminal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Terminal UI"]
  node_terminal["Financial Terminal<br/>[App.tsx]"]
  node_querybar["Query Bar<br/>[QueryBar.tsx]"]
  node_eventmap["Event Impact Map<br/>[EventImpactMap.tsx]"]
  node_marketview["Market View<br/>[MarketView.tsx]"]
  node_audit["Audit Drawer<br/>[AuditDrawer.tsx]"]
  node_eventapi["Event API Client<br/>[eventApi.ts]"]
end

subgraph group_api["API Layer"]
  node_backendapi["FastAPI Routers"]
  node_queryapi["Query Endpoint<br/>[query.py]"]
end

subgraph group_analysis["Analysis Workflow"]
  node_orchestrator["Analysis Orchestrator<br/>[orchestrator.py]"]
  node_queryparser["Query Parser<br/>[query_parser.py]"]
  node_sentiment["Sentiment Agent<br/>[sentiment_agent.py]"]
  node_weather["Weather Macro Agent"]
  node_riskagent["Risk Agent<br/>[risk_agent.py]"]
  node_scenario["Scenario Agent<br/>[scenario_agent.py]"]
  node_hedging["Hedging Agent<br/>[hedging_agent.py]"]
  node_riskengine["Quantitative Risk Engine<br/>[engine.py]"]
  node_ml["Predictive Analytics"]
  node_state["Analysis State and Evidence<br/>[orchestration.py]"]
end

subgraph group_data["Data Services"]
  node_rag["Historical Event Retrieval"]
  node_embeddings["Embedding Service"]
  node_marketdata["Market Data Service<br/>[market_service.py]"]
  node_gemini["Gemini Synthesis<br/>[gemini_service.py]"]
  node_confidence["Confidence Service"]
  node_database[("PostgreSQL / pgvector")]
  node_redis[("Redis Cache")]
end

subgraph group_ingest["Historical Data"]
  node_pipeline["Acquisition Pipeline<br/>[run_pipeline.py]"]
  node_sources["Historical Data Sources"]
  node_normalizers["Normalization and Dataset Build"]
end

node_analyst(("Analyst"))

node_analyst -->|"submits query"| node_querybar
node_terminal -->|"renders"| node_querybar
node_terminal -->|"renders"| node_eventmap
node_eventmap -->|"uses"| node_eventapi
node_eventmap -->|"renders"| node_marketview
node_terminal -->|"renders"| node_audit
node_backendapi -->|"registers"| node_queryapi
node_queryapi -->|"runs analysis"| node_orchestrator
node_queryapi -->|"synthesizes answer"| node_gemini
node_queryapi -->|"calculates confidence"| node_confidence
node_orchestrator -->|"parses query"| node_queryparser
node_orchestrator -->|"dispatches"| node_sentiment
node_orchestrator -->|"dispatches"| node_weather
node_orchestrator -->|"retrieves events"| node_rag
node_orchestrator -->|"loads market context"| node_marketdata
node_orchestrator -->|"dispatches"| node_riskagent
node_orchestrator -->|"dispatches"| node_scenario
node_orchestrator -->|"dispatches"| node_hedging
node_riskagent -->|"calculates risk"| node_riskengine
node_orchestrator -->|"persists run data"| node_database
node_orchestrator -->|"updates state"| node_state
node_rag -->|"embeds queries"| node_embeddings
node_rag -->|"retrieves vectors"| node_database
node_rag -->|"reads cache"| node_redis
node_pipeline -->|"downloads"| node_sources
node_pipeline -->|"builds datasets"| node_normalizers

click node_terminal "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/App.tsx"
click node_querybar "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/components/layout/QueryBar.tsx"
click node_eventmap "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/components/intelligence/EventImpactMap.tsx"
click node_marketview "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/components/intelligence/MarketView.tsx"
click node_audit "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/components/terminal/AuditDrawer.tsx"
click node_eventapi "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/services/eventApi.ts"
click node_backendapi "https://github.com/higgsboson0906/financial-intelligence-terminal/tree/main/backend/app/api"
click node_queryapi "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/api/query.py"
click node_orchestrator "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/orchestrator.py"
click node_queryparser "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/query_parser.py"
click node_sentiment "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/sentiment_agent.py"
click node_weather "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/weather_macro_agent.py"
click node_riskagent "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/risk_agent.py"
click node_scenario "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/scenario_agent.py"
click node_hedging "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/hedging_agent.py"
click node_riskengine "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/risk/engine.py"
click node_rag "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/historical_rag_service.py"
click node_embeddings "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/embedding_service.py"
click node_marketdata "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/market_service.py"
click node_gemini "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/gemini_service.py"
click node_confidence "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/confidence_service.py"
click node_pipeline "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/scripts/data_acquisition/run_pipeline.py"
click node_normalizers "https://github.com/higgsboson0906/financial-intelligence-terminal/tree/main/scripts/data_acquisition"
click node_ml "https://github.com/higgsboson0906/financial-intelligence-terminal/tree/main/ml"
click node_state "https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/schemas/orchestration.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_terminal,node_querybar,node_eventmap,node_marketview,node_audit,node_eventapi toneBlue
class node_backendapi,node_queryapi toneAmber
class node_orchestrator,node_queryparser,node_sentiment,node_weather,node_riskagent,node_scenario,node_hedging,node_riskengine,node_ml,node_state toneMint
class node_rag,node_embeddings,node_marketdata,node_gemini,node_confidence,node_database,node_redis toneRose
class node_pipeline,node_sources,node_normalizers,node_analyst toneIndigo
```

## Components

### Terminal UI

- [Financial Terminal](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Query Bar](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/components/layout/QueryBar.tsx): `frontend/src/components/layout/QueryBar.tsx`
- [Event Impact Map](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/components/intelligence/EventImpactMap.tsx): `frontend/src/components/intelligence/EventImpactMap.tsx`
- [Market View](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/components/intelligence/MarketView.tsx): `frontend/src/components/intelligence/MarketView.tsx`
- [Audit Drawer](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/components/terminal/AuditDrawer.tsx): `frontend/src/components/terminal/AuditDrawer.tsx`
- [Event API Client](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/frontend/src/services/eventApi.ts): `frontend/src/services/eventApi.ts`

### API Layer

- [FastAPI Routers](https://github.com/higgsboson0906/financial-intelligence-terminal/tree/main/backend/app/api): `backend/app/api`
- [Query Endpoint](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/api/query.py): `backend/app/api/query.py`

### Analysis Workflow

- [Analysis Orchestrator](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/orchestrator.py): `backend/app/agents/orchestrator.py`
- [Query Parser](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/query_parser.py): `backend/app/services/query_parser.py`
- [Sentiment Agent](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/sentiment_agent.py): `backend/app/agents/sentiment_agent.py`
- [Weather Macro Agent](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/weather_macro_agent.py): `backend/app/agents/weather_macro_agent.py`
- [Risk Agent](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/risk_agent.py): `backend/app/agents/risk_agent.py`
- [Scenario Agent](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/scenario_agent.py): `backend/app/agents/scenario_agent.py`
- [Hedging Agent](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/agents/hedging_agent.py): `backend/app/agents/hedging_agent.py`
- [Quantitative Risk Engine](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/risk/engine.py): `risk/engine.py`
- [Predictive Analytics](https://github.com/higgsboson0906/financial-intelligence-terminal/tree/main/ml): `ml`
- [Analysis State and Evidence](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/schemas/orchestration.py): `backend/app/schemas/orchestration.py`

### Data Services

- [Historical Event Retrieval](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/historical_rag_service.py): `backend/app/services/historical_rag_service.py`
- [Embedding Service](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/embedding_service.py): `backend/app/services/embedding_service.py`
- [Market Data Service](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/market_service.py): `backend/app/services/market_service.py`
- [Gemini Synthesis](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/gemini_service.py): `backend/app/services/gemini_service.py`
- [Confidence Service](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/backend/app/services/confidence_service.py): `backend/app/services/confidence_service.py`
- **PostgreSQL / pgvector**
- **Redis Cache**

### Historical Data

- [Acquisition Pipeline](https://github.com/higgsboson0906/financial-intelligence-terminal/blob/main/scripts/data_acquisition/run_pipeline.py): `scripts/data_acquisition/run_pipeline.py`
- **Historical Data Sources**
- [Normalization and Dataset Build](https://github.com/higgsboson0906/financial-intelligence-terminal/tree/main/scripts/data_acquisition): `scripts/data_acquisition`

### Other components

- **Analyst**

## Connections

- Analyst → Query Bar: submits query (evidence: `frontend/src/components/layout/QueryBar.tsx`)
- Financial Terminal → Query Bar: renders (evidence: `frontend/src/App.tsx`)
- Financial Terminal → Event Impact Map: renders (evidence: `frontend/src/App.tsx`)
- Event Impact Map → Event API Client: uses (evidence: `frontend/src/components/intelligence/EventImpactMap.tsx`)
- Event Impact Map → Market View: renders (evidence: `frontend/src/components/intelligence/EventImpactMap.tsx`)
- Financial Terminal → Audit Drawer: renders (evidence: `frontend/src/App.tsx`)
- FastAPI Routers → Query Endpoint: registers (evidence: `backend/app/main.py`)
- Query Endpoint → Analysis Orchestrator: runs analysis (evidence: `backend/app/api/query.py`)
- Query Endpoint → Gemini Synthesis: synthesizes answer (evidence: `backend/app/api/query.py`)
- Query Endpoint → Confidence Service: calculates confidence (evidence: `backend/app/api/query.py`)
- Analysis Orchestrator → Query Parser: parses query (evidence: `backend/app/agents/orchestrator.py`)
- Analysis Orchestrator → Sentiment Agent: dispatches (evidence: `backend/app/agents/orchestrator.py`)
- Analysis Orchestrator → Weather Macro Agent: dispatches (evidence: `backend/app/agents/orchestrator.py`)
- Analysis Orchestrator → Historical Event Retrieval: retrieves events (evidence: `backend/app/agents/orchestrator.py`)
- Analysis Orchestrator → Market Data Service: loads market context (evidence: `backend/app/agents/orchestrator.py`)
- Analysis Orchestrator → Risk Agent: dispatches (evidence: `backend/app/agents/orchestrator.py`)
- Analysis Orchestrator → Scenario Agent: dispatches (evidence: `backend/app/agents/orchestrator.py`)
- Analysis Orchestrator → Hedging Agent: dispatches (evidence: `backend/app/agents/orchestrator.py`)
- Risk Agent → Quantitative Risk Engine: calculates risk (evidence: `backend/app/agents/risk_agent.py`)
- Analysis Orchestrator → PostgreSQL / pgvector: persists run data (evidence: `backend/app/agents/orchestrator.py`)
- Analysis Orchestrator → Analysis State and Evidence: updates state (evidence: `backend/app/agents/orchestrator.py`)
- Historical Event Retrieval → Embedding Service: embeds queries (evidence: `backend/app/services/historical_rag_service.py`)
- Historical Event Retrieval → PostgreSQL / pgvector: retrieves vectors (evidence: `backend/app/services/historical_rag_service.py`)
- Historical Event Retrieval → Redis Cache: reads cache (evidence: `backend/app/services/historical_rag_service.py`)
- Acquisition Pipeline → Historical Data Sources: downloads (evidence: `scripts/data_acquisition/run_pipeline.py`)
- Acquisition Pipeline → Normalization and Dataset Build: builds datasets (evidence: `scripts/data_acquisition/run_pipeline.py`)
