# dhi/terracotta architecture

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

- Interactive diagram: https://gitdiagram.com/dhi/terracotta
- Repository: https://github.com/dhi/terracotta

## Overview

##### Main Components
- CLI / Command-line Interface: Terracotta exposes several command-line tools (find these under terracotta/scripts, e.g., ingest.py, optimize_rasters.py, serve.py, connect.py) that allow users to optimize rasters, ingest file patterns into a database, and serve the API.
- API Server: The core server implementation (located in terracotta/server) is a Flask WSGI application that exposes API endpoints. It handles requests related to datasets, colormaps, computation, metadata, etc. This is the service that clients interact with.
- Client Application: Found under terracotta/client, this includes both the React-based web client (with its own configuration, source, package.json, etc.) and the Flask API (client_app.py) for serving the client. It provides the graphical interface that communicates with the API server.
- Data Processing and Ingestion: Under terracotta and terracotta/drivers, the application supports various drivers that handle different file formats (GeoTIFF through geotiff_raster_store.py and relational meta stores for SQLite, MySQL, PostgreSQL, etc.). This component is responsible for parsing and ingesting geo-data.
- Deployment / Containerization: The docker directory (with Dockerfile, Makefile, and entrypoint scripts) encapsulates how the application is containerized. Also, configuration files like zappa_settings are used for serverless deployment. Additionally, GitHub workflows and configuration files support CI/CD processes.
- Testing and Documentation: While not directly part of the runtime architecture, directories like tests and docs provide insight into how the project is maintained, which can be useful when explaining the overall software lifecycle.

##### Interactions and Data Flow
- User Interaction Layer: Users invoke CLI commands (e.g., terracotta optimize-rasters, terracotta ingest, terracotta serve, terracotta connect) and/or interact with the frontend client via a web browser.
- CLI to Ingestion Pipeline: The optimize and ingest commands process input GeoTIFF files, leverage the drivers (from terracotta/drivers) for reading and processing raster data, and save metadata to a database (SQLite or another supported meta store).
- Database / Data Store: The ingested datasets are stored in a database (as seen in the README’s example with greenland.sqlite). This component stores metadata and pointers to raster files.
- API Server Communication: When running the serve command, the Flask-based API (terracotta/server) exposes endpoints that interact with the previously ingested data and colormap modules. It handles HTTP requests from both curl clients and the web client.
- API to Client Web App: The client application (React app in terracotta/client/app) consumes these endpoints to display interactive maps and raster details to the user.
- External Integration and Deployment: Docker and serverless configurations allow the API server (and the client, if required) to be deployed across different environments. Zappa integration facilitates AWS Lambda deployments.

##### Architectural Patterns and Design Principles
- Modular Design: The separation of concerns is evident with distinct submodules handling ingestion, API serving, client presentation, and colormaps.
- Separation of Frontend and Backend: The structure clearly delineates the client (React) and the API server (Flask on Python). This aids in scaling and maintenance.
- Extensible Driver System: The drivers package indicates adherence to the strategy pattern; different data sources can be abstracted behind a uniform API.
- Container and Serverless Friendly: Docker configurations and Zappa settings show attention to modern deployment practices, ensuring scalability.

## Diagram (Mermaid)

```mermaid
graph TD
    %% High Level User Interaction
    User["User"]

    %% Core Components
    CLI_Tools["Terracotta CLI Tools"]
    DataProc["Data Processing & Ingestion"]
    Database["SQLite / Meta Store"]
    API_Server["Flask API Server"]
    Colormap["Colormap Module"]
    React_Client["React Frontend"]
    Flask_Client_API["Flask Client API"]
    Deployment["Deployment (Docker & Zappa)"]
    Testing["Testing & Documentation"]

    %% Data Flow Connections
    User -->|"CLIcommands"| CLI_Tools
    CLI_Tools -->|"ingest/optimize"| DataProc
    DataProc -->|"storeMetadata"| Database
    CLI_Tools -->|"serveCommand"| API_Server
    Database -->|"queryData"| API_Server
    API_Server -->|"uses"| Colormap
    API_Server -->|"providesAPI"| React_Client
    React_Client -->|"AJAXcalls"| API_Server
    API_Server -->|"servesClient"| Flask_Client_API
    Deployment -->|"containerizes"| API_Server
    Deployment -->|"deploys"| React_Client
    Testing --- CLI_Tools
    Testing --- DataProc
    Testing --- API_Server
    Testing --- Deployment

    %% Click Events
    click CLI_Tools "https://github.com/dhi/terracotta/tree/main/terracotta/scripts"
    click DataProc "https://github.com/dhi/terracotta/tree/main/terracotta/drivers"
    click API_Server "https://github.com/dhi/terracotta/tree/main/terracotta/server"
    click Colormap "https://github.com/dhi/terracotta/tree/main/terracotta/cmaps"
    click React_Client "https://github.com/dhi/terracotta/tree/main/terracotta/client/app"
    click Flask_Client_API "https://github.com/dhi/terracotta/blob/main/terracotta/client/client_app.py"
    click Deployment "https://github.com/dhi/terracotta/tree/main/docker"
    click Testing "https://github.com/dhi/terracotta/tree/main/tests"

    %% Styling Classes
    classDef cli fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef processing fill:#ffa07a,stroke:#000,stroke-width:1px;
    classDef database fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef backend fill:#d8bfd8,stroke:#000,stroke-width:1px;
    classDef frontend fill:#87cefa,stroke:#000,stroke-width:1px;
    classDef deployment fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef testing fill:#ffebcd,stroke:#000,stroke-width:1px;
    
    class CLI_Tools cli;
    class DataProc,Colormap processing;
    class Database database;
    class API_Server backend;
    class React_Client,Flask_Client_API frontend;
    class Deployment deployment;
    class Testing testing;
```
