# jjw712/capstone2 architecture

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

- Interactive diagram: https://gitdiagram.com/jjw712/capstone2
- Repository: https://github.com/jjw712/capstone2

## Overview

This repository is an early-stage robo-advisor combining a planned PPO asset-allocation engine with a LangGraph research agent. The only working API route is health; dashboard tabs are placeholders. The graph distinguishes that running health-check path from the documented research, portfolio, risk, evaluation, and explainability capabilities, whose implementations are not present in the sampled source. Dashed links mark documented but not yet verified runtime integration.

Main entry points: [`dashboard/app.py`](https://github.com/jjw712/capstone2/blob/main/dashboard/app.py) (Dashboard App), [`src/roboadvisor/rl`](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/rl) (PPO Allocation), [`src/roboadvisor/research`](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/research) (RAG Research Agent), [`api/main.py`](https://github.com/jjw712/capstone2/blob/main/api/main.py) (FastAPI App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_dashboard["Dashboard App<br/>[app.py]"]
  node_shared_ui["Shared UI<br/>[common.py]"]
  node_api_client["API Client<br/>[client.py]"]
  node_portfolio_page["Portfolio Page<br/>[portfolio.py]"]
  node_rl_page["RL Performance<br/>[rl_performance.py]"]
  node_shap_page["SHAP Explain<br/>[shap_explain.py]"]
  node_research_page["Research Page<br/>[research.py]"]
  node_anova_page["ANOVA Results<br/>[anova.py]"]
  node_risk_page["Risk Monitor<br/>[risk_monitor.py]"]
end

subgraph group_serving["API Serving"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_health_route["Health Route<br/>[health.py]"]
  node_serving_state["Serving State<br/>[dependencies.py]"]
  node_api_schema["Health Schema<br/>[schemas.py]"]
end

subgraph group_investment["Investment Workflow"]
  node_data_pipeline["Market Data"]
  node_trading_env["Trading Environment"]
  node_rl_engine["PPO Allocation"]
  node_baselines["Portfolio Baselines"]
  node_research_agent["RAG Research Agent"]
  node_risk_analysis["Risk Analysis"]
  node_evaluation["Evaluation"]
  node_services["Integration Services"]
end

subgraph group_foundation["Shared Foundation"]
  node_contracts["Decision Contracts<br/>[contracts.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_storage["Persistence"]
  node_serving_artifacts["Serving Artifacts"]
  node_market_data_store[("Market Data Files")]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_shared_ui
node_dashboard -->|"routes to"| node_portfolio_page
node_dashboard -->|"routes to"| node_rl_page
node_dashboard -->|"routes to"| node_shap_page
node_dashboard -->|"routes to"| node_research_page
node_dashboard -->|"routes to"| node_anova_page
node_dashboard -->|"routes to"| node_risk_page
node_shared_ui -->|"checks health via"| node_api_client
node_api_client -->|"requests"| node_api_app
node_user -->|"calls"| node_api_app
node_api_app -->|"loads at startup"| node_serving_state
node_api_app -->|"registers"| node_health_route
node_health_route -->|"reads"| node_serving_state
node_health_route -->|"returns"| node_api_schema
node_serving_state -->|"gets settings"| node_config
node_serving_state -->|"reads manifest"| node_serving_artifacts
node_config -->|"defines data paths"| node_market_data_store
node_config -->|"defines serving path"| node_serving_artifacts
node_data_pipeline -.->|"uses data"| node_market_data_store
node_trading_env -.->|"consumes market data"| node_data_pipeline
node_rl_engine -.->|"trains against"| node_trading_env
node_evaluation -.->|"evaluates"| node_rl_engine
node_evaluation -.->|"compares"| node_baselines
node_research_agent -.->|"adds risk tags"| node_risk_analysis
node_rl_engine -.->|"combines with"| node_research_agent
node_services -.->|"integrates"| node_rl_engine
node_services -.->|"integrates"| node_research_agent
node_contracts -.->|"structures decisions"| node_rl_engine
node_contracts -.->|"structures evidence"| node_research_agent
node_storage -.->|"persists data"| node_market_data_store
node_rl_page -.->|"presents results"| node_evaluation
node_shap_page -.->|"explains allocations"| node_rl_engine
node_research_page -.->|"presents research"| node_research_agent
node_risk_page -.->|"presents risks"| node_risk_analysis
node_portfolio_page -.->|"presents allocation"| node_rl_engine
node_anova_page -.->|"presents validation"| node_evaluation

click node_dashboard "https://github.com/jjw712/capstone2/blob/main/dashboard/app.py"
click node_shared_ui "https://github.com/jjw712/capstone2/blob/main/dashboard/components/common.py"
click node_api_client "https://github.com/jjw712/capstone2/blob/main/dashboard/client.py"
click node_portfolio_page "https://github.com/jjw712/capstone2/blob/main/dashboard/pages/portfolio.py"
click node_rl_page "https://github.com/jjw712/capstone2/blob/main/dashboard/pages/rl_performance.py"
click node_shap_page "https://github.com/jjw712/capstone2/blob/main/dashboard/pages/shap_explain.py"
click node_research_page "https://github.com/jjw712/capstone2/blob/main/dashboard/pages/research.py"
click node_anova_page "https://github.com/jjw712/capstone2/blob/main/dashboard/pages/anova.py"
click node_risk_page "https://github.com/jjw712/capstone2/blob/main/dashboard/pages/risk_monitor.py"
click node_api_app "https://github.com/jjw712/capstone2/blob/main/api/main.py"
click node_health_route "https://github.com/jjw712/capstone2/blob/main/api/routers/health.py"
click node_serving_state "https://github.com/jjw712/capstone2/blob/main/api/dependencies.py"
click node_api_schema "https://github.com/jjw712/capstone2/blob/main/api/schemas.py"
click node_data_pipeline "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/data"
click node_trading_env "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/trading_env"
click node_rl_engine "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/rl"
click node_baselines "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/baselines"
click node_research_agent "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/research"
click node_risk_analysis "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/risk"
click node_evaluation "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/evaluation"
click node_services "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/services"
click node_contracts "https://github.com/jjw712/capstone2/blob/main/src/roboadvisor/contracts.py"
click node_config "https://github.com/jjw712/capstone2/blob/main/src/roboadvisor/config.py"
click node_storage "https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/storage"
click node_serving_artifacts "https://github.com/jjw712/capstone2/tree/main/artifacts/serving"
click node_market_data_store "https://github.com/jjw712/capstone2/tree/main/data"

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_dashboard,node_shared_ui,node_api_client,node_portfolio_page,node_rl_page,node_shap_page,node_research_page,node_anova_page,node_risk_page,node_user toneBlue
class node_api_app,node_health_route,node_serving_state,node_api_schema toneAmber
class node_data_pipeline,node_trading_env,node_rl_engine,node_baselines,node_research_agent,node_risk_analysis,node_evaluation,node_services toneMint
class node_contracts,node_config,node_storage,node_serving_artifacts,node_market_data_store toneRose
```

## Components

### User Interfaces

- [Dashboard App](https://github.com/jjw712/capstone2/blob/main/dashboard/app.py): `dashboard/app.py`
- [Shared UI](https://github.com/jjw712/capstone2/blob/main/dashboard/components/common.py): `dashboard/components/common.py`
- [API Client](https://github.com/jjw712/capstone2/blob/main/dashboard/client.py): `dashboard/client.py`
- [Portfolio Page](https://github.com/jjw712/capstone2/blob/main/dashboard/pages/portfolio.py): `dashboard/pages/portfolio.py`
- [RL Performance](https://github.com/jjw712/capstone2/blob/main/dashboard/pages/rl_performance.py): `dashboard/pages/rl_performance.py`
- [SHAP Explain](https://github.com/jjw712/capstone2/blob/main/dashboard/pages/shap_explain.py): `dashboard/pages/shap_explain.py`
- [Research Page](https://github.com/jjw712/capstone2/blob/main/dashboard/pages/research.py): `dashboard/pages/research.py`
- [ANOVA Results](https://github.com/jjw712/capstone2/blob/main/dashboard/pages/anova.py): `dashboard/pages/anova.py`
- [Risk Monitor](https://github.com/jjw712/capstone2/blob/main/dashboard/pages/risk_monitor.py): `dashboard/pages/risk_monitor.py`

### API Serving

- [FastAPI App](https://github.com/jjw712/capstone2/blob/main/api/main.py): `api/main.py`
- [Health Route](https://github.com/jjw712/capstone2/blob/main/api/routers/health.py): `api/routers/health.py`
- [Serving State](https://github.com/jjw712/capstone2/blob/main/api/dependencies.py): `api/dependencies.py`
- [Health Schema](https://github.com/jjw712/capstone2/blob/main/api/schemas.py): `api/schemas.py`

### Investment Workflow

- [Market Data](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/data): `src/roboadvisor/data`
- [Trading Environment](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/trading_env): `src/roboadvisor/trading_env`
- [PPO Allocation](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/rl): `src/roboadvisor/rl`
- [Portfolio Baselines](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/baselines): `src/roboadvisor/baselines`
- [RAG Research Agent](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/research): `src/roboadvisor/research`
- [Risk Analysis](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/risk): `src/roboadvisor/risk`
- [Evaluation](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/evaluation): `src/roboadvisor/evaluation`
- [Integration Services](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/services): `src/roboadvisor/services`

### Shared Foundation

- [Decision Contracts](https://github.com/jjw712/capstone2/blob/main/src/roboadvisor/contracts.py): `src/roboadvisor/contracts.py`
- [Configuration](https://github.com/jjw712/capstone2/blob/main/src/roboadvisor/config.py): `src/roboadvisor/config.py`
- [Persistence](https://github.com/jjw712/capstone2/tree/main/src/roboadvisor/storage): `src/roboadvisor/storage`
- [Serving Artifacts](https://github.com/jjw712/capstone2/tree/main/artifacts/serving): `artifacts/serving`
- [Market Data Files](https://github.com/jjw712/capstone2/tree/main/data): `data`

### Other components

- **User**

## Connections

- User → Dashboard App: uses (evidence: `README.md`)
- Dashboard App → Shared UI: renders (evidence: `dashboard/app.py`)
- Dashboard App → Portfolio Page: routes to (evidence: `dashboard/app.py`)
- Dashboard App → RL Performance: routes to (evidence: `dashboard/app.py`)
- Dashboard App → SHAP Explain: routes to (evidence: `dashboard/app.py`)
- Dashboard App → Research Page: routes to (evidence: `dashboard/app.py`)
- Dashboard App → ANOVA Results: routes to (evidence: `dashboard/app.py`)
- Dashboard App → Risk Monitor: routes to (evidence: `dashboard/app.py`)
- Shared UI → API Client: checks health via (evidence: `dashboard/components/common.py`)
- API Client → FastAPI App: requests (evidence: `README.md`)
- User → FastAPI App: calls (evidence: `README.md`)
- FastAPI App → Serving State: loads at startup (evidence: `api/main.py`)
- FastAPI App → Health Route: registers (evidence: `api/main.py`)
- Health Route → Serving State: reads (evidence: `api/routers/health.py`)
- Health Route → Health Schema: returns (evidence: `api/routers/health.py`)
- Serving State → Configuration: gets settings (evidence: `api/dependencies.py`)
- Serving State → Serving Artifacts: reads manifest (evidence: `api/dependencies.py`)
- Configuration → Market Data Files: defines data paths (evidence: `src/roboadvisor/config.py`)
- Configuration → Serving Artifacts: defines serving path (evidence: `src/roboadvisor/config.py`)
- Market Data → Market Data Files: uses data
- Trading Environment → Market Data: consumes market data (evidence: `README.md`)
- PPO Allocation → Trading Environment: trains against (evidence: `README.md`)
- Evaluation → PPO Allocation: evaluates (evidence: `README.md`)
- Evaluation → Portfolio Baselines: compares (evidence: `README.md`)
- RAG Research Agent → Risk Analysis: adds risk tags (evidence: `README.md`)
- PPO Allocation → RAG Research Agent: combines with (evidence: `README.md`)
- Integration Services → PPO Allocation: integrates
- Integration Services → RAG Research Agent: integrates
- Decision Contracts → PPO Allocation: structures decisions (evidence: `README.md`)
- Decision Contracts → RAG Research Agent: structures evidence (evidence: `README.md`)
- Persistence → Market Data Files: persists data
- RL Performance → Evaluation: presents results (evidence: `README.md`)
- SHAP Explain → PPO Allocation: explains allocations (evidence: `README.md`)
- Research Page → RAG Research Agent: presents research (evidence: `README.md`)
- Risk Monitor → Risk Analysis: presents risks (evidence: `README.md`)
- Portfolio Page → PPO Allocation: presents allocation (evidence: `README.md`)
- ANOVA Results → Evaluation: presents validation (evidence: `README.md`)