# mapproxy/mapproxy architecture

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

- Interactive diagram: https://gitdiagram.com/mapproxy/mapproxy
- Repository: https://github.com/mapproxy/mapproxy

## Overview

##### Project type and purpose
- MapProxy is an open-source geospatial proxy/cache tool written in Python.
- It accelerates, transforms and caches tiles and images from existing map services (WMS, WMTS, TMS, ArcGIS, Mapnik, etc.) and re-serves them to desktop or web GIS clients.
- It bundles a core engine, a service layer (WMS/TMS/WMTS endpoints), a pluggable cache subsystem, and command-line utilities (seeding, export, config generation).

##### High-level file structure analysis
- Top-level:
- Dockerfile, docker-compose.yaml, .github (CI), development metadata (setup.py, pyproject.toml).
- doc/ – Sphinx documentation.
- mapproxy/ – Python package:
– cache/ – pluggable tile caches (file, mbtiles, Redis, S3, Azure, CouchDB, etc.).
– client/ – HTTP/CGI/WMS/ArcGIS consumers.
– config/ – loader, validator, schema definitions.
– service/ – WMS/WMS-C/TMS/WMTS/OgcAPI endpoints & templates.
– source/ – upstream data sources (WMS, WMTS, Mapnik, ArcGIS).
– image/ – tile merging, masking, transformations.
– grid/, layer.py, proj.py – spatial grid & projection logic.
– seed/ – seeding engine.
– script/ – command-line tools for export, rendering scripts, grid generation, etc.
– util/ – shared utilities (yaml, fs, lock, async).
– wsgiapp.py – WSGI entrypoint for the services.
- Tests: Extensive unit and system tests under mapproxy/test/.
- Docker/docker-compose: ready-to-run container definitions with Nginx, uWSGI, logging.

##### README & docs insights
- Purpose: tile proxy & cache with full WMS compatibility.
- Supports many cache backends, pluggable via mapproxy/cache.
- Exposes standard OGC endpoints, configurable through YAML.

##### Components
a. Main components:
1. Configuration subsystem
– Config loader & validator (mapproxy/config/)
– YAML schemas & defaults
2. Core engine
– Request dispatcher & router
– Grid & projection module
– Tile/image processing (merge, mask, transform)
– Seeder engine
3. Cache subsystem
– File system, MBTiles, Redis, S3, Azure, CouchDB, others
4. Service layer (WSGI)
– WMS, TMS, WMTS, OGC API endpoints
– Demo service & templates
5. Source connectors
– Upstream data services: WMS, WMTS, ArcGIS, Mapnik
6. Command-line tools
– mapproxy-util, mapproxy-seed, export, defrag, etc.
7. External systems
– Remote map services, object stores, GIS clients
8. Deployment layer
– Nginx → uWSGI → WSGI app
– Docker containers, docker-compose

b. Relationships & interactions
– Client request → Nginx/uWSGI → WSGI app (service layer)
– Service layer → core engine (grid, render, cache lookup)
– Core engine → cache backend (read/write)
- On miss → core engine fetches from source connector → image processing → cache write → respond
– Seeder CLI → core engine batch tile generation → populates cache backends
– Config subsystem feeds parameters to all components at startup
– Docker compose orchestrates Nginx, uWSGI, optional Redis or object store

c. Architectural patterns / design principles
– Layered architecture (config → core → service → transport)
– Plugin pattern for caches, sources, services (each backend is a plugin module)
– Separation of concerns: service endpoints vs. processing engine vs. storage
– WSGI standard for web services, CLI entrypoints for batch tasks

