# tavisshore/spagbol architecture

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

- Interactive diagram: https://gitdiagram.com/tavisshore/spagbol
- Repository: https://github.com/tavisshore/spagbol

## Overview

##### Project Type and Purpose
- This is a research-oriented ML pipeline for Cross-View Geo-Localisation (SpaGBOL). It ingests raw map data and imagery, constructs spatial graph datasets, trains a GNN model, and produces evaluation metrics.

##### File Structure Analysis
- Top level
- run.py – CLI entry point that ties together configuration, data preparation, model training, and evaluation.
- config/ – Configuration loader (config.py) and default settings (standard.yaml).
- cache/ – Local JSON cache of downloaded graph and image metadata.
- requirements.yaml – Conda environment spec.
- src/utils/ – Data-preparation modules:
- data.py – Orchestrates dataset download, graph construction, and “walk” generation.
- image_downloading.py & satellite.py – Download panoramic street-view and satellite tiles.
- guillame.py – Extracts road network graphs (via OSM).
- write_db.py – Writes processed data into persistent storage.
- metric.py – Computes evaluation metrics.
- src/models/
- model.py – Defines the GNN architecture, loss functions, and forward/training logic.

##### Key Architectural Patterns
- Modular pipeline: clear separation between configuration, data ingestion, graph construction, model definition, and evaluation.
- Data-centric design: cache layer for downloaded assets, write_db for persistence.
- Batch ML training workflow: run.py orchestrates end-to-end steps.

##### Main Components
a. External Data Sources
- OpenStreetMap (via Guillame)
- Google Street View API (panoramic images)
- Satellite imagery provider
b. Data Pipeline
1. Config Loader (config/config.py + standard.yaml)
2. Graph Constructor (src/utils/guillame.py → constructs node/edge graph)
3. Image Downloaders (image_downloading.py & satellite.py)
4. Cache Store (cache/*.json)
5. Data Writer (src/utils/write_db.py → local file system or DB)
6. Walk Generator (src/utils/data.py → exhaustive/random DFS walks)
c. Model Training
- Model Definition (src/models/model.py)
- Training Loop (invoked by run.py)
- Metrics Computation (src/utils/metric.py)
d. Orchestration
- run.py – CLI front end, argument parsing, pipeline coordination

##### Relationships and Data Flow
- Graph Constructor & Downloaders → Cache Store → Write_DB → Dataset Store
- Dataset Store → Walk Generator → Training Data Loader
- Training Data Loader → Model → Metrics → Output Reports

##### Final Checklist
- Components: Config Loader, Graph Builder, Image Downloaders, Cache, DB, Walk Generator, Model, Metrics.
- External APIs: OSM/Guillame, Street View, Satellite.
- Data Stores: cache/*.json, processed dataset folder or DB.
- Orchestration: run.py as the central coordinator.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Systems"
        OSM["OpenStreetMap API"]:::external
        StreetView["Google Street View API"]:::external
        SatelliteAPI["Satellite Imagery Provider"]:::external
    end

    subgraph "Configuration"
        ConfigLoader["Config Loader\n(config/config.py & standard.yaml)"]:::config
    end

    subgraph "Data Preparation"
        GraphBuilder["Graph Constructor\n(src/utils/guillame.py)"]:::dataprep
        StreetDownloader["Street View Downloader\n(src/utils/image_downloading.py)"]:::dataprep
        SatDownloader["Satellite Downloader\n(src/utils/satellite.py)"]:::dataprep
        CacheStore["Cache Store\n(cache/*.json)"]:::store
        DataWriter["Data Writer\n(src/utils/write_db.py)"]:::dataprep
        WalkGen["Walk Generator\n(src/utils/data.py)"]:::dataprep
        DatasetStore["Dataset Store\n(processed dataset)"]:::store
    end

    subgraph "Model Training & Evaluation"
        ModelDef["Model Definition & Training\n(src/models/model.py)"]:::model
        MetricsComp["Metrics Computation\n(src/utils/metric.py)"]:::model
    end

    Run["run.py\n(Orchestration)"]:::orchestration

    %% Data Flow
    ConfigLoader --> GraphBuilder
    ConfigLoader --> StreetDownloader
    ConfigLoader --> SatDownloader

    OSM --> GraphBuilder
    StreetView --> StreetDownloader
    SatelliteAPI --> SatDownloader

    GraphBuilder --> CacheStore
    StreetDownloader --> CacheStore
    SatDownloader --> CacheStore

    CacheStore --> DataWriter
    DataWriter --> DatasetStore

    DatasetStore --> WalkGen
    WalkGen --> ModelDef

    ModelDef --> MetricsComp

    %% Orchestration
    Run --> ConfigLoader
    Run --> GraphBuilder
    Run --> StreetDownloader
    Run --> SatDownloader
    Run --> DataWriter
    Run --> WalkGen
    Run --> ModelDef
    Run --> MetricsComp

    %% Click Events
    click ConfigLoader "https://github.com/tavisshore/spagbol/blob/main/config/config.py"
    click GraphBuilder "https://github.com/tavisshore/spagbol/blob/main/src/utils/guillame.py"
    click StreetDownloader "https://github.com/tavisshore/spagbol/blob/main/src/utils/image_downloading.py"
    click SatDownloader "https://github.com/tavisshore/spagbol/blob/main/src/utils/satellite.py"
    click CacheStore "https://github.com/tavisshore/spagbol/tree/main/cache/"
    click DataWriter "https://github.com/tavisshore/spagbol/blob/main/src/utils/write_db.py"
    click WalkGen "https://github.com/tavisshore/spagbol/blob/main/src/utils/data.py"
    click ModelDef "https://github.com/tavisshore/spagbol/blob/main/src/models/model.py"
    click MetricsComp "https://github.com/tavisshore/spagbol/blob/main/src/utils/metric.py"
    click Run "https://github.com/tavisshore/spagbol/blob/main/run.py"

    %% Styles
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef config fill:#ccf,stroke:#333,stroke-width:1px
    classDef dataprep fill:#9cf,stroke:#333,stroke-width:1px
    classDef model fill:#bfb,stroke:#333,stroke-width:1px
    classDef orchestration fill:#fcf,stroke:#333,stroke-width:1px
    classDef store fill:#fff2a8,stroke:#333,stroke-width:1px
```
