# ada-nuevalos/garbage-classification architecture

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

- Interactive diagram: https://gitdiagram.com/ada-nuevalos/garbage-classification
- Repository: https://github.com/ada-nuevalos/garbage-classification

## Overview

Este repositorio es un proyecto de investigación/experimentación, no una aplicación de producción. Su arquitectura está organizada alrededor de un flujo de trabajo de clasificación de imágenes de residuos, con notebooks como capa principal de orquestación y módulos Python reutilizables para las arquitecturas.

##### Visión general del sistema

El sistema se puede entender en cuatro capas:

1. **Datos**
   - Imágenes originales del dataset TrashNet en `data/raw/`, organizadas por clase:
     cardboard, glass, metal, paper, plastic y trash.
   - Un dataset ya preprocesado y serializado en `data/processed/trashnet_224x224.npz`, que representa la versión normalizada y redimensionada a 224×224.
   - Esta separación marca el límite entre ingestión cruda y entrenamiento experimental.

2. **Experimentos y entrenamiento**
   - Los notebooks en `notebooks/` son el centro de ejecución del proyecto.
   - Hay dos líneas experimentales claramente diferenciadas:
     - **Modelos clásicos / baselines**: EDA, regresión logística y SVM usando características tipo HOG.
     - **Deep Learning**: CNNs entrenadas desde cero y modelos con transfer learning basados en EfficientNetV2.

3. **Definición de modelos**
   - El directorio `models/` contiene las arquitecturas reutilizables en Python.
   - Cada archivo define una variante concreta de modelo:
     - Serie **A**: CNNs desde cero, de menor a mayor capacidad.
     - Serie **D**: variantes de EfficientNetV2 con distintos grados de fine-tuning y cabezas de clasificación.
   - Esto separa la arquitectura del modelo del proceso experimental de los notebooks.

4. **Resultados, documentación y referencias**
   - `reports/` almacena figuras y artefactos generados, como la infografía y la gráfica bias-varianza.
   - `sota_references/` contiene los papers y un índice de bibliografía que sustentan el estado del arte.
   - `code_exmaple/` incluye notebooks externos de referencia, útiles como comparación o inspiración, pero no forman parte del flujo principal del proyecto.

---

##### Flujo de datos principal

El flujo de trabajo del repositorio sigue esta secuencia:

**Imágenes originales en `data/raw/`**
→ **preprocesamiento y normalización**
→ **dataset empaquetado en `data/processed/trashnet_224x224.npz`**
→ **carga desde notebooks**
→ **entrenamiento/evaluación de modelos**
→ **generación de métricas y gráficos en `reports/`**

En paralelo, para las baselines clásicas el flujo alternativo es:

**Imágenes**
→ **extracción de características manuales**
→ **clasificadores como regresión logística o SVM**
→ **evaluación comparativa**

Y para deep learning:

**Imágenes preprocesadas**
→ **CNNs A1–A5 o EfficientNet D0–D4**
→ **entrenamiento con validación**
→ **métricas macro y matriz de confusión**
→ **selección del mejor modelo final**

---

##### Subsistemas principales

###### 1. Subsistema de datos
- `data/raw/` es la fuente primaria.
- `data/processed/trashnet_224x224.npz` es la representación lista para modelado.
- El dataset está desbalanceado, especialmente la clase `trash`, lo que influye en la elección de métricas y en el análisis de resultados.

Este subsistema es importante porque separa el almacenamiento del dato original del formato consumido por entrenamiento.

###### 2. Subsistema de exploración y análisis
- `notebooks/1_EDA_Garbage_Classification.ipynb` se dedica al análisis exploratorio.
- Sirve para inspeccionar clases, distribución, ejemplos visuales y características generales del dataset.
- También ayuda a justificar decisiones posteriores, como el uso de F1 macro frente a accuracy simple.

