How dhi/terracotta works
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.