# shettigarpratham6-web/portfolio-health-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/shettigarpratham6-web/portfolio-health-monitor
- Repository: https://github.com/shettigarpratham6-web/portfolio-health-monitor

## Overview

Portfolio Health Monitor is a web-based, evidence-focused portfolio surveillance product. Users authenticate, manage holdings, and initiate monitoring; the backend orchestrates portfolio analysis, research discovery, verification, impact assessment, and alert reporting, then presents results in the dashboard. The README documents additional capabilities including live market data, external research, audit exports, and observability. Edges are limited to relationships supported by excerpts, the source index, or README; unsampled subsystem paths use their enclosing directories.

Main entry points: [`app/agents/supervisor.py`](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/supervisor.py) (Supervisor agent), [`app/mcp/clients.py`](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/mcp/clients.py) (MCP tool gateway), [`frontend/src/App.tsx`](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/App.tsx) (Web application), [`app/api/routes/portfolios.py`](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/api/routes/portfolios.py) (Portfolio routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_authui["Authentication UI<br/>[AuthModal.tsx]"]
  node_authstate["Auth context<br/>[AuthContext.tsx]"]
  node_portfolio_ui["Portfolio dashboard"]
  node_alerts_ui["Alerts dashboard<br/>[AlertsManager.tsx]"]
  node_frontend_api["Frontend API client<br/>[client.ts]"]
end

subgraph group_api["API and security"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_portfolio_routes["Portfolio routes<br/>[portfolios.py]"]
  node_guardrails["Input and output guardrails"]
end

subgraph group_workflow["Monitoring workflow"]
  node_workflow["LangGraph workflow<br/>[workflow.py]"]
  node_supervisor["Supervisor agent<br/>[supervisor.py]"]
  node_portfolio_agent["Portfolio analysis<br/>[portfolio_agent.py]"]
  node_discovery_agent["Research discovery<br/>[discovery_agent.py]"]
  node_verification_agent["Evidence verification"]
  node_impact_agent["Risk impact analysis<br/>[impact_agent.py]"]
  node_reporting_agent["Alert reporting<br/>[reporting_agent.py]"]
end

subgraph group_tools["Tools and integrations"]
  node_mcp_gateway["MCP tool gateway<br/>[clients.py]"]
  node_mcp_servers["MCP tool servers"]
  node_llm["LLM service<br/>[llm.py]"]
  node_market_data["Market data and FX<br/>[twelve_data.py]"]
  node_research_service["Research service<br/>[research.py]"]
  node_tracing["LangSmith tracing<br/>[tracing.py]"]
end

subgraph group_persistence["Persistence"]
  node_postgres[("PostgreSQL")]
  node_db_access["Database access<br/>[connection.py]"]
  node_domain_models["Portfolio and event models"]
end

node_user(("Portfolio user"))
node_tavily{{"Tavily search"}}
node_openrouter{{"OpenRouter"}}
node_langsmith{{"LangSmith Cloud"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"renders"| node_authui
node_webapp -->|"renders"| node_portfolio_ui
node_webapp -->|"renders"| node_alerts_ui
node_webapp -->|"provides auth"| node_authstate
node_authui -->|"uses"| node_authstate
node_authstate -->|"stores credentials"| node_frontend_api
node_portfolio_ui -->|"calls API"| node_frontend_api
node_alerts_ui -->|"calls API"| node_frontend_api
node_frontend_api -.->|"HTTP requests"| node_auth_routes
node_frontend_api -.->|"HTTP requests"| node_portfolio_routes
node_auth_routes -->|"uses sessions"| node_db_access
node_auth_routes -->|"queries users"| node_domain_models
node_portfolio_routes -->|"starts monitoring"| node_workflow
node_portfolio_routes -->|"fetches quotes"| node_market_data
node_portfolio_routes -->|"uses sessions"| node_db_access
node_workflow -->|"validates inputs"| node_guardrails
node_workflow -->|"routes work"| node_supervisor
node_supervisor -->|"loads holdings"| node_portfolio_agent
node_supervisor -->|"requests research"| node_discovery_agent
node_supervisor -->|"verifies events"| node_verification_agent
node_supervisor -->|"assesses impact"| node_impact_agent
node_supervisor -->|"builds report"| node_reporting_agent
node_portfolio_agent -->|"requests tools"| node_mcp_gateway
node_discovery_agent -->|"requests tools"| node_mcp_gateway
node_verification_agent -->|"checks duplicates"| node_mcp_gateway
node_impact_agent -->|"requests analysis"| node_mcp_gateway
node_reporting_agent -->|"persists alerts"| node_mcp_gateway
node_mcp_gateway -->|"dispatches tools"| node_mcp_servers
node_mcp_servers -->|"reads and writes"| node_postgres
node_mcp_servers -->|"searches"| node_tavily
node_discovery_agent -->|"uses language model"| node_llm
node_verification_agent -->|"classifies evidence"| node_llm
node_llm -->|"sends completions"| node_openrouter
node_portfolio_routes -->|"reads and writes"| node_domain_models
node_db_access -->|"connects"| node_postgres
node_workflow -->|"configures tracing"| node_tracing
node_tracing -->|"sends traces"| node_langsmith
node_research_service -.->|"searches"| node_tavily
node_market_data -.-> node_tavily

click node_webapp "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/App.tsx"
click node_authui "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/components/auth/AuthModal.tsx"
click node_authstate "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/context/AuthContext.tsx"
click node_portfolio_ui "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/components/dashboard/PortfolioManager.tsx"
click node_alerts_ui "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/components/dashboard/AlertsManager.tsx"
click node_frontend_api "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/api/client.ts"
click node_auth_routes "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/api/routes/auth.py"
click node_portfolio_routes "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/api/routes/portfolios.py"
click node_guardrails "https://github.com/shettigarpratham6-web/portfolio-health-monitor/tree/main/app/guardrails"
click node_workflow "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/graph/workflow.py"
click node_supervisor "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/supervisor.py"
click node_portfolio_agent "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/portfolio_agent.py"
click node_discovery_agent "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/discovery_agent.py"
click node_verification_agent "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/verification_agent.py"
click node_impact_agent "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/impact_agent.py"
click node_reporting_agent "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/reporting_agent.py"
click node_mcp_gateway "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/mcp/clients.py"
click node_mcp_servers "https://github.com/shettigarpratham6-web/portfolio-health-monitor/tree/main/app/mcp/servers"
click node_llm "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/services/llm.py"
click node_market_data "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/services/twelve_data.py"
click node_research_service "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/services/research.py"
click node_db_access "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/database/connection.py"
click node_domain_models "https://github.com/shettigarpratham6-web/portfolio-health-monitor/tree/main/app/models"
click node_tracing "https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/core/tracing.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_webapp,node_authui,node_authstate,node_portfolio_ui,node_alerts_ui,node_frontend_api,node_user toneBlue
class node_auth_routes,node_portfolio_routes,node_guardrails toneAmber
class node_workflow,node_supervisor,node_portfolio_agent,node_discovery_agent,node_verification_agent,node_impact_agent,node_reporting_agent,node_openrouter toneMint
class node_mcp_gateway,node_mcp_servers,node_llm,node_market_data,node_research_service,node_tracing toneRose
class node_postgres,node_db_access,node_domain_models,node_tavily,node_langsmith toneIndigo
```

## Components

### Web client

- [Web application](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Authentication UI](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/components/auth/AuthModal.tsx): `frontend/src/components/auth/AuthModal.tsx`
- [Auth context](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Portfolio dashboard](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/components/dashboard/PortfolioManager.tsx): `frontend/src/components/dashboard/PortfolioManager.tsx`
- [Alerts dashboard](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/components/dashboard/AlertsManager.tsx): `frontend/src/components/dashboard/AlertsManager.tsx`
- [Frontend API client](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and security

- [Authentication routes](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/api/routes/auth.py): `app/api/routes/auth.py`
- [Portfolio routes](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/api/routes/portfolios.py): `app/api/routes/portfolios.py`
- [Input and output guardrails](https://github.com/shettigarpratham6-web/portfolio-health-monitor/tree/main/app/guardrails): `app/guardrails`

### Monitoring workflow

- [LangGraph workflow](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/graph/workflow.py): `app/graph/workflow.py`
- [Supervisor agent](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/supervisor.py): `app/agents/supervisor.py`
- [Portfolio analysis](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/portfolio_agent.py): `app/agents/portfolio_agent.py`
- [Research discovery](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/discovery_agent.py): `app/agents/discovery_agent.py`
- [Evidence verification](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/verification_agent.py): `app/agents/verification_agent.py`
- [Risk impact analysis](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/impact_agent.py): `app/agents/impact_agent.py`
- [Alert reporting](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/agents/reporting_agent.py): `app/agents/reporting_agent.py`

### Tools and integrations

- [MCP tool gateway](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/mcp/clients.py): `app/mcp/clients.py`
- [MCP tool servers](https://github.com/shettigarpratham6-web/portfolio-health-monitor/tree/main/app/mcp/servers): `app/mcp/servers`
- [LLM service](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/services/llm.py): `app/services/llm.py`
- [Market data and FX](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/services/twelve_data.py): `app/services/twelve_data.py`
- [Research service](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/services/research.py): `app/services/research.py`
- [LangSmith tracing](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/core/tracing.py): `app/core/tracing.py`

### Persistence

- **PostgreSQL**
- [Database access](https://github.com/shettigarpratham6-web/portfolio-health-monitor/blob/main/app/database/connection.py): `app/database/connection.py`
- [Portfolio and event models](https://github.com/shettigarpratham6-web/portfolio-health-monitor/tree/main/app/models): `app/models`

### Other components

- **Portfolio user**
- **Tavily search**
- **OpenRouter**
- **LangSmith Cloud**

## Connections

- Portfolio user → Web application: uses
- Web application → Authentication UI: renders (evidence: `frontend/src/App.tsx`)
- Web application → Portfolio dashboard: renders (evidence: `frontend/src/App.tsx`)
- Web application → Alerts dashboard: renders (evidence: `frontend/src/App.tsx`)
- Web application → Auth context: provides auth (evidence: `frontend/src/App.tsx`)
- Authentication UI → Auth context: uses (evidence: `frontend/src/components/auth/AuthModal.tsx`)
- Auth context → Frontend API client: stores credentials (evidence: `frontend/src/context/AuthContext.tsx`)
- Portfolio dashboard → Frontend API client: calls API (evidence: `frontend/src/components/dashboard/PortfolioManager.tsx`)
- Alerts dashboard → Frontend API client: calls API (evidence: `frontend/src/components/dashboard/AlertsManager.tsx`)
- Frontend API client → Authentication routes: HTTP requests
- Frontend API client → Portfolio routes: HTTP requests
- Authentication routes → Database access: uses sessions (evidence: `app/api/routes/auth.py`)
- Authentication routes → Portfolio and event models: queries users (evidence: `app/api/routes/auth.py`)
- Portfolio routes → LangGraph workflow: starts monitoring (evidence: `app/api/routes/portfolios.py`)
- Portfolio routes → Market data and FX: fetches quotes (evidence: `app/api/routes/portfolios.py`)
- Portfolio routes → Database access: uses sessions (evidence: `app/api/routes/portfolios.py`)
- LangGraph workflow → Input and output guardrails: validates inputs (evidence: `app/graph/workflow.py`)
- LangGraph workflow → Supervisor agent: routes work (evidence: `app/graph/workflow.py`)
- Supervisor agent → Portfolio analysis: loads holdings (evidence: `app/agents/supervisor.py`)
- Supervisor agent → Research discovery: requests research (evidence: `app/agents/supervisor.py`)
- Supervisor agent → Evidence verification: verifies events (evidence: `app/agents/supervisor.py`)
- Supervisor agent → Risk impact analysis: assesses impact (evidence: `app/agents/supervisor.py`)
- Supervisor agent → Alert reporting: builds report (evidence: `app/agents/supervisor.py`)
- Portfolio analysis → MCP tool gateway: requests tools (evidence: `app/agents/portfolio_agent.py`)
- Research discovery → MCP tool gateway: requests tools (evidence: `app/agents/discovery_agent.py`)
- Evidence verification → MCP tool gateway: checks duplicates (evidence: `app/agents/verification_agent.py`)
- Risk impact analysis → MCP tool gateway: requests analysis (evidence: `app/agents/impact_agent.py`)
- Alert reporting → MCP tool gateway: persists alerts (evidence: `app/agents/reporting_agent.py`)
- MCP tool gateway → MCP tool servers: dispatches tools (evidence: `app/mcp/clients.py`)
- MCP tool servers → PostgreSQL: reads and writes
- MCP tool servers → Tavily search: searches
- Research discovery → LLM service: uses language model (evidence: `app/agents/discovery_agent.py`)
- Evidence verification → LLM service: classifies evidence (evidence: `app/agents/verification_agent.py`)
- LLM service → OpenRouter: sends completions (evidence: `app/services/llm.py`)
- Portfolio routes → Portfolio and event models: reads and writes (evidence: `app/api/routes/portfolios.py`)
- Database access → PostgreSQL: connects (evidence: `app/database/connection.py`)
- LangGraph workflow → LangSmith tracing: configures tracing (evidence: `app/graph/workflow.py`)
- LangSmith tracing → LangSmith Cloud: sends traces
- Research service → Tavily search: searches
- Market data and FX → Tavily search