# alessandro-deidda/isw-qubo-classification-g40 architecture

> Architecture diagram of the GitHub repository alessandro-deidda/isw-qubo-classification-g40, 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/alessandro-deidda/isw-qubo-classification-g40
- Repository: https://github.com/alessandro-deidda/isw-qubo-classification-g40

## Overview

This is a reproducible loan-risk classification application: raw tabular data is cleaned and normalized, reduced through Spearman-based QUBO feature selection, used to train a classifier, then scored for predictions and classification statistics. Users can run the stages from the CLI or use the Streamlit GUI, which the README documents as wrapping the full workflow. The feature-selection excerpt supports the correlation, annealing, and alpha-sweep mechanics; GUI excerpts are partial, so detailed UI-to-stage wiring is not expanded.

Main entry points: [`src/qubo_project/feature_selection.py`](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/feature_selection.py) (Select features), [`src/qubo_project/gui.py`](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/gui.py) (Streamlit GUI), [`src/qubo_project/preprocessing.py`](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/preprocessing.py) (Normalize data), [`src/qubo_project/model.py`](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/model.py) (Train classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Data workflow"]
  node_preprocess["Normalize data<br/>[preprocessing.py]"]
  node_normalized["Normalized CSV"]
end

subgraph group_selection["QUBO selection"]
  node_selection["Select features"]
  node_qubo["QUBO annealing"]
  node_reduced["Reduced splits"]
  node_diagnostics["Selection diagnostics"]
end

subgraph group_modeling["Modeling"]
  node_train["Train classifier<br/>[model.py]"]
  node_model["Persisted model"]
  node_metrics["Training metrics"]
  node_predict["Predict and evaluate<br/>[model.py]"]
  node_results["Predictions and stats"]
end

subgraph group_interface["User interfaces"]
  node_gui["Streamlit GUI<br/>[gui.py]"]
end

node_user(("User"))
node_cli(("CLI caller"))
node_rawdata["Loan dataset"]
node_streamlit{{"Streamlit runtime"}}

node_cli -->|"runs stage"| node_preprocess
node_rawdata -->|"reads CSV"| node_preprocess
node_preprocess -->|"writes CSV"| node_normalized
node_preprocess -.->|"GUI invokes"| node_selection
node_cli -->|"runs stage"| node_selection
node_normalized -->|"reads CSV"| node_selection
node_selection -->|"builds and solves"| node_qubo
node_selection -->|"writes splits"| node_reduced
node_selection -->|"writes reports"| node_diagnostics
node_cli -->|"runs stage"| node_train
node_reduced -->|"reads training split"| node_train
node_train -->|"persists model"| node_model
node_train -->|"writes metrics"| node_metrics
node_cli -->|"runs stage"| node_predict
node_reduced -->|"reads test split"| node_predict
node_model -->|"loads model"| node_predict
node_predict -->|"writes predictions and stats"| node_results
node_user -->|"uses"| node_gui
node_streamlit -->|"hosts"| node_gui
node_gui -.->|"invokes"| node_preprocess
node_gui -.->|"invokes"| node_selection
node_gui -.->|"invokes"| node_train
node_gui -.->|"invokes"| node_predict

click node_preprocess "https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/preprocessing.py"
click node_selection "https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/feature_selection.py"
click node_qubo "https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/feature_selection.py"
click node_train "https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/model.py"
click node_predict "https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/model.py"
click node_gui "https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/gui.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_preprocess,node_normalized,node_user toneBlue
class node_selection,node_qubo,node_reduced,node_diagnostics toneAmber
class node_train,node_model,node_metrics,node_predict,node_results toneMint
class node_gui toneRose
class node_cli,node_rawdata,node_streamlit toneIndigo
```

## Components

### Data workflow

- [Normalize data](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/preprocessing.py): `src/qubo_project/preprocessing.py`
- **Normalized CSV**

### QUBO selection

- [Select features](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/feature_selection.py): `src/qubo_project/feature_selection.py`
- [QUBO annealing](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/feature_selection.py): `src/qubo_project/feature_selection.py`
- **Reduced splits**
- **Selection diagnostics**

### Modeling

- [Train classifier](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/model.py): `src/qubo_project/model.py`
- **Persisted model**
- **Training metrics**
- [Predict and evaluate](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/model.py): `src/qubo_project/model.py`
- **Predictions and stats**

### User interfaces

- [Streamlit GUI](https://github.com/alessandro-deidda/isw-qubo-classification-g40/blob/main/src/qubo_project/gui.py): `src/qubo_project/gui.py`

### Other components

- **User**
- **CLI caller**
- **Loan dataset**
- **Streamlit runtime**

## Connections

- CLI caller → Normalize data: runs stage
- Loan dataset → Normalize data: reads CSV
- Normalize data → Normalized CSV: writes CSV
- Normalize data → Select features: GUI invokes
- CLI caller → Select features: runs stage
- Normalized CSV → Select features: reads CSV
- Select features → QUBO annealing: builds and solves
- Select features → Reduced splits: writes splits
- Select features → Selection diagnostics: writes reports
- CLI caller → Train classifier: runs stage
- Reduced splits → Train classifier: reads training split
- Train classifier → Persisted model: persists model
- Train classifier → Training metrics: writes metrics
- CLI caller → Predict and evaluate: runs stage
- Reduced splits → Predict and evaluate: reads test split
- Persisted model → Predict and evaluate: loads model
- Predict and evaluate → Predictions and stats: writes predictions and stats
- User → Streamlit GUI: uses
- Streamlit runtime → Streamlit GUI: hosts
- Streamlit GUI → Normalize data: invokes
- Streamlit GUI → Select features: invokes
- Streamlit GUI → Train classifier: invokes
- Streamlit GUI → Predict and evaluate: invokes