# gjeusel/deeproof architecture

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

- Interactive diagram: https://gitdiagram.com/gjeusel/deeproof
- Repository: https://github.com/gjeusel/deeproof

## Overview

DeepRoof is a PyTorch roof-orientation classifier. The main workflow configures a model and image transforms, builds training and validation loaders from labeled data, trains and scores the model, saves the best checkpoint, then loads it to predict the submission examples and write a CSV. A separate downloader retrieves satellite imagery for those examples. The excerpts show the handler owning training, validation, persistence, and prediction calls; unsampled modules and runtime wiring are not inferred.

Main entry points: [`src/deeproof/model_handler.py`](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/model_handler.py) (Workflow handler), [`src/deeproof/main.py`](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/main.py) (Run configuration), [`src/deeproof/dataset.py`](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/dataset.py) (Image dataset), [`src/deeproof/common.py`](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/common.py) (Paths and labels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_downloader["Image downloader<br/>[download_images.py]"]
  node_train_csv["Labeled data<br/>[train.csv]"]
  node_submission_csv["Submission examples"]
  node_images[("Roof images")]
  node_dataset["Image dataset<br/>[dataset.py]"]
end

subgraph group_learning["Model learning"]
  node_handler["Workflow handler<br/>[model_handler.py]"]
  node_resnet["ResNet and ShortNet<br/>[handcraft.py]"]
  node_dpn["Dual Path Network<br/>[dpn.py]"]
  node_losses["Classification metrics<br/>[metrics.py]"]
  node_trainer["Training loop<br/>[train.py]"]
  node_validator["Validation scoring<br/>[validation.py]"]
end

subgraph group_results["Persistence and output"]
  node_model_store[("Model registry<br/>[database_models.py]")]
  node_predictor["Prediction<br/>[prediction.py]"]
  node_common["Paths and labels<br/>[common.py]"]
end

node_runner["Run configuration<br/>[main.py]"]
node_mapbox(("Satellite imagery"))

node_mapbox -->|"serves tiles"| node_downloader
node_downloader -->|"writes images"| node_images
node_runner -->|"configures"| node_handler
node_runner -->|"selects model"| node_resnet
node_runner -->|"imports option"| node_dpn
node_runner -->|"imports loss"| node_losses
node_handler -->|"builds loaders"| node_dataset
node_dataset -->|"reads labels"| node_train_csv
node_dataset -->|"loads images"| node_images
node_handler -->|"calls training"| node_trainer
node_handler -->|"calls validation"| node_validator
node_handler -->|"checks and saves"| node_model_store
node_handler -->|"loads examples"| node_submission_csv
node_handler -->|"calls prediction"| node_predictor
node_handler -->|"writes submission"| node_predictor
node_validator -->|"imports scoring"| node_losses
node_model_store -->|"uses snapshot path"| node_common
node_handler -->|"uses data paths"| node_common
node_runner -->|"sets up logging"| node_common

click node_runner "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/main.py"
click node_downloader "https://github.com/gjeusel/deeproof/blob/master/data/download_images.py"
click node_train_csv "https://github.com/gjeusel/deeproof/blob/master/data/train.csv"
click node_submission_csv "https://github.com/gjeusel/deeproof/blob/master/data/sample_submission.csv"
click node_dataset "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/dataset.py"
click node_handler "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/model_handler.py"
click node_resnet "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/neuro/handcraft.py"
click node_dpn "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/neuro/dpn.py"
click node_losses "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/metrics.py"
click node_trainer "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/train.py"
click node_validator "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/validation.py"
click node_model_store "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/database_models.py"
click node_predictor "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/prediction.py"
click node_common "https://github.com/gjeusel/deeproof/blob/master/src/deeproof/common.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_downloader,node_train_csv,node_submission_csv,node_images,node_dataset toneBlue
class node_handler,node_resnet,node_dpn,node_losses,node_trainer,node_validator toneAmber
class node_model_store,node_predictor,node_common toneMint
class node_runner toneTeal
class node_mapbox toneIndigo
```

## Components

### Data preparation

- [Image downloader](https://github.com/gjeusel/deeproof/blob/master/data/download_images.py): `data/download_images.py`
- [Labeled data](https://github.com/gjeusel/deeproof/blob/master/data/train.csv): `data/train.csv`
- [Submission examples](https://github.com/gjeusel/deeproof/blob/master/data/sample_submission.csv): `data/sample_submission.csv`
- **Roof images**
- [Image dataset](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/dataset.py): `src/deeproof/dataset.py`

### Model learning

- [Workflow handler](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/model_handler.py): `src/deeproof/model_handler.py`
- [ResNet and ShortNet](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/neuro/handcraft.py): `src/deeproof/neuro/handcraft.py`
- [Dual Path Network](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/neuro/dpn.py): `src/deeproof/neuro/dpn.py`
- [Classification metrics](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/metrics.py): `src/deeproof/metrics.py`
- [Training loop](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/train.py): `src/deeproof/train.py`
- [Validation scoring](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/validation.py): `src/deeproof/validation.py`

### Persistence and output

- [Model registry](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/database_models.py): `src/deeproof/database_models.py`
- [Prediction](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/prediction.py): `src/deeproof/prediction.py`
- [Paths and labels](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/common.py): `src/deeproof/common.py`

### Other components

- [Run configuration](https://github.com/gjeusel/deeproof/blob/master/src/deeproof/main.py): `src/deeproof/main.py`
- **Satellite imagery**

## Connections

- Satellite imagery → Image downloader: serves tiles (evidence: `data/download_images.py`)
- Image downloader → Roof images: writes images (evidence: `data/download_images.py`)
- Run configuration → Workflow handler: configures (evidence: `src/deeproof/main.py`)
- Run configuration → ResNet and ShortNet: selects model (evidence: `src/deeproof/main.py`)
- Run configuration → Dual Path Network: imports option (evidence: `src/deeproof/main.py`)
- Run configuration → Classification metrics: imports loss (evidence: `src/deeproof/main.py`)
- Workflow handler → Image dataset: builds loaders (evidence: `src/deeproof/model_handler.py`)
- Image dataset → Labeled data: reads labels (evidence: `src/deeproof/dataset.py`)
- Image dataset → Roof images: loads images (evidence: `src/deeproof/dataset.py`)
- Workflow handler → Training loop: calls training (evidence: `src/deeproof/model_handler.py`)
- Workflow handler → Validation scoring: calls validation (evidence: `src/deeproof/model_handler.py`)
- Workflow handler → Model registry: checks and saves (evidence: `src/deeproof/model_handler.py`)
- Workflow handler → Submission examples: loads examples (evidence: `src/deeproof/model_handler.py`)
- Workflow handler → Prediction: calls prediction (evidence: `src/deeproof/model_handler.py`)
- Workflow handler → Prediction: writes submission (evidence: `src/deeproof/model_handler.py`)
- Validation scoring → Classification metrics: imports scoring (evidence: `src/deeproof/validation.py`)
- Model registry → Paths and labels: uses snapshot path (evidence: `src/deeproof/database_models.py`)
- Workflow handler → Paths and labels: uses data paths (evidence: `src/deeproof/model_handler.py`)
- Run configuration → Paths and labels: sets up logging (evidence: `src/deeproof/main.py`)
