# pooja2420/liquidity-scoring architecture

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

- Interactive diagram: https://gitdiagram.com/pooja2420/liquidity-scoring
- Repository: https://github.com/pooja2420/liquidity-scoring

## Overview

This repository builds corporate-bond liquidity scores and pre-trade cost estimates from bond reference, TRACE trade and macro data. Its principal workflow loads those inputs, engineers features and a composite score, trains temporal ML models, calibrates and shrinks impact parameters, then serves scores and cost estimates through an API and Streamlit dashboard. The README also documents model explainability, universe views and TCA/RFQ connectors. Arrows are limited to relationships visible in excerpts, the source index or README; unsampled details are not inferred.

Main entry points: [`run_pipeline.py`](https://github.com/pooja2420/liquidity-scoring/blob/main/run_pipeline.py) (Pipeline runner), [`src/features/feature_pipeline.py`](https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/feature_pipeline.py) (Feature builder), [`app.py`](https://github.com/pooja2420/liquidity-scoring/blob/main/app.py) (Streamlit dashboard), [`src/api/main.py`](https://github.com/pooja2420/liquidity-scoring/blob/main/src/api/main.py) (Scoring API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Market data"]
  node_bond_data["Bond universe<br/>[bond_reference.py]"]
  node_trace_data["TRACE trades<br/>[trace_loader.py]"]
  node_macro_data["Macro factors<br/>[macro_factors.py]"]
end

subgraph group_features["Feature engineering"]
  node_feature_pipeline["Feature builder"]
  node_roll["Roll spread<br/>[roll_measure.py]"]
  node_amihud["Amihud ratio<br/>[amihud.py]"]
  node_price_impact["Kyle lambda<br/>[price_impact.py]"]
  node_frequency["Trade frequency<br/>[trade_frequency.py]"]
  node_trade_time["Inter-trade time"]
  node_feature_store[("Feature store")]
end

subgraph group_models["Scoring models"]
  node_trainer["Model trainer<br/>[trainer.py]"]
  node_cross_validation["Walk-forward CV<br/>[cross_validator.py]"]
  node_shap["SHAP explainer<br/>[shap_explainer.py]"]
end

subgraph group_impact["Impact and costs"]
  node_calibrator["Impact calibrator"]
  node_shrinkage["Bayesian shrinkage"]
  node_cost_estimator["Pre-trade estimator<br/>[cost_estimator.py]"]
end

subgraph group_products["User products"]
  node_api["Scoring API<br/>[main.py]"]
  node_schemas["API schemas<br/>[models.py]"]
  node_dashboard["Streamlit dashboard<br/>[app.py]"]
end

node_analyst(("Analyst / trader"))
node_pipeline["Pipeline runner<br/>[run_pipeline.py]"]
node_fred["FRED"]
node_tca["TCA engine"]
node_rfq["RFQ pricing engine"]

node_pipeline -->|"loads"| node_bond_data
node_pipeline -->|"loads"| node_trace_data
node_pipeline -->|"loads"| node_macro_data
node_macro_data -->|"fetches data"| node_fred
node_pipeline -->|"builds features"| node_feature_pipeline
node_feature_pipeline -->|"uses"| node_roll
node_feature_pipeline -->|"uses"| node_amihud
node_feature_pipeline -->|"uses"| node_price_impact
node_feature_pipeline -->|"uses"| node_frequency
node_feature_pipeline -->|"uses"| node_trade_time
node_feature_pipeline -->|"persists features"| node_feature_store
node_pipeline -->|"trains models"| node_trainer
node_pipeline -->|"runs validation"| node_cross_validation
node_cross_validation -->|"trains folds"| node_trainer
node_pipeline -->|"computes explanations"| node_shap
node_pipeline -->|"calibrates impact"| node_calibrator
node_pipeline -->|"shrinks parameters"| node_shrinkage
node_calibrator -->|"provides fit parameters"| node_shrinkage
node_api -->|"reads features"| node_feature_store
node_api -->|"estimates costs"| node_cost_estimator
node_api -->|"uses schemas"| node_schemas
node_analyst -->|"requests scores"| node_api
node_analyst -->|"explores results"| node_dashboard
node_dashboard -->|"loads feature data"| node_feature_store
node_dashboard -->|"estimates costs"| node_cost_estimator
node_dashboard -->|"shows importance"| node_shap
node_dashboard -->|"shows calibration"| node_calibrator
node_dashboard -->|"shows universe map"| node_feature_store
node_api -.->|"integrates"| node_tca
node_api -.->|"integrates"| node_rfq

click node_pipeline "https://github.com/pooja2420/liquidity-scoring/blob/main/run_pipeline.py"
click node_bond_data "https://github.com/pooja2420/liquidity-scoring/blob/main/src/data/bond_reference.py"
click node_trace_data "https://github.com/pooja2420/liquidity-scoring/blob/main/src/data/trace_loader.py"
click node_macro_data "https://github.com/pooja2420/liquidity-scoring/blob/main/src/data/macro_factors.py"
click node_feature_pipeline "https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/feature_pipeline.py"
click node_roll "https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/roll_measure.py"
click node_amihud "https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/amihud.py"
click node_price_impact "https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/price_impact.py"
click node_frequency "https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/trade_frequency.py"
click node_trade_time "https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/inter_trade_time.py"
click node_feature_store "https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/feature_pipeline.py"
click node_trainer "https://github.com/pooja2420/liquidity-scoring/blob/main/src/models/trainer.py"
click node_cross_validation "https://github.com/pooja2420/liquidity-scoring/blob/main/src/models/cross_validator.py"
click node_shap "https://github.com/pooja2420/liquidity-scoring/blob/main/src/models/shap_explainer.py"
click node_calibrator "https://github.com/pooja2420/liquidity-scoring/blob/main/src/impact/impact_calibrator.py"
click node_shrinkage "https://github.com/pooja2420/liquidity-scoring/blob/main/src/impact/bayesian_shrinkage.py"
click node_cost_estimator "https://github.com/pooja2420/liquidity-scoring/blob/main/src/impact/cost_estimator.py"
click node_api "https://github.com/pooja2420/liquidity-scoring/blob/main/src/api/main.py"
click node_schemas "https://github.com/pooja2420/liquidity-scoring/blob/main/src/api/models.py"
click node_dashboard "https://github.com/pooja2420/liquidity-scoring/blob/main/app.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_bond_data,node_trace_data,node_macro_data toneBlue
class node_feature_pipeline,node_roll,node_amihud,node_price_impact,node_frequency,node_trade_time,node_feature_store toneAmber
class node_trainer,node_cross_validation,node_shap toneMint
class node_calibrator,node_shrinkage,node_cost_estimator toneRose
class node_api,node_schemas,node_dashboard,node_analyst,node_fred,node_tca,node_rfq toneIndigo
class node_pipeline toneTeal
```

## Components

### Market data

- [Bond universe](https://github.com/pooja2420/liquidity-scoring/blob/main/src/data/bond_reference.py): `src/data/bond_reference.py`
- [TRACE trades](https://github.com/pooja2420/liquidity-scoring/blob/main/src/data/trace_loader.py): `src/data/trace_loader.py`
- [Macro factors](https://github.com/pooja2420/liquidity-scoring/blob/main/src/data/macro_factors.py): `src/data/macro_factors.py`

### Feature engineering

- [Feature builder](https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/feature_pipeline.py): `src/features/feature_pipeline.py`
- [Roll spread](https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/roll_measure.py): `src/features/roll_measure.py`
- [Amihud ratio](https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/amihud.py): `src/features/amihud.py`
- [Kyle lambda](https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/price_impact.py): `src/features/price_impact.py`
- [Trade frequency](https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/trade_frequency.py): `src/features/trade_frequency.py`
- [Inter-trade time](https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/inter_trade_time.py): `src/features/inter_trade_time.py`
- [Feature store](https://github.com/pooja2420/liquidity-scoring/blob/main/src/features/feature_pipeline.py): `src/features/feature_pipeline.py`

### Scoring models

- [Model trainer](https://github.com/pooja2420/liquidity-scoring/blob/main/src/models/trainer.py): `src/models/trainer.py`
- [Walk-forward CV](https://github.com/pooja2420/liquidity-scoring/blob/main/src/models/cross_validator.py): `src/models/cross_validator.py`
- [SHAP explainer](https://github.com/pooja2420/liquidity-scoring/blob/main/src/models/shap_explainer.py): `src/models/shap_explainer.py`

### Impact and costs

- [Impact calibrator](https://github.com/pooja2420/liquidity-scoring/blob/main/src/impact/impact_calibrator.py): `src/impact/impact_calibrator.py`
- [Bayesian shrinkage](https://github.com/pooja2420/liquidity-scoring/blob/main/src/impact/bayesian_shrinkage.py): `src/impact/bayesian_shrinkage.py`
- [Pre-trade estimator](https://github.com/pooja2420/liquidity-scoring/blob/main/src/impact/cost_estimator.py): `src/impact/cost_estimator.py`

### User products

- [Scoring API](https://github.com/pooja2420/liquidity-scoring/blob/main/src/api/main.py): `src/api/main.py`
- [API schemas](https://github.com/pooja2420/liquidity-scoring/blob/main/src/api/models.py): `src/api/models.py`
- [Streamlit dashboard](https://github.com/pooja2420/liquidity-scoring/blob/main/app.py): `app.py`

### Other components

- **Analyst / trader**
- [Pipeline runner](https://github.com/pooja2420/liquidity-scoring/blob/main/run_pipeline.py): `run_pipeline.py`
- **FRED**
- **TCA engine**
- **RFQ pricing engine**

## Connections

- Pipeline runner → Bond universe: loads (evidence: `run_pipeline.py`)
- Pipeline runner → TRACE trades: loads (evidence: `run_pipeline.py`)
- Pipeline runner → Macro factors: loads (evidence: `run_pipeline.py`)
- Macro factors → FRED: fetches data (evidence: `src/data/macro_factors.py`)
- Pipeline runner → Feature builder: builds features (evidence: `run_pipeline.py`)
- Feature builder → Roll spread: uses (evidence: `src/features/feature_pipeline.py`)
- Feature builder → Amihud ratio: uses (evidence: `src/features/feature_pipeline.py`)
- Feature builder → Kyle lambda: uses (evidence: `src/features/feature_pipeline.py`)
- Feature builder → Trade frequency: uses (evidence: `src/features/feature_pipeline.py`)
- Feature builder → Inter-trade time: uses (evidence: `src/features/feature_pipeline.py`)
- Feature builder → Feature store: persists features (evidence: `src/features/feature_pipeline.py`)
- Pipeline runner → Model trainer: trains models (evidence: `run_pipeline.py`)
- Pipeline runner → Walk-forward CV: runs validation (evidence: `run_pipeline.py`)
- Walk-forward CV → Model trainer: trains folds (evidence: `src/models/cross_validator.py`)
- Pipeline runner → SHAP explainer: computes explanations (evidence: `run_pipeline.py`)
- Pipeline runner → Impact calibrator: calibrates impact (evidence: `run_pipeline.py`)
- Pipeline runner → Bayesian shrinkage: shrinks parameters (evidence: `run_pipeline.py`)
- Impact calibrator → Bayesian shrinkage: provides fit parameters (evidence: `README.md`)
- Scoring API → Feature store: reads features (evidence: `src/api/main.py`)
- Scoring API → Pre-trade estimator: estimates costs (evidence: `src/api/main.py`)
- Scoring API → API schemas: uses schemas (evidence: `src/api/main.py`)
- Analyst / trader → Scoring API: requests scores (evidence: `README.md`)
- Analyst / trader → Streamlit dashboard: explores results (evidence: `README.md`)
- Streamlit dashboard → Feature store: loads feature data (evidence: `app.py`)
- Streamlit dashboard → Pre-trade estimator: estimates costs (evidence: `app.py`)
- Streamlit dashboard → SHAP explainer: shows importance (evidence: `README.md`)
- Streamlit dashboard → Impact calibrator: shows calibration (evidence: `README.md`)
- Streamlit dashboard → Feature store: shows universe map (evidence: `README.md`)
- Scoring API → TCA engine: integrates (evidence: `README.md`)
- Scoring API → RFQ pricing engine: integrates (evidence: `README.md`)
