# minesh16/satellite-ground-station-tool architecture

> Architecture diagram of the GitHub repository minesh16/satellite-ground-station-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/minesh16/satellite-ground-station-tool
- Repository: https://github.com/minesh16/satellite-ground-station-tool

## Overview

##### Project Type & Purpose
- TerraLink is a full-stack geospatial analysis platform for multi-factor site‐selection optimization.
- Frontend: React + TypeScript web app with Leaflet maps and Material-UI.
- Backend: Node.js + Express REST API server.
- Database: PostgreSQL + PostGIS spatial engine.
- Auxiliary: Python data‐ingestion scripts that populate the database with external datasets.

##### High-Level Component Breakdown
A. Frontend (frontend/)
- React/TypeScript app
- Components: map view, analysis panels, export panels, dashboards
- API client layer (src/services/api.ts)
- Static assets (public/)
B. Backend API (backend/)
- Express server (server.js → src/app.js)
- Routes (routes/): analysis, advanced, datasets, exports, infrastructure, sites
- Services (services/): business logic for elevation, population, crown land, satellite optimization, exports
- Middleware (middleware/): DB connection, error handling
- Utilities (utils/): spatialAnalysis, raw DB functions
C. Database
- PostgreSQL 14+ with PostGIS
- Tables: mobile_sites, nbn_coverage, candidate_sites (plus others ingested via scripts)
- R-tree indexes, JSONB for score_breakdown
D. External Data & Services
- ELVIS Elevation API
- ABS Demographics
- Crown Land Registry API
- NBN coverage files (shapefiles + DBF)
- Amazon Kuiper orbital model (in satelliteOptimization service)
E. Data Ingestion (scripts/data_ingestion.py)
- Reads CSV/DBF files (mobile sites, NBN coverage)
- Populates PostGIS tables via psycopg2 (or SQLAlchemy)
F. Exports
- PDF generation (exportService)
- GeoJSON / CSV endpoints

##### Relationships & Data Flows
- User interacts with React UI → sends HTTP(s) requests to Express API.
- Express routes delegate to service layer → call external APIs (elevation, population, satellite) or query PostGIS.
- Service results → JSON response → UI renders map layers, charts, tables.
- Export requests travel UI → backend exportService → generate PDF/GeoJSON/CSV → return download link.
- Data ingestion scripts run independently or CI/CD → load/update raw spatial data into PostGIS.

##### Key Architectural Patterns & Design Principles
- Layered architecture: Presentation (React) → API routes → Business services → Data access → Database.
- Separation of concerns: services encapsulate domain logic, middleware for cross-cutting concerns (errors, DB).
- External‐integration layer: wrappers around each external API.
- Caching & parallel processing in services for elevation/population.
- RESTful API design with clear endpoint grouping.