###### 3. Subsistema de baselines clásicos
- `2.1.Modelo_Lineal_Garbage_Classification.ipynb`
- `2.2.Modelo_ML_Garbage_Classification.ipynb`
- Estos notebooks representan la línea de base tradicional:
  - regresión logística
  - SVM
  - características manuales tipo HOG

Arquitecturalmente, este bloque funciona como referencia mínima para medir si las CNN aportan valor real.

###### 4. Subsistema de CNNs desde cero
- Archivos en `models/` y notebooks asociados:
  - A1_simple_cnn
  - A2_cnn_small
  - A3_cnn_medium
  - A4_cnn_large
  - A5_D5_cnn_frontier
- Esta serie explora el trade-off entre capacidad del modelo y sobreajuste.
- El objetivo es ver cómo escala el rendimiento cuando aumenta la complejidad de la red sin usar preentrenamiento.

###### 5. Subsistema de transfer learning
- Serie `D0` a `D4` basada en EfficientNetV2.
- Los notebooks correspondientes prueban distintas estrategias de fine-tuning:
  - descongelado completo
  - bloques superiores
  - cabeza personalizada
  - pooling global adicional
  - versión mínima descongelada
- Este es el bloque más importante del proyecto, porque termina produciendo el modelo final recomendado: **D4 — EffNet Minimal**.

---

##### Boundarys importantes

###### Boundary de preprocesamiento
El proyecto distingue claramente entre:
- datos crudos del dataset,
- y datos preprocesados 224×224 normalizados.

Esa frontera es importante porque el entrenamiento y la reproducibilidad dependen de la versión procesada del dataset, no de las imágenes originales.

###### Boundary entre experimentación y definición de modelo
Los notebooks controlan el ciclo experimental, pero la lógica de las arquitecturas está separada en `models/`.
Eso permite reutilizar las redes en distintos experimentos sin duplicar código.

###### Boundary entre código propio y referencias externas
- `sota_references/` contiene la base académica.
- `code_exmaple/` contiene ejemplos externos o notebooks de referencia.
Ninguno de los dos parece ser parte del pipeline principal; son soportes para investigación.

---

##### Tecnologías y estilo de arquitectura

Aunque el repositorio no expone una aplicación desplegada, sí se reconoce un stack típico de aprendizaje profundo en Python:
- notebooks para experimentación,
- módulos `.py` para modelos reutilizables,
- procesamiento de imágenes y entrenamiento de clasificadores,
- serialización de datos procesados en `.npz`.

La estructura sugiere un flujo de trabajo orientado a ciencia de datos/ML más que a servicio online:
- no hay API,
- no hay frontend,
- no hay capa de inferencia en producción,
- no hay microservicios ni componentes de despliegue.

---

##### Resultado arquitectónico final

El repositorio culmina en una arquitectura de investigación comparativa con tres familias de modelos:

1. **Baselines clásicos**  
   Regresión logística y SVM sobre características manuales.

2. **CNNs entrenadas desde cero**  
   Serie A, usada para estudiar capacidad, sesgo y varianza.

3. **Transfer learning con EfficientNetV2**  
   Serie D, que ofrece el mejor equilibrio entre rendimiento y coste.

La selección final del proyecto es **D4 — EffNet Minimal**, porque mantiene una métrica alta en test con menor complejidad que el modelo completo.

En resumen, el diagrama arquitectónico correcto para este repositorio debería mostrar:
- una fuente de datos TrashNet,
- una etapa de preprocesamiento a 224×224,
- dos ramas de modelado (clásica y deep learning),
- un conjunto de notebooks que orquestan los experimentos,
- módulos de arquitecturas compartidas,
- y una capa de artefactos/resultados/documentación.

Main entry points: [`data/processed/trashnet_224x224.npz`](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/data/processed/trashnet_224x224.npz) (224x224 NPZ), [`scr/utils.py`](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/scr/utils.py) (Utilities), [`notebooks/D4_effnet_minimal.ipynb`](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/D4_effnet_minimal.ipynb) (D4 run), [`models/A1_simple_cnn.py`](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/models/A1_simple_cnn.py) (CNN series)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Data"
  raw_trashnet[("TrashNet raw<br/>image dataset")]
  processed_npz[("224x224 NPZ<br/>processed dataset")]
