# gitiann/topological-portfolio-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/gitiann/topological-portfolio-analysis
- Repository: https://github.com/gitiann/topological-portfolio-analysis

## Overview

Toporisk computes per-asset topological risk from price returns, then uses those risks to construct a long-only minimum-risk portfolio. The main workflow runs through the CLI; the README also describes plotting landscapes and comparing topological risk with volatility. Portfolio performance evaluation is explicitly outside the project’s scope. Relationships follow the sampled CLI and risk implementations and README documentation; no unsampled source behavior is assumed.

Main entry points: [`src/toporisk/cli.py`](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/cli.py) (Build CLI), [`src/toporisk/risk.py`](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/risk.py) (Asset risk and matrix), [`src/toporisk/topology.py`](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/topology.py) (H0 persistence), [`src/toporisk/viz.py`](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/viz.py) (Portfolio and landscape plots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Market data"]
  node_price_data["Price and returns<br/>[data.py]"]
end

subgraph group_topology["Topology analysis"]
  node_embedding["Windows and embedding<br/>[embedding.py]"]
  node_h0["H0 persistence<br/>[topology.py]"]
  node_landscape["Persistence landscapes<br/>[landscape.py]"]
end

subgraph group_risk["Risk calculation"]
  node_asset_risk["Asset risk and matrix<br/>[risk.py]"]
end

subgraph group_portfolio["Portfolio construction"]
  node_optimizer["Risk optimizer<br/>[portfolio.py]"]
end

subgraph group_presentation["Results and plots"]
  node_cli["Build CLI<br/>[cli.py]"]
  node_plots["Portfolio and landscape plots<br/>[viz.py]"]
end

node_user(("Analyst"))
node_results["Weights and charts"]
node_gudhi["Gudhi library"]

node_user -->|"runs build"| node_cli
node_cli -->|"loads prices and returns"| node_price_data
node_cli -->|"computes asset risks"| node_asset_risk
node_cli -->|"optimizes weights"| node_optimizer
node_cli -->|"plots weights"| node_plots
node_cli -->|"prints or saves"| node_results
node_asset_risk -->|"windows and embeds"| node_embedding
node_asset_risk -->|"computes H0 diagrams"| node_h0
node_asset_risk -->|"builds and norms landscapes"| node_landscape
node_h0 -->|"builds Rips filtration"| node_gudhi
node_plots -->|"renders charts"| node_results

click node_cli "https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/cli.py"
click node_price_data "https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/data.py"
click node_embedding "https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/embedding.py"
click node_h0 "https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/topology.py"
click node_landscape "https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/landscape.py"
click node_asset_risk "https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/risk.py"
click node_optimizer "https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/portfolio.py"
click node_plots "https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/viz.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_price_data toneBlue
class node_embedding,node_h0,node_landscape toneAmber
class node_asset_risk toneMint
class node_optimizer toneRose
class node_cli,node_plots,node_user,node_results,node_gudhi toneIndigo
```

## Components

### Market data

- [Price and returns](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/data.py): `src/toporisk/data.py`

### Topology analysis

- [Windows and embedding](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/embedding.py): `src/toporisk/embedding.py`
- [H0 persistence](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/topology.py): `src/toporisk/topology.py`
- [Persistence landscapes](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/landscape.py): `src/toporisk/landscape.py`

### Risk calculation

- [Asset risk and matrix](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/risk.py): `src/toporisk/risk.py`

### Portfolio construction

- [Risk optimizer](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/portfolio.py): `src/toporisk/portfolio.py`

### Results and plots

- [Build CLI](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/cli.py): `src/toporisk/cli.py`
- [Portfolio and landscape plots](https://github.com/gitiann/topological-portfolio-analysis/blob/master/src/toporisk/viz.py): `src/toporisk/viz.py`

### Other components

- **Analyst**
- **Weights and charts**
- **Gudhi library**

## Connections

- Analyst → Build CLI: runs build (evidence: `README.md`)
- Build CLI → Price and returns: loads prices and returns (evidence: `src/toporisk/cli.py`)
- Build CLI → Asset risk and matrix: computes asset risks (evidence: `src/toporisk/cli.py`)
- Build CLI → Risk optimizer: optimizes weights (evidence: `src/toporisk/cli.py`)
- Build CLI → Portfolio and landscape plots: plots weights (evidence: `src/toporisk/cli.py`)
- Build CLI → Weights and charts: prints or saves (evidence: `src/toporisk/cli.py`)
- Asset risk and matrix → Windows and embedding: windows and embeds (evidence: `src/toporisk/risk.py`)
- Asset risk and matrix → H0 persistence: computes H0 diagrams (evidence: `src/toporisk/risk.py`)
- Asset risk and matrix → Persistence landscapes: builds and norms landscapes (evidence: `src/toporisk/risk.py`)
- H0 persistence → Gudhi library: builds Rips filtration (evidence: `src/toporisk/topology.py`)
- Portfolio and landscape plots → Weights and charts: renders charts (evidence: `README.md`)
