# ajharshal45/just_to_learn architecture

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

- Interactive diagram: https://gitdiagram.com/ajharshal45/just_to_learn
- Repository: https://github.com/ajharshal45/just_to_learn

## Overview

This repository is a research benchmark and interactive platform for comparing conventional and SHAP-guided oversampling on imbalanced tabular classification. The main workflow is dataset selection or upload, leak-free experiment execution, oversampling and model evaluation, then inspection of metrics, explanations, fidelity, and persisted results. It also includes a public-facing research site and a standalone results simulator. The graph combines documented protocol stages with sampled API/UI wiring; several internal calls are supported only by the source index, so unsampled links are omitted.

Main entry points: [`src/api/experiment_service.py`](https://github.com/ajharshal45/just_to_learn/blob/main/src/api/experiment_service.py) (Experiment service), [`src/experiment/runner.py`](https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/runner.py) (Leak-free runner), [`src/api/main.py`](https://github.com/ajharshal45/just_to_learn/blob/main/src/api/main.py) (REST endpoints), [`src/oversampling`](https://github.com/ajharshal45/just_to_learn/tree/main/src/oversampling) (Oversampling methods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Research interfaces"]
  node_frontend["Platform pages"]
  node_api_client["API client<br/>[api.ts]"]
  node_ui_types["API contracts<br/>[api.ts]"]
  node_shared_ui["Shared UI"]
  node_research_site["Research website<br/>[App.jsx]"]
  node_website_sim["Website simulator<br/>[Simulator.jsx]"]
  node_website_data["Simulator data<br/>[simulatorData.js]"]
  node_standalone_sim["Standalone simulator<br/>[App.jsx]"]
  node_standalone_data["Simulator data<br/>[simulatorData.js]"]
end

subgraph group_api["Platform API"]
  node_api["REST endpoints<br/>[main.py]"]
  node_datasets["Dataset management<br/>[dataset_service.py]"]
  node_experiment_service["Experiment service"]
end

subgraph group_experiment["Experiment workflow"]
  node_dataset_loaders["Dataset loaders<br/>[datasets.py]"]
  node_config["Benchmark config<br/>[config.py]"]
  node_runner["Leak-free runner<br/>[runner.py]"]
  node_preprocessing["Fold preprocessing<br/>[preprocessing.py]"]
end

subgraph group_methods["ML methods"]
  node_oversampling["Oversampling methods"]
  node_shap_weights["SHAP weighting<br/>[base.py]"]
  node_models["Classifiers<br/>[models.py]"]
  node_evaluation["Metrics and stability"]
  node_fidelity["Synthetic fidelity<br/>[fidelity.py]"]
end

subgraph group_state["Results and persistence"]
  node_inspection["Run inspection<br/>[inspection.py]"]
  node_database[("SQLite results<br/>[database.py]")]
end

node_user(("Researcher"))
node_external_data["Dataset files"]

node_user -->|"uses"| node_frontend
node_frontend -->|"requests"| node_api_client
node_frontend -->|"renders"| node_shared_ui
node_api_client -->|"uses types"| node_ui_types
node_api_client -->|"calls REST"| node_api
node_user -->|"explores research"| node_research_site
node_research_site -->|"renders"| node_website_sim
node_website_sim -->|"reads data"| node_website_data
node_user -->|"runs simulation"| node_standalone_sim
node_standalone_sim -->|"reads data"| node_standalone_data
node_api -->|"routes dataset requests"| node_datasets
node_api -->|"routes experiment requests"| node_experiment_service
node_api -->|"reads and writes"| node_database
node_datasets -->|"loads benchmarks"| node_dataset_loaders
node_datasets -->|"stores uploads"| node_database
node_experiment_service -->|"loads experiment data"| node_dataset_loaders
node_experiment_service -->|"selects sampler"| node_oversampling
node_experiment_service -->|"selects classifier"| node_models
node_experiment_service -->|"measures fidelity"| node_fidelity
node_experiment_service -->|"runs cross-validation"| node_runner
node_experiment_service -->|"persists run"| node_database
node_config -->|"configures methods"| node_oversampling
node_config -->|"configures models"| node_models
node_runner -->|"uses settings"| node_config
node_runner -->|"fits in folds"| node_preprocessing
node_runner -->|"computes metrics"| node_evaluation
node_runner -.->|"resamples training folds"| node_oversampling
node_runner -.->|"fits classifiers"| node_models
node_oversampling -->|"uses attributions"| node_shap_weights
node_experiment_service -->|"produces diagnostics"| node_inspection
node_inspection -->|"analyzes samples"| node_fidelity
node_external_data -.->|"provides datasets"| node_dataset_loaders
node_api -.->|"serves explanations"| node_inspection

click node_frontend "https://github.com/ajharshal45/just_to_learn/tree/main/frontend/src/pages"
click node_api_client "https://github.com/ajharshal45/just_to_learn/blob/main/frontend/src/services/api.ts"
click node_ui_types "https://github.com/ajharshal45/just_to_learn/blob/main/frontend/src/types/api.ts"
click node_shared_ui "https://github.com/ajharshal45/just_to_learn/tree/main/frontend/src/components/common"
click node_research_site "https://github.com/ajharshal45/just_to_learn/blob/main/website/src/App.jsx"
click node_website_sim "https://github.com/ajharshal45/just_to_learn/blob/main/website/src/components/Simulator.jsx"
click node_website_data "https://github.com/ajharshal45/just_to_learn/blob/main/website/src/data/simulatorData.js"
click node_standalone_sim "https://github.com/ajharshal45/just_to_learn/blob/main/simulator-app/src/App.jsx"
click node_standalone_data "https://github.com/ajharshal45/just_to_learn/blob/main/simulator-app/src/data/simulatorData.js"
click node_api "https://github.com/ajharshal45/just_to_learn/blob/main/src/api/main.py"
click node_datasets "https://github.com/ajharshal45/just_to_learn/blob/main/src/api/dataset_service.py"
click node_experiment_service "https://github.com/ajharshal45/just_to_learn/blob/main/src/api/experiment_service.py"
click node_dataset_loaders "https://github.com/ajharshal45/just_to_learn/blob/main/src/pipeline/datasets.py"
click node_config "https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/config.py"
click node_runner "https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/runner.py"
click node_preprocessing "https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/preprocessing.py"
click node_oversampling "https://github.com/ajharshal45/just_to_learn/tree/main/src/oversampling"
click node_shap_weights "https://github.com/ajharshal45/just_to_learn/blob/main/src/oversampling/base.py"
click node_models "https://github.com/ajharshal45/just_to_learn/blob/main/src/pipeline/models.py"
click node_evaluation "https://github.com/ajharshal45/just_to_learn/tree/main/src/evaluation"
click node_fidelity "https://github.com/ajharshal45/just_to_learn/blob/main/src/evaluation/fidelity.py"
click node_inspection "https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/inspection.py"
click node_database "https://github.com/ajharshal45/just_to_learn/blob/main/src/api/database.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_frontend,node_api_client,node_ui_types,node_shared_ui,node_research_site,node_website_sim,node_website_data,node_standalone_sim,node_standalone_data toneBlue
class node_api,node_datasets,node_experiment_service toneAmber
class node_dataset_loaders,node_config,node_runner,node_preprocessing toneMint
class node_oversampling,node_shap_weights,node_models,node_evaluation,node_fidelity toneRose
class node_inspection,node_database,node_user,node_external_data toneIndigo
```

## Components

### Research interfaces

- [Platform pages](https://github.com/ajharshal45/just_to_learn/tree/main/frontend/src/pages): `frontend/src/pages`
- [API client](https://github.com/ajharshal45/just_to_learn/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [API contracts](https://github.com/ajharshal45/just_to_learn/blob/main/frontend/src/types/api.ts): `frontend/src/types/api.ts`
- [Shared UI](https://github.com/ajharshal45/just_to_learn/tree/main/frontend/src/components/common): `frontend/src/components/common`
- [Research website](https://github.com/ajharshal45/just_to_learn/blob/main/website/src/App.jsx): `website/src/App.jsx`
- [Website simulator](https://github.com/ajharshal45/just_to_learn/blob/main/website/src/components/Simulator.jsx): `website/src/components/Simulator.jsx`
- [Simulator data](https://github.com/ajharshal45/just_to_learn/blob/main/website/src/data/simulatorData.js): `website/src/data/simulatorData.js`
- [Standalone simulator](https://github.com/ajharshal45/just_to_learn/blob/main/simulator-app/src/App.jsx): `simulator-app/src/App.jsx`
- [Simulator data](https://github.com/ajharshal45/just_to_learn/blob/main/simulator-app/src/data/simulatorData.js): `simulator-app/src/data/simulatorData.js`

### Platform API

- [REST endpoints](https://github.com/ajharshal45/just_to_learn/blob/main/src/api/main.py): `src/api/main.py`
- [Dataset management](https://github.com/ajharshal45/just_to_learn/blob/main/src/api/dataset_service.py): `src/api/dataset_service.py`
- [Experiment service](https://github.com/ajharshal45/just_to_learn/blob/main/src/api/experiment_service.py): `src/api/experiment_service.py`

### Experiment workflow

- [Dataset loaders](https://github.com/ajharshal45/just_to_learn/blob/main/src/pipeline/datasets.py): `src/pipeline/datasets.py`
- [Benchmark config](https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/config.py): `src/experiment/config.py`
- [Leak-free runner](https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/runner.py): `src/experiment/runner.py`
- [Fold preprocessing](https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/preprocessing.py): `src/experiment/preprocessing.py`

### ML methods

- [Oversampling methods](https://github.com/ajharshal45/just_to_learn/tree/main/src/oversampling): `src/oversampling`
- [SHAP weighting](https://github.com/ajharshal45/just_to_learn/blob/main/src/oversampling/base.py): `src/oversampling/base.py`
- [Classifiers](https://github.com/ajharshal45/just_to_learn/blob/main/src/pipeline/models.py): `src/pipeline/models.py`
- [Metrics and stability](https://github.com/ajharshal45/just_to_learn/tree/main/src/evaluation): `src/evaluation`
- [Synthetic fidelity](https://github.com/ajharshal45/just_to_learn/blob/main/src/evaluation/fidelity.py): `src/evaluation/fidelity.py`

### Results and persistence

- [Run inspection](https://github.com/ajharshal45/just_to_learn/blob/main/src/experiment/inspection.py): `src/experiment/inspection.py`
- [SQLite results](https://github.com/ajharshal45/just_to_learn/blob/main/src/api/database.py): `src/api/database.py`

### Other components

- **Researcher**
- **Dataset files**

## Connections

- Researcher → Platform pages: uses
- Platform pages → API client: requests (evidence: `frontend/src/pages/DatasetExplorer.tsx`)
- Platform pages → Shared UI: renders (evidence: `frontend/src/pages/DatasetExplorer.tsx`)
- API client → API contracts: uses types (evidence: `frontend/src/services/api.ts`)
- API client → REST endpoints: calls REST (evidence: `frontend/src/services/api.ts`)
- Researcher → Research website: explores research (evidence: `website/src/App.jsx`)
- Research website → Website simulator: renders (evidence: `website/src/App.jsx`)
- Website simulator → Simulator data: reads data (evidence: `website/src/components/Simulator.jsx`)
- Researcher → Standalone simulator: runs simulation (evidence: `simulator-app/src/App.jsx`)
- Standalone simulator → Simulator data: reads data (evidence: `simulator-app/src/App.jsx`)
- REST endpoints → Dataset management: routes dataset requests (evidence: `src/api/main.py`)
- REST endpoints → Experiment service: routes experiment requests (evidence: `src/api/main.py`)
- REST endpoints → SQLite results: reads and writes (evidence: `src/api/main.py`)
- Dataset management → Dataset loaders: loads benchmarks (evidence: `src/api/dataset_service.py`)
- Dataset management → SQLite results: stores uploads (evidence: `src/api/dataset_service.py`)
- Experiment service → Dataset loaders: loads experiment data (evidence: `src/api/experiment_service.py`)
- Experiment service → Oversampling methods: selects sampler (evidence: `src/api/experiment_service.py`)
- Experiment service → Classifiers: selects classifier (evidence: `src/api/experiment_service.py`)
- Experiment service → Synthetic fidelity: measures fidelity (evidence: `src/api/experiment_service.py`)
- Experiment service → Leak-free runner: runs cross-validation (evidence: `src/api/experiment_service.py`)
- Experiment service → SQLite results: persists run (evidence: `src/api/experiment_service.py`)
- Benchmark config → Oversampling methods: configures methods (evidence: `src/experiment/config.py`)
- Benchmark config → Classifiers: configures models (evidence: `src/experiment/config.py`)
- Leak-free runner → Benchmark config: uses settings (evidence: `src/experiment/runner.py`)
- Leak-free runner → Fold preprocessing: fits in folds (evidence: `src/experiment/runner.py`)
- Leak-free runner → Metrics and stability: computes metrics (evidence: `src/experiment/runner.py`)
- Leak-free runner → Oversampling methods: resamples training folds
- Leak-free runner → Classifiers: fits classifiers
- Oversampling methods → SHAP weighting: uses attributions (evidence: `src/oversampling/__init__.py`)
- Experiment service → Run inspection: produces diagnostics (evidence: `src/api/experiment_service.py`)
- Run inspection → Synthetic fidelity: analyzes samples (evidence: `src/experiment/inspection.py`)
- Dataset files → Dataset loaders: provides datasets
- REST endpoints → Run inspection: serves explanations
