# reogento/puchinaai architecture

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

- Interactive diagram: https://gitdiagram.com/reogento/puchinaai
- Repository: https://github.com/reogento/puchinaai

## Overview

PuchinaAI is a research and operational system for forecasting road frost-heave and deformation risk at 30-, 60-, and 90-day horizons. Its research workflow loads or generates telemetry, derives physical freeze–thaw features, builds chronological horizon-specific datasets, trains models, and evaluates risk and alarm thresholds. Engineers can also run a separate CLI inference workflow using saved models, with batch predictions and operational recommendations. The graph follows documented and indexed relationships; some internal links are omitted where excerpts do not establish the caller or data flow.

Main entry points: [`main.py`](https://github.com/reogento/puchinaai/blob/main/main.py) (Research CLI), [`predict.py`](https://github.com/reogento/puchinaai/blob/main/predict.py) (Inference CLI), [`src/data_loader.py`](https://github.com/reogento/puchinaai/blob/main/src/data_loader.py) (Dataset loader), [`src/dataset_builder.py`](https://github.com/reogento/puchinaai/blob/main/src/dataset_builder.py) (Horizon datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Telemetry and labeling"]
  node_generator["Synthetic telemetry<br/>[data_generator.py]"]
  node_loader["Dataset loader<br/>[data_loader.py]"]
  node_labeler["Defect labeling<br/>[label_dataset.py]"]
end

subgraph group_research["Research pipeline"]
  node_research_cli["Research CLI<br/>[main.py]"]
  node_features["Physical features<br/>[features.py]"]
  node_builder["Horizon datasets<br/>[dataset_builder.py]"]
end

subgraph group_models["Risk models"]
  node_baselines["RF and XGBoost<br/>[baselines.py]"]
  node_hybrid["Hybrid neural model<br/>[hybrid_nn.py]"]
end

subgraph group_operations["Operational inference"]
  node_inference_cli["Inference CLI<br/>[predict.py]"]
  node_saved_models["Saved models"]
  node_results["Prediction and research outputs"]
end

subgraph group_analysis["Evaluation and interpretation"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
  node_interpretation["SHAP interpretation<br/>[interpretation.py]"]
  node_threshold["Alarm thresholds"]
  node_plausibility["Physical plausibility checks"]
end

node_engineer(("Road engineer"))

node_engineer -->|"runs research"| node_research_cli
node_engineer -->|"requests forecast"| node_inference_cli
node_research_cli -->|"loads data"| node_loader
node_loader -->|"labels telemetry"| node_labeler
node_loader -->|"generates fallback"| node_generator
node_research_cli -->|"builds datasets"| node_builder
node_builder -->|"computes features"| node_features
node_research_cli -->|"trains baselines"| node_baselines
node_research_cli -->|"trains hybrid"| node_hybrid
node_research_cli -->|"evaluates predictions"| node_evaluation
node_research_cli -->|"interprets models"| node_interpretation
node_research_cli -->|"analyzes alarms"| node_threshold
node_research_cli -.->|"checks plausibility"| node_plausibility
node_inference_cli -->|"computes features"| node_features
node_inference_cli -->|"loads model"| node_saved_models
node_inference_cli -->|"exports forecasts"| node_results
node_research_cli -->|"writes metrics"| node_results

click node_research_cli "https://github.com/reogento/puchinaai/blob/main/main.py"
click node_inference_cli "https://github.com/reogento/puchinaai/blob/main/predict.py"
click node_generator "https://github.com/reogento/puchinaai/blob/main/src/data_generator.py"
click node_loader "https://github.com/reogento/puchinaai/blob/main/src/data_loader.py"
click node_labeler "https://github.com/reogento/puchinaai/blob/main/src/label_dataset.py"
click node_features "https://github.com/reogento/puchinaai/blob/main/src/features.py"
click node_builder "https://github.com/reogento/puchinaai/blob/main/src/dataset_builder.py"
click node_baselines "https://github.com/reogento/puchinaai/blob/main/src/models/baselines.py"
click node_hybrid "https://github.com/reogento/puchinaai/blob/main/src/models/hybrid_nn.py"
click node_saved_models "https://github.com/reogento/puchinaai/tree/main/saved_models"
click node_evaluation "https://github.com/reogento/puchinaai/blob/main/src/evaluate.py"
click node_interpretation "https://github.com/reogento/puchinaai/blob/main/src/interpretation.py"
click node_threshold "https://github.com/reogento/puchinaai/blob/main/src/threshold_analysis.py"
click node_plausibility "https://github.com/reogento/puchinaai/blob/main/run_plausibility_checks.py"
click node_results "https://github.com/reogento/puchinaai/tree/main/results"

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_generator,node_loader,node_labeler toneBlue
class node_research_cli,node_features,node_builder toneAmber
class node_baselines,node_hybrid toneMint
class node_inference_cli,node_saved_models,node_results toneRose
class node_evaluation,node_interpretation,node_threshold,node_plausibility,node_engineer toneIndigo
```

## Components

### Telemetry and labeling

- [Synthetic telemetry](https://github.com/reogento/puchinaai/blob/main/src/data_generator.py): `src/data_generator.py`
- [Dataset loader](https://github.com/reogento/puchinaai/blob/main/src/data_loader.py): `src/data_loader.py`
- [Defect labeling](https://github.com/reogento/puchinaai/blob/main/src/label_dataset.py): `src/label_dataset.py`

### Research pipeline

- [Research CLI](https://github.com/reogento/puchinaai/blob/main/main.py): `main.py`
- [Physical features](https://github.com/reogento/puchinaai/blob/main/src/features.py): `src/features.py`
- [Horizon datasets](https://github.com/reogento/puchinaai/blob/main/src/dataset_builder.py): `src/dataset_builder.py`

### Risk models

- [RF and XGBoost](https://github.com/reogento/puchinaai/blob/main/src/models/baselines.py): `src/models/baselines.py`
- [Hybrid neural model](https://github.com/reogento/puchinaai/blob/main/src/models/hybrid_nn.py): `src/models/hybrid_nn.py`

### Operational inference

- [Inference CLI](https://github.com/reogento/puchinaai/blob/main/predict.py): `predict.py`
- [Saved models](https://github.com/reogento/puchinaai/tree/main/saved_models): `saved_models`
- [Prediction and research outputs](https://github.com/reogento/puchinaai/tree/main/results): `results`

### Evaluation and interpretation

- [Model evaluation](https://github.com/reogento/puchinaai/blob/main/src/evaluate.py): `src/evaluate.py`
- [SHAP interpretation](https://github.com/reogento/puchinaai/blob/main/src/interpretation.py): `src/interpretation.py`
- [Alarm thresholds](https://github.com/reogento/puchinaai/blob/main/src/threshold_analysis.py): `src/threshold_analysis.py`
- [Physical plausibility checks](https://github.com/reogento/puchinaai/blob/main/run_plausibility_checks.py): `run_plausibility_checks.py`

### Other components

- **Road engineer**

## Connections

- Road engineer → Research CLI: runs research (evidence: `README.md`)
- Road engineer → Inference CLI: requests forecast (evidence: `README.md`)
- Research CLI → Dataset loader: loads data (evidence: `main.py`)
- Dataset loader → Defect labeling: labels telemetry (evidence: `src/data_loader.py`)
- Dataset loader → Synthetic telemetry: generates fallback (evidence: `src/data_loader.py`)
- Research CLI → Horizon datasets: builds datasets (evidence: `main.py`)
- Horizon datasets → Physical features: computes features (evidence: `src/dataset_builder.py`)
- Research CLI → RF and XGBoost: trains baselines (evidence: `main.py`)
- Research CLI → Hybrid neural model: trains hybrid (evidence: `main.py`)
- Research CLI → Model evaluation: evaluates predictions (evidence: `main.py`)
- Research CLI → SHAP interpretation: interprets models (evidence: `main.py`)
- Research CLI → Alarm thresholds: analyzes alarms (evidence: `main.py`)
- Research CLI → Physical plausibility checks: checks plausibility
- Inference CLI → Physical features: computes features (evidence: `predict.py`)
- Inference CLI → Saved models: loads model (evidence: `predict.py`)
- Inference CLI → Prediction and research outputs: exports forecasts (evidence: `README.md`)
- Research CLI → Prediction and research outputs: writes metrics (evidence: `main.py`)