# triscravello/running-readiness-ml architecture

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

- Interactive diagram: https://gitdiagram.com/triscravello/running-readiness-ml
- Repository: https://github.com/triscravello/running-readiness-ml

## Overview

This repository is an educational, end-to-end running-readiness prediction system, spanning synthetic data preparation and leakage controls through group-safe model selection, feature gating, neural-network transfer learning, and a secured CPU inference API. The main user path is a validated prediction request through the service into a lineage-verified runtime model. Separate development experiments and deployment-integrity checks support that path. Relationships follow the README and shown imports/calls; unsampled subsystem details are represented conservatively.

Main entry points: [`src/feature_experiment.py`](https://github.com/triscravello/running-readiness-ml/blob/main/src/feature_experiment.py) (Feature gate), [`src/train_models.py`](https://github.com/triscravello/running-readiness-ml/blob/main/src/train_models.py) (Group-safe training), [`src/data_pipeline.py`](https://github.com/triscravello/running-readiness-ml/blob/main/src/data_pipeline.py) (Data pipeline), [`src/neural_network_experiment.py`](https://github.com/triscravello/running-readiness-ml/blob/main/src/neural_network_experiment.py) (Denoising pretraining)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data contracts"]
  node_pipeline["Data pipeline<br/>[data_pipeline.py]"]
  node_schema_gate["Schema drift gate"]
  node_feature_gate["Feature gate"]
end

subgraph group_classical["Classical modeling"]
  node_group_training["Group-safe training<br/>[train_models.py]"]
  node_evaluation["Evaluation and lock<br/>[evaluate_models.py]"]
  node_threshold["Threshold analysis"]
end

subgraph group_neural["Neural modeling"]
  node_pretraining["Denoising pretraining"]
  node_finetuning["Transfer fine-tuning"]
end

subgraph group_security["Serving integrity"]
  node_lineage["Lineage verification<br/>[level7_lineage.py]"]
  node_manifest["Serving manifest<br/>[level7_manifest.py]"]
  node_packaging["Deployment packaging<br/>[level7_package.py]"]
  node_service["API validation<br/>[level7_service.py]"]
  node_runtime["CPU model runtime<br/>[level7_runtime.py]"]
  node_artifacts["Model and handoff artifacts"]
end

subgraph group_experiments["Model experiments"]
  node_capacity["Tree capacity study"]
  node_leakage["Leakage proxy study"]
  node_overfit["Overfit study"]
end

node_raw_source(("Raw data source"))
node_client(("Prediction client"))

node_raw_source -->|"provides data"| node_pipeline
node_pipeline -->|"prepares splits"| node_group_training
node_pipeline -->|"checks drift"| node_schema_gate
node_group_training -->|"evaluates models"| node_evaluation
node_evaluation -->|"locks handoff"| node_feature_gate
node_group_training -->|"supplies candidates"| node_threshold
node_group_training -->|"supplies models"| node_capacity
node_feature_gate -->|"audits proxies"| node_leakage
node_feature_gate -->|"approves features"| node_pretraining
node_pretraining -->|"transfers encoder"| node_finetuning
node_feature_gate -->|"audits handoff"| node_finetuning
node_pretraining -->|"provides training methods"| node_overfit
node_finetuning -->|"produces model handoff"| node_artifacts
node_artifacts -->|"hash-verified inputs"| node_lineage
node_lineage -->|"verifies lineage"| node_manifest
node_lineage -->|"gates packaging"| node_packaging
node_artifacts -->|"loads model files"| node_runtime
node_runtime -->|"verifies hashes"| node_manifest
node_service -->|"predicts with"| node_runtime
node_client -->|"submits request"| node_service

click node_pipeline "https://github.com/triscravello/running-readiness-ml/blob/main/src/data_pipeline.py"
click node_schema_gate "https://github.com/triscravello/running-readiness-ml/blob/main/src/schema_drift_gate.py"
click node_group_training "https://github.com/triscravello/running-readiness-ml/blob/main/src/train_models.py"
click node_evaluation "https://github.com/triscravello/running-readiness-ml/blob/main/src/evaluate_models.py"
click node_feature_gate "https://github.com/triscravello/running-readiness-ml/blob/main/src/feature_experiment.py"
click node_threshold "https://github.com/triscravello/running-readiness-ml/blob/main/src/threshold_analysis.py"
click node_capacity "https://github.com/triscravello/running-readiness-ml/blob/main/src/capacity_experiment.py"
click node_leakage "https://github.com/triscravello/running-readiness-ml/blob/main/src/leakage_proxy_experiment.py"
click node_pretraining "https://github.com/triscravello/running-readiness-ml/blob/main/src/neural_network_experiment.py"
click node_finetuning "https://github.com/triscravello/running-readiness-ml/blob/main/src/finetune_experiment.py"
click node_overfit "https://github.com/triscravello/running-readiness-ml/blob/main/src/overfit_experiment.py"
click node_lineage "https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_lineage.py"
click node_manifest "https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_manifest.py"
click node_packaging "https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_package.py"
click node_service "https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_service.py"
click node_runtime "https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_runtime.py"
click node_artifacts "https://github.com/triscravello/running-readiness-ml/tree/main/artifacts"

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_pipeline,node_schema_gate,node_feature_gate,node_client toneBlue
class node_group_training,node_evaluation,node_threshold toneAmber
class node_pretraining,node_finetuning toneMint
class node_lineage,node_manifest,node_packaging,node_service,node_runtime,node_artifacts toneRose
class node_capacity,node_leakage,node_overfit,node_raw_source toneIndigo
```

## Components

### Data contracts

- [Data pipeline](https://github.com/triscravello/running-readiness-ml/blob/main/src/data_pipeline.py): `src/data_pipeline.py`
- [Schema drift gate](https://github.com/triscravello/running-readiness-ml/blob/main/src/schema_drift_gate.py): `src/schema_drift_gate.py`
- [Feature gate](https://github.com/triscravello/running-readiness-ml/blob/main/src/feature_experiment.py): `src/feature_experiment.py`

### Classical modeling

- [Group-safe training](https://github.com/triscravello/running-readiness-ml/blob/main/src/train_models.py): `src/train_models.py`
- [Evaluation and lock](https://github.com/triscravello/running-readiness-ml/blob/main/src/evaluate_models.py): `src/evaluate_models.py`
- [Threshold analysis](https://github.com/triscravello/running-readiness-ml/blob/main/src/threshold_analysis.py): `src/threshold_analysis.py`

### Neural modeling

- [Denoising pretraining](https://github.com/triscravello/running-readiness-ml/blob/main/src/neural_network_experiment.py): `src/neural_network_experiment.py`
- [Transfer fine-tuning](https://github.com/triscravello/running-readiness-ml/blob/main/src/finetune_experiment.py): `src/finetune_experiment.py`

### Serving integrity

- [Lineage verification](https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_lineage.py): `src/level7_lineage.py`
- [Serving manifest](https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_manifest.py): `src/level7_manifest.py`
- [Deployment packaging](https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_package.py): `src/level7_package.py`
- [API validation](https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_service.py): `src/level7_service.py`
- [CPU model runtime](https://github.com/triscravello/running-readiness-ml/blob/main/src/level7_runtime.py): `src/level7_runtime.py`
- [Model and handoff artifacts](https://github.com/triscravello/running-readiness-ml/tree/main/artifacts): `artifacts`

### Model experiments

- [Tree capacity study](https://github.com/triscravello/running-readiness-ml/blob/main/src/capacity_experiment.py): `src/capacity_experiment.py`
- [Leakage proxy study](https://github.com/triscravello/running-readiness-ml/blob/main/src/leakage_proxy_experiment.py): `src/leakage_proxy_experiment.py`
- [Overfit study](https://github.com/triscravello/running-readiness-ml/blob/main/src/overfit_experiment.py): `src/overfit_experiment.py`

### Other components

- **Raw data source**
- **Prediction client**

## Connections

- Raw data source → Data pipeline: provides data (evidence: `README.md`)
- Data pipeline → Group-safe training: prepares splits (evidence: `README.md`)
- Data pipeline → Schema drift gate: checks drift (evidence: `src/schema_drift_gate.py`)
- Group-safe training → Evaluation and lock: evaluates models (evidence: `README.md`)
- Evaluation and lock → Feature gate: locks handoff (evidence: `README.md`)
- Group-safe training → Threshold analysis: supplies candidates (evidence: `src/threshold_analysis.py`)
- Group-safe training → Tree capacity study: supplies models (evidence: `src/capacity_experiment.py`)
- Feature gate → Leakage proxy study: audits proxies (evidence: `src/leakage_proxy_experiment.py`)
- Feature gate → Denoising pretraining: approves features (evidence: `README.md`)
- Denoising pretraining → Transfer fine-tuning: transfers encoder (evidence: `src/finetune_experiment.py`)
- Feature gate → Transfer fine-tuning: audits handoff (evidence: `src/finetune_experiment.py`)
- Denoising pretraining → Overfit study: provides training methods (evidence: `src/overfit_experiment.py`)
- Transfer fine-tuning → Model and handoff artifacts: produces model handoff (evidence: `README.md`)
- Model and handoff artifacts → Lineage verification: hash-verified inputs (evidence: `README.md`)
- Lineage verification → Serving manifest: verifies lineage (evidence: `src/level7_manifest.py`)
- Lineage verification → Deployment packaging: gates packaging (evidence: `src/level7_package.py`)
- Model and handoff artifacts → CPU model runtime: loads model files (evidence: `README.md`)
- CPU model runtime → Serving manifest: verifies hashes (evidence: `src/level7_runtime.py`)
- API validation → CPU model runtime: predicts with (evidence: `src/level7_service.py`)
- Prediction client → API validation: submits request (evidence: `README.md`)