##### Detail & Granularity
- Break out backend into sub-components: routes layer vs. service layer vs. middleware vs. utils.
- Ingestion script’s flow: file system → Python script → PostGIS.
- Export paths: API → exportService → PDF/GeoJSON/CSV outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Tier 1: Client (Browser)"
    ReactApp["React App\n(Leaflet, MUI)"]:::frontend
    Index["index.tsx"]:::frontend
    AppShell["App.tsx"]:::frontend
    APIClient["api.ts\n(API Client)"]:::frontend
    Static["Static Assets\n(public/)"]:::frontend
  end

  subgraph "Tier 2: API Server"
    Server["server.js"]:::backend
    App["app.js"]:::backend
    subgraph "Routes"
      Analysis["analysis.js"]:::backend
      Advanced["advanced.js"]:::backend
      Datasets["datasets.js"]:::backend
      ExportsR["exports.js"]:::backend
      Infrastructure["infrastructure.js"]:::backend
      Sites["sites.js"]:::backend
    end
    subgraph "Middleware"
      DBMW["database.js"]:::backend
      ErrMW["errorHandler.js"]:::backend
    end
    subgraph "Services"
      Elevation["elevationService.js"]:::backend
      Population["populationService.js"]:::backend
      CrownLand["crownLandService.js"]:::backend
      Satellite["satelliteOptimization.js"]:::backend
      ExportS["exportService.js"]:::backend
    end
    subgraph "Utils"
      DBUtils["database.js"]:::backend
      SpatialUtils["spatialAnalysis.js"]:::backend
    end
  end

  subgraph "Tier 3: Database"
    DB["PostgreSQL + PostGIS"]:::database
  end

  subgraph "Tier 4: External Services"
    ELVIS["ELVIS Elevation API"]:::external
    ABS["ABS Demographics API"]:::external
    CrownExt["Crown Land API"]:::external
    NBN["NBN Coverage Files"]:::external
    Amazon["Amazon Kuiper Model"]:::external
  end

  subgraph "Tier 5: ETL Scripts"
    Ingestion["data_ingestion.py"]:::scripts
  end

  Outputs["PDF/GeoJSON/CSV"]:::scripts

  ReactApp -->|"uses"| APIClient
  ReactApp -->|"served from"| Static
  APIClient -->|"HTTPS Requests"| App
  App -->|"routes to"| Analysis
  App -->|"routes to"| Advanced
  App -->|"routes to"| Datasets
  App -->|"routes to"| ExportsR
  App -->|"routes to"| Infrastructure
  App -->|"routes to"| Sites

  Analysis -->|"invokes"| Elevation
  Analysis -->|"invokes"| Population
  Analysis -->|"invokes"| CrownLand
  Analysis -->|"invokes"| Satellite

  Population -->|"queries"| DB
  Elevation -->|"queries"| DB
  CrownLand -->|"queries"| DB
  Satellite -->|"queries"| DB

  ExportS -->|"generates"| Outputs
  ExportsR -->|"calls"| ExportS

  Elevation -->|"calls"| ELVIS
  Population -->|"calls"| ABS
  CrownLand -->|"calls"| CrownExt
  Satellite -->|"calls"| Amazon
  Datasets -->|"reads files"| NBN

  Ingestion -.->|"batch load"| DB

  classDef frontend fill:#ccffcc,stroke:#2f6627,stroke-width:1px
  classDef backend fill:#cde5ff,stroke:#3561a7,stroke-width:1px
  classDef database fill:#ffe0b3,stroke:#b37f00,stroke-width:1px
  classDef external fill:#e0ccff,stroke:#7f3faf,stroke-width:1px
  classDef scripts fill:#f0f0f0,stroke:#888888,stroke-width:1px

  click ReactApp "https://github.com/minesh16/satellite-ground-station-tool/tree/main/frontend/"
  click Index "https://github.com/minesh16/satellite-ground-station-tool/blob/main/frontend/src/index.tsx"
  click AppShell "https://github.com/minesh16/satellite-ground-station-tool/blob/main/frontend/src/App.tsx"
  click APIClient "https://github.com/minesh16/satellite-ground-station-tool/blob/main/frontend/src/services/api.ts"
  click Static "https://github.com/minesh16/satellite-ground-station-tool/tree/main/frontend/public/"
  click Server "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/server.js"
  click App "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/src/app.js"
  click Analysis "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/routes/analysis.js"
  click Advanced "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/routes/advanced.js"
  click Datasets "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/routes/datasets.js"
  click ExportsR "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/routes/exports.js"
  click Infrastructure "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/routes/infrastructure.js"
  click Sites "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/routes/sites.js"
  click DBMW "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/middleware/database.js"
  click ErrMW "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/middleware/errorHandler.js"
  click Elevation "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/services/elevationService.js"
  click Population "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/services/populationService.js"
  click CrownLand "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/services/crownLandService.js"
  click Satellite "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/services/satelliteOptimization.js"
  click ExportS "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/services/exportService.js"
  click DBUtils "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/utils/database.js"
  click SpatialUtils "https://github.com/minesh16/satellite-ground-station-tool/blob/main/backend/utils/spatialAnalysis.js"
  click Ingestion "https://github.com/minesh16/satellite-ground-station-tool/blob/main/scripts/data_ingestion.py"
```
