# georgeqanfin-stack/stf-alpha-pricer architecture

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

- Interactive diagram: https://gitdiagram.com/georgeqanfin-stack/stf-alpha-pricer
- Repository: https://github.com/georgeqanfin-stack/stf-alpha-pricer

## Overview

STF-Alpha-Pricer is a Streamlit commodity trade-finance pricing engine. A user supplies deal terms; the app combines a macro credit-risk prediction, corridor-specific FX hedge cost, commodity volatility adjustment, tenor adjustment, and margin into an all-in rate and finance cost, then presents a rate waterfall and market context. The runtime implementation is concentrated in `app/app.py`; the separate pricing stages below are logical responsibilities within that file, not independently sampled modules. README capabilities are included; runtime data wiring is based on the sampled app source.

Main entry points: [`app/app.py`](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py) (Streamlit App), [`app/data/fred_master.csv`](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/fred_master.csv) (Macro Series), [`app/data/xgboost_model.pkl`](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/xgboost_model.pkl) (XGBoost Model), [`app/data/fx_oracle_clean.csv`](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/fx_oracle_clean.csv) (FX Regimes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Deal Interface"]
  node_app["Streamlit App<br/>[app.py]"]
  node_deal_terms["Deal Terms<br/>[app.py]"]
  node_rate_breakdown["Rate Waterfall<br/>[app.py]"]
  node_market_context["Market Context<br/>[app.py]"]
end

subgraph group_pricing["Pricing Engine"]
  node_macro_pricing["Macro Risk Pricing<br/>[app.py]"]
  node_fx_pricing["FX Hedge Pricing<br/>[app.py]"]
  node_commodity_pricing["Commodity Adjustment<br/>[app.py]"]
  node_tenor_margin["Tenor and Margin<br/>[app.py]"]
  node_finance_cost["Finance Cost<br/>[app.py]"]
end

subgraph group_inputs["Local Inputs"]
  node_macro_data["Macro Series<br/>[fred_master.csv]"]
  node_macro_model["XGBoost Model<br/>[xgboost_model.pkl]"]
  node_fx_data["FX Regimes"]
  node_corridor_data["Corridor Map<br/>[corridor_map.csv]"]
  node_commodity_data["Commodity Volatility<br/>[commodity_adj.csv]"]
end

node_user(("Deal User"))

node_user -->|"enters terms"| node_deal_terms
node_deal_terms -->|"submits deal"| node_app
node_app -->|"reads series"| node_macro_data
node_app -->|"loads model"| node_macro_model
node_app -->|"predicts spread"| node_macro_pricing
node_app -->|"reads mapping"| node_corridor_data
node_app -->|"selects regime"| node_fx_data
node_app -->|"gets hedge cost"| node_fx_pricing
node_app -->|"reads adjustment"| node_commodity_data
node_app -->|"gets adjustment"| node_commodity_pricing
node_app -->|"calculates additions"| node_tenor_margin
node_app -->|"calculates cost"| node_finance_cost
node_app -->|"renders breakdown"| node_rate_breakdown
node_app -->|"renders context"| node_market_context
node_app -->|"shows pricing"| node_user

click node_app "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_deal_terms "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_rate_breakdown "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_market_context "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_macro_pricing "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_fx_pricing "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_commodity_pricing "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_tenor_margin "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_finance_cost "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py"
click node_macro_data "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/fred_master.csv"
click node_macro_model "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/xgboost_model.pkl"
click node_fx_data "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/fx_oracle_clean.csv"
click node_corridor_data "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/corridor_map.csv"
click node_commodity_data "https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/commodity_adj.csv"

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_app,node_deal_terms,node_rate_breakdown,node_market_context,node_user toneBlue
class node_macro_pricing,node_fx_pricing,node_commodity_pricing,node_tenor_margin,node_finance_cost toneAmber
class node_macro_data,node_macro_model,node_fx_data,node_corridor_data,node_commodity_data toneMint
```

## Components

### Deal Interface

- [Streamlit App](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`
- [Deal Terms](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`
- [Rate Waterfall](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`
- [Market Context](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`

### Pricing Engine

- [Macro Risk Pricing](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`
- [FX Hedge Pricing](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`
- [Commodity Adjustment](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`
- [Tenor and Margin](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`
- [Finance Cost](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/app.py): `app/app.py`

### Local Inputs

- [Macro Series](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/fred_master.csv): `app/data/fred_master.csv`
- [XGBoost Model](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/xgboost_model.pkl): `app/data/xgboost_model.pkl`
- [FX Regimes](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/fx_oracle_clean.csv): `app/data/fx_oracle_clean.csv`
- [Corridor Map](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/corridor_map.csv): `app/data/corridor_map.csv`
- [Commodity Volatility](https://github.com/georgeqanfin-stack/stf-alpha-pricer/blob/main/app/data/commodity_adj.csv): `app/data/commodity_adj.csv`

### Other components

- **Deal User**

## Connections

- Deal User → Deal Terms: enters terms
- Deal Terms → Streamlit App: submits deal
- Streamlit App → Macro Series: reads series
- Streamlit App → XGBoost Model: loads model
- Streamlit App → Macro Risk Pricing: predicts spread
- Streamlit App → Corridor Map: reads mapping
- Streamlit App → FX Regimes: selects regime
- Streamlit App → FX Hedge Pricing: gets hedge cost
- Streamlit App → Commodity Volatility: reads adjustment
- Streamlit App → Commodity Adjustment: gets adjustment
- Streamlit App → Tenor and Margin: calculates additions
- Streamlit App → Finance Cost: calculates cost
- Streamlit App → Rate Waterfall: renders breakdown
- Streamlit App → Market Context: renders context
- Streamlit App → Deal User: shows pricing