# adwaitsatav/credit-risk-engine architecture

> Architecture diagram of the GitHub repository adwaitsatav/credit-risk-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adwaitsatav/credit-risk-engine
- Repository: https://github.com/adwaitsatav/credit-risk-engine

## Overview

1. **Repository purpose**
   - This repo is a two-part machine learning system: an **offline training pipeline** that builds a credit-risk classifier, and an **online Streamlit app** that serves predictions from the saved artifacts.

2. **Primary architectural boundary**
   - The key split is between **training-time code** (`train_model.py`) and **runtime inference code** (`app.py`).
   - Training produces serialized assets; the app consumes them without retraining.

3. **Offline ML pipeline**
   - `train_model.py` is responsible for generating or preparing the Lending Club-style synthetic dataset, fitting the model, evaluating it, and persisting outputs.
   - The model is a **Random Forest classifier** from scikit-learn, chosen for tabular credit-risk prediction.

4. **Persisted model artifacts**
   - `model.pkl` stores the trained classifier.
   - `model_columns.pkl` preserves the exact feature order expected by the model.
   - `label_encoder.pkl` stores categorical encoding state so the app can transform inputs consistently.
   - `metrics.pkl` stores evaluation results for display in the UI.

5. **Online inference layer**
   - `app.py` is the Streamlit application that acts as the presentation and inference layer.
   - It loads the saved artifacts at startup, collects user inputs, transforms them into the trained feature representation, and runs the model to generate a default-risk prediction.

6. **Data flow at runtime**
   - User enters applicant attributes in the Streamlit UI.
   - The app encodes/aligns those values to the saved feature schema.
   - The model returns a probability and class/risk-band output.
   - The app then renders the prediction, risk band, feature importance, and stored metrics.

7. **Feature schema and preprocessing contract**
   - The presence of `model_columns.pkl` and `label_encoder.pkl` indicates the app must strictly match the training-time schema.
   - This is an important architecture constraint: inference depends on the same categorical encoding and column ordering used during training.

8. **User-facing functionality**
   - The app exposes an interactive credit-risk calculator with adjustable inputs.
   - It also surfaces explanatory outputs such as **feature importance** and **model performance metrics** to make the decision more interpretable.

9. **Technology stack**
   - **Python** is the runtime.
   - **Streamlit** provides the web UI and deployment target.
   - **scikit-learn** provides the Random Forest model and evaluation metrics.
   - Serialization is handled through Python pickle artifacts.

10. **Deployment model**
   - The README indicates deployment on **Streamlit Cloud**, so the production boundary is a hosted Streamlit process that loads the prebuilt `.pkl` files from the repo.
   - There is no separate API service, database, or job queue visible in this repository.

11. **Operational lifecycle**
   - To refresh the system, an engineer would rerun `train_model.py` to regenerate the model and associated artifacts, then redeploy the Streamlit app.
   - This means the repository favors a simple, reproducible, file-based ML deployment pattern rather than a microservice architecture.

12. **What to draw in an architecture diagram**
   - A good diagram would show: **input form in Streamlit UI → preprocessing/encoding using saved schema → Random Forest inference → risk band + metrics/feature importance displayed back to the user**.
   - Separately, show the **training pipeline** feeding the serialized artifacts used by the live app.