end

subgraph "Experiments"
  eda_nb["EDA notebook<br/>exploration notebook"]
  linear_nb["Linear baseline<br/>classical ML notebook"]
  ml_nb["HOG + SVM<br/>classical ML notebook"]
  simple_nn_nb["Simple NN<br/>deep learning notebook"]
  cnn_small_nb["A2 run<br/>cnn experiment"]
  cnn_medium_nb["A3 run<br/>cnn experiment"]
  cnn_large_nb["A4 run<br/>cnn experiment"]
  cnn_frontier_nb["A5 run<br/>cnn experiment"]
  effnet_full_nb["D0 run<br/>transfer learning notebook"]
  effnet_min_nb["D4 run<br/>transfer learning notebook"]
end

subgraph "Model defs"
  cnn_models["CNN series<br/>model family<br/>[A1_simple_cnn.py]"]
  effnet_models["EffNet series<br/>model family<br/>[D0_effnet_full.py]"]
  utils_py["Utilities<br/>helpers<br/>[utils.py]"]
end

subgraph "References"
  reports_dir["Reports<br/>artifacts"]
  sota_refs["SOTA refs<br/>literature"]
  example_nb["Examples<br/>external notebooks"]
  readme["README<br/>project guide<br/>[README.md]"]
end

raw_trashnet -->|"preprocess"| processed_npz
processed_npz -->|"inspect"| eda_nb
processed_npz -->|"features"| linear_nb
processed_npz -->|"features"| ml_nb
processed_npz -->|"train"| simple_nn_nb
processed_npz -->|"train"| cnn_small_nb
processed_npz -->|"train"| cnn_medium_nb
processed_npz -->|"train"| cnn_large_nb
processed_npz -->|"train"| cnn_frontier_nb
processed_npz -->|"fine-tune"| effnet_full_nb
processed_npz -->|"fine-tune"| effnet_min_nb
cnn_models -->|"defines"| cnn_small_nb
cnn_models -->|"defines"| cnn_medium_nb
cnn_models -->|"defines"| cnn_large_nb
cnn_models -->|"defines"| cnn_frontier_nb
effnet_models -->|"defines"| effnet_full_nb
effnet_models -->|"defines"| effnet_min_nb
utils_py -->|"supports"| eda_nb
utils_py -->|"supports"| linear_nb
utils_py -->|"supports"| ml_nb
utils_py -->|"supports"| simple_nn_nb
utils_py -->|"supports"| cnn_small_nb
utils_py -->|"supports"| effnet_min_nb
effnet_min_nb -->|"outputs"| reports_dir
cnn_frontier_nb -->|"outputs"| reports_dir
eda_nb -.->|"context"| sota_refs
effnet_min_nb -.->|"context"| sota_refs
readme -.->|"documents"| eda_nb
readme -.->|"documents"| effnet_min_nb
example_nb -.->|"inspires"| cnn_small_nb

