# especializacionia1/bolsalab architecture

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

- Interactive diagram: https://gitdiagram.com/especializacionia1/bolsalab
- Repository: https://github.com/especializacionia1/bolsalab

## Overview

BolsaLAB is an educational investment-risk companion: it estimates whether a respondent is more, similarly, or less likely than the study population to sell during a market downturn, and explains influential answers. The principal workflow is questionnaire → prediction and explanation → result in the Streamlit prototype. The repository also documents a proposed FastAPI API, but backend/ contains no implementation; the HTML frontend files are prototypes. Training and analysis capabilities are represented where README or source-index evidence supports them; unsampled subsystem links are omitted when their wiring is uncertain.

Main entry points: [`bolsalab/modeling/train.py`](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/train.py) (Model training), [`bolsalab/config.py`](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/config.py) (Paths and settings), [`app/app.py`](https://github.com/especializacionia1/bolsalab/blob/main/app/app.py) (Questionnaire app), [`bolsalab/modeling/predict.py`](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/predict.py) (Prediction service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_streamlit["Questionnaire app<br/>[app.py]"]
  node_api["Proposed API"]
  node_htmlproto["HTML prototypes"]
end

subgraph group_model["Prediction"]
  node_predict["Prediction service<br/>[predict.py]"]
  node_artifact["Trained model"]
  node_metadata["Model metadata"]
  node_training["Model training<br/>[train.py]"]
end

subgraph group_data["Data preparation"]
  node_japan["Japan survey cleanup<br/>[dataset.py]"]
  node_features["Training features<br/>[features.py]"]
  node_config["Paths and settings<br/>[config.py]"]
end

subgraph group_research["Model research"]
  node_transformers["Feature variants<br/>[transformers.py]"]
  node_experiments["Model experiments<br/>[experiments.py]"]
  node_tuning["Family tuning<br/>[tuning.py]"]
  node_optuna["Hyperparameter search<br/>[optuna_search.py]"]
  node_earlystop["Early stopping<br/>[early_stopping.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_explain["Global SHAP analysis<br/>[explain.py]"]
  node_nfcs["NFCS comparison data<br/>[nfcs.py]"]
  node_scf["SCF panel processing<br/>[scf_panel.py]"]
end

node_person(("Respondent"))

node_person -->|"answers questions"| node_streamlit
node_streamlit -->|"requests prediction"| node_predict
node_predict -->|"loads model"| node_artifact
node_predict -->|"loads metadata"| node_metadata
node_streamlit -.->|"API proposed"| node_api
node_streamlit -.->|"prototype context"| node_htmlproto
node_japan -->|"provides cleaned data"| node_features
node_features -->|"provides training table"| node_training
node_training -->|"exports model"| node_artifact
node_training -->|"uses search"| node_optuna
node_training -->|"shares evaluation"| node_tuning
node_tuning -->|"uses stopping"| node_earlystop
node_tuning -->|"tests variants"| node_transformers
node_experiments -->|"reuses evaluation"| node_training
node_experiments -->|"tests variants"| node_transformers
node_explain -->|"uses model explainer"| node_predict
node_nfcs -->|"aligns variables"| node_features
node_scf -->|"uses configured paths"| node_config
node_japan -->|"uses configured paths"| node_config
node_features -->|"uses configured paths"| node_config
node_training -->|"uses configured paths"| node_config
node_nfcs -->|"uses configured paths"| node_config

click node_streamlit "https://github.com/especializacionia1/bolsalab/blob/main/app/app.py"
click node_api "https://github.com/especializacionia1/bolsalab/tree/main/backend"
click node_htmlproto "https://github.com/especializacionia1/bolsalab/tree/main/frontend/prototypes"
click node_predict "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/predict.py"
click node_artifact "https://github.com/especializacionia1/bolsalab/blob/main/models/crash_reaction_v1.joblib"
click node_metadata "https://github.com/especializacionia1/bolsalab/blob/main/models/crash_reaction_v1.json"
click node_japan "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/dataset.py"
click node_features "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/features.py"
click node_config "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/config.py"
click node_training "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/train.py"
click node_transformers "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/transformers.py"
click node_experiments "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/experiments.py"
click node_tuning "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/tuning.py"
click node_optuna "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/optuna_search.py"
click node_earlystop "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/early_stopping.py"
click node_explain "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/explain.py"
click node_nfcs "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/nfcs.py"
click node_scf "https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/scf_panel.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_streamlit,node_api,node_htmlproto toneBlue
class node_predict,node_artifact,node_metadata,node_training toneAmber
class node_japan,node_features,node_config toneMint
class node_transformers,node_experiments,node_tuning,node_optuna,node_earlystop toneRose
class node_explain,node_nfcs,node_scf,node_person toneIndigo
```

## Components

### User experience

- [Questionnaire app](https://github.com/especializacionia1/bolsalab/blob/main/app/app.py): `app/app.py`
- [Proposed API](https://github.com/especializacionia1/bolsalab/tree/main/backend): `backend`
- [HTML prototypes](https://github.com/especializacionia1/bolsalab/tree/main/frontend/prototypes): `frontend/prototypes`

### Prediction

- [Prediction service](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/predict.py): `bolsalab/modeling/predict.py`
- [Trained model](https://github.com/especializacionia1/bolsalab/blob/main/models/crash_reaction_v1.joblib): `models/crash_reaction_v1.joblib`
- [Model metadata](https://github.com/especializacionia1/bolsalab/blob/main/models/crash_reaction_v1.json): `models/crash_reaction_v1.json`
- [Model training](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/train.py): `bolsalab/modeling/train.py`

### Data preparation

- [Japan survey cleanup](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/dataset.py): `bolsalab/dataset.py`
- [Training features](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/features.py): `bolsalab/features.py`
- [Paths and settings](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/config.py): `bolsalab/config.py`

### Model research

- [Feature variants](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/transformers.py): `bolsalab/modeling/transformers.py`
- [Model experiments](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/experiments.py): `bolsalab/modeling/experiments.py`
- [Family tuning](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/tuning.py): `bolsalab/modeling/tuning.py`
- [Hyperparameter search](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/optuna_search.py): `bolsalab/modeling/optuna_search.py`
- [Early stopping](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/modeling/early_stopping.py): `bolsalab/modeling/early_stopping.py`

### Evaluation

- [Global SHAP analysis](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/explain.py): `bolsalab/explain.py`
- [NFCS comparison data](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/nfcs.py): `bolsalab/nfcs.py`
- [SCF panel processing](https://github.com/especializacionia1/bolsalab/blob/main/bolsalab/scf_panel.py): `bolsalab/scf_panel.py`

### Other components

- **Respondent**

## Connections

- Respondent → Questionnaire app: answers questions (evidence: `README.md`)
- Questionnaire app → Prediction service: requests prediction (evidence: `app/app.py`)
- Prediction service → Trained model: loads model (evidence: `bolsalab/modeling/predict.py`)
- Prediction service → Model metadata: loads metadata (evidence: `bolsalab/modeling/predict.py`)
- Questionnaire app → Proposed API: API proposed (evidence: `README.md`)
- Questionnaire app → HTML prototypes: prototype context
- Japan survey cleanup → Training features: provides cleaned data (evidence: `README.md`)
- Training features → Model training: provides training table (evidence: `README.md`)
- Model training → Trained model: exports model (evidence: `bolsalab/modeling/train.py`)
- Model training → Hyperparameter search: uses search (evidence: `bolsalab/modeling/train.py`)
- Model training → Family tuning: shares evaluation (evidence: `bolsalab/modeling/train.py`)
- Family tuning → Early stopping: uses stopping (evidence: `bolsalab/modeling/tuning.py`)
- Family tuning → Feature variants: tests variants (evidence: `bolsalab/modeling/tuning.py`)
- Model experiments → Model training: reuses evaluation (evidence: `bolsalab/modeling/experiments.py`)
- Model experiments → Feature variants: tests variants (evidence: `bolsalab/modeling/experiments.py`)
- Global SHAP analysis → Prediction service: uses model explainer (evidence: `bolsalab/explain.py`)
- NFCS comparison data → Training features: aligns variables (evidence: `bolsalab/nfcs.py`)
- SCF panel processing → Paths and settings: uses configured paths (evidence: `bolsalab/scf_panel.py`)
- Japan survey cleanup → Paths and settings: uses configured paths (evidence: `bolsalab/dataset.py`)
- Training features → Paths and settings: uses configured paths (evidence: `bolsalab/features.py`)
- Model training → Paths and settings: uses configured paths (evidence: `bolsalab/modeling/train.py`)
- NFCS comparison data → Paths and settings: uses configured paths (evidence: `bolsalab/nfcs.py`)
