# hzxon/deep-learning architecture

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

- Interactive diagram: https://gitdiagram.com/hzxon/deep-learning
- Repository: https://github.com/hzxon/deep-learning

## Overview

This is a reproducible speech-emotion-recognition research pipeline, with a companion validation workflow. Its main path turns four public corpora into a unified six-class dataset, prepared features and evaluation splits, then trains controlled models and summarizes results across three protocols. The graph also shows the documented pre/post-training gates and research-facing analysis. Some script implementations were not sampled, so their documented roles are represented without inferring internal call sequences beyond the README workflow.

Main entry points: [`scripts/run_experiments.py`](https://github.com/hzxon/deep-learning/blob/main/scripts/run_experiments.py) (Experiment runner), [`src/ser/train.py`](https://github.com/hzxon/deep-learning/blob/main/src/ser/train.py) (Training and evaluation), [`scripts/workflow.py`](https://github.com/hzxon/deep-learning/blob/main/scripts/workflow.py) (Workflow orchestrator), [`src/ser/analysis.py`](https://github.com/hzxon/deep-learning/blob/main/src/ser/analysis.py) (RQ analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Dataset preparation"]
  node_manifest["Unified manifest<br/>[data.py]"]
  node_prepare_manifest["Manifest preparation"]
  node_features["Log-mel features<br/>[features.py]"]
  node_preprocess["Audio preprocessing<br/>[preprocess.py]"]
  node_splits["Evaluation protocols<br/>[splits.py]"]
  node_make_splits["Split generation<br/>[make_splits.py]"]
end

subgraph group_experiment["Experiment execution"]
  node_experiment_runner["Experiment runner<br/>[run_experiments.py]"]
  node_dataset_loader["SER dataset<br/>[data.py]"]
  node_augmentations["Feature augmentation<br/>[features.py]"]
  node_trainer["Training and evaluation<br/>[train.py]"]
  node_models["CNN model variants<br/>[models.py]"]
  node_metrics["Classification metrics<br/>[metrics.py]"]
  node_run_artifacts["Run artifacts"]
end

subgraph group_research["Results and analysis"]
  node_analysis["RQ analysis<br/>[analysis.py]"]
  node_gap_analysis["Gap analysis<br/>[gap_analysis.py]"]
  node_plotting["Research plots<br/>[plotting.py]"]
  node_report["Research report<br/>[make_report.py]"]
  node_results["Research tables"]
end

subgraph group_validation["Validation workflow"]
  node_workflow["Workflow orchestrator<br/>[workflow.py]"]
  node_pre_audit["Pre-training gates"]
  node_post_audit["Post-training audit"]
  node_pipeline_validation["Pipeline validation"]
end

node_researcher(("Researcher"))
node_corpora(("Speech corpora"))

node_corpora -->|"provides audio"| node_prepare_manifest
node_researcher -->|"starts preparation"| node_prepare_manifest
node_prepare_manifest -->|"builds manifest"| node_manifest
node_researcher -->|"starts preprocessing"| node_preprocess
node_preprocess -->|"extracts features"| node_features
node_researcher -->|"chooses seed"| node_make_splits
node_make_splits -->|"builds protocols"| node_splits
node_manifest -->|"supplies samples"| node_preprocess
node_manifest -->|"supplies samples"| node_make_splits
node_researcher -->|"selects experiments"| node_experiment_runner
node_experiment_runner -->|"uses protocols"| node_splits
node_experiment_runner -->|"loads partitions"| node_dataset_loader
node_dataset_loader -->|"reads features"| node_features
node_dataset_loader -->|"augments training"| node_augmentations
node_experiment_runner -->|"runs training"| node_trainer
node_trainer -->|"builds model"| node_models
node_trainer -->|"evaluates predictions"| node_metrics
node_trainer -->|"writes checkpoints and metrics"| node_run_artifacts
node_run_artifacts -->|"supplies run results"| node_gap_analysis
node_gap_analysis -->|"builds RQ tables"| node_analysis
node_analysis -->|"writes result tables"| node_results
node_researcher -->|"requests report"| node_report
node_report -->|"summarizes results"| node_analysis
node_report -->|"generates figures"| node_plotting
node_analysis -->|"provides analysis"| node_results
node_researcher -->|"runs workflow"| node_workflow
node_workflow -->|"runs pre-training gates"| node_pre_audit
node_workflow -->|"runs post-training audit"| node_post_audit
node_workflow -->|"checks pipeline"| node_pipeline_validation

click node_manifest "https://github.com/hzxon/deep-learning/blob/main/src/ser/data.py"
click node_prepare_manifest "https://github.com/hzxon/deep-learning/blob/main/scripts/prepare_manifest.py"
click node_features "https://github.com/hzxon/deep-learning/blob/main/src/ser/features.py"
click node_preprocess "https://github.com/hzxon/deep-learning/blob/main/scripts/preprocess.py"
click node_splits "https://github.com/hzxon/deep-learning/blob/main/src/ser/splits.py"
click node_make_splits "https://github.com/hzxon/deep-learning/blob/main/scripts/make_splits.py"
click node_experiment_runner "https://github.com/hzxon/deep-learning/blob/main/scripts/run_experiments.py"
click node_dataset_loader "https://github.com/hzxon/deep-learning/blob/main/src/ser/data.py"
click node_augmentations "https://github.com/hzxon/deep-learning/blob/main/src/ser/features.py"
click node_trainer "https://github.com/hzxon/deep-learning/blob/main/src/ser/train.py"
click node_models "https://github.com/hzxon/deep-learning/blob/main/src/ser/models.py"
click node_metrics "https://github.com/hzxon/deep-learning/blob/main/src/ser/metrics.py"
click node_analysis "https://github.com/hzxon/deep-learning/blob/main/src/ser/analysis.py"
click node_gap_analysis "https://github.com/hzxon/deep-learning/blob/main/scripts/gap_analysis.py"
click node_plotting "https://github.com/hzxon/deep-learning/blob/main/src/ser/plotting.py"
click node_report "https://github.com/hzxon/deep-learning/blob/main/scripts/make_report.py"
click node_workflow "https://github.com/hzxon/deep-learning/blob/main/scripts/workflow.py"
click node_pre_audit "https://github.com/hzxon/deep-learning/blob/main/scripts/pre_training_audit.py"
click node_post_audit "https://github.com/hzxon/deep-learning/blob/main/scripts/post_training_audit.py"
click node_pipeline_validation "https://github.com/hzxon/deep-learning/blob/main/scripts/validate_pipeline.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_manifest,node_prepare_manifest,node_features,node_preprocess,node_splits,node_make_splits toneBlue
class node_experiment_runner,node_dataset_loader,node_augmentations,node_trainer,node_models,node_metrics,node_run_artifacts toneAmber
class node_analysis,node_gap_analysis,node_plotting,node_report,node_results toneMint
class node_workflow,node_pre_audit,node_post_audit,node_pipeline_validation toneRose
class node_researcher,node_corpora toneIndigo
```

## Components

### Dataset preparation

- [Unified manifest](https://github.com/hzxon/deep-learning/blob/main/src/ser/data.py): `src/ser/data.py`
- [Manifest preparation](https://github.com/hzxon/deep-learning/blob/main/scripts/prepare_manifest.py): `scripts/prepare_manifest.py`
- [Log-mel features](https://github.com/hzxon/deep-learning/blob/main/src/ser/features.py): `src/ser/features.py`
- [Audio preprocessing](https://github.com/hzxon/deep-learning/blob/main/scripts/preprocess.py): `scripts/preprocess.py`
- [Evaluation protocols](https://github.com/hzxon/deep-learning/blob/main/src/ser/splits.py): `src/ser/splits.py`
- [Split generation](https://github.com/hzxon/deep-learning/blob/main/scripts/make_splits.py): `scripts/make_splits.py`

### Experiment execution

- [Experiment runner](https://github.com/hzxon/deep-learning/blob/main/scripts/run_experiments.py): `scripts/run_experiments.py`
- [SER dataset](https://github.com/hzxon/deep-learning/blob/main/src/ser/data.py): `src/ser/data.py`
- [Feature augmentation](https://github.com/hzxon/deep-learning/blob/main/src/ser/features.py): `src/ser/features.py`
- [Training and evaluation](https://github.com/hzxon/deep-learning/blob/main/src/ser/train.py): `src/ser/train.py`
- [CNN model variants](https://github.com/hzxon/deep-learning/blob/main/src/ser/models.py): `src/ser/models.py`
- [Classification metrics](https://github.com/hzxon/deep-learning/blob/main/src/ser/metrics.py): `src/ser/metrics.py`
- **Run artifacts**

### Results and analysis

- [RQ analysis](https://github.com/hzxon/deep-learning/blob/main/src/ser/analysis.py): `src/ser/analysis.py`
- [Gap analysis](https://github.com/hzxon/deep-learning/blob/main/scripts/gap_analysis.py): `scripts/gap_analysis.py`
- [Research plots](https://github.com/hzxon/deep-learning/blob/main/src/ser/plotting.py): `src/ser/plotting.py`
- [Research report](https://github.com/hzxon/deep-learning/blob/main/scripts/make_report.py): `scripts/make_report.py`
- **Research tables**

### Validation workflow

- [Workflow orchestrator](https://github.com/hzxon/deep-learning/blob/main/scripts/workflow.py): `scripts/workflow.py`
- [Pre-training gates](https://github.com/hzxon/deep-learning/blob/main/scripts/pre_training_audit.py): `scripts/pre_training_audit.py`
- [Post-training audit](https://github.com/hzxon/deep-learning/blob/main/scripts/post_training_audit.py): `scripts/post_training_audit.py`
- [Pipeline validation](https://github.com/hzxon/deep-learning/blob/main/scripts/validate_pipeline.py): `scripts/validate_pipeline.py`

### Other components

- **Researcher**
- **Speech corpora**

## Connections

- Speech corpora → Manifest preparation: provides audio
- Researcher → Manifest preparation: starts preparation
- Manifest preparation → Unified manifest: builds manifest
- Researcher → Audio preprocessing: starts preprocessing
- Audio preprocessing → Log-mel features: extracts features
- Researcher → Split generation: chooses seed
- Split generation → Evaluation protocols: builds protocols
- Unified manifest → Audio preprocessing: supplies samples
- Unified manifest → Split generation: supplies samples
- Researcher → Experiment runner: selects experiments
- Experiment runner → Evaluation protocols: uses protocols
- Experiment runner → SER dataset: loads partitions
- SER dataset → Log-mel features: reads features
- SER dataset → Feature augmentation: augments training
- Experiment runner → Training and evaluation: runs training
- Training and evaluation → CNN model variants: builds model
- Training and evaluation → Classification metrics: evaluates predictions
- Training and evaluation → Run artifacts: writes checkpoints and metrics
- Run artifacts → Gap analysis: supplies run results
- Gap analysis → RQ analysis: builds RQ tables
- RQ analysis → Research tables: writes result tables
- Researcher → Research report: requests report
- Research report → RQ analysis: summarizes results
- Research report → Research plots: generates figures
- RQ analysis → Research tables: provides analysis
- Researcher → Workflow orchestrator: runs workflow
- Workflow orchestrator → Pre-training gates: runs pre-training gates
- Workflow orchestrator → Post-training audit: runs post-training audit
- Workflow orchestrator → Pipeline validation: checks pipeline