# jay4ignite/ml-cornerstone architecture

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

## Overview

This repository is a config-driven loan default-risk estimator with a scikit-learn training pipeline and an in-process Streamlit application—not an approval engine or HTTP service. The training workflow acquires or generates data, standardizes and validates it, splits and trains candidates, selects and calibrates a model, evaluates and explains it, then persists artifacts. In the app, an applicant submits inputs for validation and prediction; the result presents probability, score, band, limitations, and explanatory context. README documents additional analytics and governance pages; unsampled implementations are represented at their listed paths.

Main entry points: [`loan_risk/pipeline/run.py`](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/run.py) (Training workflow), [`streamlit_app.py`](https://github.com/jay4ignite/ml-cornerstone/blob/main/streamlit_app.py) (Streamlit app), [`loan_risk/serving/service.py`](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/serving/service.py) (Model service), [`ui/pages/assessment.py`](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/assessment.py) (Applicant assessment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_config["Configuration<br/>[config.py]"]
  node_schema["Feature contract<br/>[schema.py]"]
  node_acquire["Dataset acquisition<br/>[download.py]"]
  node_synthetic["Synthetic data<br/>[synthetic.py]"]
  node_ingestion["Data ingestion<br/>[ingestion.py]"]
  node_validation["Data validation<br/>[validate.py]"]
  node_manifest["Dataset manifest<br/>[manifest.py]"]
end

subgraph group_training["Model training"]
  node_orchestrator["Training workflow<br/>[run.py]"]
  node_split["Data splitting<br/>[split.py]"]
  node_preprocess["Feature preprocessing<br/>[preprocess.py]"]
  node_models["Candidate models<br/>[models.py]"]
  node_tuning["Model tuning<br/>[tuning.py]"]
  node_calibration["Probability calibration<br/>[calibrate.py]"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_fairness["Fairness diagnostics<br/>[fairness.py]"]
  node_explanation["Model explanations<br/>[explain.py]"]
  node_artifacts[("Model artifacts<br/>[artifacts.py]")]
end

subgraph group_serving["Prediction serving"]
  node_service["Model service<br/>[service.py]"]
  node_input_validation["Input validation<br/>[validation.py]"]
  node_risk_mapping["Risk mapping<br/>[risk_score.py]"]
end

subgraph group_interface["Assessment interface"]
  node_streamlit["Streamlit app<br/>[streamlit_app.py]"]
  node_assessment["Applicant assessment<br/>[assessment.py]"]
  node_session[("Session prediction store<br/>[state.py]")]
  node_results["Prediction results<br/>[result.py]"]
  node_explain_page["Local explanations<br/>[explainability.py]"]
  node_helpers["Shared UI helpers<br/>[helpers.py]"]
end

subgraph group_insight["Analytics and governance"]
  node_performance_page["Performance analytics<br/>[performance.py]"]
  node_analytics_page["Analytics dashboard<br/>[analytics.py]"]
  node_selection_page["Model comparison<br/>[model_selection.py]"]
  node_quality_page["Dataset quality<br/>[dataset_quality.py]"]
  node_feature_page["Feature reference"]
  node_methodology_page["Methodology<br/>[methodology.py]"]
  node_model_page["Model information<br/>[model_info.py]"]
end

node_applicant(("Applicant"))

node_config -->|"configures"| node_acquire
node_config -->|"selects source"| node_ingestion
node_schema -->|"defines columns"| node_ingestion
node_orchestrator -->|"acquires data"| node_acquire
node_orchestrator -->|"generates fixture"| node_synthetic
node_orchestrator -->|"loads and standardizes"| node_ingestion
node_orchestrator -->|"validates data"| node_validation
node_orchestrator -->|"builds manifest"| node_manifest
node_orchestrator -->|"splits data"| node_split
node_orchestrator -->|"builds candidates"| node_models
node_orchestrator -->|"tunes candidates"| node_tuning
node_orchestrator -->|"calibrates selected"| node_calibration
node_orchestrator -->|"evaluates test set"| node_evaluation
node_orchestrator -->|"runs diagnostics"| node_fairness
node_orchestrator -->|"computes explanations"| node_explanation
node_orchestrator -->|"persists artifacts"| node_artifacts
node_schema -->|"defines features"| node_preprocess
node_preprocess -->|"transforms inputs"| node_models
node_applicant -->|"enters application"| node_assessment
node_streamlit -->|"routes page"| node_assessment
node_assessment -->|"validates payload"| node_input_validation
node_assessment -->|"requests prediction"| node_service
node_service -->|"loads model"| node_artifacts
node_service -->|"builds model frame"| node_schema
node_service -->|"maps probability"| node_risk_mapping
node_service -->|"computes local explanation"| node_explanation
node_assessment -->|"saves prediction"| node_session
node_results -->|"reads prediction"| node_session
node_explain_page -->|"reads prediction"| node_session
node_streamlit -->|"routes page"| node_results
node_streamlit -->|"routes page"| node_explain_page
node_streamlit -->|"routes page"| node_performance_page
node_streamlit -->|"routes page"| node_quality_page
node_streamlit -->|"routes page"| node_feature_page
node_streamlit -->|"routes page"| node_methodology_page
node_streamlit -->|"routes page"| node_model_page
node_streamlit -->|"routes page"| node_selection_page
node_streamlit -->|"routes page"| node_analytics_page
node_helpers -->|"provides cached service"| node_service
node_performance_page -->|"uses rendering helpers"| node_helpers
node_quality_page -->|"uses rendering helpers"| node_helpers
node_feature_page -.->|"references feature contract"| node_schema

click node_config "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/config.py"
click node_schema "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/schema.py"
click node_acquire "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/download.py"
click node_synthetic "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/synthetic.py"
click node_ingestion "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/ingestion.py"
click node_validation "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/validate.py"
click node_manifest "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/manifest.py"
click node_orchestrator "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/run.py"
click node_split "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/split.py"
click node_preprocess "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/preprocess.py"
click node_models "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/models.py"
click node_tuning "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/tuning.py"
click node_calibration "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/calibrate.py"
click node_evaluation "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/evaluate.py"
click node_fairness "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/fairness.py"
click node_explanation "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/explain.py"
click node_artifacts "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/artifacts.py"
click node_service "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/serving/service.py"
click node_input_validation "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/serving/validation.py"
click node_risk_mapping "https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/risk_score.py"
click node_streamlit "https://github.com/jay4ignite/ml-cornerstone/blob/main/streamlit_app.py"
click node_assessment "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/assessment.py"
click node_session "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/state.py"
click node_results "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/result.py"
click node_explain_page "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/explainability.py"
click node_helpers "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/helpers.py"
click node_performance_page "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/performance.py"
click node_analytics_page "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/analytics.py"
click node_selection_page "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/model_selection.py"
click node_quality_page "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/dataset_quality.py"
click node_feature_page "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/feature_reference.py"
click node_methodology_page "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/methodology.py"
click node_model_page "https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/model_info.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_config,node_schema,node_acquire,node_synthetic,node_ingestion,node_validation,node_manifest toneBlue
class node_orchestrator,node_split,node_preprocess,node_models,node_tuning,node_calibration,node_evaluation,node_fairness,node_explanation,node_artifacts toneAmber
class node_service,node_input_validation,node_risk_mapping toneMint
class node_streamlit,node_assessment,node_session,node_results,node_explain_page,node_helpers toneRose
class node_performance_page,node_analytics_page,node_selection_page,node_quality_page,node_feature_page,node_methodology_page,node_model_page,node_applicant toneIndigo
```

## Components

### Data preparation

- [Configuration](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/config.py): `loan_risk/config.py`
- [Feature contract](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/schema.py): `loan_risk/schema.py`
- [Dataset acquisition](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/download.py): `loan_risk/data/download.py`
- [Synthetic data](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/synthetic.py): `loan_risk/data/synthetic.py`
- [Data ingestion](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/ingestion.py): `loan_risk/data/ingestion.py`
- [Data validation](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/validate.py): `loan_risk/data/validate.py`
- [Dataset manifest](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/data/manifest.py): `loan_risk/data/manifest.py`

### Model training

- [Training workflow](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/run.py): `loan_risk/pipeline/run.py`
- [Data splitting](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/split.py): `loan_risk/pipeline/split.py`
- [Feature preprocessing](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/preprocess.py): `loan_risk/pipeline/preprocess.py`
- [Candidate models](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/models.py): `loan_risk/pipeline/models.py`
- [Model tuning](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/tuning.py): `loan_risk/pipeline/tuning.py`
- [Probability calibration](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/calibrate.py): `loan_risk/pipeline/calibrate.py`
- [Model evaluation](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/evaluate.py): `loan_risk/pipeline/evaluate.py`
- [Fairness diagnostics](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/fairness.py): `loan_risk/pipeline/fairness.py`
- [Model explanations](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/explain.py): `loan_risk/pipeline/explain.py`
- [Model artifacts](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/artifacts.py): `loan_risk/pipeline/artifacts.py`

### Prediction serving

- [Model service](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/serving/service.py): `loan_risk/serving/service.py`
- [Input validation](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/serving/validation.py): `loan_risk/serving/validation.py`
- [Risk mapping](https://github.com/jay4ignite/ml-cornerstone/blob/main/loan_risk/pipeline/risk_score.py): `loan_risk/pipeline/risk_score.py`

### Assessment interface

- [Streamlit app](https://github.com/jay4ignite/ml-cornerstone/blob/main/streamlit_app.py): `streamlit_app.py`
- [Applicant assessment](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/assessment.py): `ui/pages/assessment.py`
- [Session prediction store](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/state.py): `ui/state.py`
- [Prediction results](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/result.py): `ui/pages/result.py`
- [Local explanations](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/explainability.py): `ui/pages/explainability.py`
- [Shared UI helpers](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/helpers.py): `ui/helpers.py`

### Analytics and governance

- [Performance analytics](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/performance.py): `ui/pages/performance.py`
- [Analytics dashboard](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/analytics.py): `ui/pages/analytics.py`
- [Model comparison](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/model_selection.py): `ui/pages/model_selection.py`
- [Dataset quality](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/dataset_quality.py): `ui/pages/dataset_quality.py`
- [Feature reference](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/feature_reference.py): `ui/pages/feature_reference.py`
- [Methodology](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/methodology.py): `ui/pages/methodology.py`
- [Model information](https://github.com/jay4ignite/ml-cornerstone/blob/main/ui/pages/model_info.py): `ui/pages/model_info.py`

### Other components

- **Applicant**

## Connections

- Configuration → Dataset acquisition: configures (evidence: `loan_risk/data/download.py`)
- Configuration → Data ingestion: selects source (evidence: `loan_risk/data/ingestion.py`)
- Feature contract → Data ingestion: defines columns (evidence: `loan_risk/data/ingestion.py`)
- Training workflow → Dataset acquisition: acquires data (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Synthetic data: generates fixture (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Data ingestion: loads and standardizes (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Data validation: validates data (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Dataset manifest: builds manifest (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Data splitting: splits data (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Candidate models: builds candidates (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Model tuning: tunes candidates (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Probability calibration: calibrates selected (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Model evaluation: evaluates test set (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Fairness diagnostics: runs diagnostics (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Model explanations: computes explanations (evidence: `loan_risk/pipeline/run.py`)
- Training workflow → Model artifacts: persists artifacts (evidence: `loan_risk/pipeline/run.py`)
- Feature contract → Feature preprocessing: defines features (evidence: `loan_risk/pipeline/preprocess.py`)
- Feature preprocessing → Candidate models: transforms inputs (evidence: `loan_risk/pipeline/models.py`)
- Applicant → Applicant assessment: enters application (evidence: `README.md`)
- Streamlit app → Applicant assessment: routes page (evidence: `streamlit_app.py`)
- Applicant assessment → Input validation: validates payload (evidence: `ui/pages/assessment.py`)
- Applicant assessment → Model service: requests prediction (evidence: `ui/pages/assessment.py`)
- Model service → Model artifacts: loads model (evidence: `loan_risk/serving/service.py`)
- Model service → Feature contract: builds model frame (evidence: `loan_risk/serving/service.py`)
- Model service → Risk mapping: maps probability (evidence: `loan_risk/serving/service.py`)
- Model service → Model explanations: computes local explanation (evidence: `loan_risk/serving/service.py`)
- Applicant assessment → Session prediction store: saves prediction (evidence: `ui/pages/assessment.py`)
- Prediction results → Session prediction store: reads prediction (evidence: `ui/pages/result.py`)
- Local explanations → Session prediction store: reads prediction (evidence: `ui/pages/explainability.py`)
- Streamlit app → Prediction results: routes page (evidence: `streamlit_app.py`)
- Streamlit app → Local explanations: routes page (evidence: `streamlit_app.py`)
- Streamlit app → Performance analytics: routes page (evidence: `streamlit_app.py`)
- Streamlit app → Dataset quality: routes page (evidence: `streamlit_app.py`)
- Streamlit app → Feature reference: routes page (evidence: `streamlit_app.py`)
- Streamlit app → Methodology: routes page (evidence: `streamlit_app.py`)
- Streamlit app → Model information: routes page (evidence: `streamlit_app.py`)
- Streamlit app → Model comparison: routes page (evidence: `streamlit_app.py`)
- Streamlit app → Analytics dashboard: routes page (evidence: `streamlit_app.py`)
- Shared UI helpers → Model service: provides cached service (evidence: `ui/helpers.py`)
- Performance analytics → Shared UI helpers: uses rendering helpers (evidence: `ui/pages/performance.py`)
- Dataset quality → Shared UI helpers: uses rendering helpers (evidence: `ui/pages/dataset_quality.py`)
- Feature reference → Feature contract: references feature contract
