# matth-info/damaged-building-detector architecture

> Architecture diagram of the GitHub repository matth-info/damaged-building-detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matth-info/damaged-building-detector
- Repository: https://github.com/matth-info/damaged-building-detector

## Overview

##### Project type and purpose
- This is an end-to-end machine-learning (computer-vision) pipeline for “before/after” satellite image analysis, specifically detecting building damage.
- It’s organized with preprocessing, training, inference, and deployment (via Docker/MLOps) phases.

##### File structure
- Top-level directories:
- configs/         ← YAML files for model, logging, etc.
- data/            ← raw and sample imagery datasets
- notebooks/       ← exploratory data analysis & prototyping
- scripts/         ← shell/Python wrappers for training & testing
- src/             ← core Python modules subdivided into:
– datasets/       (data‐loading & augmentation)
– models/         (network definitions)
– losses/         (loss functions)
– metrics/        (evaluation metrics)
– training/       (training loop, augmentations)
– inference/      (prediction API)
– explainability/ (Grad-CAM)
– utils/          (visualization, helpers)
- tests/           ← unit tests for modules
- Dockerfile, docker-compose.yaml, Makefile, .githubignore

##### README for additional insights
- Confirms:
- “Satellite Image Damage Detection Pipeline”
- MLOps with Docker, reproducible workflows
- Steps: preprocess, train, infer

1. Data Storage
– Raw imagery buckets or local folders (data/)
– Sample data (data/data_samples/)
2. Configuration
– configs/config.yaml, logging.yaml
3. Data Preprocessing
– src/datasets/ + preprocessing scripts (scripts/run_*.sh)
4. Model Training
– src/training/ + src/models/, src/losses/, src/metrics/
– Entrypoint: scripts/run_training.sh
5. Model Artifacts
– Checkpoint storage (e.g., volumes or cloud storage)
6. Inference Service
– src/inference/predict.py + functional API
– Dockerized REST or CLI service
7. Explainability Module
– src/explainability/grad_cam.py
8. MLOps & Deployment
– Dockerfile, docker-compose.yaml, Makefile
– CI/CD pipelines (not shown in code but implied)
9. Monitoring & Logging
– logging.yaml → centralized logs

- Data Storage → Data Preprocessing
- Configurations → Preprocessing, Training, Inference
- Preprocessing → Training
- Training → Model Artifacts
- Model Artifacts → Inference
- Inference → Prediction Output
- Explainability module can tap into both Training (for validation) and Inference (for live explanations)
- All components run inside Docker container(s)

c. Architectural patterns and design principles
- Modular separation of concerns: Data → Compute → Serving
- Pipeline orchestration via scripts + Docker (loosely coupled stages)
- Config-driven: single source of truth in YAML
- Reproducibility: notebooks + Docker for dev, scripts for prod
- Test-driven development: tests/ validating each module

d. Key technologies
- Python 3.8+
- PyTorch or TensorFlow (notebooks indicate both)
- Docker & Docker Compose for containerization
- YAML-based configs
- Jupyter notebooks for prototyping
- Standard ML libraries: numpy, pandas, rasterio, albumentations

##### Essential details without overcomplicating
- External dependencies (e.g., cloud storage, if used) only if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container: damaged-building-detector"
        DS["Data Storage"]:::data
        CFG_M["Model Config"]:::config
        CFG_L["Logging Config"]:::config
        DP["Data Preprocessing"]:::compute
        MT["Model Training"]:::compute
        MA["Model Artifacts"]:::artifact
        IS["Inference Service"]:::serve
        EX["Explainability Module"]:::compute
    end
    MO["MLOps & Deployment"]:::deployment
    ML["Monitoring & Logging"]:::monitor
    Output["Prediction Output"]:::output

    DS-->DP
    CFG_M-->DP
    DP-->MT
    CFG_M-->MT
    MT-->MA
    MA-->IS
    CFG_M-->IS
    IS-->Output
    MT---EX
    IS---EX
    DP-->ML
    MT-->ML
    IS-->ML
    CFG_L-->ML
    MO-->DP
    MO-->MT
    MO-->IS

    click DS "https://github.com/matth-info/damaged-building-detector/tree/main/data/"
    click CFG_M "https://github.com/matth-info/damaged-building-detector/blob/main/configs/config.yaml"
    click CFG_L "https://github.com/matth-info/damaged-building-detector/blob/main/configs/logging.yaml"
    click DP "https://github.com/matth-info/damaged-building-detector/tree/main/src/datasets/"
    click MT "https://github.com/matth-info/damaged-building-detector/tree/main/src/training/"
    click IS "https://github.com/matth-info/damaged-building-detector/blob/main/src/inference/predict.py"
    click EX "https://github.com/matth-info/damaged-building-detector/blob/main/src/explainability/grad_cam.py"
    click MO "https://github.com/matth-info/damaged-building-detector/tree/main/Dockerfile"

    classDef data fill:#D6EAF8,stroke:#1F618D,color:#1F618D
    classDef config fill:#D6EAF8,stroke:#1F618D,color:#1F618D
    classDef compute fill:#FAD7A0,stroke:#B9770E,color:#B9770E
    classDef artifact fill:#ABEBC6,stroke:#196F3D,color:#196F3D
    classDef serve fill:#ABEBC6,stroke:#196F3D,color:#196F3D
    classDef deployment fill:#F5B7B1,stroke:#78281F,color:#78281F
    classDef monitor fill:#D2B4DE,stroke:#6C3483,color:#6C3483
    classDef output fill:#F2F3F4,stroke:#99A3A4,color:#99A3A4
```
