# maplibre/martin architecture

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

- Interactive diagram: https://gitdiagram.com/maplibre/martin
- Repository: https://github.com/maplibre/martin

## Overview

##### Project type and purpose
- Martin is an open-source tile server and toolkit written in Rust.
- It provides both a library (core tile‐generation engine) and multiple command-line binaries (martin, martin-cp, mbtiles, etc.), plus a demo full-stack application (PostgreSQL, Rust server, React frontend).
- Its purpose is to serve vector tiles on‐the‐fly from PostGIS, PMTiles, MBTiles, composite sources, sprites, and fonts.

##### File structure
- Top‐level crates (Cargo.toml describes a workspace):
- martin/         — core library & binaries (martin, martin-cp)
- mbtiles/        — MBTiles CLI tool & library
- martin-tile-utils/ — shared Rust helpers (decoders, fixtures)
- demo/ directory:
- docker-compose.yml defines Postgres, Rust server, React frontend
- demo/frontend holds a Vite/React UI for “Try it” demos
- docs/ directory: mdBook documentation
- tests/ and fixtures/ for integration/unit tests and sample data
- Workflow configs for CI, audit, benchmarks, release

##### README for additional insights
- Core features: on‐the‐fly vector tile generation, support for multiple tile formats, composite sources, bulk generation (martin-cp), MBTiles utilities (mbtiles tool).
- Provides HTTP server with configurable CORS, TLS, API endpoints (/tiles/{z}/{x}/{y}.{format}).
- Can run as CLI, Docker container, AWS Lambda.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Clients"
        MapClient["Map Viewers"]:::external
        ShellClient["CLI Users"]:::external
    end

    subgraph "Presentation Layer"
        HTTP["HTTP Server (martin)"]:::presentation
        CLI_CP["CLI: martin-cp"]:::presentation
        CLI_MB["CLI: mbtiles"]:::presentation
    end

    subgraph "Application / Core Engine"
        Lib["Core Tile-Generation Library"]:::rustcore
        Config["Configuration Loader"]:::rustcore
        SourceReg["Composite Source Registry"]:::rustcore
        TileBuilder["Tile Encoder"]:::rustcore
        Pool["Connection Pooling"]:::rustcore
        Cache["Cache Utilities"]:::rustcore
    end

    subgraph "Adapter Layer"
        PG["PostGIS Adapter"]:::rustcore
        PMT["PMTiles Adapter"]:::rustcore
        MBT["MBTiles Adapter"]:::rustcore
        Sprites["Sprites Module"]:::rustcore
        Fonts["Fonts Module"]:::rustcore
    end

    subgraph "Data Layer"
        Postgres["PostgreSQL/PostGIS"]:::external
        PMTilesFile["PMTiles Files"]:::external
        MBTilesFile["MBTiles Files"]:::external
        FontFiles["Font Files"]:::external
    end

    subgraph "Demo Stack"
        DC["Docker Compose"]:::demo
        DemoUI["Demo Frontend (React)"]:::demo
        DemoDB["Demo Database Init"]:::demo
    end

    MapClient -->|"HTTP Request"| HTTP
    HTTP -->|"load config"| Config
    Config --> SourceReg
    HTTP -->|"invoke tile build"| Lib
    Lib --> SourceReg
    SourceReg --> PG
    SourceReg --> PMT
    SourceReg --> MBT
    SourceReg --> Sprites
    SourceReg --> Fonts
    PG --> Pool
    PG -->|"TLS"| PG
    PG --> Postgres
    PMT --> PMTilesFile
    MBT --> MBTilesFile
    Sprites --> FontFiles
    Fonts --> FontFiles
    Lib --> TileBuilder
    TileBuilder -->|"MVT Protobuf"| HTTP
    HTTP --> Cache
    ShellClient --> CLI_CP
    ShellClient --> CLI_MB
    CLI_CP --> Lib
    CLI_MB --> Lib

    DC --> HTTP
    DC --> DemoUI
    DC --> DemoDB
    DemoDB --> Postgres
    DemoUI --> HTTP

    classDef rustcore fill:#a8e6cf,stroke:#379683;
    classDef external fill:#dcedc1,stroke:#558b2f;
    classDef presentation fill:#ffd3b6,stroke:#e65100;
    classDef demo fill:#ffaaa5,stroke:#d32f2f;

    click Lib "https://github.com/maplibre/martin/blob/main/martin/src/lib.rs"
    click HTTP "https://github.com/maplibre/martin/blob/main/martin/src/bin/martin.rs"
    click HTTP "https://github.com/maplibre/martin/blob/main/martin/src/srv/server.rs"
    click CLI_CP "https://github.com/maplibre/martin/blob/main/martin/src/bin/martin-cp.rs"
    click PG "https://github.com/maplibre/martin/tree/main/martin/src/pg/"
    click PMT "https://github.com/maplibre/martin/blob/main/martin/src/pmtiles/mod.rs"
    click MBT "https://github.com/maplibre/martin/blob/main/martin/src/mbtiles/mod.rs"
    click SourceReg "https://github.com/maplibre/martin/blob/main/martin/src/source.rs"
    click Sprites "https://github.com/maplibre/martin/blob/main/martin/src/sprites/mod.rs"
    click Fonts "https://github.com/maplibre/martin/blob/main/martin/src/fonts/mod.rs"
    click Pool "https://github.com/maplibre/martin/blob/main/martin/src/pg/pool.rs"
    click Config "https://github.com/maplibre/martin/blob/main/martin/src/config.rs"
    click Config "https://github.com/maplibre/martin/blob/main/martin/src/file_config.rs"
    click HTTP "https://github.com/maplibre/martin/blob/main/martin/src/srv/cors.rs"
    click HTTP "https://github.com/maplibre/martin/blob/main/martin/src/srv/mod.rs"
    click PG "https://github.com/maplibre/martin/blob/main/martin/src/pg/tls.rs"
    click Cache "https://github.com/maplibre/martin/blob/main/martin/src/utils/cache.rs"
    click CLI_MB "https://github.com/maplibre/martin/blob/main/mbtiles/src/bin/mbtiles.rs"
    click CLI_MB "https://github.com/maplibre/martin/blob/main/mbtiles/src/lib.rs"
    click DC "https://github.com/maplibre/martin/blob/main/demo/docker-compose.yml"
    click DemoUI "https://github.com/maplibre/martin/tree/main/demo/frontend/"
    click DemoDB "https://github.com/maplibre/martin/tree/main/demo/db/Dockerfile"
    click DemoDB "https://github.com/maplibre/martin/tree/main/demo/db/initdb/"
    click Docs "https://github.com/maplibre/martin/blob/main/docs/book.toml"
    click Docs "https://github.com/maplibre/martin/tree/main/docs/src/"
```
