# songalobung/parity architecture

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

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

## Overview

Parity is a command-line and Python toolkit for estimating frontier-market FX risk and translating local-currency deal cash flows into hard-currency return distributions. The main workflow loads deal and macro inputs, builds risk features, estimates devaluation hazard, simulates FX paths, applies repatriation and cash-flow frictions, and reports returns; scenario comparisons and hedging are additional analytical branches. Internal links reflect the sampled excerpts and SOURCE INDEX; documented pipeline links cite the README, and no unsampled implementation details are assumed.

Main entry points: [`src/parity/fxpaths.py`](https://github.com/songalobung/parity/blob/main/src/parity/fxpaths.py) (FX path simulator), [`src/parity/loaders.py`](https://github.com/songalobung/parity/blob/main/src/parity/loaders.py) (Data loaders), [`src/parity/devaluation.py`](https://github.com/songalobung/parity/blob/main/src/parity/devaluation.py) (Devaluation hazard), [`src/parity/cli.py`](https://github.com/songalobung/parity/blob/main/src/parity/cli.py) (Parity CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and validation"]
  node_schemas["Input schemas<br/>[schemas.py]"]
  node_loaders["Data loaders<br/>[loaders.py]"]
end

subgraph group_risk["FX risk modeling"]
  node_features["Macro features<br/>[features.py]"]
  node_devaluation["Devaluation hazard<br/>[devaluation.py]"]
  node_magnitude["Jump magnitude<br/>[magnitude.py]"]
  node_fxpaths["FX path simulator<br/>[fxpaths.py]"]
end

subgraph group_analysis["Deal analytics"]
  node_deal["Deal conversion<br/>[deal.py]"]
  node_hedging["Hedging analytics<br/>[hedging.py]"]
  node_scenarios["Scenario switchboard<br/>[scenarios.py]"]
end

subgraph group_delivery["User interface and reports"]
  node_cli["Parity CLI<br/>[cli.py]"]
  node_report["IC reports<br/>[report.py]"]
end

node_user(("Analyst"))
node_data["Deal and market data"]
node_priors["Model priors<br/>[priors.yaml]"]
node_scenario_defs["Scenario definitions<br/>[scenarios.yaml]"]

node_user -->|"runs analyses"| node_cli
node_data -->|"loads inputs"| node_loaders
node_loaders -->|"validates against"| node_schemas
node_loaders -->|"supplies panel"| node_features
node_priors -->|"sets coefficients"| node_devaluation
node_features -->|"provides predictors"| node_devaluation
node_devaluation -->|"sets hazard"| node_fxpaths
node_magnitude -->|"sets jump sizes"| node_fxpaths
node_priors -->|"sets simulation defaults"| node_fxpaths
node_fxpaths -->|"provides FX paths"| node_deal
node_scenario_defs -->|"configures scenarios"| node_scenarios
node_scenarios -->|"runs simulations"| node_fxpaths
node_deal -->|"compares hedged returns"| node_hedging
node_data -.->|"may include forwards"| node_hedging
node_user -->|"requests reports"| node_cli
node_cli -->|"generates deliverables"| node_report
node_report -->|"delivers return analysis"| node_user

click node_priors "https://github.com/songalobung/parity/blob/main/config/priors.yaml"
click node_scenario_defs "https://github.com/songalobung/parity/blob/main/config/scenarios.yaml"
click node_schemas "https://github.com/songalobung/parity/blob/main/src/parity/schemas.py"
click node_loaders "https://github.com/songalobung/parity/blob/main/src/parity/loaders.py"
click node_features "https://github.com/songalobung/parity/blob/main/src/parity/features.py"
click node_devaluation "https://github.com/songalobung/parity/blob/main/src/parity/devaluation.py"
click node_magnitude "https://github.com/songalobung/parity/blob/main/src/parity/magnitude.py"
click node_fxpaths "https://github.com/songalobung/parity/blob/main/src/parity/fxpaths.py"
click node_deal "https://github.com/songalobung/parity/blob/main/src/parity/deal.py"
click node_hedging "https://github.com/songalobung/parity/blob/main/src/parity/hedging.py"
click node_scenarios "https://github.com/songalobung/parity/blob/main/src/parity/scenarios.py"
click node_cli "https://github.com/songalobung/parity/blob/main/src/parity/cli.py"
click node_report "https://github.com/songalobung/parity/blob/main/src/parity/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_schemas,node_loaders toneBlue
class node_features,node_devaluation,node_magnitude,node_fxpaths toneAmber
class node_deal,node_hedging,node_scenarios toneMint
class node_cli,node_report toneRose
class node_user,node_data,node_priors toneIndigo
class node_scenario_defs toneTeal
```

## Components

### Inputs and validation

- [Input schemas](https://github.com/songalobung/parity/blob/main/src/parity/schemas.py): `src/parity/schemas.py`
- [Data loaders](https://github.com/songalobung/parity/blob/main/src/parity/loaders.py): `src/parity/loaders.py`

### FX risk modeling

- [Macro features](https://github.com/songalobung/parity/blob/main/src/parity/features.py): `src/parity/features.py`
- [Devaluation hazard](https://github.com/songalobung/parity/blob/main/src/parity/devaluation.py): `src/parity/devaluation.py`
- [Jump magnitude](https://github.com/songalobung/parity/blob/main/src/parity/magnitude.py): `src/parity/magnitude.py`
- [FX path simulator](https://github.com/songalobung/parity/blob/main/src/parity/fxpaths.py): `src/parity/fxpaths.py`

### Deal analytics

- [Deal conversion](https://github.com/songalobung/parity/blob/main/src/parity/deal.py): `src/parity/deal.py`
- [Hedging analytics](https://github.com/songalobung/parity/blob/main/src/parity/hedging.py): `src/parity/hedging.py`
- [Scenario switchboard](https://github.com/songalobung/parity/blob/main/src/parity/scenarios.py): `src/parity/scenarios.py`

### User interface and reports

- [Parity CLI](https://github.com/songalobung/parity/blob/main/src/parity/cli.py): `src/parity/cli.py`
- [IC reports](https://github.com/songalobung/parity/blob/main/src/parity/report.py): `src/parity/report.py`

### Other components

- **Analyst**
- **Deal and market data**
- [Model priors](https://github.com/songalobung/parity/blob/main/config/priors.yaml): `config/priors.yaml`
- [Scenario definitions](https://github.com/songalobung/parity/blob/main/config/scenarios.yaml): `config/scenarios.yaml`

## Connections

- Analyst → Parity CLI: runs analyses (evidence: `README.md`)
- Deal and market data → Data loaders: loads inputs (evidence: `README.md`)
- Data loaders → Input schemas: validates against (evidence: `src/parity/loaders.py`)
- Data loaders → Macro features: supplies panel (evidence: `README.md`)
- Model priors → Devaluation hazard: sets coefficients (evidence: `src/parity/devaluation.py`)
- Macro features → Devaluation hazard: provides predictors (evidence: `README.md`)
- Devaluation hazard → FX path simulator: sets hazard (evidence: `src/parity/fxpaths.py`)
- Jump magnitude → FX path simulator: sets jump sizes (evidence: `src/parity/fxpaths.py`)
- Model priors → FX path simulator: sets simulation defaults (evidence: `src/parity/fxpaths.py`)
- FX path simulator → Deal conversion: provides FX paths (evidence: `src/parity/deal.py`)
- Scenario definitions → Scenario switchboard: configures scenarios (evidence: `README.md`)
- Scenario switchboard → FX path simulator: runs simulations (evidence: `src/parity/scenarios.py`)
- Deal conversion → Hedging analytics: compares hedged returns (evidence: `README.md`)
- Deal and market data → Hedging analytics: may include forwards (evidence: `README.md`)
- Analyst → Parity CLI: requests reports (evidence: `README.md`)
- Parity CLI → IC reports: generates deliverables (evidence: `README.md`)
- IC reports → Analyst: delivers return analysis (evidence: `README.md`)
