# mwasifanwar/terracognita architecture

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

- Interactive diagram: https://gitdiagram.com/mwasifanwar/terracognita
- Repository: https://github.com/mwasifanwar/terracognita

## Overview

##### Project type and purpose
- TerraCognita is a machine-learning/data-analysis pipeline for archaeological site prediction. It ingests multi-modal data (satellite imagery + geological/archaeological datasets), trains a fusion model, and runs inference to produce geospatial predictions of potential ancient sites.

##### File structure
- Top-level:
- train_model.py – orchestrates end-to-end training
- predict_sites.py – entry point for running inference
- models/ – serialized model artifacts
- setup.py, requirements.txt – packaging & dependencies
- src/:
- config.py – global configuration, paths, hyperparameters
- data_loader.py – loads/merges various data sources
- satellite_processor.py – satellite imagery preprocessing (e.g., tiling, normalization)
- geological_analyzer.py – feature extraction from geological data
- fusion_model.py – defines the multi-modal ML architecture
- site_predictor.py – wraps model inference logic
- utils/ – geospatial_tools.py (coordinate reprojections, shapefile handling), visualization.py (plot maps & results)
- tests/: unit tests for each core component

##### Key insights from README
- Multi-modal fusion of imagery + geological/archaeological inputs
- Produces spatial predictions of undiscovered ancient sites
- Likely integrates GIS libraries, a deep-learning framework, and visualization tools

##### Main components
a. Data Sources
- Satellite Imagery (e.g., GeoTIFFs)
- Geological Data (e.g., elevation, soil type)
- Archaeological Records (optional shapefiles or CSV)
b. Ingestion & Preprocessing
- SatelliteProcessor
- GeologicalAnalyzer
- DataLoader (merges and aligns datasets)
c. Core ML Pipeline
- FusionModel (multi-modal neural net)
- Training Engine (train_model.py orchestrator)
- Model Registry (models/ directory)
d. Inference & Prediction
- SitePredictor (predict_sites.py entry point)
- Post-processing (thresholding, clustering)
- Visualization (maps, heatmaps)
e. Configuration & Utilities
- Config Manager (config.py)
- GeospatialTools & Visualization utilities

##### Relationships & data flow
- DataLoader ↔ SatelliteProcessor & GeologicalAnalyzer for feature extraction
- Processed features → FusionModel
- FusionModel ← config settings
- Training Engine triggers FusionModel training → Model Registry
- Inference Engine loads trained model → SitePredictor → Output Results
- Visualization module subscribes to output → renders maps

##### Architectural patterns & principles
- Modular pipeline: each stage is a self-contained component
- Separation of concerns: preprocessing, modeling, inference, visualization
- Config-driven: all file paths and hyperparameters in config.py
- Testable units: each module has corresponding tests

##### Technologies & frameworks
- Core language: Python
- GIS libs: GDAL/rasterio, GeoPandas
- ML framework: PyTorch or TensorFlow (implied by fusion_model)
- Visualization: Matplotlib/Seaborn or Folium
- Packaging: setuptools (setup.py)

- Config.py feeding parameters to loaders and models
- Separation between training and inference flows
- Where models are saved/loaded (models/ directory)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        SI["Satellite Imagery"]:::data
        GD["Geological Data"]:::data
        AR["Archaeological Records"]:::data
    end

    %% Ingestion & Preprocessing
    subgraph "Ingestion & Preprocessing"
        DL["DataLoader"]:::processing
        SP["SatelliteProcessor"]:::processing
        GA["GeologicalAnalyzer"]:::processing
    end

    SI --> DL
    GD --> DL
    AR --> DL
    DL --> SP
    DL --> GA

    %% Configuration
    Config["Config Manager"]:::config
    Config --> DL
    Config --> SP
    Config --> GA

    %% Core ML Pipeline
    subgraph "Core ML Pipeline"
        FM["FusionModel"]:::model
        TE["Training Engine"]:::model
        MR["Model Registry"]:::data
    end

    Config --> FM
    TE --> FM
    FM --> MR

    %% Training Entry Point
    TE --> MR

    %% Inference & Prediction
    subgraph "Inference & Prediction"
        PSE["predict_sites.py"]:::io
        SPred["SitePredictor"]:::model
        PP["Post-processing"]:::processing
        Viz["Visualization"]:::io
    end

    MR --> SPred
    PSE --> SPred
    SPred --> PP
    PP --> Viz

    %% Utilities
    subgraph "Utilities"
        GT["GeospatialTools"]:::processing
        VU["Visualization Utils"]:::io
    end

    GT --> SP
    GT --> GA
    VU --> Viz

    %% Packaging & Dependencies
    subgraph "Packaging"
        Req["requirements.txt"]:::config
        Set["setup.py"]:::config
    end

    %% Tests
    subgraph "Tests"
        TDL["test_data_loading.py"]:::test
        TFM["test_fusion_model.py"]:::test
    end

    TDL --> DL
    TFM --> FM

    %% Click Events
    click DL "https://github.com/mwasifanwar/terracognita/blob/main/src/data_loader.py"
    click SP "https://github.com/mwasifanwar/terracognita/blob/main/src/satellite_processor.py"
    click GA "https://github.com/mwasifanwar/terracognita/blob/main/src/geological_analyzer.py"
    click FM "https://github.com/mwasifanwar/terracognita/blob/main/src/fusion_model.py"
    click TE "https://github.com/mwasifanwar/terracognita/blob/main/train_model.py"
    click MR "https://github.com/mwasifanwar/terracognita/tree/main/models/"
    click PSE "https://github.com/mwasifanwar/terracognita/blob/main/predict_sites.py"
    click SPred "https://github.com/mwasifanwar/terracognita/blob/main/src/site_predictor.py"
    click Config "https://github.com/mwasifanwar/terracognita/blob/main/src/config.py"
    click GT "https://github.com/mwasifanwar/terracognita/blob/main/src/utils/geospatial_tools.py"
    click VU "https://github.com/mwasifanwar/terracognita/blob/main/src/utils/visualization.py"
    click Req "https://github.com/mwasifanwar/terracognita/blob/main/requirements.txt"
    click Set "https://github.com/mwasifanwar/terracognita/blob/main/setup.py"
    click TDL "https://github.com/mwasifanwar/terracognita/blob/main/tests/test_data_loading.py"
    click TFM "https://github.com/mwasifanwar/terracognita/blob/main/tests/test_fusion_model.py"

    %% Styles
    classDef data fill:#e0f7fa,stroke:#333,stroke-width:1px
    classDef processing fill:#e8f5e9,stroke:#333,stroke-width:1px
    classDef model fill:#d1c4e9,stroke:#333,stroke-width:1px
    classDef config fill:#fff9c4,stroke:#333,stroke-width:1px
    classDef io fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef test fill:#fce4ec,stroke:#333,stroke-width:1px
```
