geoserver/geoserver-cloud

1. What this repository is

This is a multi-module Maven monorepo for GeoServer Cloud, a cloud-native decomposition of GeoServer into independently deployable Spring Boot services. The code is organized around reusable platform libraries, service applications, catalog/storage backends, GeoWebCache, and a large set of optional extensions.

2. Top-level runtime shape

At runtime there are three main kinds of processes:

- Edge/infrastructure services: gateway, config service, and supporting runtime pieces.

- GeoServer functional services: separate apps for WMS, WFS, WCS, WPS, REST config, Web UI, and GeoWebCache.

- Shared backend services: catalog persistence, event propagation, and optional external stores like PostgreSQL and blob stores.

3. Bootstrap and shared platform modules

src/starter/* and src/main/* provide the common bootstrapping layer:

- Spring Boot/Spring Cloud auto-configuration

- servlet and reactive web startup support

- GeoServer main security and update-sequence wiring

- observability helpers like MDC propagation and access logging

These modules are not standalone apps; they are the base building blocks imported by the service modules.

4. Gateway boundary

src/apps/infrastructure/gateway-webmvc and gateway-webflux are the ingress layer. They terminate client requests, apply routing rules, security headers, shared-auth propagation, and request rewriting before forwarding traffic to downstream services. The gateway has custom route predicates/filters for base-path stripping, profile-based routing, and shared authentication.

5. Central configuration service

src/apps/infrastructure/config is a dedicated config server-like application. It centralizes environment/service configuration and is paired with src/config/spring-factory and src/config/spring-boot-simplejndi, which adapt legacy-style XML/JNDI configuration into Spring Boot-friendly startup behavior.

6. GeoServer service applications

src/apps/geoserver/* contains the deployable business services:

- wms, wfs, wcs, wps: protocol-specific OWS services

- restconfig: REST administration/configuration service

- webui: browser-based admin UI

- gwc: GeoWebCache-facing application

These apps are intentionally thin; most behavior is pulled in through shared catalog, configuration, security, and extension modules.

7. Catalog subsystem

src/catalog/* is the core state-management area. It splits into:

- plugin: GeoServer-side catalog abstraction, repository facade, validation, locking, and resolving/proxy support

- cache: in-memory caching decorators around catalog and GeoServer facades

- events: lifecycle/config/catalog event model plus local and remote event integration

- backends/datadir: shared filesystem data-directory backend

- backends/pgconfig: PostgreSQL-backed catalog/config backend

- jackson-bindings/*: serialization/deserialization of GeoServer catalog/config/filter objects

The main flow is: service code interacts with catalog facades; facades may be cached; changes are persisted either to the data directory or PostgreSQL backend; events are emitted to keep other services consistent.

8. Catalog backend distinction

The repository supports two primary catalog persistence modes:

- Data directory backend: filesystem-based, with lock providers and eventual-consistency helpers.

- PGConfig backend: PostgreSQL-backed catalog/config store with repositories, migrations, SQL query builders, and resource-store synchronization.

This backend choice is a major architectural boundary because it changes persistence, locking, and sync behavior without changing service APIs.

9. GeoWebCache subsystem

src/gwc/* mirrors the catalog structure for tile caching:

- core: GWC core repository/configuration and tile-layer catalog abstractions

- backends/pgconfig: PostgreSQL-backed tile layer catalog

- blobstores: S3, Azure, and Google Cloud Storage blob-store integrations

- autoconfigure: conditional wiring of core services, REST/WMS/WMTS integrations, disk quota, and blob stores

- integration-bus: remote event propagation for cache and tile-layer changes

The data flow here is from GeoServer/GWC configuration into tile-layer metadata, quota state, and optional remote object storage.

10. Eventing and distributed coordination

Two event layers are important:

- Catalog events in src/catalog/events for local/remote config and lifecycle changes.

- GeoWebCache events in src/gwc/integration-bus for tile-layer, gridset, blob-store, and config-change propagation.

These modules form the consistency mechanism across independently scaled services, and they are the bridge to the project’s distributed-event infrastructure.

11. Extensions are capability slices, not one monolith

src/extensions/* contains optional feature modules that plug into the base services via auto-configuration. They are grouped by capability:

- security: LDAP, JDBC, auth-key, gateway shared-auth, ACL, environment admin

- input/output formats: COG, PMTiles, GeoParquet, FlatGeobuf, DXF, vector tiles

- styling and misc: CSS styling, Mapbox styling, control-flow, importer, OGC API, etc.

Each extension is conditionally activated, so the architecture is modular and feature flags/auto-configuration determine what each service actually loads.

12. Security model

Security is layered:

- gateway-level shared authentication and pre-auth filters

- service-level authentication providers and ACL integration

- optional identity backends such as JDBC, LDAP, and auth-key

The repo also contains service-specific security helpers for Web UI and REST config, indicating that security concerns are split between the edge and the service boundaries.

13. Operational/deployment boundary

The compose/ and docker-build/ trees define the runnable system topology for development and CI: gateway, service apps, config, PostgreSQL, pgbouncer, monitoring, and secrets. The docs/ tree includes Helm/Kubernetes deployment material and generated architecture diagrams, which strongly suggests the repo is designed to be diagrammed as a set of deployable containers with shared infrastructure, not as a single app.

14. How to draw the architecture

A useful diagram would show:

- clients entering through the gateway

- requests routed to WMS/WFS/WCS/WPS/REST/UI/GWC services

- those services depending on shared starter/platform modules

- state flowing to either Data Directory or PGConfig/PostgreSQL

- change events flowing through the event bus / remote-event modules

- GeoWebCache additionally connecting to blob stores and quota/storage backends

- optional extensions hanging off the service layer as conditional capabilities