d. Key technologies & frameworks
– Python 3, WSGI, uWSGI
– YAML config, JSON schema validation
– Nginx reverse proxy
– Docker / Docker-Compose
– Third-party caches (Redis, S3, Azure, CouchDB, MBTiles)
– Sphinx documentation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Client["GIS Clients"]:::external
    RemoteServices["Remote Map Services"]:::external

    %% Deployment Layer
    subgraph "Deployment Layer"
        Nginx["Nginx"]:::web
        uWSGI["uWSGI"]:::web
        WSGIApp["WSGI App"]:::web
        DockerCompose["Docker Compose"]:::web
    end

    %% Service Layer
    subgraph "Service Layer"
        WMS["WMS Endpoint"]:::service
        WMTS["WMTS Endpoint"]:::service
        Demo["Demo Service"]:::service
        Templates["Templates"]:::service
    end

    %% Core Engine
    subgraph "Core Engine"
        Dispatcher["Dispatcher & Router"]:::core
        SpatialGrid["Spatial Grids"]:::core
        Projection["Projection Logic"]:::core
        ImageProc["Tile/Image Processing"]:::core
        Seeder["Seeder Engine"]:::core
    end

    %% Cache Subsystem
    subgraph "Cache Subsystem"
        FileCache["File Cache"]:::cache
        MBTiles["MBTiles"]:::cache
        RedisCache["Redis"]:::cache
        S3Cache["S3"]:::cache
        AzureCache["Azure Blob"]:::cache
        CouchDBCache["CouchDB"]:::cache
    end

    %% Source Connectors
    subgraph "Source Connectors"
        SrcWMS["WMS Source"]:::source
        ArcGISSrc["ArcGIS Source"]:::source
        MapnikSrc["Mapnik Source"]:::source
    end

    %% Configuration & CLI
    subgraph "Configuration Subsystem"
        Loader["Config Loader"]:::config
        Validator["Config Validator"]:::config
        Defaults["Config Defaults"]:::config
    end
    subgraph "CLI Tools"
        Export["Export CLI"]:::cli
        Defrag["Defrag CLI"]:::cli
        GridGen["Grid Gen CLI"]:::cli
    end

    %% Flows
    Client -->|requests| Nginx
    Nginx --> uWSGI
    uWSGI --> WSGIApp
    WSGIApp --> WMS
    WMS --> Dispatcher
    Dispatcher -->|cache lookup| FileCache
    Dispatcher -->|cache lookup| MBTiles
    Dispatcher -->|cache lookup| RedisCache
    Dispatcher -->|cache lookup| S3Cache
    Dispatcher -->|cache lookup| AzureCache
    Dispatcher -->|cache lookup| CouchDBCache
    FileCache -->|hit| Dispatcher
    MBTiles -->|hit| Dispatcher
    RedisCache -->|hit| Dispatcher
    S3Cache -->|hit| Dispatcher
    AzureCache -->|hit| Dispatcher
    CouchDBCache -->|hit| Dispatcher
    FileCache -.->|miss| SrcWMS
    MBTiles -.->|miss| SrcWMS
    RedisCache -.->|miss| SrcWMS
    S3Cache -.->|miss| SrcWMS
    AzureCache -.->|miss| SrcWMS
    CouchDBCache -.->|miss| SrcWMS
    SrcWMS --> ImageProc
    ArcGISSrc --> ImageProc
    MapnikSrc --> ImageProc
    ImageProc -->|writes| FileCache
    ImageProc -->|writes| MBTiles
    ImageProc -->|writes| RedisCache
    ImageProc -->|writes| S3Cache
    ImageProc -->|writes| AzureCache
    ImageProc -->|writes| CouchDBCache
    Dispatcher --> SpatialGrid
    Dispatcher --> Projection
    Dispatcher -->|seed tasks| Seeder
    Loader --> Dispatcher
    Validator --> Dispatcher
    Defaults --> Dispatcher
    Export --> Dispatcher
    Defrag --> FileCache
    GridGen --> SpatialGrid
    Client --> Demo

    %% Click Events
    click WSGIApp "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/wsgiapp.py"
    click Dispatcher "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/multiapp.py"
    click SpatialGrid "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/grid/tile_grid.py"
    click Projection "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/proj.py"
    click ImageProc "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/image/merge.py"
    click Seeder "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/seed/seeder.py"
    click Loader "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/config/loader.py"
    click Validator "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/config/validator.py"
    click Defaults "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/config/defaults.py"
    click FileCache "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/cache/file.py"
    click MBTiles "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/cache/mbtiles.py"
    click RedisCache "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/cache/redis.py"
    click S3Cache "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/cache/s3.py"
    click AzureCache "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/cache/azureblob.py"
    click CouchDBCache "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/cache/couchdb.py"
    click WMS "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/service/wms.py"
    click WMTS "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/service/wmts.py"
    click Demo "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/service/demo.py"
    click Templates "https://github.com/mapproxy/mapproxy/tree/master/mapproxy/service/templates/"
    click SrcWMS "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/source/wms.py"
    click ArcGISSrc "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/source/arcgis.py"
    click MapnikSrc "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/source/mapnik.py"
    click Export "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/script/export.py"
    click Defrag "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/script/defrag.py"
    click GridGen "https://github.com/mapproxy/mapproxy/blob/master/mapproxy/script/grids.py"

    %% Styles
    classDef web fill:#cce5ff,stroke:#000;
    classDef core fill:#d4edda,stroke:#000;
    classDef cache fill:#fff3cd,stroke:#000;
    classDef source fill:#f5c6cb,stroke:#000;
    classDef config fill:#e2e3e5,stroke:#000;
    classDef cli fill:#e2e3e5,stroke:#000;
    classDef service fill:#d1ecf1,stroke:#000;
    classDef external fill:#f8d7da,stroke:#000;
```
