Flo.w

# Architecture

Flo.w Engine is the core of the Flo.w ecosystem and provides base services to Flo.w applications:

  • Authentication/authorization.
  • Geospatial data management and storage.
  • Geospatial data file upload.
  • Dataset querying.
  • Services for web-based mapping libraries:
    • Vector map tiles
    • Base-map styles
    • Map fonts and sprites

The top-level architecture of Flo.w Engine is shown below:

Flo.w Engine Architecture

# Components

# Authorization Layer

The Authorization Layer implements API key-based authentication and authorization for all requests to Flo.w Engine. See Authorization for details of how API keys are created and used.

# Data Abstraction Layer

The Data Abstraction Layer provides a unified interface for accessing back-end data storage. Typically data is stored in a PostgreSQL/PostGIS database but drivers are provided for alternative storage engines and for integration with external systems.

# Map Server

The Map Server implements services used by front-end map visualizations. It provides:

# Interfaces

Flo.w Engine exposes the following interfaces:

# REST API

The Flo.w Engine REST API provides an interface for configuring resources and performing other operations such as querying datasets. See the Flo.w REST API Reference for details.

# Map API

The Map API exposes the following standard map resources:

The API is designed to support visualizations using the Maplibre GL JS (opens new window) mapping library. However, alternative web mapping libraries can also consume the same standard resources.

# Back-end Storage

Flo.w Engine integrates with back-end storage engines to provide storage for geospatial data. The Data Abstraction Layer provides a unified interface to storage engines via drivers.

# Resources

Flo.w Engine functionality is defined by resources (shown in yellow in the architecture diagram above). They are created and configured by Flo.w application developers using the Flo.w Engine REST API and associated tools. A Flo.w application can thus be thought of as a collection of Flo.w Engine resources consumed by a front-end visualization.

The following resources are provided:

# Applications

An Application is a logical container for other Flo.w Engine resources and is the basis of Flo.w Engine's multi-tenancy capability. The Authorization Layer enforces application boundaries and prevents access to resources between applications.

A separate Application is typically created for each front-end web application.

See the Flo.w REST API Reference for supported operations.

# API Keys

API Keys provide authenticated access to the Flo.w Engine REST API and must be supplied with most REST requests. An API Key provides access to an Applications's resources and can be configured to limit which resources are accessible and which operations can be performed on those resources.

See Authentication for more details of how API Keys are configured and used to authenticate requests.

See the Flo.w REST API Reference for supported operations.

# Application Configuration

Application Configurations are used to store arbitrary application-specific configuration JSON. The configuration can be retrieved or modified by front-end applications.

See the Flo.w REST API Reference for supported operations.

# Datasets

Datasets are abstractions of geospatial and non-geospatial data. They can be queried by front-end applications and exposed as vector map tiles by the Map Server.

Datasets are key resources in Flo.w Engine. See Working with Datasets for further details.

The Data Abstraction Layer provides a unified interface to access the data encapsulated by a dataset. Typically data is stored in a PostgreSQL/PostGIS database but drivers are provided for alternative storage engines and for integration with external systems.

See the Flo.w REST API Reference for supported operations.

# Databases

A Database resource specifies a driver and connection details for connecting to an external database. Databases are associated with Datasets to specify how and where the underlying data for the Dataset is stored. They are used by the Data Abstraction Layer when querying a Dataset.

Each Application will typically specify a single Database, which provides connection details to an application-specific physical database. However, to support complex scenarios or to integrate with external systems, Applications can also specify multiple databases.

See the Flo.w REST API Reference for supported operations.

# Tile Sources

Tile Sources define map tile sets that can be requested from the Map Server. A Tile Source specifies:

  • The source of the data used to produce tiles: a Dataset or an external file.
  • The tile coordinate system and extent.
  • Legal attribution text to add to maps that use the Tile Source.
  • Request headers to control tile caching by front-end applications.

See the Flo.w REST API Reference for supported operations.

# Map Styles

Map Styles define base-map styles used by the Map Server.

Four standard styles are provided:

  • 'positron': a simple light base map showing place names and transport.
  • 'darkmatter': a simple dark base map showing place names and transport.
  • 'fjord': a simple blue base map showing place names and transport.
  • 'osm-bright': a detailed base map showing land use and points of interest.

An Application can provide custom Map Styles for particular use cases.

See the Flo.w REST API Reference for supported operations.

# Users

Users represent application end-users and specify user details including:

  • Name and email address.
  • Log-in credentials.
  • Application-specific roles.
  • Tokens to support email address verification and password reset.

Flo.w Engine provides user-based authentication and authorization services for web applications. The following functionality is supported:

See the Flo.w REST API Reference for supported operations.

← Authentication →