How bbox-services/bbox works
Project type and purpose
• This is a Rust-based, full-stack suite of composable spatial microservices (“BBOX services”) plus a JavaScript/HTML frontend.
• It implements OGC API standards for Features, Maps, Tiles, Assets, Processes, and experimental Routing.
• It also provides instrumentation (Prometheus, Jaeger), health checks, and can be run standalone or via Docker.
File structure
• Top-level workspace (Cargo.toml) with multiple Rust crates under directories:
• bbox-core (shared library: config, logging, OpenAPI, templating, static assets)
• bbox-asset-server
• bbox-feature-server
• bbox-map-server
• bbox-tile-server
• bbox-processes-server
• bbox-routing-server
• bbox-server (umbrella CLI/aggregator)
• bbox-frontend (Rust code serving QWC2 + a “ui” subfolder with a Node/Tailwind UI)
• Docker folder with Dockerfiles for each service, nginx templates, docker-compose orchestration, Prometheus/Grafana config.
• website/ folder: static docs powered by Hugo (site of record).
README for additional insights
• Lists each microservice and the OGC API it implements.
• Mentions built-in high-performance HTTP server, QWC2 viewer, tracing, health-endpoints.
• Points to Docker usage and configuration via bbox.toml.
Main components
a. Clients
• Web browser (QWC2 front-end UI)
• CLI or other HTTP clients hitting OGC APIs
b. Reverse-proxy/API gateway
• Nginx (templates in docker/bbox/nginx/)
• Authentication integration (Authentik / OIDC in bbox-core)
c. Front-end
• bbox-frontend service (static HTML/JS with MapLibre GL and QWC2)
• Optional separate ui build pipeline (Node/Tailwind)
d. Microservices (each a Rust binary/container):
• Asset Server (static files, templates)
• Feature Server (OGC API Features, PostGIS/GPKG)
• Server (OGC API Maps, optional FCgi-WMS backend, QGIS plugins)
• Tile Server (OGC API Tiles, MBTiles/PMTiles/S3/WMS)
• Processes Server (OGC API Processes, Dagster integration)
• Routing Server (experimental, routing engine)
• bbox-server CLI (orchestration entrypoint combining core + selected services)
e. Shared library
• bbox-core (common REST framework, OpenAPI YAML, metrics, templating, static assets)
f. Data stores
• PostgreSQL/PostGIS
• Local file stores (MBTiles, GeoPackage)
• S3 or object store (for tiles)
g. Instrumentation & observability
• Prometheus (metrics endpoint)
• Jaeger (tracing)
• Grafana dashboards (containers in docker/bbox/instrumentation)
Relationships and data flow
• Client → (HTTPS) → Nginx/API Gateway → appropriate microservice
• Each microservice → bbox-core library → common config, logging, OpenAPI spec →
then → external data store (PostGIS, file, S3)
• Front-end fetches map tiles (Tile Server), features (Feature Server), static files (Asset Server)
• All services expose /metrics (Prometheus) and tracing spans (Jaeger)
• Docker-Compose wires up containers, PostGIS DB, Prometheus, Grafana, Jaeger
Architectural patterns & design principles
• Microservices: each OGC API is its own independently deployable binary
• Shared core library: enforces consistency (authentication, OpenAPI, metrics)
• Plugin/templating model: QGIS plugins, HTML templates served by asset server
• Configuration via bbox.toml + environment variables (12-factor design)
• Containerization: one container per service + sidecars (Prometheus, Grafana)
• Standard REST + OpenAPI contract for each service