====== Realisation of System Architecture ======

Although the mode of deployment has little impact on the operation, it is proposed to deploy the infrastructure as Docker containers on each of the server machines. This simplifies scaling, migration and the operation of test/staging environments.

===== 1. Authentication =====

Authentication for all addressing related apps should be done through a single MoHUP user account. Ideally, an identity provider already exists within the ministry and can be used.

If not, a third virtual server running KeyCloak as an authorization server shall be installed. This exposes full authentication workflows in accordance with OIDC and can be connected to existing user catalogues in the Ministry as well as allow for self-registration of external users.

Authorization will take place on application level.

===== 2. Database container =====

The addressing system will need a spatial enabled database.

Based on the [[:background:the-best-spatial-database-in-2025|rationale analysed]], PostgreSQL + PostGIS run on Linux is recommended for the following five reasons:

  * performs better and faster
  * has more features
  * is free
  * is Open Source and has a huge user community
  * is considered the leading spatial database

For a comprehensive reasoning behind the recommendation, please see [[:background:the-best-spatial-database-in-2025|this page]] that provides a structured and objective comparison of spatial database technologies.

The organisation operating the addressing system may select other database platforms, but the decision to do so must be based on considerations that are not related to technical or functional requirements of the National Addressing System.

===== 3. Web server container =====

The best web server for the use cases of the national addressing system and associated work loads is NGINX run on Linux platform. This is a:

  - High-performance reverse proxy for underlying application servers, i.e. API servers
  - Excels at serving static content, e.g. end-user clients written in HTML5/Javascript frameworks such as Vue and React
  - TLS termination and load balancing for security and scalability
  - Lightweight deployments for no-nonsense management and observability

It provides:

  - Efficient reverse proxy and load balancer
  - HTTP/2 and gRPC support
  - Native TLS with Let's Encrypt integration
  - Can forward to FastAPI, Node.js, .NET, Flask, etc.

===== 4. Wiki container =====

**DokuWiki**  is a **lightweight, flat-file wiki**  system written in PHP8 (running on version 8.3), designed for creating and managing documentation without requiring a database. It is a ready-to-use solution with a low level of configuration.

== Key Features: ==

  * Stores content in plain text files (no MySQL/PostgreSQL needed)
  * Simple, readable syntax (inspired by MediaWiki but more intuitive)
  * Built-in access control (ACLs, user authentication)
  * Extensible via plugins and templates
  * File-based version control of pages
  * Search-friendly and portable

===== 5. Vector tile and web map service container(s) =====

For the purpose of the addressing application, only vector tiles are required. Assuming that PostresSQL + PostGIS is used, this can be accomplished by a simple pg_tileserv container.

For the purpose of serving third parties with web map services like OGC APIs, WMS, WFS and TMS services, it is necessary to introduce a map server application. This can be accomplished by means of a GeoServer container. Alternatively, MapServer or ArcGIS Enterprise server may be employed for the same purpose. The advantage of GeoServer over either of these is that it comes with a built-in management interface and that it is free.

===== 6. API container =====

An API that allows check-in check-out and CRUD operations for the various data models is provisioned as a Python FastAPI container running uvcorn.

===== 7. Tile cache container =====

To improve the performance of tile services that operate directly on vector data, a tile cache implements a cache storage for generated files, allowing these to be used rather than issuing a fresh request/processing for every requested tile. This particularly has impact for start-up areas where people come to work many times.

The tile cache is implemented by means of either MapCache or Varnish containers.