click raw_trashnet "https://github.com/ada-nuevalos/garbage-classification/tree/main/data/raw"
click processed_npz "https://github.com/ada-nuevalos/garbage-classification/blob/main/data/processed/trashnet_224x224.npz"
click eda_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/1_EDA_Garbage_Classification.ipynb"
click linear_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/2.1.Modelo_Lineal_Garbage_Classification.ipynb"
click ml_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/2.2.Modelo_ML_Garbage_Classification.ipynb"
click simple_nn_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/2.3.Modelo_Red_Neuronal_Simple.ipynb"
click cnn_small_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/3.A2_cnn_small.ipynb"
click cnn_medium_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/3.A3_cnn_medium.ipynb"
click cnn_large_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/3.A4_cnn_large.ipynb"
click cnn_frontier_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/3.A5_cnn_frontier.ipynb"
click effnet_full_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/D0_effnet_full.ipynb"
click effnet_min_nb "https://github.com/ada-nuevalos/garbage-classification/blob/main/notebooks/D4_effnet_minimal.ipynb"
click cnn_models "https://github.com/ada-nuevalos/garbage-classification/blob/main/models/A1_simple_cnn.py"
click effnet_models "https://github.com/ada-nuevalos/garbage-classification/blob/main/models/D0_effnet_full.py"
click utils_py "https://github.com/ada-nuevalos/garbage-classification/blob/main/scr/utils.py"
click reports_dir "https://github.com/ada-nuevalos/garbage-classification/tree/main/reports"
click sota_refs "https://github.com/ada-nuevalos/garbage-classification/tree/main/sota_references"
click example_nb "https://github.com/ada-nuevalos/garbage-classification/tree/main/code_exmaple"
click readme "https://github.com/ada-nuevalos/garbage-classification/blob/main/README.md"

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 raw_trashnet,processed_npz toneBlue
class eda_nb,linear_nb,ml_nb,simple_nn_nb,cnn_small_nb,cnn_medium_nb,cnn_large_nb,cnn_frontier_nb,effnet_full_nb,effnet_min_nb toneAmber
class cnn_models,effnet_models,utils_py toneMint
class reports_dir,sota_refs,example_nb,readme toneRose
```

## Components

### Data

Raw images and processed dataset artifacts.

- [TrashNet raw](https://github.com/ada-nuevalos/garbage-classification/tree/HEAD/data/raw): image dataset · Original class-organized images under data/raw/. · `data/raw`
- [224x224 NPZ](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/data/processed/trashnet_224x224.npz): processed dataset · Serialized preprocessed dataset used by the experiments. · `data/processed/trashnet_224x224.npz`

### Experiments

Notebooks that orchestrate exploration, baselines, and training runs.

- [EDA notebook](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/1_EDA_Garbage_Classification.ipynb): exploration notebook · Dataset inspection, class balance analysis, and visual exploration. · `notebooks/1_EDA_Garbage_Classification.ipynb`
- [Linear baseline](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/2.1.Modelo_Lineal_Garbage_Classification.ipynb): classical ML notebook · Regression-logistic baseline over engineered features. · `notebooks/2.1.Modelo_Lineal_Garbage_Classification.ipynb`
- [HOG + SVM](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/2.2.Modelo_ML_Garbage_Classification.ipynb): classical ML notebook · Traditional feature-extraction and SVM experiment. · `notebooks/2.2.Modelo_ML_Garbage_Classification.ipynb`
- [Simple NN](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/2.3.Modelo_Red_Neuronal_Simple.ipynb): deep learning notebook · Early neural baseline bridging classical ML and CNN experiments. · `notebooks/2.3.Modelo_Red_Neuronal_Simple.ipynb`
- [A2 run](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/3.A2_cnn_small.ipynb): cnn experiment · Notebook for the small CNN variant. · `notebooks/3.A2_cnn_small.ipynb`
- [A3 run](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/3.A3_cnn_medium.ipynb): cnn experiment · Notebook for the medium CNN variant. · `notebooks/3.A3_cnn_medium.ipynb`
- [A4 run](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/3.A4_cnn_large.ipynb): cnn experiment · Notebook for the large CNN variant. · `notebooks/3.A4_cnn_large.ipynb`
- [A5 run](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/3.A5_cnn_frontier.ipynb): cnn experiment · Notebook for the frontier CNN variant. · `notebooks/3.A5_cnn_frontier.ipynb`
- [D0 run](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/D0_effnet_full.ipynb): transfer learning notebook · Full fine-tuning EfficientNetV2 experiment. · `notebooks/D0_effnet_full.ipynb`
- [D4 run](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/notebooks/D4_effnet_minimal.ipynb): transfer learning notebook · Minimal fine-tuning EfficientNetV2 experiment that becomes the recommended model. · `notebooks/D4_effnet_minimal.ipynb`

### Model defs

Reusable Python modules that define CNN and EfficientNet variants.

- [CNN series](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/models/A1_simple_cnn.py): model family · Reusable CNN definitions from A1 through A5. · `models/A1_simple_cnn.py`
- [EffNet series](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/models/D0_effnet_full.py): model family · Reusable EfficientNetV2 variants from D0 through D4. · `models/D0_effnet_full.py`
- [Utilities](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/scr/utils.py): helpers · Shared utility helpers used by notebooks and model code. · `scr/utils.py`

### References

Supporting literature, examples, and generated reports.

- [Reports](https://github.com/ada-nuevalos/garbage-classification/tree/HEAD/reports): artifacts · Generated figures and analysis outputs. · `reports`
- [SOTA refs](https://github.com/ada-nuevalos/garbage-classification/tree/HEAD/sota_references): literature · Papers and bibliography supporting the experimental comparison. · `sota_references`
- [Examples](https://github.com/ada-nuevalos/garbage-classification/tree/HEAD/code_exmaple): external notebooks · Reference notebooks kept for inspiration and comparison. · `code_exmaple`
- [README](https://github.com/ada-nuevalos/garbage-classification/blob/HEAD/README.md): project guide · Top-level project overview and usage notes. · `README.md`

## Connections

- TrashNet raw → 224x224 NPZ: preprocess · Raw images are normalized and resized into the serialized dataset.
- 224x224 NPZ → EDA notebook: inspect · EDA reads the processed dataset to understand classes and balance.
- 224x224 NPZ → Linear baseline: features · Classical baselines consume image data through engineered features.
- 224x224 NPZ → HOG + SVM: features · HOG-style feature extraction feeds the SVM baseline.
- 224x224 NPZ → Simple NN: train · The simple neural baseline trains from the prepared dataset.
- 224x224 NPZ → A2 run: train · CNN experiments use the prepared dataset for training and validation.
- 224x224 NPZ → A3 run: train · CNN experiments use the prepared dataset for training and validation.
- 224x224 NPZ → A4 run: train · CNN experiments use the prepared dataset for training and validation.
- 224x224 NPZ → A5 run: train · CNN experiments use the prepared dataset for training and validation.
- 224x224 NPZ → D0 run: fine-tune · Transfer-learning experiments consume the prepared dataset.
- 224x224 NPZ → D4 run: fine-tune · Minimal fine-tuning experiment consumes the prepared dataset.
- CNN series → A2 run: defines · Notebook runs use the shared CNN architecture implementations.
- CNN series → A3 run: defines · Notebook runs use the shared CNN architecture implementations.
- CNN series → A4 run: defines · Notebook runs use the shared CNN architecture implementations.
- CNN series → A5 run: defines · Notebook runs use the shared CNN architecture implementations.
- EffNet series → D0 run: defines · Notebook runs use the shared EfficientNetV2 variants.
- EffNet series → D4 run: defines · Notebook runs use the shared EfficientNetV2 variants.
- Utilities → EDA notebook: supports · Shared utilities support data handling and plotting.
- Utilities → Linear baseline: supports · Shared utilities support feature extraction and evaluation.
- Utilities → HOG + SVM: supports · Shared utilities support feature extraction and evaluation.
- Utilities → Simple NN: supports · Shared utilities support training workflow helpers.
- Utilities → A2 run: supports · Shared utilities support training workflow helpers.
- Utilities → D4 run: supports · Shared utilities support training workflow helpers.
- D4 run → Reports: outputs · Best-performing transfer-learning run produces the main artifacts and figures.
- A5 run → Reports: outputs · CNN experiments contribute comparative metrics and plots.
- EDA notebook → SOTA refs: context · Exploration and analysis are informed by the bibliography.
- D4 run → SOTA refs: context · Transfer-learning choices are grounded in the referenced papers.
- README → EDA notebook: documents · Repository documentation points to the experimental workflow.
- README → D4 run: documents · Repository documentation summarizes the final recommended model.
- Examples → A2 run: inspires · External examples provide reference implementations and comparisons.
