# nandar-zaw/marketmind architecture

> Architecture diagram of the GitHub repository nandar-zaw/marketmind, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nandar-zaw/marketmind
- Repository: https://github.com/nandar-zaw/marketmind

## Overview

MarketMind is a stock-analysis web app: a user submits a ticker and horizon through the dashboard or API, then receives a BUY/HOLD/SELL recommendation, confidence, and reasoning. The Coordinator validates the request, fetches shared data, collects Technical, Sentiment, and Fundamental signals, obtains a Risk assessment, and combines the results. The dashboard also presents charts and audit checks. README documentation establishes major integrations and capabilities; some agent and service implementations were not sampled, so their documented links are shown without implying additional internal calls.

Main entry points: [`app/agents/coordinator_agent.py`](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/coordinator_agent.py) (Coordinator), [`app/agents/data_agent.py`](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/data_agent.py) (Data Agent), [`app/ui.py`](https://github.com/nandar-zaw/marketmind/blob/main/app/ui.py) (Dashboard), [`app/models/schemas.py`](https://github.com/nandar-zaw/marketmind/blob/main/app/models/schemas.py) (Data Schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_api["API<br/>[main.py]"]
  node_dashboard["Dashboard<br/>[ui.py]"]
end

subgraph group_decision["Analysis"]
  node_coordinator["Coordinator"]
  node_technical["Technical Agent<br/>[technical_agent.py]"]
  node_sentiment["Sentiment Agent<br/>[sentiment_agent.py]"]
  node_fundamental["Fundamental Agent"]
  node_risk["Risk Manager<br/>[risk_agent.py]"]
end

subgraph group_data["Data Sources"]
  node_data_agent["Data Agent<br/>[data_agent.py]"]
  node_market_data["Market Data<br/>[market_data.py]"]
  node_news_data["News Data<br/>[news_data.py]"]
  node_filings_data["Filings Data<br/>[filings_data.py]"]
end

subgraph group_support["Shared Support"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_schemas["Data Schemas<br/>[schemas.py]"]
  node_base_agent["Agent Interface<br/>[base_agent.py]"]
  node_symbols["Symbol Resolver<br/>[symbols.py]"]
  node_exceptions["Data Errors<br/>[exceptions.py]"]
end

node_user(("Analyst"))
node_yahoo["Yahoo Finance"]
node_openai["OpenAI Services"]

node_user -->|"submits ticker"| node_api
node_user -->|"analyzes ticker"| node_dashboard
node_api -->|"routes analysis"| node_coordinator
node_dashboard -->|"runs analysis"| node_coordinator
node_coordinator -->|"checks inputs"| node_guardrails
node_coordinator -->|"loads shared data"| node_data_agent
node_coordinator -->|"requests signal"| node_technical
node_coordinator -->|"requests signal"| node_sentiment
node_coordinator -->|"requests signal"| node_fundamental
node_coordinator -->|"requests risk review"| node_risk
node_coordinator -->|"checks outputs"| node_guardrails
node_coordinator -->|"uses result types"| node_schemas
node_dashboard -->|"uses result types"| node_schemas
node_data_agent -->|"fetches prices"| node_market_data
node_data_agent -->|"fetches headlines"| node_news_data
node_data_agent -->|"retrieves filings"| node_filings_data
node_data_agent -->|"builds data result"| node_schemas
node_data_agent -->|"normalizes ticker"| node_symbols
node_data_agent -->|"raises data errors"| node_exceptions
node_market_data -->|"fetches market data"| node_yahoo
node_news_data -->|"searches headlines"| node_yahoo
node_filings_data -->|"searches filing store"| node_openai
node_sentiment -->|"scores headlines"| node_openai
node_fundamental -->|"scores excerpts"| node_openai

click node_api "https://github.com/nandar-zaw/marketmind/blob/main/app/main.py"
click node_dashboard "https://github.com/nandar-zaw/marketmind/blob/main/app/ui.py"
click node_coordinator "https://github.com/nandar-zaw/marketmind/blob/main/app/agents/coordinator_agent.py"
click node_data_agent "https://github.com/nandar-zaw/marketmind/blob/main/app/agents/data_agent.py"
click node_technical "https://github.com/nandar-zaw/marketmind/blob/main/app/agents/technical_agent.py"
click node_sentiment "https://github.com/nandar-zaw/marketmind/blob/main/app/agents/sentiment_agent.py"
click node_fundamental "https://github.com/nandar-zaw/marketmind/blob/main/app/agents/fundamental_agent.py"
click node_risk "https://github.com/nandar-zaw/marketmind/blob/main/app/agents/risk_agent.py"
click node_guardrails "https://github.com/nandar-zaw/marketmind/blob/main/app/guardrails.py"
click node_schemas "https://github.com/nandar-zaw/marketmind/blob/main/app/models/schemas.py"
click node_base_agent "https://github.com/nandar-zaw/marketmind/blob/main/app/agents/base_agent.py"
click node_market_data "https://github.com/nandar-zaw/marketmind/blob/main/app/services/market_data.py"
click node_news_data "https://github.com/nandar-zaw/marketmind/blob/main/app/services/news_data.py"
click node_filings_data "https://github.com/nandar-zaw/marketmind/blob/main/app/services/filings_data.py"
click node_symbols "https://github.com/nandar-zaw/marketmind/blob/main/app/utils/symbols.py"
click node_exceptions "https://github.com/nandar-zaw/marketmind/blob/main/app/utils/exceptions.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_api,node_dashboard toneBlue
class node_coordinator,node_technical,node_sentiment,node_fundamental,node_risk toneAmber
class node_data_agent,node_market_data,node_news_data,node_filings_data toneMint
class node_guardrails,node_schemas,node_base_agent,node_symbols,node_exceptions toneRose
class node_user,node_yahoo,node_openai toneIndigo
```

## Components

### User Entry

- [API](https://github.com/nandar-zaw/marketmind/blob/main/app/main.py): `app/main.py`
- [Dashboard](https://github.com/nandar-zaw/marketmind/blob/main/app/ui.py): `app/ui.py`

### Analysis

- [Coordinator](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/coordinator_agent.py): `app/agents/coordinator_agent.py`
- [Technical Agent](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/technical_agent.py): `app/agents/technical_agent.py`
- [Sentiment Agent](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/sentiment_agent.py): `app/agents/sentiment_agent.py`
- [Fundamental Agent](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/fundamental_agent.py): `app/agents/fundamental_agent.py`
- [Risk Manager](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/risk_agent.py): `app/agents/risk_agent.py`

### Data Sources

- [Data Agent](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/data_agent.py): `app/agents/data_agent.py`
- [Market Data](https://github.com/nandar-zaw/marketmind/blob/main/app/services/market_data.py): `app/services/market_data.py`
- [News Data](https://github.com/nandar-zaw/marketmind/blob/main/app/services/news_data.py): `app/services/news_data.py`
- [Filings Data](https://github.com/nandar-zaw/marketmind/blob/main/app/services/filings_data.py): `app/services/filings_data.py`

### Shared Support

- [Guardrails](https://github.com/nandar-zaw/marketmind/blob/main/app/guardrails.py): `app/guardrails.py`
- [Data Schemas](https://github.com/nandar-zaw/marketmind/blob/main/app/models/schemas.py): `app/models/schemas.py`
- [Agent Interface](https://github.com/nandar-zaw/marketmind/blob/main/app/agents/base_agent.py): `app/agents/base_agent.py`
- [Symbol Resolver](https://github.com/nandar-zaw/marketmind/blob/main/app/utils/symbols.py): `app/utils/symbols.py`
- [Data Errors](https://github.com/nandar-zaw/marketmind/blob/main/app/utils/exceptions.py): `app/utils/exceptions.py`

### Other components

- **Analyst**
- **Yahoo Finance**
- **OpenAI Services**

## Connections

- Analyst → API: submits ticker (evidence: `README.md`)
- Analyst → Dashboard: analyzes ticker (evidence: `README.md`)
- API → Coordinator: routes analysis (evidence: `app/main.py`)
- Dashboard → Coordinator: runs analysis (evidence: `app/ui.py`)
- Coordinator → Guardrails: checks inputs (evidence: `app/agents/coordinator_agent.py`)
- Coordinator → Data Agent: loads shared data (evidence: `app/agents/coordinator_agent.py`)
- Coordinator → Technical Agent: requests signal (evidence: `app/agents/coordinator_agent.py`)
- Coordinator → Sentiment Agent: requests signal (evidence: `app/agents/coordinator_agent.py`)
- Coordinator → Fundamental Agent: requests signal (evidence: `app/agents/coordinator_agent.py`)
- Coordinator → Risk Manager: requests risk review (evidence: `app/agents/coordinator_agent.py`)
- Coordinator → Guardrails: checks outputs (evidence: `app/agents/coordinator_agent.py`)
- Coordinator → Data Schemas: uses result types (evidence: `app/agents/coordinator_agent.py`)
- Dashboard → Data Schemas: uses result types (evidence: `app/ui.py`)
- Data Agent → Market Data: fetches prices (evidence: `app/agents/data_agent.py`)
- Data Agent → News Data: fetches headlines (evidence: `app/agents/data_agent.py`)
- Data Agent → Filings Data: retrieves filings (evidence: `app/agents/data_agent.py`)
- Data Agent → Data Schemas: builds data result (evidence: `app/agents/data_agent.py`)
- Data Agent → Symbol Resolver: normalizes ticker (evidence: `app/agents/data_agent.py`)
- Data Agent → Data Errors: raises data errors (evidence: `app/agents/data_agent.py`)
- Market Data → Yahoo Finance: fetches market data (evidence: `README.md`)
- News Data → Yahoo Finance: searches headlines (evidence: `README.md`)
- Filings Data → OpenAI Services: searches filing store (evidence: `README.md`)
- Sentiment Agent → OpenAI Services: scores headlines (evidence: `README.md`)
- Fundamental Agent → OpenAI Services: scores excerpts (evidence: `README.md`)
