# angelperezcastro/ai-image-detection architecture

> Architecture diagram of the GitHub repository angelperezcastro/ai-image-detection, 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/angelperezcastro/ai-image-detection
- Repository: https://github.com/angelperezcastro/ai-image-detection

## Overview

This is a PyTorch pipeline for classifying images as AI-generated or real. Users can combine or sample generator datasets, train a ConvNeXt-Tiny classifier, evaluate it, run single-image predictions, and generate Grad-CAM overlays. Training and evaluation share the dataset loader and model utilities; inference and Grad-CAM independently load checkpoints through the same model utilities. The graph reflects the documented dataset-building capabilities; source for those scripts was sampled, while other unsampled subsystems are represented only where the README and tree support them.

Main entry points: [`src/train.py`](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/train.py) (Training pipeline), [`src/evaluate.py`](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/evaluate.py) (Evaluation pipeline), [`src/gradcam_infer.py`](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/gradcam_infer.py) (Grad-CAM inference), [`src/dataset.py`](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/dataset.py) (Dataset loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_prep["Dataset preparation"]
  node_raw_data[("Generator datasets")]
  node_sample_tool["Sample builder<br/>[create_samples.py]"]
  node_full_tool["Full combiner<br/>[create_full_all.py]"]
  node_sample_data[("Sample dataset")]
end

subgraph group_training["Training and evaluation"]
  node_dataset_loader["Dataset loader<br/>[dataset.py]"]
  node_train["Training pipeline<br/>[train.py]"]
  node_evaluation["Evaluation pipeline<br/>[evaluate.py]"]
  node_metrics["Metrics and figures"]
end

subgraph group_model_core["Model and checkpoints"]
  node_model["ConvNeXt model<br/>[model.py]"]
  node_checkpoints[("Model checkpoints")]
end

subgraph group_prediction["Prediction and explanation"]
  node_inference["Image inference<br/>[infer.py]"]
  node_gradcam["Grad-CAM inference<br/>[gradcam_infer.py]"]
  node_heatmaps["Grad-CAM overlays"]
end

node_user(("User"))
node_image["Input image"]

node_user -->|"runs"| node_sample_tool
node_user -->|"runs"| node_full_tool
node_sample_tool -->|"reads images"| node_raw_data
node_sample_tool -->|"copies samples"| node_sample_data
node_full_tool -->|"reads and writes"| node_raw_data
node_user -->|"starts training"| node_train
node_train -->|"loads batches"| node_dataset_loader
node_dataset_loader -->|"reads images"| node_raw_data
node_dataset_loader -.->|"reads images"| node_sample_data
node_train -->|"builds model"| node_model
node_train -->|"saves checkpoints"| node_checkpoints
node_train -->|"writes metrics"| node_metrics
node_user -->|"starts evaluation"| node_evaluation
node_evaluation -->|"loads validation data"| node_dataset_loader
node_evaluation -->|"builds model"| node_model
node_evaluation -->|"loads checkpoint"| node_checkpoints
node_evaluation -->|"writes reports"| node_metrics
node_user -->|"requests prediction"| node_inference
node_user -->|"requests explanation"| node_gradcam
node_image -->|"provides image"| node_inference
node_image -->|"provides image"| node_gradcam
node_inference -->|"builds model"| node_model
node_inference -->|"loads checkpoint"| node_checkpoints
node_gradcam -->|"builds model"| node_model
node_gradcam -->|"loads checkpoint"| node_checkpoints
node_gradcam -->|"writes overlay"| node_heatmaps

click node_raw_data "https://github.com/angelperezcastro/ai-image-detection/tree/main/data/raw"
click node_sample_tool "https://github.com/angelperezcastro/ai-image-detection/blob/main/scripts/create_samples.py"
click node_full_tool "https://github.com/angelperezcastro/ai-image-detection/blob/main/scripts/create_full_all.py"
click node_sample_data "https://github.com/angelperezcastro/ai-image-detection/tree/main/data/samples"
click node_dataset_loader "https://github.com/angelperezcastro/ai-image-detection/blob/main/src/dataset.py"
click node_train "https://github.com/angelperezcastro/ai-image-detection/blob/main/src/train.py"
click node_evaluation "https://github.com/angelperezcastro/ai-image-detection/blob/main/src/evaluate.py"
click node_model "https://github.com/angelperezcastro/ai-image-detection/blob/main/src/model.py"
click node_checkpoints "https://github.com/angelperezcastro/ai-image-detection/tree/main/models/saved_models"
click node_metrics "https://github.com/angelperezcastro/ai-image-detection/tree/main/results/metrics"
click node_inference "https://github.com/angelperezcastro/ai-image-detection/blob/main/src/infer.py"
click node_gradcam "https://github.com/angelperezcastro/ai-image-detection/blob/main/src/gradcam_infer.py"
click node_heatmaps "https://github.com/angelperezcastro/ai-image-detection/tree/main/results/gradcams"

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_raw_data,node_sample_tool,node_full_tool,node_sample_data,node_user toneBlue
class node_dataset_loader,node_train,node_evaluation,node_metrics toneAmber
class node_model,node_checkpoints toneMint
class node_inference,node_gradcam,node_heatmaps toneRose
class node_image toneIndigo
```

## Components

### Dataset preparation

- [Generator datasets](https://github.com/angelperezcastro/ai-image-detection/tree/main/data/raw): `data/raw`
- [Sample builder](https://github.com/angelperezcastro/ai-image-detection/blob/main/scripts/create_samples.py): `scripts/create_samples.py`
- [Full combiner](https://github.com/angelperezcastro/ai-image-detection/blob/main/scripts/create_full_all.py): `scripts/create_full_all.py`
- [Sample dataset](https://github.com/angelperezcastro/ai-image-detection/tree/main/data/samples): `data/samples`

### Training and evaluation

- [Dataset loader](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/dataset.py): `src/dataset.py`
- [Training pipeline](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/train.py): `src/train.py`
- [Evaluation pipeline](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/evaluate.py): `src/evaluate.py`
- [Metrics and figures](https://github.com/angelperezcastro/ai-image-detection/tree/main/results/metrics): `results/metrics`

### Model and checkpoints

- [ConvNeXt model](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/model.py): `src/model.py`
- [Model checkpoints](https://github.com/angelperezcastro/ai-image-detection/tree/main/models/saved_models): `models/saved_models`

### Prediction and explanation

- [Image inference](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/infer.py): `src/infer.py`
- [Grad-CAM inference](https://github.com/angelperezcastro/ai-image-detection/blob/main/src/gradcam_infer.py): `src/gradcam_infer.py`
- [Grad-CAM overlays](https://github.com/angelperezcastro/ai-image-detection/tree/main/results/gradcams): `results/gradcams`

### Other components

- **User**
- **Input image**

## Connections

- User → Sample builder: runs
- User → Full combiner: runs
- Sample builder → Generator datasets: reads images
- Sample builder → Sample dataset: copies samples
- Full combiner → Generator datasets: reads and writes
- User → Training pipeline: starts training
- Training pipeline → Dataset loader: loads batches
- Dataset loader → Generator datasets: reads images
- Dataset loader → Sample dataset: reads images
- Training pipeline → ConvNeXt model: builds model
- Training pipeline → Model checkpoints: saves checkpoints
- Training pipeline → Metrics and figures: writes metrics
- User → Evaluation pipeline: starts evaluation
- Evaluation pipeline → Dataset loader: loads validation data
- Evaluation pipeline → ConvNeXt model: builds model
- Evaluation pipeline → Model checkpoints: loads checkpoint
- Evaluation pipeline → Metrics and figures: writes reports
- User → Image inference: requests prediction
- User → Grad-CAM inference: requests explanation
- Input image → Image inference: provides image
- Input image → Grad-CAM inference: provides image
- Image inference → ConvNeXt model: builds model
- Image inference → Model checkpoints: loads checkpoint
- Grad-CAM inference → ConvNeXt model: builds model
- Grad-CAM inference → Model checkpoints: loads checkpoint
- Grad-CAM inference → Grad-CAM overlays: writes overlay