# songalobung/mizani architecture

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

- Interactive diagram: https://gitdiagram.com/songalobung/mizani
- Repository: https://github.com/songalobung/mizani

## Overview

Mizani is a pension-allocation optimizer and CLI: users provide market data, portfolio holdings, fund settings, and jurisdiction rules; the CLI validates and estimates inputs, then runs optimization or related analysis and produces results or reports. Its main domain stages are input validation, estimation and rule compilation, optimization, and compliance/transition and regulation analytics. The README documents capabilities beyond the sampled excerpts, including multiple solver methods and regulation data as YAML. Edges are limited to README statements and shown source references; unsampled details are not inferred.

Main entry points: [`src/mizani/cli.py`](https://github.com/songalobung/mizani/blob/main/src/mizani/cli.py) (Mizani CLI), [`src/mizani/optimizers.py`](https://github.com/songalobung/mizani/blob/main/src/mizani/optimizers.py) (Portfolio Solvers), [`src/mizani/report.py`](https://github.com/songalobung/mizani/blob/main/src/mizani/report.py) (Analysis Report), [`src/mizani/frontier.py`](https://github.com/songalobung/mizani/blob/main/src/mizani/frontier.py) (Efficient Frontier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and Validation"]
  node_market_data["Market Data"]
  node_holdings["Portfolio Holdings<br/>[portfolio.csv]"]
  node_regulations["Regulation Rules"]
  node_schemas["Input Schemas<br/>[schemas.py]"]
  node_loaders["Data Loaders<br/>[loaders.py]"]
end

subgraph group_engine["Quantitative Engine"]
  node_estimation["Return Estimation<br/>[estimation.py]"]
  node_rules["Rule Compiler<br/>[rules.py]"]
  node_optimizers["Portfolio Solvers<br/>[optimizers.py]"]
end

subgraph group_analysis["Analysis and Transition"]
  node_compliance["Compliance Audit<br/>[compliance.py]"]
  node_frontier["Efficient Frontier<br/>[frontier.py]"]
  node_regcost["Regulation Cost<br/>[regcost.py]"]
  node_rebalance["Rebalance Planner<br/>[rebalance.py]"]
  node_scenarios["Scenario Analysis<br/>[scenarios.py]"]
end

subgraph group_interface["User Interface"]
  node_cli["Mizani CLI<br/>[cli.py]"]
  node_report["Analysis Report<br/>[report.py]"]
end

node_manager(("Fund Manager"))

node_manager -->|"runs commands"| node_cli
node_market_data -->|"supplies data"| node_cli
node_holdings -->|"supplies holdings"| node_cli
node_regulations -->|"supplies rules"| node_cli
node_cli -->|"loads inputs"| node_loaders
node_loaders -->|"validates with"| node_schemas
node_cli -->|"estimates returns"| node_estimation
node_cli -->|"solves allocation"| node_optimizers
node_cli -->|"checks holdings"| node_compliance
node_cli -->|"generates frontier"| node_frontier
node_cli -->|"analyzes regulation cost"| node_regcost
node_cli -->|"plans rebalancing"| node_rebalance
node_cli -->|"compares scenarios"| node_scenarios
node_cli -->|"generates report"| node_report
node_optimizers -->|"uses estimates"| node_estimation
node_optimizers -->|"uses constraints"| node_rules
node_frontier -->|"uses solvers"| node_optimizers
node_frontier -->|"uses estimates"| node_estimation
node_frontier -->|"uses constraints"| node_rules
node_compliance -->|"loads holdings"| node_loaders
node_rebalance -->|"checks transitions"| node_compliance
node_rebalance -->|"uses constraints"| node_rules
node_regcost -->|"compares solutions"| node_optimizers
node_regcost -->|"uses estimates"| node_estimation
node_scenarios -->|"shocks estimates"| node_estimation
node_scenarios -->|"compares allocations"| node_optimizers
node_scenarios -->|"compares regulation cost"| node_regcost
node_report -->|"includes audit"| node_compliance
node_report -->|"includes frontier"| node_frontier
node_report -->|"includes cost analysis"| node_regcost
node_report -->|"includes trades"| node_rebalance
node_report -->|"includes allocation"| node_optimizers

click node_market_data "https://github.com/songalobung/mizani/tree/main/data/templates"
click node_holdings "https://github.com/songalobung/mizani/blob/main/data/templates/portfolio.csv"
click node_regulations "https://github.com/songalobung/mizani/tree/main/regulations"
click node_schemas "https://github.com/songalobung/mizani/blob/main/src/mizani/schemas.py"
click node_loaders "https://github.com/songalobung/mizani/blob/main/src/mizani/loaders.py"
click node_cli "https://github.com/songalobung/mizani/blob/main/src/mizani/cli.py"
click node_estimation "https://github.com/songalobung/mizani/blob/main/src/mizani/estimation.py"
click node_rules "https://github.com/songalobung/mizani/blob/main/src/mizani/rules.py"
click node_optimizers "https://github.com/songalobung/mizani/blob/main/src/mizani/optimizers.py"
click node_compliance "https://github.com/songalobung/mizani/blob/main/src/mizani/compliance.py"
click node_frontier "https://github.com/songalobung/mizani/blob/main/src/mizani/frontier.py"
click node_regcost "https://github.com/songalobung/mizani/blob/main/src/mizani/regcost.py"
click node_rebalance "https://github.com/songalobung/mizani/blob/main/src/mizani/rebalance.py"
click node_scenarios "https://github.com/songalobung/mizani/blob/main/src/mizani/scenarios.py"
click node_report "https://github.com/songalobung/mizani/blob/main/src/mizani/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_market_data,node_holdings,node_regulations,node_schemas,node_loaders toneBlue
class node_estimation,node_rules,node_optimizers toneAmber
class node_compliance,node_frontier,node_regcost,node_rebalance,node_scenarios toneMint
class node_cli,node_report toneRose
class node_manager toneIndigo
```

## Components

### Inputs and Validation

- [Market Data](https://github.com/songalobung/mizani/tree/main/data/templates): `data/templates`
- [Portfolio Holdings](https://github.com/songalobung/mizani/blob/main/data/templates/portfolio.csv): `data/templates/portfolio.csv`
- [Regulation Rules](https://github.com/songalobung/mizani/tree/main/regulations): `regulations`
- [Input Schemas](https://github.com/songalobung/mizani/blob/main/src/mizani/schemas.py): `src/mizani/schemas.py`
- [Data Loaders](https://github.com/songalobung/mizani/blob/main/src/mizani/loaders.py): `src/mizani/loaders.py`

### Quantitative Engine

- [Return Estimation](https://github.com/songalobung/mizani/blob/main/src/mizani/estimation.py): `src/mizani/estimation.py`
- [Rule Compiler](https://github.com/songalobung/mizani/blob/main/src/mizani/rules.py): `src/mizani/rules.py`
- [Portfolio Solvers](https://github.com/songalobung/mizani/blob/main/src/mizani/optimizers.py): `src/mizani/optimizers.py`

### Analysis and Transition

- [Compliance Audit](https://github.com/songalobung/mizani/blob/main/src/mizani/compliance.py): `src/mizani/compliance.py`
- [Efficient Frontier](https://github.com/songalobung/mizani/blob/main/src/mizani/frontier.py): `src/mizani/frontier.py`
- [Regulation Cost](https://github.com/songalobung/mizani/blob/main/src/mizani/regcost.py): `src/mizani/regcost.py`
- [Rebalance Planner](https://github.com/songalobung/mizani/blob/main/src/mizani/rebalance.py): `src/mizani/rebalance.py`
- [Scenario Analysis](https://github.com/songalobung/mizani/blob/main/src/mizani/scenarios.py): `src/mizani/scenarios.py`

### User Interface

- [Mizani CLI](https://github.com/songalobung/mizani/blob/main/src/mizani/cli.py): `src/mizani/cli.py`
- [Analysis Report](https://github.com/songalobung/mizani/blob/main/src/mizani/report.py): `src/mizani/report.py`

### Other components

- **Fund Manager**

## Connections

- Fund Manager → Mizani CLI: runs commands (evidence: `README.md`)
- Market Data → Mizani CLI: supplies data (evidence: `README.md`)
- Portfolio Holdings → Mizani CLI: supplies holdings (evidence: `README.md`)
- Regulation Rules → Mizani CLI: supplies rules (evidence: `README.md`)
- Mizani CLI → Data Loaders: loads inputs (evidence: `src/mizani/cli.py`)
- Data Loaders → Input Schemas: validates with (evidence: `src/mizani/loaders.py`)
- Mizani CLI → Return Estimation: estimates returns (evidence: `src/mizani/cli.py`)
- Mizani CLI → Portfolio Solvers: solves allocation (evidence: `README.md`)
- Mizani CLI → Compliance Audit: checks holdings (evidence: `src/mizani/cli.py`)
- Mizani CLI → Efficient Frontier: generates frontier (evidence: `src/mizani/cli.py`)
- Mizani CLI → Regulation Cost: analyzes regulation cost (evidence: `src/mizani/cli.py`)
- Mizani CLI → Rebalance Planner: plans rebalancing (evidence: `src/mizani/cli.py`)
- Mizani CLI → Scenario Analysis: compares scenarios (evidence: `src/mizani/cli.py`)
- Mizani CLI → Analysis Report: generates report (evidence: `README.md`)
- Portfolio Solvers → Return Estimation: uses estimates (evidence: `src/mizani/optimizers.py`)
- Portfolio Solvers → Rule Compiler: uses constraints (evidence: `src/mizani/optimizers.py`)
- Efficient Frontier → Portfolio Solvers: uses solvers (evidence: `src/mizani/frontier.py`)
- Efficient Frontier → Return Estimation: uses estimates (evidence: `src/mizani/frontier.py`)
- Efficient Frontier → Rule Compiler: uses constraints (evidence: `src/mizani/frontier.py`)
- Compliance Audit → Data Loaders: loads holdings (evidence: `src/mizani/compliance.py`)
- Rebalance Planner → Compliance Audit: checks transitions (evidence: `src/mizani/rebalance.py`)
- Rebalance Planner → Rule Compiler: uses constraints (evidence: `src/mizani/rebalance.py`)
- Regulation Cost → Portfolio Solvers: compares solutions (evidence: `src/mizani/regcost.py`)
- Regulation Cost → Return Estimation: uses estimates (evidence: `src/mizani/regcost.py`)
- Scenario Analysis → Return Estimation: shocks estimates (evidence: `src/mizani/scenarios.py`)
- Scenario Analysis → Portfolio Solvers: compares allocations (evidence: `src/mizani/scenarios.py`)
- Scenario Analysis → Regulation Cost: compares regulation cost (evidence: `src/mizani/scenarios.py`)
- Analysis Report → Compliance Audit: includes audit (evidence: `src/mizani/report.py`)
- Analysis Report → Efficient Frontier: includes frontier (evidence: `src/mizani/report.py`)
- Analysis Report → Regulation Cost: includes cost analysis (evidence: `src/mizani/report.py`)
- Analysis Report → Rebalance Planner: includes trades (evidence: `src/mizani/report.py`)
- Analysis Report → Portfolio Solvers: includes allocation (evidence: `src/mizani/report.py`)
