# songalobung/covenant architecture

> Architecture diagram of the GitHub repository songalobung/covenant, 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/covenant
- Repository: https://github.com/songalobung/covenant

## Overview

Covenant is a country-agnostic sovereign credit risk and restructuring engine, exposed through a CLI and Python package. Users supply country, creditor, debt, and event data plus a scenario; the runtime validates and loads inputs, constructs features, estimates distress, haircut, and resolution outcomes, simulates losses and bond values, and produces Markdown or Excel reports. The graph preserves the README’s modeling and reporting capabilities; some CLI-to-model wiring is documented, while unsampled implementation details are not inferred.

Main entry points: [`src/sovdistress/cli.py`](https://github.com/songalobung/covenant/blob/main/src/sovdistress/cli.py) (Covenant CLI), [`src/sovdistress/simulate.py`](https://github.com/songalobung/covenant/blob/main/src/sovdistress/simulate.py) (Monte Carlo engine), [`src/sovdistress/distress.py`](https://github.com/songalobung/covenant/blob/main/src/sovdistress/distress.py) (Distress model), [`src/sovdistress/loaders.py`](https://github.com/songalobung/covenant/blob/main/src/sovdistress/loaders.py) (Data loaders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Data inputs"]
  node_schemas["Data schemas<br/>[schemas.py]"]
  node_loaders["Data loaders<br/>[loaders.py]"]
  node_priors["Model priors<br/>[priors.yaml]"]
end

subgraph group_modeling["Risk models"]
  node_features["Feature engineering<br/>[features.py]"]
  node_distress["Distress model<br/>[distress.py]"]
  node_haircut["Haircut model<br/>[haircut.py]"]
  node_resolution["Resolution model<br/>[resolution.py]"]
end

subgraph group_analytics["Simulation"]
  node_simulator["Monte Carlo engine<br/>[simulate.py]"]
  node_scenario["Scenario analysis<br/>[simulate.py]"]
end

subgraph group_outputs["Reporting"]
  node_markdown["Markdown reports<br/>[report.py]"]
  node_excel["Excel reports<br/>[excel_report.py]"]
end

node_analyst(("Analyst"))
node_cli["Covenant CLI<br/>[cli.py]"]

node_analyst -->|"runs commands"| node_cli
node_cli -->|"loads datasets"| node_loaders
node_loaders -->|"validates data"| node_schemas
node_cli -->|"builds features"| node_features
node_distress -->|"fits from"| node_features
node_cli -->|"scores risk"| node_distress
node_cli -->|"estimates loss"| node_haircut
node_cli -->|"estimates duration"| node_resolution
node_simulator -->|"samples probability"| node_distress
node_simulator -->|"samples haircuts"| node_haircut
node_simulator -->|"samples duration"| node_resolution
node_cli -->|"runs simulation"| node_simulator
node_scenario -->|"simulates cases"| node_simulator
node_cli -->|"compares scenarios"| node_scenario
node_cli -->|"generates report"| node_markdown
node_cli -->|"exports workbook"| node_excel
node_simulator -.->|"provides metrics"| node_markdown
node_simulator -.->|"provides metrics"| node_excel

click node_cli "https://github.com/songalobung/covenant/blob/main/src/sovdistress/cli.py"
click node_schemas "https://github.com/songalobung/covenant/blob/main/src/sovdistress/schemas.py"
click node_loaders "https://github.com/songalobung/covenant/blob/main/src/sovdistress/loaders.py"
click node_priors "https://github.com/songalobung/covenant/blob/main/config/priors.yaml"
click node_features "https://github.com/songalobung/covenant/blob/main/src/sovdistress/features.py"
click node_distress "https://github.com/songalobung/covenant/blob/main/src/sovdistress/distress.py"
click node_haircut "https://github.com/songalobung/covenant/blob/main/src/sovdistress/haircut.py"
click node_resolution "https://github.com/songalobung/covenant/blob/main/src/sovdistress/resolution.py"
click node_simulator "https://github.com/songalobung/covenant/blob/main/src/sovdistress/simulate.py"
click node_scenario "https://github.com/songalobung/covenant/blob/main/src/sovdistress/simulate.py"
click node_markdown "https://github.com/songalobung/covenant/blob/main/src/sovdistress/report.py"
click node_excel "https://github.com/songalobung/covenant/blob/main/src/sovdistress/excel_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,node_priors toneBlue
class node_features,node_distress,node_haircut,node_resolution toneAmber
class node_simulator,node_scenario toneMint
class node_markdown,node_excel toneRose
class node_analyst toneIndigo
class node_cli toneTeal
```

## Components

### Data inputs

- [Data schemas](https://github.com/songalobung/covenant/blob/main/src/sovdistress/schemas.py): `src/sovdistress/schemas.py`
- [Data loaders](https://github.com/songalobung/covenant/blob/main/src/sovdistress/loaders.py): `src/sovdistress/loaders.py`
- [Model priors](https://github.com/songalobung/covenant/blob/main/config/priors.yaml): `config/priors.yaml`

### Risk models

- [Feature engineering](https://github.com/songalobung/covenant/blob/main/src/sovdistress/features.py): `src/sovdistress/features.py`
- [Distress model](https://github.com/songalobung/covenant/blob/main/src/sovdistress/distress.py): `src/sovdistress/distress.py`
- [Haircut model](https://github.com/songalobung/covenant/blob/main/src/sovdistress/haircut.py): `src/sovdistress/haircut.py`
- [Resolution model](https://github.com/songalobung/covenant/blob/main/src/sovdistress/resolution.py): `src/sovdistress/resolution.py`

### Simulation

- [Monte Carlo engine](https://github.com/songalobung/covenant/blob/main/src/sovdistress/simulate.py): `src/sovdistress/simulate.py`
- [Scenario analysis](https://github.com/songalobung/covenant/blob/main/src/sovdistress/simulate.py): `src/sovdistress/simulate.py`

### Reporting

- [Markdown reports](https://github.com/songalobung/covenant/blob/main/src/sovdistress/report.py): `src/sovdistress/report.py`
- [Excel reports](https://github.com/songalobung/covenant/blob/main/src/sovdistress/excel_report.py): `src/sovdistress/excel_report.py`

### Other components

- **Analyst**
- [Covenant CLI](https://github.com/songalobung/covenant/blob/main/src/sovdistress/cli.py): `src/sovdistress/cli.py`

## Connections

- Analyst → Covenant CLI: runs commands (evidence: `README.md`)
- Covenant CLI → Data loaders: loads datasets (evidence: `src/sovdistress/cli.py`)
- Data loaders → Data schemas: validates data (evidence: `src/sovdistress/loaders.py`)
- Covenant CLI → Feature engineering: builds features (evidence: `src/sovdistress/cli.py`)
- Distress model → Feature engineering: fits from (evidence: `src/sovdistress/distress.py`)
- Covenant CLI → Distress model: scores risk (evidence: `src/sovdistress/cli.py`)
- Covenant CLI → Haircut model: estimates loss (evidence: `README.md`)
- Covenant CLI → Resolution model: estimates duration (evidence: `README.md`)
- Monte Carlo engine → Distress model: samples probability (evidence: `src/sovdistress/simulate.py`)
- Monte Carlo engine → Haircut model: samples haircuts (evidence: `src/sovdistress/simulate.py`)
- Monte Carlo engine → Resolution model: samples duration (evidence: `src/sovdistress/simulate.py`)
- Covenant CLI → Monte Carlo engine: runs simulation (evidence: `src/sovdistress/cli.py`)
- Scenario analysis → Monte Carlo engine: simulates cases (evidence: `src/sovdistress/simulate.py`)
- Covenant CLI → Scenario analysis: compares scenarios (evidence: `src/sovdistress/cli.py`)
- Covenant CLI → Markdown reports: generates report (evidence: `src/sovdistress/cli.py`)
- Covenant CLI → Excel reports: exports workbook (evidence: `README.md`)
- Monte Carlo engine → Markdown reports: provides metrics
- Monte Carlo engine → Excel reports: provides metrics
