# developmentseed/titiler architecture

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

- Interactive diagram: https://gitdiagram.com/developmentseed/titiler
- Repository: https://github.com/developmentseed/titiler

## Overview

##### Main Components

a. Core Components:
- FastAPI Application Layer
- Core Tiling Engine
- Data Source Handlers (COG, STAC, MosaicJSON, Xarray)
- Extension System
- Tile Matrix Sets Handler (via morecantile)
- Output Formatters (JPEG, PNG, WEBP, etc.)

b. Package Structure:
- titiler.core (Base tiling functionality)
- titiler.xarray (Multi-dimensional data support)
- titiler.extensions (Plugin system)
- titiler.mosaic (MosaicJSON support)
- titiler.application (Demo application)

**┌─────────────────────────────────────────────────────┐**
- Client Layer                       │
- ┘
- ↕ HTTP/REST
**┌─────────────────────────────────────────────────────┐**
- FastAPI Layer                      │
- ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
- Routes    │  │ Middleware  │  │   OpenAPI   │ │
- ┘  └─────────────┘  └─────────────┘ │
- ┘
- ↕
**┌─────────────────────────────────────────────────────┐**
- Core Services                      │
- ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
- Tile Engine │  │  Factories  │  │ Dependencies │ │
- ┘  └─────────────┘  └─────────────┘ │
- ┘
- ↕
**┌─────────────────────────────────────────────────────┐**
- Data Source Handlers                  │
- ┌─────────┐ ┌───────┐ ┌────────┐ ┌─────────────┐ │
- COG   │ │ STAC  │ │ Mosaic │ │   Xarray    │ │
- ┘ └───────┘ └────────┘ └─────────────┘ │
- ┘
- ↕
**┌─────────────────────────────────────────────────────┐**
- External Dependencies                 │
- ┌─────────┐ ┌──────────┐ ┌────────────────────┐  │
- GDAL    │ │ Rasterio │ │    Morecantile     │  │
- ┘ └──────────┘ └────────────────────┘  │
- ┘

##### Important Relationships
- Data flow between components
- Extension points
- API routes to handlers
- Caching mechanisms
- Output format processors

##### Deployment Options
A separate section showing deployment scenarios:
- AWS Lambda
- ECS
- Kubernetes
- Docker standalone

##### Additional Elements
- Version information
- Supported file formats
- Scaling points
- Security boundaries

##### Implementation Details
- Use standard UML notation
- Component interfaces
- Major configuration points
- Stateless/stateful components

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        CL[Client Applications]
    end

    subgraph FastAPI
        FA[FastAPI Application]:::api
        MW[Middleware]:::middleware
        RT[Routes]:::routes
        OA[OpenAPI Docs]
    end

    subgraph CoreServices
        TE[Tile Engine]:::core
        FC[Factories]:::core
        DP[Dependencies]:::core
        AH[Algorithm Handlers]:::core
        RM[Response Models]:::core
        RH[Resource Handlers]:::core
        EH[Error Handlers]:::core
    end

    subgraph DataHandlers
        COG[COG Handler]:::handler
        STAC[STAC Handler]:::handler
        MOS[Mosaic Handler]:::handler
        XAR[XArray Handler]:::handler
    end

    subgraph ExternalDeps
        GDAL[GDAL]:::external
        RIO[Rasterio]:::external
        MC[Morecantile]:::external
    end

    %% Relationships
    Client --> FastAPI
    FA --> CoreServices
    CoreServices --> DataHandlers
    DataHandlers --> ExternalDeps

    %% Internal relationships
    FA --> MW
    FA --> RT
    FA --> OA
    TE --> FC
    TE --> DP
    TE --> AH
    TE --> RM
    TE --> RH
    TE --> EH

    %% Click events
    click FA "https://github.com/developmentseed/titiler/blob/main/src/titiler/application/titiler/application/main.py"
    click TE "https://github.com/developmentseed/titiler/blob/main/src/titiler/core/titiler/core/factory.py"
    click COG "https://github.com/developmentseed/titiler/blob/main/src/titiler/extensions/titiler/extensions/cogeo.py"
    click STAC "https://github.com/developmentseed/titiler/blob/main/src/titiler/extensions/titiler/extensions/stac.py"
    click MOS "https://github.com/developmentseed/titiler/blob/main/src/titiler/mosaic/titiler/mosaic/factory.py"
    click XAR "https://github.com/developmentseed/titiler/blob/main/src/titiler/xarray/titiler/xarray/factory.py"
    click DP "https://github.com/developmentseed/titiler/blob/main/src/titiler/core/titiler/core/dependencies.py"
    click AH "https://github.com/developmentseed/titiler/tree/main/src/titiler/core/titiler/core/algorithm/"
    click RM "https://github.com/developmentseed/titiler/tree/main/src/titiler/core/titiler/core/models/"
    click RH "https://github.com/developmentseed/titiler/tree/main/src/titiler/core/titiler/core/resources/"
    click MW "https://github.com/developmentseed/titiler/blob/main/src/titiler/core/titiler/core/middleware.py"
    click EH "https://github.com/developmentseed/titiler/blob/main/src/titiler/core/titiler/core/errors.py"
    click RT "https://github.com/developmentseed/titiler/blob/main/src/titiler/core/titiler/core/routing.py"

    %% Styling
    classDef api fill:#9DB6E6,stroke:#333,stroke-width:2px
    classDef middleware fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef routes fill:#98FB98,stroke:#333,stroke-width:2px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef handler fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px
```
