# bbox-services/bbox architecture

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

- Interactive diagram: https://gitdiagram.com/bbox-services/bbox
- Repository: https://github.com/bbox-services/bbox

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        Browser["Web Browser\n(QWC2 UI)"]:::frontend
        CLI["CLI/HTTP Clients"]:::frontend
    end

    %% API Gateway
    Nginx["Nginx API Gateway\n(Reverse Proxy)"]:::core

    %% Frontend
    subgraph "Frontend"
        FrontendService["bbox-frontend Service"]:::frontend
        UIBuild["Frontend UI Build\n(Node/Tailwind)"]:::frontend
    end

    %% Shared Core
    CoreLib["bbox-core\n(Shared Library)"]:::core

    %% Microservices
    subgraph "OGC API Microservices"
        Asset["Asset Server"]:::micro
        Feature["Feature Server"]:::micro
        Map["Map Server"]:::micro
        Tile["Tile Server"]:::micro
        Processes["Processes Server"]:::micro
        Routing["Routing Server"]:::micro
        CLIService["bbox-server CLI/Aggregator"]:::micro
    end

    %% Data Stores
    subgraph "Data Stores"
        PostGIS["PostgreSQL/PostGIS"]:::db
        FileStore["Local File Store\n(MBTiles/GeoPackage)"]:::db
        S3Store["Object Store (S3)"]:::db
    end

    %% Observability
    subgraph "Observability"
        Prometheus["Prometheus"]:::obs
        Jaeger["Jaeger"]:::obs
        Grafana["Grafana Dashboards"]:::obs
    end

    %% Orchestration
    DockerCompose["Docker-Compose Orchestration"]:::orchestration

    %% Connections
    Browser -->|HTTPS| Nginx
    CLI -->|HTTPS| Nginx

    Nginx -->|Proxy to| FrontendService
    Nginx -->|Proxy to| Asset
    Nginx -->|Proxy to| Feature
    Nginx -->|Proxy to| Map
    Nginx -->|Proxy to| Tile
    Nginx -->|Proxy to| Processes
    Nginx -->|Proxy to| Routing
    Nginx -->|Proxy to| CLIService

    FrontendService -->|Fetch UI| UIBuild
    FrontendService -->|Uses| CoreLib

    Asset -->|Depends on| CoreLib
    Feature -->|Depends on| CoreLib
    Map -->|Depends on| CoreLib
    Tile -->|Depends on| CoreLib
    Processes -->|Depends on| CoreLib
    Routing -->|Depends on| CoreLib
    CLIService -->|Depends on| CoreLib

    Asset -->|Reads/Writes| FileStore
    Feature -->|Reads/Writes| PostGIS
    Map -->|Reads/Writes| PostGIS
    Tile -->|Reads/Writes| FileStore
    Tile -->|Reads/Writes| S3Store
    Processes -->|Integrates with| Dagster[Dagster]:::obs
    Routing -->|Reads| PostGIS

    Asset -->|/metrics| Prometheus
    Feature -->|/metrics| Prometheus
    Map -->|/metrics| Prometheus
    Tile -->|/metrics| Prometheus
    Processes -->|/metrics| Prometheus
    Routing -->|/metrics| Prometheus
    CLIService -->|/metrics| Prometheus

    Asset -->|tracing spans| Jaeger
    Feature -->|tracing spans| Jaeger
    Map -->|tracing spans| Jaeger
    Tile -->|tracing spans| Jaeger
    Processes -->|tracing spans| Jaeger
    Routing -->|tracing spans| Jaeger
    CLIService -->|tracing spans| Jaeger

    DockerCompose --> Asset
    DockerCompose --> Feature
    DockerCompose --> Map
    DockerCompose --> Tile
    DockerCompose --> Processes
    DockerCompose --> Routing
    DockerCompose --> CLIService
    DockerCompose --> PostGIS
    DockerCompose --> Prometheus
    DockerCompose --> Grafana
    DockerCompose --> Jaeger

    %% Click Events
    click FrontendService "https://github.com/bbox-services/bbox/tree/main/bbox-frontend/"
    click UIBuild "https://github.com/bbox-services/bbox/tree/main/bbox-frontend/ui/"
    click CoreLib "https://github.com/bbox-services/bbox/tree/main/bbox-core/"
    click Asset "https://github.com/bbox-services/bbox/blob/main/bbox-asset-server/src/main.rs"
    click Feature "https://github.com/bbox-services/bbox/blob/main/bbox-feature-server/src/main.rs"
    click Map "https://github.com/bbox-services/bbox/blob/main/bbox-map-server/src/main.rs"
    click Tile "https://github.com/bbox-services/bbox/blob/main/bbox-tile-server/src/main.rs"
    click Processes "https://github.com/bbox-services/bbox/blob/main/bbox-processes-server/src/main.rs"
    click Routing "https://github.com/bbox-services/bbox/blob/main/bbox-routing-server/src/main.rs"
    click CLIService "https://github.com/bbox-services/bbox/blob/main/bbox-server/src/main.rs"
    click Nginx "https://github.com/bbox-services/bbox/tree/main/docker/bbox/nginx/"
    click DockerCompose "https://github.com/bbox-services/bbox/blob/main/docker/bbox/docker-compose.yml"
    click Prometheus "https://github.com/bbox-services/bbox/blob/main/docker/bbox/instrumentation/prometheus.yml"
    click Grafana "https://github.com/bbox-services/bbox/tree/main/docker/bbox/instrumentation/grafana/"

    %% Styles
    classDef frontend fill:#f9d5a2,stroke:#e0891f,color:#000
    classDef core fill:#d3d3d3,stroke:#888,color:#000
    classDef micro fill:#a2c4f9,stroke:#1f4e79,color:#000
    classDef db fill:#a2f9a2,stroke:#1f7725,color:#000
    classDef obs fill:#d3a2f9,stroke:#5e1f79,color:#000
    classDef orchestration fill:#f9a2a2,stroke:#791f1f,color:#000
```
