# edvinassvedas-dev/valdist architecture

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

- Interactive diagram: https://gitdiagram.com/edvinassvedas-dev/valdist
- Repository: https://github.com/edvinassvedas-dev/valdist

## Overview

valdist turns probabilistic valuation specs into simulated intrinsic-value distributions and decision/sensitivity summaries. The principal workflow is spec loading and validation, model construction and sampling, adapter-based valuation, then result reporting. Separate user-facing branches provide calibration, charts, and a read-only browser viewer with optional current-price repricing. The README documents all three built-in valuation families and these capabilities; some subsystem wiring is inferred only where the documented workflow is explicit, so uncertain links are omitted.

Main entry points: [`valdist/core/model.py`](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/model.py) (Valuation Model), [`gui/server.py`](https://github.com/edvinassvedas-dev/valdist/blob/main/gui/server.py) (Read-only Viewer), [`valdist/cli.py`](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/cli.py) (CLI Commands), [`valdist/spec/loader.py`](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/spec/loader.py) (Spec Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_spec["Specification"]
  node_specfile["Valuation Spec<br/>[vici.yaml]"]
  node_loader["Spec Loader<br/>[loader.py]"]
  node_schema["Spec Schema<br/>[schema.py]"]
  node_validate["Spec Validation<br/>[validate.py]"]
end

subgraph group_engine["Valuation Engine"]
  node_model["Valuation Model<br/>[model.py]"]
  node_marginals["Driver Marginals<br/>[marginals.py]"]
  node_factors["Dependence Factors<br/>[factors.py]"]
  node_sampler["Monte Carlo Sampler<br/>[sampler.py]"]
  node_registry["Adapter Registry<br/>[registry.py]"]
  node_equity["Equity Adapter<br/>[equity.py]"]
  node_reit["REIT Adapter<br/>[reit.py]"]
  node_preferred["Preferred Adapter<br/>[preferred.py]"]
end

subgraph group_outputs["Analysis Outputs"]
  node_cli["CLI Commands<br/>[cli.py]"]
  node_result["Simulation Result<br/>[results.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
  node_report["Text Report<br/>[report.py]"]
  node_plot["Charts<br/>[plot.py]"]
  node_coverage["Coverage Backtest<br/>[coverage.py]"]
  node_realized["Realized Outcomes<br/>[vici_2024q1.real]"]
end

subgraph group_viewer["Browser Viewer"]
  node_viewer["Read-only Viewer<br/>[server.py]"]
  node_webpage["Viewer Page<br/>[index.html]"]
  node_prices["Quote Fetcher<br/>[fetch.py]"]
end

node_analyst(("Analyst"))
node_quoteapi["Market Quote Service"]

node_analyst -->|"runs commands"| node_cli
node_analyst -->|"provides spec"| node_specfile
node_cli -->|"loads spec"| node_loader
node_loader -->|"parses against"| node_schema
node_cli -->|"validates inputs"| node_validate
node_loader -->|"hydrates spec"| node_validate
node_validate -->|"permits construction"| node_model
node_model -->|"fits drivers"| node_marginals
node_model -->|"builds dependence"| node_factors
node_model -->|"generates draws"| node_sampler
node_model -->|"selects adapter"| node_registry
node_registry -->|"dispatches equity"| node_equity
node_registry -->|"dispatches REIT"| node_reit
node_registry -->|"dispatches preferred"| node_preferred
node_model -->|"returns simulations"| node_result
node_model -->|"collects warnings"| node_diagnostics
node_cli -->|"formats output"| node_report
node_cli -->|"renders chart"| node_plot
node_cli -->|"runs backtest"| node_coverage
node_coverage -->|"loads specs"| node_loader
node_coverage -->|"reads outcomes"| node_realized
node_analyst -->|"opens viewer"| node_viewer
node_viewer -->|"serves page"| node_webpage
node_viewer -->|"loads analyses"| node_loader
node_viewer -->|"reads quotes"| node_prices
node_prices -.->|"fetches quotes"| node_quoteapi
node_prices -.->|"refreshes quotes"| node_viewer
node_viewer -->|"runs repricing"| node_model
node_result -->|"supplies summaries"| node_viewer
node_result -->|"supplies metrics"| node_report
node_result -->|"supplies distributions"| node_plot

click node_specfile "https://github.com/edvinassvedas-dev/valdist/blob/main/examples/vici.yaml"
click node_cli "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/cli.py"
click node_loader "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/spec/loader.py"
click node_schema "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/spec/schema.py"
click node_validate "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/spec/validate.py"
click node_model "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/model.py"
click node_marginals "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/marginals.py"
click node_factors "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/factors.py"
click node_sampler "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/sampler.py"
click node_registry "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/adapters/registry.py"
click node_equity "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/adapters/equity.py"
click node_reit "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/adapters/reit.py"
click node_preferred "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/adapters/preferred.py"
click node_result "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/results.py"
click node_diagnostics "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/diagnostics.py"
click node_report "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/report.py"
click node_plot "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/plot.py"
click node_coverage "https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/calibrate/coverage.py"
click node_realized "https://github.com/edvinassvedas-dev/valdist/blob/main/examples/calibration/vici_2024q1.real"
click node_viewer "https://github.com/edvinassvedas-dev/valdist/blob/main/gui/server.py"
click node_webpage "https://github.com/edvinassvedas-dev/valdist/blob/main/gui/index.html"
click node_prices "https://github.com/edvinassvedas-dev/valdist/blob/main/prices/fetch.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_specfile,node_loader,node_schema,node_validate toneBlue
class node_model,node_marginals,node_factors,node_sampler,node_registry,node_equity,node_reit,node_preferred toneAmber
class node_cli,node_result,node_diagnostics,node_report,node_plot,node_coverage,node_realized toneMint
class node_viewer,node_webpage,node_prices toneRose
class node_analyst,node_quoteapi toneIndigo
```

## Components

### Specification

- [Valuation Spec](https://github.com/edvinassvedas-dev/valdist/blob/main/examples/vici.yaml): `examples/vici.yaml`
- [Spec Loader](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/spec/loader.py): `valdist/spec/loader.py`
- [Spec Schema](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/spec/schema.py): `valdist/spec/schema.py`
- [Spec Validation](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/spec/validate.py): `valdist/spec/validate.py`

### Valuation Engine

- [Valuation Model](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/model.py): `valdist/core/model.py`
- [Driver Marginals](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/marginals.py): `valdist/core/marginals.py`
- [Dependence Factors](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/factors.py): `valdist/core/factors.py`
- [Monte Carlo Sampler](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/sampler.py): `valdist/core/sampler.py`
- [Adapter Registry](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/adapters/registry.py): `valdist/adapters/registry.py`
- [Equity Adapter](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/adapters/equity.py): `valdist/adapters/equity.py`
- [REIT Adapter](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/adapters/reit.py): `valdist/adapters/reit.py`
- [Preferred Adapter](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/adapters/preferred.py): `valdist/adapters/preferred.py`

### Analysis Outputs

- [CLI Commands](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/cli.py): `valdist/cli.py`
- [Simulation Result](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/results.py): `valdist/core/results.py`
- [Diagnostics](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/core/diagnostics.py): `valdist/core/diagnostics.py`
- [Text Report](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/report.py): `valdist/report.py`
- [Charts](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/plot.py): `valdist/plot.py`
- [Coverage Backtest](https://github.com/edvinassvedas-dev/valdist/blob/main/valdist/calibrate/coverage.py): `valdist/calibrate/coverage.py`
- [Realized Outcomes](https://github.com/edvinassvedas-dev/valdist/blob/main/examples/calibration/vici_2024q1.real): `examples/calibration/vici_2024q1.real`

### Browser Viewer

- [Read-only Viewer](https://github.com/edvinassvedas-dev/valdist/blob/main/gui/server.py): `gui/server.py`
- [Viewer Page](https://github.com/edvinassvedas-dev/valdist/blob/main/gui/index.html): `gui/index.html`
- [Quote Fetcher](https://github.com/edvinassvedas-dev/valdist/blob/main/prices/fetch.py): `prices/fetch.py`

### Other components

- **Analyst**
- **Market Quote Service**

## Connections

- Analyst → CLI Commands: runs commands
- Analyst → Valuation Spec: provides spec
- CLI Commands → Spec Loader: loads spec
- Spec Loader → Spec Schema: parses against
- CLI Commands → Spec Validation: validates inputs
- Spec Loader → Spec Validation: hydrates spec
- Spec Validation → Valuation Model: permits construction
- Valuation Model → Driver Marginals: fits drivers
- Valuation Model → Dependence Factors: builds dependence
- Valuation Model → Monte Carlo Sampler: generates draws
- Valuation Model → Adapter Registry: selects adapter
- Adapter Registry → Equity Adapter: dispatches equity
- Adapter Registry → REIT Adapter: dispatches REIT
- Adapter Registry → Preferred Adapter: dispatches preferred
- Valuation Model → Simulation Result: returns simulations
- Valuation Model → Diagnostics: collects warnings
- CLI Commands → Text Report: formats output
- CLI Commands → Charts: renders chart
- CLI Commands → Coverage Backtest: runs backtest
- Coverage Backtest → Spec Loader: loads specs
- Coverage Backtest → Realized Outcomes: reads outcomes
- Analyst → Read-only Viewer: opens viewer
- Read-only Viewer → Viewer Page: serves page
- Read-only Viewer → Spec Loader: loads analyses
- Read-only Viewer → Quote Fetcher: reads quotes
- Quote Fetcher → Market Quote Service: fetches quotes
- Quote Fetcher → Read-only Viewer: refreshes quotes
- Read-only Viewer → Valuation Model: runs repricing
- Simulation Result → Read-only Viewer: supplies summaries
- Simulation Result → Text Report: supplies metrics
- Simulation Result → Charts: supplies distributions