Containerized Application with Database and Geospatial Services Diagram

What this diagram shows

This diagram shows a containerised application architecture where multiple services run in isolated containers and communicate through defined interfaces. Data flows from client requests through an API service to a geospatial-aware database, with a separate tile server handling map imagery. The architecture separates concerns: the application container handles business logic, the PostGIS-enabled database manages spatial data, and the tile server (often using technologies like Mapnik or GeoServer) generates and caches raster map tiles for efficient client rendering. Network requests move between containers via configured ports, whilst persistent data lives in mounted volumes.

Key components

• API Service Container — Receives HTTP requests from clients and executes application logic, forwarding spatial queries to the database.
• PostGIS Database Container — Stores and indexes geospatial vector data using PostgreSQL extensions, handling spatial queries like distance calculations and polygon intersections.
• Tile Server Container — Renders vector or raster map tiles in standard web formats (PNG, WebP) from source data, responding to requests at specific zoom levels and coordinates.
• Volume Mounts — Persist database files and tile cache between container restarts, preventing data loss when containers are destroyed.
• Network Bridge — Connects containers using defined internal DNS names and port mappings, allowing the API to reach the database and tile server.
• Client Application — Web or mobile frontend that requests both API data (JSON) and map tiles (raster images) to display location-based features.

When to use it

Use this template when building location-aware services that need to separate concerns: when you want application code isolated from databases for independent scaling, when you require both vector spatial analysis and raster tile rendering, or when deploying to container orchestration platforms like Kubernetes where each service scales independently. It suits systems handling real estate lookups, logistics tracking, environmental monitoring, or any platform where maps and spatial queries both matter.

Common mistakes

• Omitting volume mounts and treating containers as stateless, causing the database to lose all data when the container is replaced during updates.
• Placing the tile server inside the same container as the application logic, preventing independent scaling when map tile generation becomes the bottleneck.
• Configuring tile server to re-render tiles on every request instead of caching rendered output, causing high CPU usage and slow client response times.

Adapting it to your system

Identify your geospatial data source: if you have vector data (points, polygons, linestrings), configure PostGIS with your tables and indexes; if you have raster sources, point the tile server to GeoTIFF files or remote services. Decide your tile generation strategy: pre-render static tiles during off-peak hours or render on-demand with aggressive caching. Adjust port mappings to match your environment, configure volume paths for persistent storage location, and add authentication between containers if deploying to untrusted networks. Replace placeholder service names with your actual domain names or internal DNS entries.