# itsaugustine04/alphadesk architecture

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

- Interactive diagram: https://gitdiagram.com/itsaugustine04/alphadesk
- Repository: https://github.com/itsaugustine04/alphadesk

## Overview

AlphaDesk turns a natural-language financial query into a routed anomaly, risk, or full analysis, fetches market data, and produces a Markdown research report. The graph coordinates specialist agents; in full mode it dispatches anomaly and risk analysis in parallel. Market data is accessed through an MCP subprocess, with live yfinance data or a synthetic fallback. The graph and state paths are sampled; the README documents checkpointing and generated reports. The graph below omits unsampled implementation details and shows only supported runtime relationships.

Main entry points: [`graph.py`](https://github.com/itsaugustine04/alphadesk/blob/main/graph.py) (LangGraph Workflow), [`agents/report.py`](https://github.com/itsaugustine04/alphadesk/blob/main/agents/report.py) (Report Synthesis), [`main.py`](https://github.com/itsaugustine04/alphadesk/blob/main/main.py) (CLI / Interactive), [`mcp_server/client.py`](https://github.com/itsaugustine04/alphadesk/blob/main/mcp_server/client.py) (MCP Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_workflow["LangGraph Workflow<br/>[graph.py]"]
  node_shared_state["Shared Run State<br/>[state.py]"]
  node_supervisor["Query Supervisor<br/>[supervisor.py]"]
end

subgraph group_market_data["Market Data"]
  node_data_fetch["Market Data Fetch<br/>[data_fetch.py]"]
  node_mcp_client["MCP Client<br/>[client.py]"]
  node_mcp_server["Market Data Server"]
end

subgraph group_analysis["Analysis"]
  node_anomaly["Anomaly Detection<br/>[anomaly.py]"]
  node_risk["Risk Metrics<br/>[risk.py]"]
end

subgraph group_reporting["Reporting"]
  node_report["Report Synthesis<br/>[report.py]"]
  node_report_files["Markdown Reports"]
end

node_user(("Researcher"))
node_cli["CLI / Interactive<br/>[main.py]"]
node_yfinance["yfinance"]
node_gemini["Gemini API"]

node_user -->|"submits query"| node_cli
node_cli -->|"calls run_query"| node_workflow
node_workflow -->|"invokes"| node_supervisor
node_supervisor -->|"classifies query"| node_gemini
node_workflow -->|"routes to fetch"| node_data_fetch
node_data_fetch -->|"requests market data"| node_mcp_client
node_risk -->|"fetches SPY data"| node_mcp_client
node_mcp_client -->|"calls tools"| node_mcp_server
node_mcp_server -.->|"fetches live data"| node_yfinance
node_workflow -->|"dispatches analysis"| node_anomaly
node_workflow -->|"dispatches analysis"| node_risk
node_workflow -->|"invokes after analysis"| node_report
node_report -->|"synthesizes findings"| node_gemini
node_report -->|"writes report"| node_report_files
node_workflow -->|"passes run state"| node_shared_state
node_cli -->|"shows completion"| node_user

click node_cli "https://github.com/itsaugustine04/alphadesk/blob/main/main.py"
click node_workflow "https://github.com/itsaugustine04/alphadesk/blob/main/graph.py"
click node_shared_state "https://github.com/itsaugustine04/alphadesk/blob/main/state.py"
click node_supervisor "https://github.com/itsaugustine04/alphadesk/blob/main/agents/supervisor.py"
click node_data_fetch "https://github.com/itsaugustine04/alphadesk/blob/main/agents/data_fetch.py"
click node_mcp_client "https://github.com/itsaugustine04/alphadesk/blob/main/mcp_server/client.py"
click node_mcp_server "https://github.com/itsaugustine04/alphadesk/blob/main/mcp_server/market_data_server.py"
click node_anomaly "https://github.com/itsaugustine04/alphadesk/blob/main/agents/anomaly.py"
click node_risk "https://github.com/itsaugustine04/alphadesk/blob/main/agents/risk.py"
click node_report "https://github.com/itsaugustine04/alphadesk/blob/main/agents/report.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_workflow,node_shared_state,node_supervisor toneBlue
class node_data_fetch,node_mcp_client,node_mcp_server toneAmber
class node_anomaly,node_risk,node_gemini toneMint
class node_report,node_report_files toneRose
class node_user,node_yfinance toneIndigo
class node_cli toneTeal
```

## Components

### Orchestration

- [LangGraph Workflow](https://github.com/itsaugustine04/alphadesk/blob/main/graph.py): `graph.py`
- [Shared Run State](https://github.com/itsaugustine04/alphadesk/blob/main/state.py): `state.py`
- [Query Supervisor](https://github.com/itsaugustine04/alphadesk/blob/main/agents/supervisor.py): `agents/supervisor.py`

### Market Data

- [Market Data Fetch](https://github.com/itsaugustine04/alphadesk/blob/main/agents/data_fetch.py): `agents/data_fetch.py`
- [MCP Client](https://github.com/itsaugustine04/alphadesk/blob/main/mcp_server/client.py): `mcp_server/client.py`
- [Market Data Server](https://github.com/itsaugustine04/alphadesk/blob/main/mcp_server/market_data_server.py): `mcp_server/market_data_server.py`

### Analysis

- [Anomaly Detection](https://github.com/itsaugustine04/alphadesk/blob/main/agents/anomaly.py): `agents/anomaly.py`
- [Risk Metrics](https://github.com/itsaugustine04/alphadesk/blob/main/agents/risk.py): `agents/risk.py`

### Reporting

- [Report Synthesis](https://github.com/itsaugustine04/alphadesk/blob/main/agents/report.py): `agents/report.py`
- **Markdown Reports**

### Other components

- **Researcher**
- [CLI / Interactive](https://github.com/itsaugustine04/alphadesk/blob/main/main.py): `main.py`
- **yfinance**
- **Gemini API**

## Connections

- Researcher → CLI / Interactive: submits query
- CLI / Interactive → LangGraph Workflow: calls run_query
- LangGraph Workflow → Query Supervisor: invokes
- Query Supervisor → Gemini API: classifies query
- LangGraph Workflow → Market Data Fetch: routes to fetch
- Market Data Fetch → MCP Client: requests market data
- Risk Metrics → MCP Client: fetches SPY data
- MCP Client → Market Data Server: calls tools
- Market Data Server → yfinance: fetches live data
- LangGraph Workflow → Anomaly Detection: dispatches analysis
- LangGraph Workflow → Risk Metrics: dispatches analysis
- LangGraph Workflow → Report Synthesis: invokes after analysis
- Report Synthesis → Gemini API: synthesizes findings
- Report Synthesis → Markdown Reports: writes report
- LangGraph Workflow → Shared Run State: passes run state
- CLI / Interactive → Researcher: shows completion