# grupo-57-machine-learning-engineering/purchase-propensity architecture

> Architecture diagram of the GitHub repository grupo-57-machine-learning-engineering/purchase-propensity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grupo-57-machine-learning-engineering/purchase-propensity
- Repository: https://github.com/grupo-57-machine-learning-engineering/purchase-propensity

## Overview

Purchase Propensity is an end-to-end purchase-intent ML system: it prepares browsing data, trains and compares classifiers, promotes a champion model, and serves predictions through FastAPI. The main training flow is owned by the experiment runner; a separate Random Forest search supports tuning. The API loads the registered champion at startup and scores submitted visits. Relationships below are limited to the excerpts, SOURCE INDEX references, and README statements; unsampled implementation details are not inferred.

Main entry points: [`src/training/experiment.py`](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/experiment.py) (Experiment runner), [`src/pipeline.py`](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/pipeline.py) (Pipeline runner), [`src/data/pipeline.py`](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/data/pipeline.py) (ETL orchestrator), [`src/training/registry.py`](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/registry.py) (Champion registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_rawdata[("Raw visits")]
  node_etl["ETL orchestrator<br/>[pipeline.py]"]
  node_extract["Dataset extraction<br/>[extract.py]"]
  node_transform["Dataset transform<br/>[transform.py]"]
  node_processed[("Processed parquet")]
end

subgraph group_training["Model training"]
  node_pipeline["Pipeline runner<br/>[pipeline.py]"]
  node_features["Feature selection<br/>[selection.py]"]
  node_split["Stratified split<br/>[split.py]"]
  node_experiment["Experiment runner<br/>[experiment.py]"]
  node_baseline["Baseline training<br/>[baseline.py]"]
  node_logistic["Logistic regression"]
  node_rftrain["Forest training<br/>[random_forest.py]"]
  node_forest["Random Forest<br/>[random_forest.py]"]
  node_crossval["Cross-validation"]
  node_metrics["Metrics<br/>[metrics.py]"]
  node_tuning["Hyperparameter search<br/>[tuning.py]"]
  node_tracking["Run tracking<br/>[tracking.py]"]
end

subgraph group_registry["Model selection"]
  node_compare["Run comparison<br/>[compare.py]"]
  node_registry["Champion registry<br/>[registry.py]"]
  node_mlflow[("MLflow service")]
end

subgraph group_serving["Prediction API"]
  node_api["FastAPI endpoints<br/>[app.py]"]
  node_apimodel["Model loading and scoring<br/>[model.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
end

node_analyst(("ML practitioner"))
node_kaggle["Kaggle dataset"]
node_consumer(("Prediction client"))

node_analyst -->|"runs pipeline"| node_pipeline
node_kaggle -->|"provides dataset"| node_extract
node_etl -->|"calls extraction"| node_extract
node_extract -->|"downloads raw"| node_rawdata
node_etl -->|"transforms data"| node_transform
node_etl -->|"writes parquet"| node_processed
node_pipeline -->|"runs ETL"| node_etl
node_pipeline -->|"runs experiments"| node_experiment
node_pipeline -->|"promotes model"| node_registry
node_experiment -->|"reads dataset"| node_processed
node_experiment -->|"creates split"| node_split
node_split -->|"selects features"| node_features
node_baseline -->|"runs experiment"| node_experiment
node_baseline -->|"builds estimator"| node_logistic
node_rftrain -->|"runs experiment"| node_experiment
node_rftrain -->|"builds estimator"| node_forest
node_experiment -->|"validates folds"| node_crossval
node_experiment -->|"saves metrics"| node_metrics
node_experiment -->|"logs run"| node_tracking
node_tuning -->|"searches parameters"| node_forest
node_tuning -->|"prepares data"| node_split
node_tracking -->|"logs runs"| node_mlflow
node_registry -->|"ranks runs"| node_compare
node_registry -->|"registers champion"| node_mlflow
node_consumer -->|"requests prediction"| node_api
node_api -->|"loads and scores"| node_apimodel
node_api -->|"validates payloads"| node_schemas
node_apimodel -->|"uses visitor fields"| node_schemas
node_apimodel -->|"loads champion"| node_mlflow

click node_rawdata "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/tree/main/data/raw"
click node_etl "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/data/pipeline.py"
click node_extract "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/data/extract.py"
click node_transform "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/data/transform.py"
click node_processed "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/tree/main/data/processed"
click node_pipeline "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/pipeline.py"
click node_features "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/features/selection.py"
click node_split "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/split.py"
click node_experiment "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/experiment.py"
click node_baseline "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/baseline.py"
click node_logistic "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/models/logistic_regression.py"
click node_rftrain "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/random_forest.py"
click node_forest "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/models/random_forest.py"
click node_crossval "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/cross_validation.py"
click node_metrics "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/metrics.py"
click node_tuning "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/tuning.py"
click node_tracking "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/tracking.py"
click node_compare "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/compare.py"
click node_registry "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/registry.py"
click node_api "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/api/app.py"
click node_apimodel "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/api/model.py"
click node_schemas "https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/api/schemas.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_rawdata,node_etl,node_extract,node_transform,node_processed,node_consumer toneBlue
class node_pipeline,node_features,node_split,node_experiment,node_baseline,node_logistic,node_rftrain,node_forest,node_crossval,node_metrics,node_tuning,node_tracking toneAmber
class node_compare,node_registry,node_mlflow toneMint
class node_api,node_apimodel,node_schemas toneRose
class node_analyst,node_kaggle toneIndigo
```

## Components

### Data preparation

- [Raw visits](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/tree/main/data/raw): `data/raw`
- [ETL orchestrator](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/data/pipeline.py): `src/data/pipeline.py`
- [Dataset extraction](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/data/extract.py): `src/data/extract.py`
- [Dataset transform](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/data/transform.py): `src/data/transform.py`
- [Processed parquet](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/tree/main/data/processed): `data/processed`

### Model training

- [Pipeline runner](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/pipeline.py): `src/pipeline.py`
- [Feature selection](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/features/selection.py): `src/features/selection.py`
- [Stratified split](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/split.py): `src/training/split.py`
- [Experiment runner](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/experiment.py): `src/training/experiment.py`
- [Baseline training](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/baseline.py): `src/training/baseline.py`
- [Logistic regression](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/models/logistic_regression.py): `src/models/logistic_regression.py`
- [Forest training](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/random_forest.py): `src/training/random_forest.py`
- [Random Forest](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/models/random_forest.py): `src/models/random_forest.py`
- [Cross-validation](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/cross_validation.py): `src/training/cross_validation.py`
- [Metrics](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/metrics.py): `src/training/metrics.py`
- [Hyperparameter search](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/tuning.py): `src/training/tuning.py`
- [Run tracking](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/tracking.py): `src/training/tracking.py`

### Model selection

- [Run comparison](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/compare.py): `src/training/compare.py`
- [Champion registry](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/training/registry.py): `src/training/registry.py`
- **MLflow service**

### Prediction API

- [FastAPI endpoints](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/api/app.py): `src/api/app.py`
- [Model loading and scoring](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/api/model.py): `src/api/model.py`
- [Request and response schemas](https://github.com/grupo-57-machine-learning-engineering/purchase-propensity/blob/main/src/api/schemas.py): `src/api/schemas.py`

### Other components

- **ML practitioner**
- **Kaggle dataset**
- **Prediction client**

## Connections

- ML practitioner → Pipeline runner: runs pipeline (evidence: `src/pipeline.py`)
- Kaggle dataset → Dataset extraction: provides dataset (evidence: `README.md`)
- ETL orchestrator → Dataset extraction: calls extraction (evidence: `src/data/pipeline.py`)
- Dataset extraction → Raw visits: downloads raw (evidence: `README.md`)
- ETL orchestrator → Dataset transform: transforms data (evidence: `src/data/pipeline.py`)
- ETL orchestrator → Processed parquet: writes parquet (evidence: `src/data/pipeline.py`)
- Pipeline runner → ETL orchestrator: runs ETL (evidence: `src/pipeline.py`)
- Pipeline runner → Experiment runner: runs experiments (evidence: `src/pipeline.py`)
- Pipeline runner → Champion registry: promotes model (evidence: `src/pipeline.py`)
- Experiment runner → Processed parquet: reads dataset (evidence: `src/training/experiment.py`)
- Experiment runner → Stratified split: creates split (evidence: `src/training/experiment.py`)
- Stratified split → Feature selection: selects features (evidence: `src/training/split.py`)
- Baseline training → Experiment runner: runs experiment (evidence: `src/training/baseline.py`)
- Baseline training → Logistic regression: builds estimator (evidence: `src/training/baseline.py`)
- Forest training → Experiment runner: runs experiment (evidence: `src/training/random_forest.py`)
- Forest training → Random Forest: builds estimator (evidence: `src/training/random_forest.py`)
- Experiment runner → Cross-validation: validates folds (evidence: `src/training/experiment.py`)
- Experiment runner → Metrics: saves metrics (evidence: `src/training/experiment.py`)
- Experiment runner → Run tracking: logs run (evidence: `README.md`)
- Hyperparameter search → Random Forest: searches parameters (evidence: `src/training/tuning.py`)
- Hyperparameter search → Stratified split: prepares data (evidence: `src/training/tuning.py`)
- Run tracking → MLflow service: logs runs (evidence: `README.md`)
- Champion registry → Run comparison: ranks runs (evidence: `src/training/registry.py`)
- Champion registry → MLflow service: registers champion (evidence: `src/training/registry.py`)
- Prediction client → FastAPI endpoints: requests prediction (evidence: `README.md`)
- FastAPI endpoints → Model loading and scoring: loads and scores (evidence: `src/api/app.py`)
- FastAPI endpoints → Request and response schemas: validates payloads (evidence: `src/api/app.py`)
- Model loading and scoring → Request and response schemas: uses visitor fields (evidence: `src/api/model.py`)
- Model loading and scoring → MLflow service: loads champion (evidence: `src/api/model.py`)