# tathyaearth/stsa architecture

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

- Interactive diagram: https://gitdiagram.com/tathyaearth/stsa
- Repository: https://github.com/tathyaearth/stsa

## Overview

##### Project type and purpose
- This is a Python-based geospatial analysis tool (a library + CLI + Streamlit web app) for parsing Sentinel-1 TOPS-SPLIT XML metadata and exporting it as shapefiles, JSON, CSV, or interactive webmaps.

##### Top-level components (from file structure)
- app.py            – Streamlit front-end web application
- stsa/             – Core library package
– search.py       – Handles Copernicus Scihub API search & download
– stsa.py         – Defines TopsSplitAnalyzer class (core logic)
– utils.py        – XML parsing, geometry construction, format conversion
- CLI entrypoint    – invoking stsa.py as a script
- setup.py + requirements.txt – packaging & dependencies
- tests/            – pytest suite with sample SAFE/ZIP data

##### Main external dependencies & services
- Copernicus Scihub API (HTTPS)
- Local filesystem (ZIP or .SAFE directories)
- GDAL/Fiona/GeoPandas/Shapely – geospatial I/O & geometry
- Streamlit – for hosting the web app

##### Architectural patterns & design principles
- Layered design:
1. Presentation layer (CLI and Streamlit UI)
2. Application layer (TopsSplitAnalyzer orchestration)
3. Integration layer (search.py for API & file I/O)
4. Utility layer (XML parsing & geo-conversion in utils.py)
- Single-responsibility modules
- Clear separation of I/O (download, file reads) vs. data processing vs. output

##### Essential elements
- Labels: module names, file & API interfaces
- Data formats at I/O boundaries (ZIP, XML, GeoJSON, Shapefile, CSV)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        CLI["CLI (python stsa.py)"]:::ui
        WebUI["Streamlit Web UI (app.py)"]:::ui
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        Analyzer["TopsSplitAnalyzer (stsa/stsa.py)"]:::core
    end

    %% Integration Layer
    subgraph "Integration Layer"
        direction TB
        SearchMod["Search Module (stsa/search.py)"]:::integration
        UtilsMod["Utils Module (stsa/utils.py)"]:::integration
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        API["Copernicus Scihub API"]:::external
        FS["Local Filesystem (.SAFE / .zip)"]:::external
        GeoLibs["GDAL/Fiona/GeoPandas"]:::external
    end

    %% Outputs
    subgraph "Outputs"
        direction TB
        Shapefile["Shapefile"]:::output
        GeoJSON["GeoJSON / CSV"]:::output
        Webmap["Interactive Webmap"]:::output
    end

    %% Packaging & Tests
    subgraph "Repository"
        direction TB
        Setup["setup.py"]:::packaging
        Req["requirements.txt"]:::packaging
        TestSearch["tests/test_search.py"]:::testing
        TestSTSA["tests/test_stsa.py"]:::testing
        TestData["tests/data*/"]:::testing
        CI1[".travis.yml"]:::ci
        CI2["codecov.yml"]:::ci
        CI3[".github/PULL_REQUEST_TEMPLATE.md"]:::ci
    end

    %% Connections
    CLI -->|"invoke load_zip/load_api"| Analyzer
    WebUI -->|"calls Analyzer"| Analyzer
    Analyzer -->|"use search/download"| SearchMod
    Analyzer -->|"parse & convert XML"| UtilsMod
    SearchMod -->|"OData calls / HTTP"| API
    SearchMod -->|"read ZIP/.SAFE"| FS
    Analyzer -->|"write shapefile"| Shapefile
    Analyzer -->|"write GeoJSON/CSV"| GeoJSON
    WebUI -->|"render GeoJSON"| Webmap
    UtilsMod -->|"use lxml & shapely"| GeoLibs
    UtilsMod -->|"read/write files"| FS

    %% Click Events
    click WebUI "https://github.com/tathyaearth/stsa/blob/main/app.py"
    click Analyzer "https://github.com/tathyaearth/stsa/blob/main/stsa/stsa.py"
    click SearchMod "https://github.com/tathyaearth/stsa/blob/main/stsa/search.py"
    click UtilsMod "https://github.com/tathyaearth/stsa/blob/main/stsa/utils.py"
    click Setup "https://github.com/tathyaearth/stsa/blob/main/setup.py"
    click Req "https://github.com/tathyaearth/stsa/blob/main/requirements.txt"
    click TestSearch "https://github.com/tathyaearth/stsa/blob/main/tests/test_search.py"
    click TestSTSA "https://github.com/tathyaearth/stsa/blob/main/tests/test_stsa.py"
    click TestData "https://github.com/tathyaearth/stsa/tree/main/tests/data*/"
    click CI1 "https://github.com/tathyaearth/stsa/blob/main/.travis.yml"
    click CI2 "https://github.com/tathyaearth/stsa/blob/main/codecov.yml"
    click CI3 "https://github.com/tathyaearth/stsa/blob/main/.github/PULL_REQUEST_TEMPLATE.md"

    %% Styles
    classDef ui fill:#D0E7FF,stroke:#0366d6,color:#0366d6
    classDef core fill:#DFFFE0,stroke:#28a745,color:#28a745
    classDef integration fill:#FFF4D6,stroke:#e36209,color:#e36209
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d
    classDef output fill:#ECDCF1,stroke:#6f42c1,color:#6f42c1
    classDef packaging fill:#E8F1F2,stroke:#0052CC,color:#0052CC
    classDef testing fill:#FFEFEF,stroke:#d73a49,color:#d73a49
    classDef ci fill:#FAF5FF,stroke:#8250DF,color:#8250DF
```
