Architecture¶
Tileverse is a set of loosely coupled libraries. Each module works on its own, for one domain: I/O, tile grids, or tile encodings.
Module map¶
The Tileverse monorepo ships ten library modules and two BOMs. Two foundation modules hold the code shared by the others: tileverse-io has the byte buffer pool and the stream and channel adapters over buffers, and tileverse-cache has the in-memory caches. tileverse-io-ffm has a pool of native memory segments, and is the one module requiring Java 25. Three modules are independent of each other: tileverse-storage, tileverse-vectortiles and tileverse-tilematrixset. tileverse-tilestore builds on the format and grid libraries. tileverse-compression holds the gzip, Brotli and Zstandard codecs and takes its buffers from tileverse-io. The archive readers tileverse-pmtiles and tileverse-versatiles depend on all the others (tileverse-storage for I/O, tileverse-cache for their caches of parsed directories and indexes, tileverse-compression for decompression, tileverse-vectortiles for MVT decoding, tileverse-tilematrixset for grid math, tileverse-tilestore for the high-level tile-store wrappers).
graph TD
subgraph "Application Layer"
App[User Application]
end
subgraph "Independent Modules"
ST[tileverse-storage<br/>Storage + RangeReader]
VT[tileverse-vectortiles]
TMS[tileverse-tilematrixset]
end
subgraph "Foundation"
IO[tileverse-io<br/>ByteBufferPool]
CACHE[tileverse-cache]
FFM[tileverse-io-ffm<br/>SegmentPool, Java 25]
end
subgraph "Cross-cutting"
TS[tileverse-tilestore<br/>TileStore<T>]
CMP[tileverse-compression<br/>Codec]
end
subgraph "Composed Modules"
PMT[tileverse-pmtiles]
VER[tileverse-versatiles]
end
App --> ST
App --> VT
App --> TMS
App --> TS
App --> PMT
App --> VER
App --> FFM
ST --> IO
ST --> CACHE
TS --> VT
TS --> TMS
TS --> CACHE
CMP --> IO
PMT --> ST
PMT --> VT
PMT --> TMS
PMT --> TS
PMT --> CMP
PMT --> CACHE
VER --> ST
VER --> VT
VER --> TMS
VER --> TS
VER --> CMP
VER --> CACHE System context¶
The Tileverse system sits between consumer applications and five external storage families: local FS, HTTP, S3-compatible object stores, Azure and GCS.
Container view¶
The library modules, their dependencies on each other, and their dependencies on the external storage systems. tileverse-pmtiles and tileverse-versatiles depend on every other Tileverse module; tileverse-tilestore brings the format-agnostic TileStore<T> abstraction; the four storage containers (-core, -s3, -azure, -gcs) compose under -all for callers that want every backend at once.
Per-module C4 component views are embedded in each library's section:
- Storage core internals
- PMTiles internals
- Versatiles internals
- Vector Tiles internals
- Tile Matrix Set internals
- Tile Stores internals
All C4 diagrams are generated from docs/structurizr/workspace.dsl and docs/structurizr/dynamic-views.dsl via docs/build.sh (Docker required). Edit the DSL and rerun the build to regenerate.
Design principles¶
- I/O stays separate from formats. A format library, such as a GeoTIFF reader, should not implement its own S3 client.
Storageprovides the container API, and itsRangeReaderthe byte-range reads of single files. - Grid math needs no GIS library.
tileverse-tilematrixsetcomputes tile coordinates and bounding boxes with no GIS or I/O library; it depends on Jackson for its JSON encoding. A tile server can use it whatever its data source. - Codecs do no I/O.
tileverse-vectortilesconverts between the protobuf encoding and JTS geometries. - Archive readers compose the rest.
tileverse-pmtilesandtileverse-versatilesread through aRangeReader, use the tile matrix set for the grid, and decode tiles with the vector tile codec orjavax.imageio.
Reading a tile¶
When a PMTilesReader reads the tile (z, x, y):
- It computes the tile id of the tile along the Hilbert curve.
- It looks the id up in the directories. A directory missing from its cache costs one range request.
- It reads the tile body with one range request, and removes the tile compression of the archive.
- A tile store decodes the bytes:
PMTilesVectorTileStorewithVectorTileCodec, andPMTilesRasterTileStorewithjavax.imageio.ImageIO. The decoder reads from a stream over a pooled buffer holding the tile bytes.
PMTilesReader keeps parsed directories in its own cache, and block-aligns its reads of the header, the directories and the metadata. Tile bytes are cached only when the reader passed to PMTilesReader is a CachingRangeReader.
Extension points¶
- Implement
StorageProvider, registered throughServiceLoader, to add a storage backend: for example an internal content-addressed store, a store with its own URI scheme, or a test harness. Native protocols like OpenStack Swift, Azure Files (SMB), or HDFS through WebHDFS are out of scope; see Why tileverse-storage?. - Subclass
AbstractTileStore<T>to expose a different archive format under the sameTileStore<T>contract, astileverse-versatilesdoes for VersaTiles containers. MBTiles would fit the same way. - Implement
TileMatrixSetto support non-Earth or custom grids while reusing the rest of the stack unchanged.
Third-party dependencies¶
The Module column names the modules declaring each dependency.
| Library | Usage | Module |
|---|---|---|
| JTS Topology Suite | Geometry model (Points, Polygons, etc.) | vectortiles, tilestore |
| Caffeine | High-performance in-memory caching | cache, storage-core, tilestore, pmtiles, versatiles |
| Jackson 3 | JSON encodings (OGC TMS, TileJSON, PMTiles and Versatiles metadata) | tilematrixset, tilestore, pmtiles, versatiles |
| webp-imageio | ImageIO plugin for WebP-encoded raster tiles (registered via JDK SPI; ships native libs for Linux and macOS on x86_64 and arm64, and for Windows on x86 and x86_64) | pmtiles, versatiles |
| Brotli4j | Native Brotli decoder for tiles, directories and indexes (native libraries for Linux and macOS on x86_64 and arm64, and for Windows on x86_64) | compression |
| Brotli decoder | Pure-Java Brotli decoder, used when the Brotli4j native library cannot load | compression |
| jlibdeflate | Native gzip decoder (libdeflate) for tiles, directories and metadata; the JDK decodes gzip when its native library cannot load | compression |
| zstd-jni | Native Zstandard codec | compression |
| SLF4J | Logging abstraction | All |
The cloud SDKs come only with the storage module of their backend:
| Library | Usage | Module |
|---|---|---|
| AWS SDK for Java v2 | S3 storage backend | storage-s3 |
| Azure SDK for Java | Azure Blob and Data Lake Gen2 storage backend | storage-azure |
| Google Cloud Java | GCS storage backend | storage-gcs |