Main entry points: [`metrics.pkl`](https://github.com/adwaitsatav/credit-risk-engine/blob/main/metrics.pkl) (Metrics pickle), [`model.pkl`](https://github.com/adwaitsatav/credit-risk-engine/blob/main/model.pkl) (Model pickle), [`model_columns.pkl`](https://github.com/adwaitsatav/credit-risk-engine/blob/main/model_columns.pkl) (Column schema), [`label_encoder.pkl`](https://github.com/adwaitsatav/credit-risk-engine/blob/main/label_encoder.pkl) (Encoder pickle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Offline training"]
  node_train_script["Train model<br/>pipeline script<br/>[train_model.py]"]
  node_prep_data["Prep data<br/>data prep"]
  node_fit_model["Fit RF<br/>sklearn model"]
  node_evaluate_model["Evaluate<br/>metrics"]
  node_persist_artifacts["Save artifacts<br/>serialization"]
end

subgraph group_runtime["Online inference"]
  node_app_script["Streamlit app<br/>web app<br/>[app.py]"]
  node_load_artifacts["Load assets<br/>startup load"]
  node_collect_input["Input form<br/>ui form"]
  node_encode_input["Encode input<br/>preprocessing"]
  node_align_schema["Align columns<br/>schema contract"]
  node_predict_risk["Predict risk<br/>inference"]
  node_show_results["Show results<br/>presentation"]
end

subgraph group_artifacts["Saved artifacts"]
  node_model_file["Model pickle<br/>artifact<br/>[model.pkl]"]
  node_columns_file["Column schema<br/>artifact<br/>[model_columns.pkl]"]
  node_encoder_file["Encoder pickle<br/>artifact<br/>[label_encoder.pkl]"]
  node_metrics_file["Metrics pickle<br/>artifact<br/>[metrics.pkl]"]
end

node_train_script -->|"orchestrates"| node_prep_data
node_prep_data -->|"feeds"| node_fit_model
node_fit_model -->|"produces"| node_evaluate_model
node_evaluate_model -->|"records"| node_persist_artifacts
node_persist_artifacts -->|"writes"| node_model_file
node_persist_artifacts -->|"writes"| node_columns_file
node_persist_artifacts -->|"writes"| node_encoder_file
node_persist_artifacts -->|"writes"| node_metrics_file
node_app_script -->|"starts with"| node_load_artifacts
node_load_artifacts -->|"reads"| node_model_file
node_load_artifacts -->|"reads"| node_columns_file
node_load_artifacts -->|"reads"| node_encoder_file
node_load_artifacts -->|"reads"| node_metrics_file
node_collect_input -->|"feeds"| node_encode_input
node_encode_input -->|"normalizes"| node_align_schema
node_align_schema -->|"inputs"| node_predict_risk
node_predict_risk -->|"outputs"| node_show_results
node_show_results -->|"displays"| node_metrics_file

click node_train_script "https://github.com/adwaitsatav/credit-risk-engine/blob/main/train_model.py"
click node_app_script "https://github.com/adwaitsatav/credit-risk-engine/blob/main/app.py"
click node_model_file "https://github.com/adwaitsatav/credit-risk-engine/blob/main/model.pkl"
click node_columns_file "https://github.com/adwaitsatav/credit-risk-engine/blob/main/model_columns.pkl"
click node_encoder_file "https://github.com/adwaitsatav/credit-risk-engine/blob/main/label_encoder.pkl"
click node_metrics_file "https://github.com/adwaitsatav/credit-risk-engine/blob/main/metrics.pkl"

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_train_script,node_prep_data,node_fit_model,node_evaluate_model,node_persist_artifacts toneBlue
class node_app_script,node_load_artifacts,node_collect_input,node_encode_input,node_align_schema,node_predict_risk,node_show_results toneAmber
class node_model_file,node_columns_file,node_encoder_file,node_metrics_file toneMint
```

## Components

### Offline training

Builds the credit-risk model and serializes the reusable artifacts.

- [Train model](https://github.com/adwaitsatav/credit-risk-engine/blob/main/train_model.py): pipeline script · Orchestrates data preparation, model fitting, evaluation, and persistence. · `train_model.py`
- **Prep data**: data prep · Generates or prepares the Lending Club-style training dataset.
- **Fit RF**: sklearn model · Trains the Random Forest classifier for credit-risk prediction.
- **Evaluate**: metrics · Computes model performance metrics for later display.
- **Save artifacts**: serialization · Writes the trained model, schema, encoder state, and metrics to disk.

### Online inference

Streamlit app that loads saved artifacts and serves predictions.

- [Streamlit app](https://github.com/adwaitsatav/credit-risk-engine/blob/main/app.py): web app · Interactive UI and inference layer for credit-risk prediction. · `app.py`
- **Load assets**: startup load · Reads the saved model, column order, encoder, and metrics at app startup.
- **Input form**: ui form · Collects applicant attributes from the user.
- **Encode input**: preprocessing · Transforms user values into the trained feature representation.
- **Align columns**: schema contract · Matches inference features to the saved training-time column order.
- **Predict risk**: inference · Runs the saved classifier to produce class and probability outputs.
- **Show results**: presentation · Renders prediction, risk band, feature importance, and metrics.

### Saved artifacts

Files persisted by training and consumed at runtime.

- [Model pickle](https://github.com/adwaitsatav/credit-risk-engine/blob/main/model.pkl): artifact · Serialized Random Forest classifier. · `model.pkl`
- [Column schema](https://github.com/adwaitsatav/credit-risk-engine/blob/main/model_columns.pkl): artifact · Persisted feature order expected by the model. · `model_columns.pkl`
- [Encoder pickle](https://github.com/adwaitsatav/credit-risk-engine/blob/main/label_encoder.pkl): artifact · Stored categorical encoding state used during inference. · `label_encoder.pkl`
- [Metrics pickle](https://github.com/adwaitsatav/credit-risk-engine/blob/main/metrics.pkl): artifact · Saved evaluation results displayed in the UI. · `metrics.pkl`

## Connections

- Train model → Prep data: orchestrates · Training begins by preparing the dataset.
- Prep data → Fit RF: feeds · Prepared features and target are used to train the classifier.
- Fit RF → Evaluate: produces · The trained model is scored on evaluation metrics.
- Evaluate → Save artifacts: records · Metrics and trained state are written out together.
- Save artifacts → Model pickle: writes · Stores the trained classifier.
- Save artifacts → Column schema: writes · Stores the exact feature order.
- Save artifacts → Encoder pickle: writes · Stores categorical encoding state.
- Save artifacts → Metrics pickle: writes · Stores performance metrics.
- Streamlit app → Load assets: starts with · The app loads serialized assets when it launches.
- Load assets → Model pickle: reads · Loads the classifier for inference.
- Load assets → Column schema: reads · Loads the expected feature schema.
- Load assets → Encoder pickle: reads · Loads the encoding state.
- Load assets → Metrics pickle: reads · Loads metrics for display.
- Input form → Encode input: feeds · User-entered values are transformed for the model.
- Encode input → Align columns: normalizes · Encoded values are aligned to the saved column order.
- Align columns → Predict risk: inputs · Schema-aligned features are passed to the model.
- Predict risk → Show results: outputs · Prediction results are rendered to the user.
- Show results → Metrics pickle: displays · Stored metrics are surfaced in the UI.
