From e3e278dacb4efa526b6320b7e7e9dc7ebc279207 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 26 Jun 2026 15:44:05 +0200
Subject: [PATCH 001/117] Initial Commit

---
 Loud.xcodeproj/project.pbxproj                | 72 +++++++++++++++++++
 .../contents.xcworkspacedata                  |  7 ++
 2 files changed, 79 insertions(+)
 create mode 100644 Loud.xcodeproj/project.pbxproj
 create mode 100644 Loud.xcodeproj/project.xcworkspace/contents.xcworkspacedata

diff --git a/Loud.xcodeproj/project.pbxproj b/Loud.xcodeproj/project.pbxproj
new file mode 100644
index 0000000..727bc00
--- /dev/null
+++ b/Loud.xcodeproj/project.pbxproj
@@ -0,0 +1,72 @@
+// !$*UTF8*$!
+{
+	archiveVersion = 1;
+	classes = {
+	};
+	objectVersion = 110;
+	objects = {
+
+/* Begin PBXGroup section */
+		02642FD02FEEB9A5007FA466 = {
+			isa = PBXGroup;
+			children = (
+			);
+			sourceTree = "<group>";
+		};
+/* End PBXGroup section */
+
+/* Begin PBXProject section */
+		02642FD12FEEB9A5007FA466 /* Project object */ = {
+			isa = PBXProject;
+			attributes = {
+				BuildIndependentTargetsInParallel = 1;
+				LastUpgradeCheck = 2700;
+			};
+			buildConfigurationList = 02642FD42FEEB9A5007FA466 /* Build configuration list for PBXProject "Loud" */;
+			developmentRegion = en;
+			hasScannedForEncodings = 0;
+			knownRegions = (
+				en,
+				Base,
+			);
+			mainGroup = 02642FD02FEEB9A5007FA466;
+			minimizedProjectReferenceProxies = 1;
+			preferredProjectObjectVersion = 77;
+			projectDirPath = "";
+			projectRoot = "";
+			targets = (
+			);
+		};
+/* End PBXProject section */
+
+/* Begin XCBuildConfiguration section */
+		02642FD52FEEB9A5007FA466 /* Debug configuration for PBXProject "Loud" */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				DEVELOPMENT_TEAM = 7FMNM89WKG;
+			};
+			name = Debug;
+		};
+		02642FD62FEEB9A5007FA466 /* Release configuration for PBXProject "Loud" */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				DEVELOPMENT_TEAM = 7FMNM89WKG;
+			};
+			name = Release;
+		};
+/* End XCBuildConfiguration section */
+
+/* Begin XCConfigurationList section */
+		02642FD42FEEB9A5007FA466 /* Build configuration list for PBXProject "Loud" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				02642FD52FEEB9A5007FA466 /* Debug configuration for PBXProject "Loud" */,
+				02642FD62FEEB9A5007FA466 /* Release configuration for PBXProject "Loud" */,
+			);
+			defaultConfigurationName = Release;
+		};
+/* End XCConfigurationList section */
+	};
+	rootObject = 02642FD12FEEB9A5007FA466 /* Project object */;
+	validationLevel = 1;
+}
diff --git a/Loud.xcodeproj/project.xcworkspace/contents.xcworkspacedata b/Loud.xcodeproj/project.xcworkspace/contents.xcworkspacedata
new file mode 100644
index 0000000..919434a
--- /dev/null
+++ b/Loud.xcodeproj/project.xcworkspace/contents.xcworkspacedata
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Workspace
+   version = "1.0">
+   <FileRef
+      location = "self:">
+   </FileRef>
+</Workspace>
-- 
2.54.0


From a15271772e8c5379c4b68587814ce97fcfd216f7 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 26 Jun 2026 21:08:28 +0000
Subject: [PATCH 002/117] Xcode project setup (#1)

This PR contains the work done to setup the *Xcode* project, with its `.gitignore` and `.swift-format` files.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/1
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .gitignore                     | 54 ++++++++++++++++++++++++++++
 .swift-format                  | 65 ++++++++++++++++++++++++++++++++++
 Loud.xcodeproj/project.pbxproj | 24 ++++++++++++-
 3 files changed, 142 insertions(+), 1 deletion(-)
 create mode 100644 .gitignore
 create mode 100644 .swift-format

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..0a05440
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,54 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+
+# Xcode
+## User settings
+xcuserdata/
+
+## Build generated
+build/
+DerivedData/
+
+## Various settings
+*.pbxuser
+!default.pbxuser
+*.mode1v3
+!default.mode1v3
+*.mode2v3
+!default.mode2v3
+*.perspectivev3
+!default.perspectivev3
+
+## Other
+*.moved-aside
+*.hmap
+*.ipa
+*.dSYM.zip
+*.dSYM
+
+## Playgrounds
+timeline.xctimeline
+playground.xcworkspace
+
+# Swift Package Manager
+## Build output and resolved dependency checkouts
+.build/
+## SwiftPM's local registry config and per-user Xcode data (schemes live in
+## xcuserdata, already ignored above). Shared .swiftpm metadata is committed.
+.swiftpm/configuration/registries.json
+.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
+
+# NOTE: `Packages/` is intentionally NOT ignored — it holds this repo's local
+# Swift packages (source), not checked-out dependencies.
+# NOTE: `Package.resolved` is intentionally NOT ignored — committing it locks
+# dependency versions across the team and CI.
+
+# Fastlane
+fastlane/report.xml
+fastlane/Preview.html
+fastlane/screenshots/**/*.png
+fastlane/test_output
\ No newline at end of file
diff --git a/.swift-format b/.swift-format
new file mode 100644
index 0000000..f015b36
--- /dev/null
+++ b/.swift-format
@@ -0,0 +1,65 @@
+{
+  "version": 1,
+  "lineLength": 200,
+  "indentation": {
+    "spaces": 4
+  },
+  "tabWidth": 4,
+  "maximumBlankLines": 1,
+  "respectsExistingLineBreaks": true,
+  "lineBreakBeforeControlFlowKeywords": true,
+  "lineBreakBeforeEachArgument": true,
+  "lineBreakBeforeEachGenericRequirement": true,
+  "lineBreakBetweenDeclarationAttributes": true,
+  "prioritizeKeepingFunctionOutputTogether": false,
+  "indentConditionalCompilationBlocks": true,
+  "indentSwitchCaseLabels": false,
+  "lineBreakAroundMultilineExpressionChainComponents": false,
+  "spacesAroundRangeFormationOperators": true,
+  "multiElementCollectionTrailingCommas": true,
+  "fileScopedDeclarationPrivacy": {
+    "accessLevel": "private"
+  },
+  "noAssignmentInExpressions": {
+    "allowedFunctions": [
+      "XCTAssertNoThrow"
+    ]
+  },
+  "rules": {
+    "AllPublicDeclarationsHaveDocumentation": false,
+    "AlwaysUseLowerCamelCase": true,
+    "AmbiguousTrailingClosureOverload": true,
+    "BeginDocumentationCommentWithOneLineSummary": true,
+    "DoNotUseSemicolons": true,
+    "DontRepeatTypeInStaticProperties": true,
+    "FileScopedDeclarationPrivacy": true,
+    "FullyIndirectEnum": true,
+    "GroupNumericLiterals": true,
+    "IdentifiersMustBeASCII": true,
+    "NeverForceUnwrap": true,
+    "NeverUseForceTry": true,
+    "NeverUseImplicitlyUnwrappedOptionals": true,
+    "NoAccessLevelOnExtensionDeclaration": true,
+    "NoAssignmentInExpressions": true,
+    "NoBlockComments": true,
+    "NoCasesWithOnlyFallthrough": true,
+    "NoEmptyTrailingClosureParentheses": true,
+    "NoLabelsInCasePatterns": true,
+    "NoLeadingUnderscores": false,
+    "NoParensAroundConditions": true,
+    "NoVoidReturnOnFunctionSignature": true,
+    "OneCasePerLine": true,
+    "OneVariableDeclarationPerLine": true,
+    "OnlyOneTrailingClosureArgument": true,
+    "OrderedImports": true,
+    "ReturnVoidInsteadOfEmptyTuple": true,
+    "UseEarlyExits": true,
+    "UseLetInEveryBoundCaseVariable": true,
+    "UseShorthandTypeNames": true,
+    "UseSingleLinePropertyGetter": true,
+    "UseSynthesizedInitializer": true,
+    "UseTripleSlashForDocumentationComments": true,
+    "UseWhereClausesInForLoops": false,
+    "ValidateDocumentationComments": false
+  }
+}
diff --git a/Loud.xcodeproj/project.pbxproj b/Loud.xcodeproj/project.pbxproj
index 727bc00..9b48f17 100644
--- a/Loud.xcodeproj/project.pbxproj
+++ b/Loud.xcodeproj/project.pbxproj
@@ -6,10 +6,31 @@
 	objectVersion = 110;
 	objects = {
 
+/* Begin PBXFileSystemSynchronizedRootGroup section */
+		02B32DD62FEEC5A700DA6788 /* Apps */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			path = Apps;
+			sourceTree = "<group>";
+		};
+		02B32DD72FEEC5AE00DA6788 /* Services */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			path = Services;
+			sourceTree = "<group>";
+		};
+		02B32DD82FEEC5B400DA6788 /* Packages */ = {
+			isa = PBXFileSystemSynchronizedRootGroup;
+			path = Packages;
+			sourceTree = "<group>";
+		};
+/* End PBXFileSystemSynchronizedRootGroup section */
+
 /* Begin PBXGroup section */
 		02642FD02FEEB9A5007FA466 = {
 			isa = PBXGroup;
 			children = (
+				02B32DD82FEEC5B400DA6788 /* Packages */,
+				02B32DD72FEEC5AE00DA6788 /* Services */,
+				02B32DD62FEEC5A700DA6788 /* Apps */,
 			);
 			sourceTree = "<group>";
 		};
@@ -21,6 +42,7 @@
 			attributes = {
 				BuildIndependentTargetsInParallel = 1;
 				LastUpgradeCheck = 2700;
+				ORGANIZATIONNAME = "Röck+Cöde VoF";
 			};
 			buildConfigurationList = 02642FD42FEEB9A5007FA466 /* Build configuration list for PBXProject "Loud" */;
 			developmentRegion = en;
@@ -31,7 +53,7 @@
 			);
 			mainGroup = 02642FD02FEEB9A5007FA466;
 			minimizedProjectReferenceProxies = 1;
-			preferredProjectObjectVersion = 77;
+			preferredProjectObjectVersion = 110;
 			projectDirPath = "";
 			projectRoot = "";
 			targets = (
-- 
2.54.0


From 08b210e7c6404d296a4473e4f45d4d2d4b171d92 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 27 Jun 2026 02:26:33 +0000
Subject: [PATCH 003/117] Website service target setup (#2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR contains the work done to add and setup the *Website* service target, a **Hummingbird** server app, into the Xcode project as a SwiftPM package with full support for containerization and driven by a `Makefile` file.

To provide further details about the work done:

* Swift package — SwiftPM manifest with a Website executable, related library, and test targets; depends on **hummingbird** and **swift-configuration**.
* Containerization — Multi-stage `Dockerfile` producing a static-linked release build with jemalloc, running as a non-root user on port 8080. Production and local-dev `docker-compose` files included.
* Configuration — `.env.local` template (with `.env` git-ignored) and `.dockerignore`/`.gitignore` entries.
* Makefile — Self-documenting operational commands:
  * pkg — SwiftPM: _build, release, test, clean, reset, deps, outdated, update_
  * img — Docker lifecycle: _build, mount, unmount, release_

Notes

* New service only — no changes to existing code; nothing else in the repo is affected.
* App logic is currently scaffolding; this PR establishes the service structure, build, and deployment tooling.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/2
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .gitignore                                    |   4 +
 Services/Website/.dockerignore                |   6 +
 Services/Website/.env.local                   |  42 +++++++
 Services/Website/Dockerfile                   |  87 ++++++++++++++
 Services/Website/Makefile                     | 107 ++++++++++++++++++
 Services/Website/Package.swift                |  74 ++++++++++++
 Services/Website/README.md                    |   2 +
 Services/Website/Sources/App/App+build.swift  |  62 ++++++++++
 Services/Website/Sources/App/App.swift        |  28 +++++
 .../Website/Sources/Library/Library.swift     |   2 +
 Services/Website/Tests/App/AppTests.swift     |  34 ++++++
 .../Website/Tests/Library/LibraryTest.swift   |   1 +
 Services/Website/docker-compose.override.yml  |  18 +++
 Services/Website/docker-compose.yml           |  22 ++++
 14 files changed, 489 insertions(+)
 create mode 100644 Services/Website/.dockerignore
 create mode 100644 Services/Website/.env.local
 create mode 100644 Services/Website/Dockerfile
 create mode 100644 Services/Website/Makefile
 create mode 100644 Services/Website/Package.swift
 create mode 100644 Services/Website/README.md
 create mode 100644 Services/Website/Sources/App/App+build.swift
 create mode 100644 Services/Website/Sources/App/App.swift
 create mode 100644 Services/Website/Sources/Library/Library.swift
 create mode 100644 Services/Website/Tests/App/AppTests.swift
 create mode 100644 Services/Website/Tests/Library/LibraryTest.swift
 create mode 100644 Services/Website/docker-compose.override.yml
 create mode 100644 Services/Website/docker-compose.yml

diff --git a/.gitignore b/.gitignore
index 0a05440..e33ea89 100644
--- a/.gitignore
+++ b/.gitignore
@@ -47,6 +47,10 @@ playground.xcworkspace
 # NOTE: `Package.resolved` is intentionally NOT ignored — committing it locks
 # dependency versions across the team and CI.
 
+# Docker / environment
+.env
+!.env.local
+
 # Fastlane
 fastlane/report.xml
 fastlane/Preview.html
diff --git a/Services/Website/.dockerignore b/Services/Website/.dockerignore
new file mode 100644
index 0000000..5842fb7
--- /dev/null
+++ b/Services/Website/.dockerignore
@@ -0,0 +1,6 @@
+.build
+.swiftpm
+.env.local
+docker-compose.*
+Makefile
+README.md
\ No newline at end of file
diff --git a/Services/Website/.env.local b/Services/Website/.env.local
new file mode 100644
index 0000000..a3d7faa
--- /dev/null
+++ b/Services/Website/.env.local
@@ -0,0 +1,42 @@
+# Copy this file to `.env` and adjust values as needed.
+#   cp .env.example .env
+#
+# Compose reads `.env` automatically to fill the ${VAR} placeholders in
+# docker-compose.yml. The Website app ALSO reads a `.env` file at runtime via
+# swift-configuration (allowMissing: true), so any extra app config keys placed
+# here are picked up by the running service too.
+
+# --- Image / deployment -------------------------------------------------------
+
+# Host name of the container running the Website service.
+HOST_CONTAINER=containers.rock-n-code.com
+
+# Owner of the container running the Website service.
+HOST_OWNER=loud
+
+# Password for authenticating to the container registry.
+HOST_PASSWORD=
+
+# Host port mapped to the container's port 8080.
+HOST_PORT=8080
+
+# User name for authenticating to the container registry.
+HOST_USER=
+
+# Name of the Docker image to pull/run.
+IMAGE_NAME=website
+
+# Platform of the Docker image to pull/run.
+IMAGE_PLATFORM=linux/arm64
+
+# Tag of the image to pull/run. 
+# Use a semver in production; avoid `latest` so rollbacks are unambiguous.
+IMAGE_TAG=latest
+
+# --- Application config -------------------------------------------------------
+
+# Server name reported by the HTTP service.
+HTTP_SERVER_NAME=LoudWebsite
+
+# Log verbosity: trace | debug | info | notice | warning | error | critical
+LOG_LEVEL=info
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
new file mode 100644
index 0000000..a08d2fb
--- /dev/null
+++ b/Services/Website/Dockerfile
@@ -0,0 +1,87 @@
+# ================================
+# Build image
+# ================================
+FROM swift:6.3-noble AS build
+
+# Install OS updates
+RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
+    && apt-get -q update \
+    && apt-get -q dist-upgrade -y \
+    && apt-get install -y libjemalloc-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up a build area
+WORKDIR /build
+
+# First just resolve dependencies.
+# This creates a cached layer that can be reused
+# as long as your Package.swift/Package.resolved
+# files do not change.
+COPY ./Package.* ./
+RUN swift package resolve
+
+# Copy entire repo into container
+COPY . .
+
+# Build the application, with optimizations, with static linking, and using jemalloc
+RUN swift build -c release \
+    --product "Website" \
+    --static-swift-stdlib \
+    -Xlinker -ljemalloc
+
+# Switch to the staging area
+WORKDIR /staging
+
+# Copy main executable to staging area
+RUN cp "$(swift build --package-path /build -c release --show-bin-path)/Website" ./
+
+# Copy static swift backtracer binary to staging area
+RUN cp "/usr/libexec/swift/linux/swift-backtrace-static" ./
+
+# Copy resources bundled by SPM to staging area
+RUN find -L "$(swift build --package-path /build -c release --show-bin-path)/" -regex '.*\.resources$' -exec cp -Ra {} ./ \;
+
+# Copy any resouces from the public directory and views directory if the directories exist
+# Ensure that by default, neither the directory nor any of its contents are writable.
+RUN [ -d /build/public ] && { mv /build/public ./public && chmod -R a-w ./public; } || true
+
+# ================================
+# Run image
+# ================================
+FROM ubuntu:noble
+
+# Make sure all system packages are up to date, and install only essential packages.
+RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
+    && apt-get -q update \
+    && apt-get -q dist-upgrade -y \
+    && apt-get -q install -y \
+      libjemalloc2 \
+      ca-certificates \
+      tzdata \
+# If your app or its dependencies import FoundationNetworking, also install `libcurl4`.
+      # libcurl4 \
+# If your app or its dependencies import FoundationXML, also install `libxml2`.
+      # libxml2 \
+    && rm -r /var/lib/apt/lists/*
+
+# Create a hummingbird user and group with /app as its home directory
+RUN useradd --user-group --create-home --system --skel /dev/null --home-dir /app hummingbird
+
+# Switch to the new home directory
+WORKDIR /app
+
+# Copy built executable and any staged resources from builder
+COPY --from=build --chown=hummingbird:hummingbird /staging /app
+
+# Provide configuration needed by the built-in crash reporter and some sensible default behaviors.
+ENV SWIFT_BACKTRACE=enable=yes,sanitize=yes,threads=all,images=all,interactive=no,swift-backtrace=./swift-backtrace-static
+
+# Ensure all further commands run as the hummingbird user
+USER hummingbird:hummingbird
+
+# Let Docker bind to port 8080
+EXPOSE 8080
+
+# Start the Hummingbird service when the image is run, default to listening on 8080 in production environment
+ENTRYPOINT ["./Website"]
+CMD ["--http-host", "0.0.0.0", "--http-port", "8080"]
diff --git a/Services/Website/Makefile b/Services/Website/Makefile
new file mode 100644
index 0000000..98cb6b7
--- /dev/null
+++ b/Services/Website/Makefile
@@ -0,0 +1,107 @@
+# Website service — operational commands
+# --- Configuration ------------------------------------------------------------
+
+# Load configuration from .env (the same file Compose reads).
+ENV_FILE := $(if $(wildcard .env),.env,.env.local)
+include $(ENV_FILE)
+export
+
+# Variables
+IMAGE_URL := $(HOST_CONTAINER)/$(HOST_OWNER)/$(IMAGE_NAME)
+
+# Arguments
+override version ?= $(IMAGE_TAG)
+
+# Show help if no target is specified.
+.DEFAULT_GOAL := help
+
+# --- Swift package ------------------------------------------------------------
+
+.PHONY: pkg-build
+pkg-build: ## Build the Swift package
+	@swift build
+
+.PHONY: pkg-release
+pkg-release: ## Release the Swift package
+	@swift build -c release
+
+.PHONY: pkg-test
+pkg-test: ## Run the Swift package tests
+	@swift test \
+		--disable-xctest \
+		--enable-code-coverage \
+		--enable-swift-testing \
+		--parallel
+
+.PHONY: pkg-clean
+pkg-clean: ## Remove the Swift build artifacts
+	@swift package clean
+
+.PHONY: pkg-reset
+pkg-reset: ## Resets the complete SPM cache/build folder
+	@swift package reset
+
+.PHONY: pkg-deps
+pkg-deps: ## Lists the SPM package dependencies
+	@swift package show-dependencies
+
+.PHONY: pkg-outdated
+pkg-outdated: ## Lists the SPM package dependencies that can be updated
+	@swift package update --dry-run
+
+.PHONY: pkg-update
+pkg-update: ## Updates the SPM package dependencies
+	@swift package update
+
+# --- Local development --------------------------------------------------------
+
+.PHONY: img-build
+img-build: ## Build the local dev image
+	@docker compose build
+
+.PHONY: img-mount
+img-mount: ## Mount the service locally (build if needed)
+	@docker compose up --build --detach
+
+.PHONY: img-unmount
+img-unmount: ## Unmount and remove the local service
+	@docker compose down
+	@$(MAKE) img-remove
+
+# --- Registry deployment ------------------------------------------------------
+
+.PHONY: img-release
+img-release: ## Build the production (amd64) image, tag with version + latest, push both
+	@if [ -z "$(version)" ] || [ "$(version)" = "latest" ]; then \
+		echo "Error: 'version' must be an explicit tag — e.g. make img-release version=1.2.3"; \
+		exit 1; \
+	fi
+	@docker build \
+		--platform $(IMAGE_PLATFORM) \
+		--tag $(IMAGE_URL):$(version) \
+		--tag $(IMAGE_URL):latest \
+		.
+	@echo "${HOST_PASSWORD}" \
+		| docker login $(HOST_CONTAINER) \
+			--username $(HOST_USER) \
+			--password-stdin
+	@docker push $(IMAGE_URL):$(version)
+	@docker push $(IMAGE_URL):latest
+	@docker logout $(HOST_CONTAINER)
+	@$(MAKE) img-remove
+
+.PHONY: img-remove
+img-remove: # Removes the generated Docker images
+	@images="$$(docker image ls --format '{{.Repository}}:{{.Tag}}' | grep '$(IMAGE_NAME)' | awk '{print $$1}')"; \
+	if [ -n "$$images" ]; then \
+		docker image rm --force $$images; \
+	else \
+		echo "No '$(IMAGE_NAME)' images to remove."; \
+	fi
+
+# --- Meta ---------------------------------------------------------------------
+
+.PHONY: help
+help: ## Show available commands
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
new file mode 100644
index 0000000..a6d6bf0
--- /dev/null
+++ b/Services/Website/Package.swift
@@ -0,0 +1,74 @@
+// swift-tools-version:6.3
+
+import PackageDescription
+
+let package = Package(
+    name: "Website",
+    platforms: [
+        .macOS(.v15),
+        .iOS(.v18),
+        .tvOS(.v18),
+    ],
+    products: [
+        .executable(
+            name: "Website",
+            targets: [
+                "Website",
+                "WebsiteCore",
+            ]
+        )
+    ],
+    dependencies: [
+        .package(
+            url: "https://github.com/hummingbird-project/hummingbird.git",
+            from: "2.25.0"
+        ),
+        .package(
+            url: "https://github.com/apple/swift-configuration.git",
+            from: "1.0.0",
+            traits: [
+                .defaults,
+                "CommandLineArguments",
+            ]
+        ),
+    ],
+    targets: [
+        .executableTarget(
+            name: "Website",
+            dependencies: [
+                .product(
+                    name: "Configuration",
+                    package: "swift-configuration"
+                ),
+                .product(
+                    name: "Hummingbird",
+                    package: "hummingbird"
+                ),
+            ],
+            path: "Sources/App"
+        ),
+        .target(
+            name: "WebsiteCore",
+            dependencies: [],
+            path: "Sources/Library"
+        ),
+        .testTarget(
+            name: "WebsiteTests",
+            dependencies: [
+                .product(
+                    name: "HummingbirdTesting",
+                    package: "hummingbird"
+                ),
+                .byName(name: "Website"),
+            ],
+            path: "Tests/App"
+        ),
+        .testTarget(
+            name: "WebsiteCoreTests",
+            dependencies: [
+                .byName(name: "WebsiteCore"),
+            ],
+            path: "Tests/Library"
+        ),
+    ]
+)
diff --git a/Services/Website/README.md b/Services/Website/README.md
new file mode 100644
index 0000000..eb5764d
--- /dev/null
+++ b/Services/Website/README.md
@@ -0,0 +1,2 @@
+# Website
+Hummingbird server framework project
\ No newline at end of file
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
new file mode 100644
index 0000000..d5df224
--- /dev/null
+++ b/Services/Website/Sources/App/App+build.swift
@@ -0,0 +1,62 @@
+import Configuration
+import Hummingbird
+import Logging
+
+///  Build application
+/// - Parameter reader: configuration reader
+func application(
+    reader: ConfigReader
+) async throws -> some ApplicationProtocol {
+    let logLevel = reader.string(
+        forKey: "log.level",
+        as: Logger.Level.self,
+        default: .info
+    )
+    let serverName = reader.string(
+        forKey: "http.serverName",
+        default: "LoudWebsite"
+    )
+
+    return Application(
+        router: try router(),
+        configuration: ApplicationConfiguration(
+            reader: reader.scoped(to: "http")
+        ),
+        logger: logger(
+            serverName: serverName,
+            logLevel: logLevel
+        )
+    )
+}
+
+// MARK: - Helpers
+
+// Request context used by application
+private typealias AppRequestContext = BasicRequestContext
+
+/// Build logger
+private func logger(
+    serverName: String,
+    logLevel: Logger.Level
+) -> Logger {
+    var logger = Logger(label: serverName)
+
+    logger.logLevel = logLevel
+
+    return logger
+}
+
+/// Build router
+private func router() throws -> Router<AppRequestContext> {
+    let router = Router(context: AppRequestContext.self)
+
+    router.addMiddleware {
+        LogRequestsMiddleware(.info)
+    }
+
+    router.get("/") { _, _ in
+        return "Hello!"
+    }
+
+    return router
+}
diff --git a/Services/Website/Sources/App/App.swift b/Services/Website/Sources/App/App.swift
new file mode 100644
index 0000000..c46a698
--- /dev/null
+++ b/Services/Website/Sources/App/App.swift
@@ -0,0 +1,28 @@
+import Configuration
+import Hummingbird
+import Logging
+
+@main
+struct App {
+    static func main() async throws {
+        let reader = try await ConfigReader(
+            providers: [
+                CommandLineArgumentsProvider(),
+                EnvironmentVariablesProvider(),
+                EnvironmentVariablesProvider(
+                    environmentFilePath: ".env",
+                    allowMissing: true
+                ),
+                InMemoryProvider(values: [
+                    "http.serverName": "LoudWebsite"
+                ]),
+            ]
+        )
+
+        let app = try await application(
+            reader: reader
+        )
+
+        try await app.runService()
+    }
+}
diff --git a/Services/Website/Sources/Library/Library.swift b/Services/Website/Sources/Library/Library.swift
new file mode 100644
index 0000000..139597f
--- /dev/null
+++ b/Services/Website/Sources/Library/Library.swift
@@ -0,0 +1,2 @@
+
+
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
new file mode 100644
index 0000000..379de9f
--- /dev/null
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -0,0 +1,34 @@
+import Configuration
+import Hummingbird
+import HummingbirdTesting
+import Logging
+import Testing
+
+@testable import Website
+
+private let reader = ConfigReader(providers: [
+    InMemoryProvider(values: [
+        "http.host": "127.0.0.1",
+        "http.port": "0",
+        "log.level": "trace",
+    ])
+])
+
+@Suite
+struct AppTests {
+    @Test
+    func hello() async throws {
+        let app = try await application(
+            reader: reader
+        )
+
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                #expect(response.body == ByteBuffer(string: "Hello!"))
+            }
+        }
+    }
+}
diff --git a/Services/Website/Tests/Library/LibraryTest.swift b/Services/Website/Tests/Library/LibraryTest.swift
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/Services/Website/Tests/Library/LibraryTest.swift
@@ -0,0 +1 @@
+
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
new file mode 100644
index 0000000..22467b1
--- /dev/null
+++ b/Services/Website/docker-compose.override.yml
@@ -0,0 +1,18 @@
+# Local development overrides.
+# Compose merges this file on top of docker-compose.yml automatically, so a
+# plain `docker compose up` builds from source instead of pulling a registry image:
+#
+#   docker compose up --build       # build locally and run
+#   docker compose up -d            # reuse the last local build
+#
+# It reuses the `image:` name from the base file, so the local build is tagged
+# the same way the production image would be.
+services:
+  website:
+    image: ${IMAGE_NAME}:${IMAGE_TAG:-latest}
+    platform: linux/arm64
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      LOG_LEVEL: debug
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
new file mode 100644
index 0000000..8a29503
--- /dev/null
+++ b/Services/Website/docker-compose.yml
@@ -0,0 +1,22 @@
+name: loud-platform
+
+# Production base configuration.
+# Deploys a pre-built image pulled from a registry — no build step.
+#
+#   docker compose -f docker-compose.yml pull
+#   docker compose -f docker-compose.yml up -d
+#
+# The `-f docker-compose.yml` flag is important in production: it skips the
+# docker-compose.override.yml file, which Compose would otherwise merge in
+# automatically for local development.
+services:
+  website:
+    image: ${HOST_CONTAINER}/${HOST_OWNER}/${IMAGE_NAME}:${IMAGE_TAG:-latest}
+    platform: linux/amd64
+    container_name: ${HOST_OWNER}-${IMAGE_NAME}
+    restart: unless-stopped
+    ports:
+      - "${HOST_PORT:-8080}:8080"
+    environment:
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-LoudWebsite}
-- 
2.54.0


From 7542bc595fd79a6a972898cd21be1455cbf76955 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 27 Jun 2026 10:59:32 +0000
Subject: [PATCH 004/117] Static file serving support for the Website service
 (#3)

This PR contains the work done to support the static files serving for the **Website** service, and also included the essential boilerplate assets from the **HTML5 boilerplate** project.

To provide further details about the work done:

* Serving: Added the `FileMiddleware` middlewqare to the router; `path`, `server name`, and `log level` now read from config with defaults.
* Library: Added the `StaticFile` enumeration with a `contentType` property, plus typed config-key/value constants and the `Configuration` dependency on WebsiteCore.
* Assets: Added the **HTML5 boilerplate** (HTML, CSS, JS, icons, manifest, robots) to the *Resources/Static* folder.
* Docker: Stage the Resources directory as read-only.
* Tests: Added a test plan, and a shared Xcode scheme.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/3
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/.dockerignore                |   1 +
 .../xcshareddata/xcschemes/Website.xcscheme   |  92 +++++++
 Services/Website/Dockerfile                   |   4 +-
 Services/Website/Package.swift                |  10 +-
 Services/Website/Resources/Static/404.html    |  62 +++++
 .../Website/Resources/Static/css/style.css    | 246 ++++++++++++++++++
 Services/Website/Resources/Static/favicon.ico | Bin 0 -> 766 bytes
 Services/Website/Resources/Static/icon.png    | Bin 0 -> 4029 bytes
 Services/Website/Resources/Static/icon.svg    |   1 +
 Services/Website/Resources/Static/index.html  |  33 +++
 Services/Website/Resources/Static/js/app.js   |   0
 Services/Website/Resources/Static/robots.txt  |   5 +
 .../Website/Resources/Static/site.webmanifest |  12 +
 Services/Website/Sources/App/App+build.swift  |  55 +++-
 Services/Website/Sources/App/App.swift        |   2 +-
 .../Internal/Enumerations/StaticFile.swift    | 166 ++++++++++++
 .../Website/Sources/Library/Library.swift     |   2 -
 .../AbsoluteConfigKey+Constants.swift         |  23 ++
 .../Extensions/ConfigKey+Constants.swift      |  23 ++
 .../Extensions/ConfigValue+Constants.swift    |  18 ++
 .../Public/Extensions/String+Constants.swift  |  12 +
 Services/Website/Tests/App/AppTests.swift     |  63 ++++-
 .../Enumerations/StaticFileTests.swift        | 141 ++++++++++
 .../Website/Tests/Library/LibraryTest.swift   |   1 -
 Services/Website/Website.xctestplan           |  37 +++
 25 files changed, 973 insertions(+), 36 deletions(-)
 create mode 100644 Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
 create mode 100644 Services/Website/Resources/Static/404.html
 create mode 100644 Services/Website/Resources/Static/css/style.css
 create mode 100644 Services/Website/Resources/Static/favicon.ico
 create mode 100644 Services/Website/Resources/Static/icon.png
 create mode 100644 Services/Website/Resources/Static/icon.svg
 create mode 100644 Services/Website/Resources/Static/index.html
 create mode 100644 Services/Website/Resources/Static/js/app.js
 create mode 100644 Services/Website/Resources/Static/robots.txt
 create mode 100644 Services/Website/Resources/Static/site.webmanifest
 create mode 100644 Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
 delete mode 100644 Services/Website/Sources/Library/Library.swift
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/ConfigValue+Constants.swift
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
 delete mode 100644 Services/Website/Tests/Library/LibraryTest.swift
 create mode 100644 Services/Website/Website.xctestplan

diff --git a/Services/Website/.dockerignore b/Services/Website/.dockerignore
index 5842fb7..1f3233b 100644
--- a/Services/Website/.dockerignore
+++ b/Services/Website/.dockerignore
@@ -1,5 +1,6 @@
 .build
 .swiftpm
+.DS_Store
 .env.local
 docker-compose.*
 Makefile
diff --git a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
new file mode 100644
index 0000000..01a4a46
--- /dev/null
+++ b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
@@ -0,0 +1,92 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "2700"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "Website"
+               BuildableName = "Website"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <TestPlans>
+         <TestPlanReference
+            reference = "container:Website.xctestplan"
+            default = "YES">
+         </TestPlanReference>
+      </TestPlans>
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "WebsiteTests"
+               BuildableName = "WebsiteTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES"
+      queueDebuggingEnabled = "No">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "Website"
+            BuildableName = "Website"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "Website"
+            BuildableName = "Website"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index a08d2fb..e3f71bf 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -41,9 +41,9 @@ RUN cp "/usr/libexec/swift/linux/swift-backtrace-static" ./
 # Copy resources bundled by SPM to staging area
 RUN find -L "$(swift build --package-path /build -c release --show-bin-path)/" -regex '.*\.resources$' -exec cp -Ra {} ./ \;
 
-# Copy any resouces from the public directory and views directory if the directories exist
+# Copy the static files directory (served by FileMiddleware) if it exists
 # Ensure that by default, neither the directory nor any of its contents are writable.
-RUN [ -d /build/public ] && { mv /build/public ./public && chmod -R a-w ./public; } || true
+RUN [ -d /build/Resources ] && { mv /build/Resources ./Resources && chmod -R a-w ./Resources; } || true
 
 # ================================
 # Run image
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index a6d6bf0..e44f6bb 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -36,6 +36,7 @@ let package = Package(
         .executableTarget(
             name: "Website",
             dependencies: [
+                .byName(name: "WebsiteCore"),
                 .product(
                     name: "Configuration",
                     package: "swift-configuration"
@@ -49,17 +50,22 @@ let package = Package(
         ),
         .target(
             name: "WebsiteCore",
-            dependencies: [],
+            dependencies: [
+                .product(
+                    name: "Configuration",
+                    package: "swift-configuration"
+                ),
+            ],
             path: "Sources/Library"
         ),
         .testTarget(
             name: "WebsiteTests",
             dependencies: [
+                .byName(name: "Website"),
                 .product(
                     name: "HummingbirdTesting",
                     package: "hummingbird"
                 ),
-                .byName(name: "Website"),
             ],
             path: "Tests/App"
         ),
diff --git a/Services/Website/Resources/Static/404.html b/Services/Website/Resources/Static/404.html
new file mode 100644
index 0000000..260cc4c
--- /dev/null
+++ b/Services/Website/Resources/Static/404.html
@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>Page Not Found</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    * {
+      line-height: 1.2;
+      margin: 0;
+    }
+
+    html {
+      color: #888;
+      display: table;
+      font-family: sans-serif;
+      height: 100%;
+      text-align: center;
+      width: 100%;
+    }
+
+    body {
+      display: table-cell;
+      vertical-align: middle;
+      margin: 2em auto;
+    }
+
+    h1 {
+      color: #555;
+      font-size: 2em;
+      font-weight: 400;
+    }
+
+    p {
+      margin: 0 auto;
+      width: 280px;
+    }
+
+    @media only screen and (max-width: 280px) {
+
+      body,
+      p {
+        width: 95%;
+      }
+
+      h1 {
+        font-size: 1.5em;
+        margin: 0 0 0.3em;
+      }
+
+    }
+  </style>
+</head>
+
+<body>
+  <h1>Page Not Found</h1>
+  <p>Sorry, but the page you were trying to view does not exist.</p>
+</body>
+
+</html>
+<!-- IE needs 512+ bytes: https://docs.microsoft.com/archive/blogs/ieinternals/friendly-http-error-pages -->
diff --git a/Services/Website/Resources/Static/css/style.css b/Services/Website/Resources/Static/css/style.css
new file mode 100644
index 0000000..ba80dc8
--- /dev/null
+++ b/Services/Website/Resources/Static/css/style.css
@@ -0,0 +1,246 @@
+/*! HTML5 Boilerplate v9.0.1 | MIT License | https://html5boilerplate.com/ */
+
+/* main.css 3.0.0 | MIT License | https://github.com/h5bp/main.css#readme */
+/*
+ * What follows is the result of much research on cross-browser styling.
+ * Credit left inline and big thanks to Nicolas Gallagher, Jonathan Neal,
+ * Kroc Camen, and the H5BP dev community and team.
+ */
+
+/* ==========================================================================
+   Base styles: opinionated defaults
+   ========================================================================== */
+
+html {
+  color: #222;
+  font-size: 1em;
+  line-height: 1.4;
+}
+
+/*
+ * Remove text-shadow in selection highlight:
+ * https://twitter.com/miketaylr/status/12228805301
+ *
+ * Customize the background color to match your design.
+ */
+
+::-moz-selection {
+  background: #b3d4fc;
+  text-shadow: none;
+}
+
+::selection {
+  background: #b3d4fc;
+  text-shadow: none;
+}
+
+/*
+ * A better looking default horizontal rule
+ */
+
+hr {
+  display: block;
+  height: 1px;
+  border: 0;
+  border-top: 1px solid #ccc;
+  margin: 1em 0;
+  padding: 0;
+}
+
+/*
+ * Remove the gap between audio, canvas, iframes,
+ * images, videos and the bottom of their containers:
+ * https://github.com/h5bp/html5-boilerplate/issues/440
+ */
+
+audio,
+canvas,
+iframe,
+img,
+svg,
+video {
+  vertical-align: middle;
+}
+
+/*
+ * Remove default fieldset styles.
+ */
+
+fieldset {
+  border: 0;
+  margin: 0;
+  padding: 0;
+}
+
+/*
+ * Allow only vertical resizing of textareas.
+ */
+
+textarea {
+  resize: vertical;
+}
+
+/* ==========================================================================
+   Author's custom styles
+   ========================================================================== */
+
+/* ==========================================================================
+   Helper classes
+   ========================================================================== */
+
+/*
+ * Hide visually and from screen readers
+ */
+
+.hidden,
+[hidden] {
+  display: none !important;
+}
+
+/*
+ * Hide only visually, but have it available for screen readers:
+ * https://snook.ca/archives/html_and_css/hiding-content-for-accessibility
+ *
+ * 1. For long content, line feeds are not interpreted as spaces and small width
+ *    causes content to wrap 1 word per line:
+ *    https://medium.com/@jessebeach/beware-smushed-off-screen-accessible-text-5952a4c2cbfe
+ */
+
+.visually-hidden {
+  border: 0;
+  clip: rect(0, 0, 0, 0);
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  padding: 0;
+  position: absolute;
+  white-space: nowrap;
+  width: 1px;
+  /* 1 */
+}
+
+/*
+ * Extends the .visually-hidden class to allow the element
+ * to be focusable when navigated to via the keyboard:
+ * https://www.drupal.org/node/897638
+ */
+
+.visually-hidden.focusable:active,
+.visually-hidden.focusable:focus {
+  clip: auto;
+  height: auto;
+  margin: 0;
+  overflow: visible;
+  position: static;
+  white-space: inherit;
+  width: auto;
+}
+
+/*
+ * Hide visually and from screen readers, but maintain layout
+ */
+
+.invisible {
+  visibility: hidden;
+}
+
+/*
+ * Clearfix: contain floats
+ *
+ * The use of `table` rather than `block` is only necessary if using
+ * `::before` to contain the top-margins of child elements.
+ */
+
+.clearfix::before,
+.clearfix::after {
+  content: "";
+  display: table;
+}
+
+.clearfix::after {
+  clear: both;
+}
+
+/* ==========================================================================
+   EXAMPLE Media Queries for Responsive Design.
+   These examples override the primary ('mobile first') styles.
+   Modify as content requires.
+   ========================================================================== */
+
+@media only screen and (min-width: 35em) {
+  /* Style adjustments for viewports that meet the condition */
+}
+
+@media print,
+  (min-resolution: 1.25dppx),
+  (min-resolution: 120dpi) {
+  /* Style adjustments for high resolution devices */
+}
+
+/* ==========================================================================
+   Print styles.
+   Inlined to avoid the additional HTTP request:
+   https://www.phpied.com/delay-loading-your-print-css/
+   ========================================================================== */
+
+@media print {
+  *,
+  *::before,
+  *::after {
+    background: #fff !important;
+    color: #000 !important;
+    /* Black prints faster */
+    box-shadow: none !important;
+    text-shadow: none !important;
+  }
+
+  a,
+  a:visited {
+    text-decoration: underline;
+  }
+
+  a[href]::after {
+    content: " (" attr(href) ")";
+  }
+
+  abbr[title]::after {
+    content: " (" attr(title) ")";
+  }
+
+  /*
+   * Don't show links that are fragment identifiers,
+   * or use the `javascript:` pseudo protocol
+   */
+  a[href^="#"]::after,
+  a[href^="javascript:"]::after {
+    content: "";
+  }
+
+  pre {
+    white-space: pre-wrap !important;
+  }
+
+  pre,
+  blockquote {
+    border: 1px solid #999;
+    page-break-inside: avoid;
+  }
+
+  tr,
+  img {
+    page-break-inside: avoid;
+  }
+
+  p,
+  h2,
+  h3 {
+    orphans: 3;
+    widows: 3;
+  }
+
+  h2,
+  h3 {
+    page-break-after: avoid;
+  }
+}
+
diff --git a/Services/Website/Resources/Static/favicon.ico b/Services/Website/Resources/Static/favicon.ico
new file mode 100644
index 0000000000000000000000000000000000000000..be74abd69ad6a32de7375df13cab9354798e328f
GIT binary patch
literal 766
zcmc(dze~eV5XUd2fg&jH87YDYDQKxq1{4b-_ydP-wqS9vgGh17QXQQAwOE{VaBvi*
zmu^z9t({y-&1ey<?*19x`_a%0;^>8Y_x;?x+`BviV9;aRjMgZ8M*!jgkRrFqSI9;F
zHyfX@Az|AvVmn~YWWZP`0&JWEY~BFm?*Vq}VD7&_%x%MP$p`D`4JMC!K|B7pt?Mmp
zUJAB7rxMXS6=!P+AtLU9V)J#61WPxwipRXCHO{BJ`l{m53#=t97a!znv~vfmr|AaP
zRGIT7#0FyJy3Z*hL{GQp-0TRhX8UzZ)+>%?mK0^goaX4Q;x<h|7I8a@t8#9Z`A~@1
zIx{#+`h7(7bA0+s7#-k=_?cTQZjqG{+al%<xj`*i0llsi@&x*V=JS=7GQ@hVV0w`-
td#$W2=*99o&LFePcYQf3%L?7WGUv;WVIDdObG#I0%L#Kp!H@7y;s@Y5ipBr{

literal 0
HcmV?d00001

diff --git a/Services/Website/Resources/Static/icon.png b/Services/Website/Resources/Static/icon.png
new file mode 100644
index 0000000000000000000000000000000000000000..8a42581d4a2a2a28bee1888835d21ffe4d6378d0
GIT binary patch
literal 4029
zcma)9c{CJU+-8i7DZ7xZ8I2`GWQk%1lRYM~MW$%%yP>koG_P!lF_<icv1Q8=Le@&i
z&e#>+$k;;moo~MP{oen-d(OT0oZo$ZzjM$1-E*GjiAI^|v4I7_3=9lx2Kq=d`u^#E
zCkQ}aCz}pY3=AC44Uk%QpD?bZhX)E73`U%~7cQl85yvVXk(g;IUxeEq-gAn`O#OGr
z&lO(^T_yYT*6U?-xaqF>yQNy04owaZTcEWi85lr72<I~d1Ar04tH}TaaDosJhW{eK
z{{jSte<5@%!#@bZKPTl6Y=Dq>tIo@UX7J#rUIBw~lJs={CYso;p)qnluna#RzIviF
z@XZ9aXw3jLGsYiRA9QXSBQ0g8nvapf3GwJckKb+73+ey{f{A?pDZc1rRRp8J`eE{{
z12JxDMe;-X+2{~b8vxQ@V~^p|pRo&j-hK3?0HH28U;1{w2ngwys?NrTti=FA`$T!T
zWQv0~2?Ezt()hh=Kb*P7^9=EYtP-u>vPa~wP}kMQgxcDviA`8}&)>U$C)P<Av=ypq
zGc>UNAT?UbMk-poy=~^hjqHKnI3X=cZp-P;XD9*pla$REW99w&It*Gp-~k}4%869y
z&75l9QBIC77(y%a7F0CpRI&mOI)cS|2G^(9c}R(dLg1mseUuF!Fip+R_aKwl4%%uj
zlX2n}oG-heo>Vvj?eAXyA{Zm*=ok=ZaL!#;5M1SRAVx>y)(5UJAJiEcBVWyKd1<I{
z=~oO_2AqNkH0oA!W`Q#+tngO5SXNzV?;j(5uZPh7bL%5~F;aTZVFJt_>#y?aD-LnG
zMC`33$8jx0dMU7WPc|M#u(wXi0@GOU?K}P^?X3|lR7|v=Vg^wZDpj2x*3|TGKydpR
zU&=<7K9K64`B2||j*v}!6l4rM7?yl-rb=#F2`gn$il9VYQWGV$TuoDx$aZ)<j-u?F
z=R;9jU70=139WHax!3P0YUqv%9uku<I+Unn`0KM<{NB>EpYE|T5oqmIZ63g_SCfJl
zigFx_JCR8xHRqU%GC!Uph;`N2Vafm<Xl-O?HRh>e<A^>Ciuy_~JBx;+d|yA`?-``$
zhxc*=UqF&=VcN!=!6Mvdc`vdMB}S@H6mb6}R5=v^$0bKcrSg|eD>sgOqy1k2yyl%&
zUe>(103E_Fj1uq#@8g4s41<|rHi>NOHhSwSA7`dOQP{oc`Xw0Pc*N+%8U68yES-U;
zZD2x$?}_*Qlbf#CvoPL?P#r>%tuqvbd{Uvle~>rZ)hFUM?dw5rky$kpLCpTdLll3^
zXZr$pIZO43yL03_r_{_`U&f3_di1vvm2=Dq5u%(@TMZvOn#L}zr;nyajZs%_#BoTb
z{)KobkGI6J!cuc{b+j>#?I?=FV`jjuhNE%wA1jIRvPo>r3A$G~rM`w>C!7g58si{?
zLQ8)ZXH9z;0)LdYVFei{_T?E!?Y#W{_?@Q?CH@sWk+`(*B>21SVO;MNlO-4sPAqHs
zqy^eyDN`i1?}%)k<>Cj?FX!;lSi5Ohfw!PKR1^^YQsn-LFe0R<_2FS$%ELqUkH_)w
z3xM!w@1`%GS+_XWq>V_Z?`qzA;z{m-5L9hvCet0g_B=k0x`a{VGG#ftNCb50q?<5t
z33^P3jw0V1Yb^JnB^W$+Iv<9Zer(Qsr5}&WRqX3w0VTzegy62fX72hEiI(=sa26q=
z)wefEn@1-cNoK+T!UpR>VX$V%IZ*T9T{ne`3EmK=1ULUlS=CxZ3jZ6J2X(B__#H}u
zR%riaMEc0t8(8%S(rt8m2$$>%ydzm(N4`JVyEXDAgp`_p2h!NOPYAuf^)Y<t=5S^1
z!!8qL_3U1kM|H&}D)2nO;@t1%_isW)yDWc5#F9H79V|O^kLiCntSG&`cG=^jF@8f`
zbLf+fDsF5!J|cB?uBg63JX=_#&}q~VmcJ#CiCqZZ0ib(1oA<Nt`53fRC%SDT*$1u1
z4dtrHJg=!Y`zJM-lV56uY+7JssAI09E8bCjQ;sq=p3>h_+mH@7`kD{Hn!h2huDs=X
zG~T&{anJTiR^{<mwj3G4WIOVOu82=JMRGQ;XBUasS5sG-1pYRvHOhC$16QWi6~A1L
zIqF-RorT}|CUt8+>xs*_pZ^Bw5JQaHvkMSh`%)x#y2KN~lGxhZQ066kuiDyDczU=)
z&fBobH^_VT$}MzY+-cvejN{j`=Bom;LC^dg61vtWGqz?bUbO0<dVTYH>IUbMfUiov
zhNP$Hm~$v4zeNX~gU3bVpP1hFP!##}?w8}veUZnmEhf$_RwyTh&?jk`lS)iod{%nN
zCDwMY1g2L=AyvH$;l_|j)f4ZjHa``o@d{p7hmQ_{n8C-vuwZ0&mb`0^NU32<ML?65
zpd~@pHgz>E-B>SILeRoh9rqKOJZQ{fy^efaIdh8pI0Ccek}X1~4_dfdSAXl^`xW&0
zRLQiIbI$6*qCn{BZ;QMRp;mu3iCD9aa7zZ)4Drx)Q5(XR-wyg>Pj|((eyp6WbVgF$
z=f4MUa-G+&y!!%YktS=44wUQ180A0xVH0AVf?cT3u_f>9t`$|XiE4P}Ev?YOBu<cp
zEBq7{t9ew(efg>K&q@s$TeB3c?&tYER|*Y-)x?(ci?lb^UT`!w*o<%7=&3B4=_t_f
z)U}wHZp`VGeJN}EitL8{%XAY#(Z8E_{F}+bnAB$YR`Gsj@|E#tT`IzpYT1_L9eCzT
z+iJ^DdaFItX#@mUk>O!+%@FPACreI`7sOT6VT)x$MROOPuQ|SVL*7@#L{NrI|LXLF
z1ED|(BYOfO9CjOjWdPk!xbW<W>(usP75SZf1!e$<py<i`9AgbQtCTy0cDJu3p*I&}
zoH6DqW=aa23wmCWI+WeOlru2D@Q1}cwD9HD?R1`%<Qp=QK_l#hnLronpjoOR3s%>u
zS5<CG$|Q}Zwm1X?Vc&N^>lD(B2ID&qstc|OmUOAcxZh}V%`mU4=KyXLhdlw!tV<6*
z!{({uC}VTS)PvsluA)2QJxqiYg9I5Uw?1unxjts~B<DT5K~?EZogDHN_~1=WmqO&v
zPNb2q9W@I|R{-rVRT~2HtD2T^uV^;AA72Xq4}4TZYKlhrQqO$j^=Y}BnmqvNaZGGR
zP^Lo^UTT~>&sILmy54e?>c9C*p0nT$JI4FWg+m7gHWD^F3*qM$hS1!6qWsQ6%huv8
zqayPU6s0#dn9h1fzuMO#EGT8y+m#?RTDO%#2U-UL=jlH^$pRN5HoiS)w;sB@IGf#2
z#ZEZ7$jC=^nM*y>UE+BGJk;cO7O>w|W5-s5@b*+-(<jT&imhd1Z^mCN7yT?eu{YOl
z*bG=+g)8w&HIGFinyTz6<;|V(;9BhjplMDJMo9y>K_K=ae?I+rj7d-MqL-{cMpB8K
z3%N%-Mg;hNFnbRM_p3Ua(Nb2<NkARO51}93R%5!2h*1|J&##Bvp>hVjc`*CKg3fhd
zK0taD|LFDphqeZ<m8`yRnXWNwdfH22U){EPZ%ZW83A$syFjz|&)<Bhr&EUGz(Jv2Y
z_vq{;hb3VpmVY{YFbhNQBw(*cNj`vYKI<wZy?rqJmUr5^1KWQ;YA(D1mnV%8iU9Ov
zPJ|<P{64H~GTLK9f@97T*Gd&9jsk0R@yD-Di|6l!yCVLP8mm)G4iSjNKP#h0M<D#E
z#jyN)`>HlgbJLoj&Oj{xOlIwJB_cCJP2V8-W^Qg`xFT@lrNhDZn$Tbf)ck~d=i9dg
z%e8`DpHvS-%kx_fo<6%YroouuIX2L*)NSzLht1l4SnMnf$z^)`tYwIZ#5+B#RZXuT
z7$zh^N0=V#BToN#l4CAT$OpSz8(Vt6vNu(|{=wXs>Bqg6mR7g6aKzMJV`8k`F_B}q
zSSYfdE6_?(0C>48wb@fBuYT>b;nG&DIkk0_ey>j<5hmC3OGww&bQiLQ{bc%@kGV7d
z&|pHlZxX!hYS{@l|7@t=4p}RiuUaH5H7Nx<OR7v%ufzCdA0HSq<vwT$Ilt-i9!$U;
zXqpa@^{mR5x$r`oJJ71hBbUr#{F|+**~8rc!wF@6sZs0a2wj-xK^akE|E^sl+KK#5
z`FKsz%Jb^x!mTxV%{1f|{t%_c$3~*kyUrIVuMN56g&kYIesUu;?6^WJ1s19MKIuoW
zv0|xVpEXICn1!gARdLhgAT(`8M4HZ6Wfr8lm!sMJJU#^u`wy(B+BpeAY@9YNx=ZL1
zb-l!TuINWYbg6O$+N9<Hw~JO;kxY&mBu+i_Cm^qjN`L(^e(knFpLa$CqTR=BYT;-*
zvTVaot(-Jgcj_lA`lGfekDIN~D?@=--wU2{9;gmp1bW^D(R?VCx9B7%mhq0I=VG%H
zEIuTZ%22Ze6;GG$)uQC=g<0({aN(^cat<-4kyRbSfcrv97ks}LAS~S)U7uBG<mTqF
z0|6R|X~9DW;vHFjX~*O8Eby{NW&TGY92ys!a65Eu7&E$xpg4;KgA%o`Rv%v!g0KX%
z_h`)Ti^`W=%+39-!NFhb#SVy_pBIfQ%UUE~??3h{8eo-bbtudMKf)h~4l+olD)JYM
z*%A=5EUKrw?T)$*H!Po3?rm#npn6B1dicJ11i7XlC>D!nV|KG|U?jA82`&_Bmv6FB
zr8HvTl(3*bmo#xpQz>&EWjeIWt|BIi%!CZ5Du?ArFJBd}4D`+lMfAvSGk;B^DcCeW
z*N6s~OA`TMK}MnLeuvWm(3I0d%w|{+rBQ6JZ)(pNqE=|*R>1#wcU1^{7w&%nAmUKp
z*0RsNE$jO0#B8SvDk$sL^!@PUxKDVZWFVd{&U@r7ue3u!x%(Ub@0{0{kNwJ3m&~t@
zhK$v$xyvmjVJGQ7zl4#X`&tTEjUJ)DPuAre+obOLcP{GUp1WRf6<&SO00boVGwx{}
z$C6~jZvWsSU$33wN`3ih6q%X8-Y?!AYXag}(!?_Mdxv(fwVLIDfr4SO4?DuE;Vc18
zV4;LrlF2rm%SWoA{ny?n6h=44=3@RL8=AWe2#QR08P}QUKu(pZEZZQ?u3B>J{Q;MX
zh#gLS_au{=AR5bd6qga)JjV=w9`KY}fWNy~Ka0YWymJO{=Yn>mfg2I&fpZ=h9EvF5
zt9qEEYa-1=kf6Hwy8c<PzBuF@g={KtcHx@{1t~$p3bTzXU;L(suS?C9bGrCF8zNl2
q1`HDY&;HU)@4uGz|LuPNJ{xA}F1aHn=0LaQ3<kGMkfquW{`w#5IHleI

literal 0
HcmV?d00001

diff --git a/Services/Website/Resources/Static/icon.svg b/Services/Website/Resources/Static/icon.svg
new file mode 100644
index 0000000..f232922
--- /dev/null
+++ b/Services/Website/Resources/Static/icon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" viewBox="0 0 192 192"><path fill="#e08524" d="M75.3 73.4H18.4l45.3 34.3L48.3 163l46.1-32.3 48.2 34.6-16.9-58.3 44.9-33.6H115l-20.5-55-19.2 55z"/><path d="m96.7 18.8 18.2 8.2 16.5 44.3h-15.1L96.7 18.8zm-47 146 18.7 9.9 42.6-29.9-16.5-11.4-44.8 31.4zm79.1-56.8 17.4 9.4 18.6 60.1-19.7-11.3-16.3-58.2z"/><path d="m173.1 74.3 17.8 9.2-44.7 34-17.4-9.4 44.3-33.8z"/></svg>
diff --git a/Services/Website/Resources/Static/index.html b/Services/Website/Resources/Static/index.html
new file mode 100644
index 0000000..f3add49
--- /dev/null
+++ b/Services/Website/Resources/Static/index.html
@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="">
+
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title></title>
+  <link rel="stylesheet" href="css/style.css">
+  <meta name="description" content="">
+
+  <meta property="og:title" content="">
+  <meta property="og:type" content="">
+  <meta property="og:url" content="">
+  <meta property="og:image" content="">
+  <meta property="og:image:alt" content="">
+
+  <link rel="icon" href="/favicon.ico" sizes="any">
+  <link rel="icon" href="/icon.svg" type="image/svg+xml">
+  <link rel="apple-touch-icon" href="icon.png">
+
+  <link rel="manifest" href="site.webmanifest">
+  <meta name="theme-color" content="#fafafa">
+</head>
+
+<body>
+
+  <!-- Add your site or application content here -->
+  <p>Hello world! This is HTML5 Boilerplate.</p>
+  <script src="js/app.js"></script>
+
+</body>
+
+</html>
diff --git a/Services/Website/Resources/Static/js/app.js b/Services/Website/Resources/Static/js/app.js
new file mode 100644
index 0000000..e69de29
diff --git a/Services/Website/Resources/Static/robots.txt b/Services/Website/Resources/Static/robots.txt
new file mode 100644
index 0000000..51d2d2e
--- /dev/null
+++ b/Services/Website/Resources/Static/robots.txt
@@ -0,0 +1,5 @@
+# https://www.robotstxt.org/
+
+# Allow crawling of all content
+User-agent: *
+Disallow:
diff --git a/Services/Website/Resources/Static/site.webmanifest b/Services/Website/Resources/Static/site.webmanifest
new file mode 100644
index 0000000..222ae16
--- /dev/null
+++ b/Services/Website/Resources/Static/site.webmanifest
@@ -0,0 +1,12 @@
+{
+  "short_name": "",
+  "name": "",
+  "icons": [{
+    "src": "icon.png",
+    "type": "image/png",
+    "sizes": "192x192"
+  }],
+  "start_url": "/?utm_source=homescreen",
+  "background_color": "#fafafa",
+  "theme_color": "#fafafa"
+}
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
index d5df224..3561f8b 100644
--- a/Services/Website/Sources/App/App+build.swift
+++ b/Services/Website/Sources/App/App+build.swift
@@ -1,24 +1,37 @@
 import Configuration
 import Hummingbird
 import Logging
+import WebsiteCore
 
-///  Build application
-/// - Parameter reader: configuration reader
+/// Builds the website application.
+///
+/// Reads the log level, server name, and static files location from the configuration,
+/// then assembles the router, server configuration, and logger.
+/// - Parameter reader: the configuration reader the values are read from.
+/// - Returns: the configured application, ready to run as a service.
+/// - Throws: an error if the router fails to build.
 func application(
     reader: ConfigReader
 ) async throws -> some ApplicationProtocol {
     let logLevel = reader.string(
-        forKey: "log.level",
+        forKey: .Log.level,
         as: Logger.Level.self,
         default: .info
     )
     let serverName = reader.string(
-        forKey: "http.serverName",
-        default: "LoudWebsite"
+        forKey: .HTTP.serverName,
+        default: .Server.name
+    )
+    let staticFilesPath = reader.string(
+        forKey: .Path.staticFiles,
+        default: .Path.staticResources
     )
 
     return Application(
-        router: try router(),
+        router: router(
+            staticFilesPath: staticFilesPath,
+            logLevel: logLevel
+        ),
         configuration: ApplicationConfiguration(
             reader: reader.scoped(to: "http")
         ),
@@ -34,7 +47,11 @@ func application(
 // Request context used by application
 private typealias AppRequestContext = BasicRequestContext
 
-/// Build logger
+/// Builds the application's logger.
+/// - Parameters:
+///   - serverName: the label applied to the logger.
+///   - logLevel: the minimum level the logger emits.
+/// - Returns: the configured logger.
 private func logger(
     serverName: String,
     logLevel: Logger.Level
@@ -46,16 +63,26 @@ private func logger(
     return logger
 }
 
-/// Build router
-private func router() throws -> Router<AppRequestContext> {
+/// Builds the application's router.
+///
+/// Registers the request-logging middleware and the static file middleware that serves
+/// the contents of `staticFilesPath`.
+/// - Parameters:
+///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
+///   - logLevel: the level the request-logging middleware logs at.
+/// - Returns: the configured router.
+private func router(
+    staticFilesPath: String,
+    logLevel: Logger.Level
+) -> Router<AppRequestContext> {
     let router = Router(context: AppRequestContext.self)
 
     router.addMiddleware {
-        LogRequestsMiddleware(.info)
-    }
-
-    router.get("/") { _, _ in
-        return "Hello!"
+        LogRequestsMiddleware(logLevel)
+        FileMiddleware(
+            staticFilesPath,
+            searchForIndexHtml: false
+        )
     }
 
     return router
diff --git a/Services/Website/Sources/App/App.swift b/Services/Website/Sources/App/App.swift
index c46a698..335916c 100644
--- a/Services/Website/Sources/App/App.swift
+++ b/Services/Website/Sources/App/App.swift
@@ -14,7 +14,7 @@ struct App {
                     allowMissing: true
                 ),
                 InMemoryProvider(values: [
-                    "http.serverName": "LoudWebsite"
+                    .HTTP.serverName: .HTTP.serverName
                 ]),
             ]
         )
diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
new file mode 100644
index 0000000..656f369
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
@@ -0,0 +1,166 @@
+import Foundation
+
+/// A static file shipped with the website service.
+///
+/// Each case identifies a file stored under the static files root (the `Resources/Static`
+/// directory) and served by Hummingbird's `FileMiddleware` middleware.
+enum StaticFile: CaseIterable, Sendable {
+    /// The `js/app.js` script.
+    case appJS
+    /// The `404.html` error page.
+    case errorHTML
+    /// The `favicon.ico` icon.
+    case faviconICO
+    /// The `icon.png` icon.
+    case iconPNG
+    /// The `icon.svg` icon.
+    case iconSVG
+    /// The `index.html` landing page.
+    case indexHTML
+    /// The `robots.txt` crawler directives.
+    case robotsTXT
+    /// The `site.webmanifest` web application manifest.
+    case siteWebmanifest
+    /// The `css/style.css` stylesheet.
+    case styleCSS
+}
+
+// MARK: - Enumerations
+
+extension StaticFile {
+    /// A file extension used by a ``StaticFile``.
+    enum Extension: String, Sendable {
+        /// A Cascading Style Sheets file.
+        case css
+        /// A HyperText Markup Language file.
+        case html
+        /// A JavaScript file.
+        case js
+        /// A Portable Network Graphics image.
+        case png
+        /// A Windows icon image.
+        case ico
+        /// A Scalable Vector Graphics image.
+        case svg
+        /// A plain text file.
+        case txt
+        /// A web application manifest file.
+        case webmanifest
+    }
+}
+
+// MARK: - Extensions
+
+extension StaticFile {
+
+    // MARK: Computed
+    
+    /// The file's content type.
+    var contentType: String {
+        switch fileExtension {
+        case .css: "text/css"
+        case .html: "text/html"
+        case .js: "text/javascript"
+        case .png: "image/png"
+        case .ico: "image/vnd.microsoft.icon"
+        case .svg: "image/svg+xml"
+        case .txt: "text/plain"
+        case .webmanifest: "application/manifest+json"
+        }
+    }
+
+    /// The file's extension.
+    var fileExtension: Extension {
+        switch self {
+        case .styleCSS: .css
+        case .appJS: .js
+        case .errorHTML,
+             .indexHTML: .html
+        case .faviconICO: .ico
+        case .iconPNG: .png
+        case .iconSVG: .svg
+        case .robotsTXT: .txt
+        case .siteWebmanifest: .webmanifest
+        }
+    }
+
+    /// The file's name, without extension.
+    var fileName: String {
+        switch self {
+        case .appJS: "app"
+        case .errorHTML: "404"
+        case .faviconICO: "favicon"
+        case .iconPNG,
+             .iconSVG: "icon"
+        case .indexHTML: "index"
+        case .robotsTXT: "robots"
+        case .siteWebmanifest: "site"
+        case .styleCSS: "style"
+        }
+    }
+
+    /// The path relative to the static files root (e.g. `"css/style.css"`).
+    ///
+    /// This also matches the URL path the file is served at by `FileMiddleware`.
+    var relativePath: String {
+        let file = String(
+            format: Constant.Format.file,
+            fileName,
+            fileExtension.rawValue
+        )
+
+        return subdirectory
+            .map { .init(
+                format: Constant.Format.path,
+                $0,
+                file
+            )} ?? file
+    }
+
+    // MARK: Methods
+
+    /// Resolves the file's path against the given base directory.
+    /// 
+    /// - Parameter basePath: the directory the static files are served from.
+    /// - Returns: the path to the file, relative to the `basePath` path.
+    public func path(
+        relativeTo basePath: String
+    ) -> String {
+        guard !basePath.isEmpty else {
+            return relativePath
+        }
+        
+        return .init(
+            format: Constant.Format.path,
+            basePath,
+            relativePath
+        )
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension StaticFile {
+
+    // MARK: Computed
+
+    /// The sub-directory within the static root that holds the file, if any.
+    var subdirectory: String? {
+        switch self {
+        case .appJS: "js"
+        case .styleCSS: "css"
+        default: nil
+        }
+    }
+
+}
+
+// MARK: - Constants
+
+private enum Constant {
+    enum Format {
+        static let file = "%@.%@"
+        static let path = "%@/%@"
+    }
+}
diff --git a/Services/Website/Sources/Library/Library.swift b/Services/Website/Sources/Library/Library.swift
deleted file mode 100644
index 139597f..0000000
--- a/Services/Website/Sources/Library/Library.swift
+++ /dev/null
@@ -1,2 +0,0 @@
-
-
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
new file mode 100644
index 0000000..94a8cbf
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -0,0 +1,23 @@
+import Configuration
+
+extension AbsoluteConfigKey {
+    /// A namespace for the HTTP server configuration keys, as absolute keys.
+    public enum HTTP {
+        /// The absolute configuration key for the host the server binds to.
+        public static let host: AbsoluteConfigKey = .init(.HTTP.host)
+        /// The absolute configuration key for the port the server listens on.
+        public static let port: AbsoluteConfigKey = .init(.HTTP.port)
+        /// The absolute configuration key for the server's name.
+        public static let serverName: AbsoluteConfigKey = .init(.HTTP.serverName)
+    }
+    /// A namespace for the logging configuration keys, as absolute keys.
+    public enum Log {
+        /// The absolute configuration key for the minimum log level.
+        public static let level: AbsoluteConfigKey = .init(.Log.level)
+    }
+    /// A namespace for the path configuration keys, as absolute keys.
+    public enum Path {
+        /// The absolute configuration key for the directory the static files are served from.
+        public static let staticFiles: AbsoluteConfigKey = .init(.Path.staticFiles)
+    }
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
new file mode 100644
index 0000000..55c6f7d
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -0,0 +1,23 @@
+import Configuration
+
+extension ConfigKey {
+    /// A namespace for the HTTP server configuration keys.
+    public enum HTTP {
+        /// The configuration key for the host the server binds to.
+        public static let host: ConfigKey = "http.host"
+        /// The configuration key for the port the server listens on.
+        public static let port: ConfigKey = "http.port"
+        /// The configuration key for the server's name.
+        public static let serverName: ConfigKey = "http.serverName"
+    }
+    /// A namespace for the logging configuration keys.
+    public enum Log {
+        /// The configuration key for the minimum log level.
+        public static let level: ConfigKey = "log.level"
+    }
+    /// A namespace for the path configuration keys.
+    public enum Path {
+        /// The configuration key for the directory the static files are served from.
+        public static let staticFiles: ConfigKey = "path.staticFiles"
+    }
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigValue+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigValue+Constants.swift
new file mode 100644
index 0000000..58973bf
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigValue+Constants.swift
@@ -0,0 +1,18 @@
+import Configuration
+
+extension ConfigValue {
+    /// A namespace for the HTTP server's default configuration values.
+    public enum HTTP {
+        /// The default host the server binds to.
+        public static let host: ConfigValue = .init(stringLiteral: "127.0.0.1")
+        /// The default port the server listens on.
+        public static let port: ConfigValue = .init(stringLiteral: "0")
+        /// The default server name.
+        public static let serverName: ConfigValue = .init(stringLiteral: .Server.name)
+    }
+    /// A namespace for the logging default configuration values.
+    enum Log {
+        /// The default minimum log level.
+        public static let level: ConfigValue = .init(stringLiteral: "trace")
+    }
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
new file mode 100644
index 0000000..22a1e0f
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -0,0 +1,12 @@
+extension String {
+    /// A namespace for well-known path string constants.
+    public enum Path {
+        /// The directory, relative to the working directory, that the website's static files are served from.
+        public static let staticResources = "Resources/Static"
+    }
+    /// A namespace for the server string constants.
+    public enum Server {
+        /// The website server's name.
+        public static let name = "LoudWebsite"
+    }
+}
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 379de9f..c784d94 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -1,34 +1,69 @@
 import Configuration
+import Foundation
 import Hummingbird
 import HummingbirdTesting
 import Logging
 import Testing
 
 @testable import Website
+@testable import WebsiteCore
 
-private let reader = ConfigReader(providers: [
-    InMemoryProvider(values: [
-        "http.host": "127.0.0.1",
-        "http.port": "0",
-        "log.level": "trace",
-    ])
-])
-
-@Suite
+@Suite("App executable")
 struct AppTests {
-    @Test
-    func hello() async throws {
+
+    // MARK: Constants
+
+    // Absolute path to the package's "Resources/Static" folder, derived from this
+    // file's location so the static files resolve regardless of the working directory.
+    private let staticFilesPath = URL(fileURLWithPath: #filePath)
+        .deletingLastPathComponent()  // Tests/App
+        .deletingLastPathComponent()  // Tests
+        .deletingLastPathComponent()  // package root
+        .appendingPathComponent(.Path.staticResources)
+        .path
+    
+    // MARK: Functional tests
+
+    @Test(arguments: StaticFile.allCases)
+    func `static files to be served`(
+        staticFile file: StaticFile
+    ) async throws {
         let app = try await application(
-            reader: reader
+            reader: reader(
+                staticFilesPath: staticFilesPath
+            )
         )
 
         try await app.test(.router) { client in
             try await client.execute(
-                uri: "/",
+                uri: "/\(file.relativePath)",
                 method: .get
             ) { response in
-                #expect(response.body == ByteBuffer(string: "Hello!"))
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == file.contentType)
             }
         }
     }
+
+}
+
+// MARK: - Helpers
+
+private extension AppTests {
+
+    // MARK: Methods
+
+    func reader(
+        staticFilesPath: String
+    ) -> ConfigReader {
+        ConfigReader(providers: [
+            InMemoryProvider(values: [
+                .HTTP.host: .HTTP.host,
+                .HTTP.port: .HTTP.port,
+                .Log.level: .Log.level,
+                .Path.staticFiles: .init(stringLiteral: staticFilesPath),
+            ])
+        ])
+    }
+
 }
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
new file mode 100644
index 0000000..1ac3872
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -0,0 +1,141 @@
+import Foundation
+import Testing
+
+@testable import WebsiteCore
+
+@Suite("StaticFile enumeration")
+struct StaticFileTests {
+    
+    // MARK: Type aliases
+    
+    typealias File = StaticFile
+    typealias FileExtension = StaticFile.Extension
+    
+    // MARK: Computed tests
+    
+    @Test(arguments: zip(
+        File.allCases,
+        Self.contentTypes
+    ))
+    func `content type`(
+        for file: File,
+        expects contentType: String
+    ) {
+        #expect(file.contentType == contentType)
+    }
+    
+    @Test(arguments: zip(
+        File.allCases,
+        Self.fileExtensions
+    ))
+    func `file extension`(
+        for file: File,
+        expects `extension`: FileExtension
+    ) {
+        #expect(file.fileExtension == `extension`)
+    }
+    
+    @Test(arguments: zip(
+        File.allCases,
+        Self.fileNames
+    ))
+    func `file name`(
+        for file: File,
+        expects fileName: String
+    ) {
+        #expect(file.fileName == fileName)
+    }
+    
+    @Test(arguments: zip(
+        File.allCases,
+        Self.relativePaths
+    ))
+    func `relative path`(
+        for file: File,
+        expects relativePath: String
+    ) {
+        #expect(file.relativePath == relativePath)
+    }
+    
+    // MARK: Method tests
+    
+    @Test(arguments: [
+        "",
+        ".",
+        "Resources/Static"
+    ])
+    func `path relative to`(
+        _ basePath: String
+    ) {
+        for file in File.allCases {
+            let pathRelativeToBasePath = file.path(relativeTo: basePath)
+
+            if basePath.isEmpty {
+                #expect(pathRelativeToBasePath == file.relativePath)
+            } else {
+                #expect(pathRelativeToBasePath == "\(basePath)/\(file.relativePath)")
+            }
+        }
+    }
+
+    // MARK: CaseIterable tests
+    
+    @Test
+    func `all cases`() {
+        #expect(File.allCases.count == 9)
+    }
+    
+}
+
+// MARK: - Helpers
+
+private extension StaticFileTests {
+    
+    // MARK: Constants
+    
+    static let contentTypes: [String] = [
+        "text/javascript",
+        "text/html",
+        "image/vnd.microsoft.icon",
+        "image/png",
+        "image/svg+xml",
+        "text/html",
+        "text/plain",
+        "application/manifest+json",
+        "text/css"
+    ]
+    static let fileExtensions: [FileExtension] = [
+        .js,
+        .html,
+        .ico,
+        .png,
+        .svg,
+        .html,
+        .txt,
+        .webmanifest,
+        .css
+    ]
+    static let fileNames: [String] = [
+        "app",
+        "404",
+        "favicon",
+        "icon",
+        "icon",
+        "index",
+        "robots",
+        "site",
+        "style"
+    ]
+    static let relativePaths: [String] = [
+        "js/app.js",
+        "404.html",
+        "favicon.ico",
+        "icon.png",
+        "icon.svg",
+        "index.html",
+        "robots.txt",
+        "site.webmanifest",
+        "css/style.css"
+    ]
+    
+}
diff --git a/Services/Website/Tests/Library/LibraryTest.swift b/Services/Website/Tests/Library/LibraryTest.swift
deleted file mode 100644
index 8b13789..0000000
--- a/Services/Website/Tests/Library/LibraryTest.swift
+++ /dev/null
@@ -1 +0,0 @@
-
diff --git a/Services/Website/Website.xctestplan b/Services/Website/Website.xctestplan
new file mode 100644
index 0000000..5156232
--- /dev/null
+++ b/Services/Website/Website.xctestplan
@@ -0,0 +1,37 @@
+{
+  "configurations" : [
+    {
+      "id" : "F3231E68-357B-4ED7-98E9-F5767AB17024",
+      "name" : "Test Scheme Action",
+      "options" : {
+
+      }
+    }
+  ],
+  "defaultOptions" : {
+    "performanceAntipatternCheckerEnabled" : true,
+    "targetForVariableExpansion" : {
+      "containerPath" : "container:",
+      "identifier" : "Website",
+      "name" : "Website"
+    },
+    "testInteropMode" : "complete"
+  },
+  "testTargets" : [
+    {
+      "target" : {
+        "containerPath" : "container:",
+        "identifier" : "WebsiteTests",
+        "name" : "WebsiteTests"
+      }
+    },
+    {
+      "target" : {
+        "containerPath" : "container:",
+        "identifier" : "WebsiteCoreTests",
+        "name" : "WebsiteCoreTests"
+      }
+    }
+  ],
+  "version" : 1
+}
-- 
2.54.0


From f5f14eb97c9afe34577c09d8f64539266abd5158 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 27 Jun 2026 12:16:50 +0000
Subject: [PATCH 005/117] File not found middleware for the Website service
 (#4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR contains the work done to add a `NotFoundMiddleware` middleware to the Website service so requests matching neither a route nor a static file return a custom 404.html page with a 404 Not Found status. Also enables index.html fallback so the landing page is served at the site root.

To provider further details about the work done:
* NotFoundMiddleware — intercepts the `.notFound` error from the  `FileMiddleware` middleware and serves the preloaded error page with the correct content type; all other errors propagate. Falls back to a minimal body if the file is missing.
* Router — wires the `NotFoundMiddleware` middleware ahead of the `FileMiddleware` and enables searchForIndexHtml.
* Package — adds the **Hummingbird** product to the Library target.
* Tooling — sets a custom working directory in the Xcode scheme; removes the unused `pkg-deps` target from the `Makefile` file.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/4
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../xcshareddata/xcschemes/Website.xcscheme   |  3 +-
 Services/Website/Makefile                     |  4 -
 Services/Website/Package.swift                |  4 +
 Services/Website/Sources/App/App+build.swift  |  8 +-
 .../Middlewares/NotFoundMiddleware.swift      | 80 +++++++++++++++++++
 Services/Website/Tests/App/AppTests.swift     | 63 ++++++++++++++-
 6 files changed, 150 insertions(+), 12 deletions(-)
 create mode 100644 Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift

diff --git a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
index 01a4a46..24b3ac5 100644
--- a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
+++ b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
@@ -50,7 +50,8 @@
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
       launchStyle = "0"
-      useCustomWorkingDirectory = "NO"
+      useCustomWorkingDirectory = "YES"
+      customWorkingDirectory = "/Users/logan/Documents/Development/Platforms/Ro&#x308;ck+Co&#x308;de/Loud/Services/Website"
       ignoresPersistentStateOnLaunch = "NO"
       debugDocumentVersioning = "YES"
       debugServiceExtension = "internal"
diff --git a/Services/Website/Makefile b/Services/Website/Makefile
index 98cb6b7..30aa03f 100644
--- a/Services/Website/Makefile
+++ b/Services/Website/Makefile
@@ -41,10 +41,6 @@ pkg-clean: ## Remove the Swift build artifacts
 pkg-reset: ## Resets the complete SPM cache/build folder
 	@swift package reset
 
-.PHONY: pkg-deps
-pkg-deps: ## Lists the SPM package dependencies
-	@swift package show-dependencies
-
 .PHONY: pkg-outdated
 pkg-outdated: ## Lists the SPM package dependencies that can be updated
 	@swift package update --dry-run
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index e44f6bb..0d09443 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -55,6 +55,10 @@ let package = Package(
                     name: "Configuration",
                     package: "swift-configuration"
                 ),
+                .product(
+                    name: "Hummingbird",
+                    package: "hummingbird"
+                ),
             ],
             path: "Sources/Library"
         ),
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
index 3561f8b..41d2fee 100644
--- a/Services/Website/Sources/App/App+build.swift
+++ b/Services/Website/Sources/App/App+build.swift
@@ -65,8 +65,9 @@ private func logger(
 
 /// Builds the application's router.
 ///
-/// Registers the request-logging middleware and the static file middleware that serves
-/// the contents of `staticFilesPath`.
+/// Registers, in order, the request-logging middleware, the not-found middleware that serves
+/// the error page, and the static file middleware that serves the contents of `staticFilesPath`
+/// (falling back to `index.html` for directory requests).
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
 ///   - logLevel: the level the request-logging middleware logs at.
@@ -79,9 +80,10 @@ private func router(
 
     router.addMiddleware {
         LogRequestsMiddleware(logLevel)
+        NotFoundMiddleware(staticFilesPath)
         FileMiddleware(
             staticFilesPath,
-            searchForIndexHtml: false
+            searchForIndexHtml: true
         )
     }
 
diff --git a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift b/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
new file mode 100644
index 0000000..d82fbfe
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
@@ -0,0 +1,80 @@
+import Foundation
+import Hummingbird
+import NIOCore
+
+/// Serves a custom error page for requests that match neither a route nor a static file.
+///
+/// Placed ahead of `FileMiddleware` in the middleware chain, it catches the `.notFound` error
+/// that bubbles up when no file exists for the requested path and responds with the preloaded
+/// error page and a `404 Not Found` status.
+public struct NotFoundMiddleware<Context: RequestContext> {
+    
+    // MARK: Properties
+    
+    /// The body of the error page served on a not-found response.
+    private let page: ByteBuffer
+    
+    // MARK: Initializers
+    
+    /// Creates a middleware that serves the error page (`404.html`) from the static files folder.
+    ///
+    /// The page is read once, at construction. A minimal fallback body is used when the file is
+    /// missing.
+    /// - Parameter staticFilesPath: the folder, relative to the working directory, the static files are served from.
+    public init(
+        _ staticFilesPath: String
+    ) {
+        let path = StaticFile.errorHTML.path(relativeTo: staticFilesPath)
+        
+        if let data = try? Data(contentsOf: URL(fileURLWithPath: path)) {
+            self.init(page: .init(bytes: data))
+        } else {
+            self.init(page: .init(string: "404 Not Found"))
+        }
+    }
+    
+    /// Creates a middleware that serves the given error page on a not-found response.
+    /// - Parameter page: the body of the error page.
+    init(
+        page: ByteBuffer
+    ) {
+        self.page = page
+    }
+    
+}
+
+// MARK: - RouterMiddleware
+
+extension NotFoundMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        do {
+            return try await next(request, context)
+        } catch let error {
+            // Only intercept "not found"; let every other error propagate.
+            guard
+                let responseError = error as? any HTTPResponseError,
+                responseError.status == .notFound
+            else {
+                throw error
+            }
+
+            var headers = HTTPFields()
+
+            headers[.contentType] = StaticFile.errorHTML.contentType
+
+            return Response(
+                status: .notFound,
+                headers: headers,
+                body: .init(byteBuffer: page)
+            )
+        }
+    }
+
+}
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index c784d94..ec7dfb1 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -3,6 +3,7 @@ import Foundation
 import Hummingbird
 import HummingbirdTesting
 import Logging
+import NIOCore
 import Testing
 
 @testable import Website
@@ -21,9 +22,30 @@ struct AppTests {
         .deletingLastPathComponent()  // package root
         .appendingPathComponent(.Path.staticResources)
         .path
-    
+
     // MARK: Functional tests
 
+    @Test
+    func `landing page to be served at root`() async throws {
+        let file: StaticFile = .indexHTML
+        let app = try await application(
+            reader: reader(
+                staticFilesPath: staticFilesPath
+            )
+        )
+
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == file.contentType)
+                #expect(response.body == data(of: file))
+            }
+        }
+    }
+
     @Test(arguments: StaticFile.allCases)
     func `static files to be served`(
         staticFile file: StaticFile
@@ -45,14 +67,47 @@ struct AppTests {
         }
     }
 
+    @Test
+    func `error page to be served when not found`() async throws {
+        let file: StaticFile = .errorHTML
+        let app = try await application(
+            reader: reader(
+                staticFilesPath: staticFilesPath
+            )
+        )
+
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                #expect(response.status == .notFound)
+                #expect(response.headers[.contentType] == file.contentType)
+                #expect(response.body == data(of: file))
+            }
+        }
+    }
+
 }
 
 // MARK: - Helpers
 
 private extension AppTests {
-
+    
     // MARK: Methods
-
+    
+    func data(
+        of file: StaticFile
+    ) -> ByteBuffer {
+        let url = URL(fileURLWithPath: file.path(relativeTo: staticFilesPath))
+        
+        guard let data = try? Data(contentsOf: url) else {
+            return ByteBuffer()
+        }
+        
+        return ByteBuffer(bytes: data)
+    }
+    
     func reader(
         staticFilesPath: String
     ) -> ConfigReader {
@@ -65,5 +120,5 @@ private extension AppTests {
             ])
         ])
     }
-
+    
 }
-- 
2.54.0


From a621ada0bf9d3fc1f83b02522a84a78c94d6f363 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 28 Jun 2026 05:07:19 +0000
Subject: [PATCH 006/117] HTML rendering support for the Website service (#5)

This PR contains the work done to replace the use of static _HTML_ files with type-safe HTML rendered server-side via **Elementary** through **Hummingbird**.

To provide further details about the work done:

* Added the **Elementary** dependencies.
* Added the `IndexPage` and `ErrorPage` pages, ported from the old HTML boilerplate; removed the static files.
* Added the `RootController` controller serving GET / using the `IndexPage` page, wired into the router.
* Reworked the `NotFoundMiddleware` middleare to render `ErrorPage` page directly; non-notFound errors still propagate.
* the `FileMiddleware` middleware no longer searches for any static `index.html` file.
* Simplified the `StaticFile` enumeration, dropped unused constants and now-unnecessary throws.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/5
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/Package.swift                | 28 +++++++
 Services/Website/Resources/Static/404.html    | 62 ---------------
 Services/Website/Resources/Static/index.html  | 33 --------
 Services/Website/Sources/App/App+build.swift  | 18 ++---
 Services/Website/Sources/App/App.swift        |  2 +-
 .../Internal/Enumerations/StaticFile.swift    | 42 +---------
 .../Library/Internal/Pages/ErrorPage.swift    | 79 +++++++++++++++++++
 .../Library/Internal/Pages/IndexPage.swift    | 63 +++++++++++++++
 .../Public/Controllers/RootController.swift   | 71 +++++++++++++++++
 .../Extensions/ConfigValue+Constants.swift    |  9 ---
 .../Middlewares/NotFoundMiddleware.swift      | 72 +++++++----------
 Services/Website/Tests/App/AppTests.swift     | 58 +++++---------
 .../Enumerations/StaticFileTests.swift        | 10 +--
 .../Cases/Internal/Pages/ErrorPageTests.swift | 20 +++++
 .../Cases/Internal/Pages/IndexPageTests.swift | 21 +++++
 .../Controllers/RootControllerTests.swift     | 39 +++++++++
 .../Middlewares/NotFoundMiddlewareTests.swift | 77 ++++++++++++++++++
 17 files changed, 460 insertions(+), 244 deletions(-)
 delete mode 100644 Services/Website/Resources/Static/404.html
 delete mode 100644 Services/Website/Resources/Static/index.html
 create mode 100644 Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
 create mode 100644 Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
 create mode 100644 Services/Website/Sources/Library/Public/Controllers/RootController.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift

diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 0d09443..8b81b82 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -19,6 +19,14 @@ let package = Package(
         )
     ],
     dependencies: [
+        .package(
+            url: "https://github.com/elementary-swift/elementary.git",
+            from: "0.6.0"
+        ),
+        .package(
+            url: "https://github.com/hummingbird-community/hummingbird-elementary.git",
+            from: "0.3.0"
+        ),
         .package(
             url: "https://github.com/hummingbird-project/hummingbird.git",
             from: "2.25.0"
@@ -55,10 +63,18 @@ let package = Package(
                     name: "Configuration",
                     package: "swift-configuration"
                 ),
+                .product(
+                    name: "Elementary",
+                    package: "elementary"
+                ),
                 .product(
                     name: "Hummingbird",
                     package: "hummingbird"
                 ),
+                .product(
+                    name: "HummingbirdElementary",
+                    package: "hummingbird-elementary"
+                ),
             ],
             path: "Sources/Library"
         ),
@@ -77,6 +93,18 @@ let package = Package(
             name: "WebsiteCoreTests",
             dependencies: [
                 .byName(name: "WebsiteCore"),
+                .product(
+                    name: "Elementary",
+                    package: "elementary"
+                ),
+                .product(
+                    name: "Hummingbird",
+                    package: "hummingbird"
+                ),
+                .product(
+                    name: "HummingbirdTesting",
+                    package: "hummingbird"
+                ),
             ],
             path: "Tests/Library"
         ),
diff --git a/Services/Website/Resources/Static/404.html b/Services/Website/Resources/Static/404.html
deleted file mode 100644
index 260cc4c..0000000
--- a/Services/Website/Resources/Static/404.html
+++ /dev/null
@@ -1,62 +0,0 @@
-<!doctype html>
-<html lang="en">
-
-<head>
-  <meta charset="utf-8">
-  <title>Page Not Found</title>
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <style>
-    * {
-      line-height: 1.2;
-      margin: 0;
-    }
-
-    html {
-      color: #888;
-      display: table;
-      font-family: sans-serif;
-      height: 100%;
-      text-align: center;
-      width: 100%;
-    }
-
-    body {
-      display: table-cell;
-      vertical-align: middle;
-      margin: 2em auto;
-    }
-
-    h1 {
-      color: #555;
-      font-size: 2em;
-      font-weight: 400;
-    }
-
-    p {
-      margin: 0 auto;
-      width: 280px;
-    }
-
-    @media only screen and (max-width: 280px) {
-
-      body,
-      p {
-        width: 95%;
-      }
-
-      h1 {
-        font-size: 1.5em;
-        margin: 0 0 0.3em;
-      }
-
-    }
-  </style>
-</head>
-
-<body>
-  <h1>Page Not Found</h1>
-  <p>Sorry, but the page you were trying to view does not exist.</p>
-</body>
-
-</html>
-<!-- IE needs 512+ bytes: https://docs.microsoft.com/archive/blogs/ieinternals/friendly-http-error-pages -->
diff --git a/Services/Website/Resources/Static/index.html b/Services/Website/Resources/Static/index.html
deleted file mode 100644
index f3add49..0000000
--- a/Services/Website/Resources/Static/index.html
+++ /dev/null
@@ -1,33 +0,0 @@
-<!doctype html>
-<html lang="">
-
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title></title>
-  <link rel="stylesheet" href="css/style.css">
-  <meta name="description" content="">
-
-  <meta property="og:title" content="">
-  <meta property="og:type" content="">
-  <meta property="og:url" content="">
-  <meta property="og:image" content="">
-  <meta property="og:image:alt" content="">
-
-  <link rel="icon" href="/favicon.ico" sizes="any">
-  <link rel="icon" href="/icon.svg" type="image/svg+xml">
-  <link rel="apple-touch-icon" href="icon.png">
-
-  <link rel="manifest" href="site.webmanifest">
-  <meta name="theme-color" content="#fafafa">
-</head>
-
-<body>
-
-  <!-- Add your site or application content here -->
-  <p>Hello world! This is HTML5 Boilerplate.</p>
-  <script src="js/app.js"></script>
-
-</body>
-
-</html>
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
index 41d2fee..2358bb5 100644
--- a/Services/Website/Sources/App/App+build.swift
+++ b/Services/Website/Sources/App/App+build.swift
@@ -9,10 +9,9 @@ import WebsiteCore
 /// then assembles the router, server configuration, and logger.
 /// - Parameter reader: the configuration reader the values are read from.
 /// - Returns: the configured application, ready to run as a service.
-/// - Throws: an error if the router fails to build.
 func application(
     reader: ConfigReader
-) async throws -> some ApplicationProtocol {
+) async -> some ApplicationProtocol {
     let logLevel = reader.string(
         forKey: .Log.level,
         as: Logger.Level.self,
@@ -65,9 +64,9 @@ private func logger(
 
 /// Builds the application's router.
 ///
-/// Registers, in order, the request-logging middleware, the not-found middleware that serves
-/// the error page, and the static file middleware that serves the contents of `staticFilesPath`
-/// (falling back to `index.html` for directory requests).
+/// Registers the request-logging middleware, the not-found middleware that serves the error
+/// page, and the static file middleware that serves the contents of `staticFilesPath`, then
+/// adds the `RootController` routes that render the landing page.
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
 ///   - logLevel: the level the request-logging middleware logs at.
@@ -80,12 +79,11 @@ private func router(
 
     router.addMiddleware {
         LogRequestsMiddleware(logLevel)
-        NotFoundMiddleware(staticFilesPath)
-        FileMiddleware(
-            staticFilesPath,
-            searchForIndexHtml: true
-        )
+        NotFoundMiddleware()
+        FileMiddleware(staticFilesPath)
     }
 
+    router.addRoutes(RootController<AppRequestContext>().routes)
+
     return router
 }
diff --git a/Services/Website/Sources/App/App.swift b/Services/Website/Sources/App/App.swift
index 335916c..cf3e8bf 100644
--- a/Services/Website/Sources/App/App.swift
+++ b/Services/Website/Sources/App/App.swift
@@ -19,7 +19,7 @@ struct App {
             ]
         )
 
-        let app = try await application(
+        let app = await application(
             reader: reader
         )
 
diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
index 656f369..0c72430 100644
--- a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
@@ -1,5 +1,3 @@
-import Foundation
-
 /// A static file shipped with the website service.
 ///
 /// Each case identifies a file stored under the static files root (the `Resources/Static`
@@ -7,16 +5,12 @@ import Foundation
 enum StaticFile: CaseIterable, Sendable {
     /// The `js/app.js` script.
     case appJS
-    /// The `404.html` error page.
-    case errorHTML
     /// The `favicon.ico` icon.
     case faviconICO
     /// The `icon.png` icon.
     case iconPNG
     /// The `icon.svg` icon.
     case iconSVG
-    /// The `index.html` landing page.
-    case indexHTML
     /// The `robots.txt` crawler directives.
     case robotsTXT
     /// The `site.webmanifest` web application manifest.
@@ -32,8 +26,6 @@ extension StaticFile {
     enum Extension: String, Sendable {
         /// A Cascading Style Sheets file.
         case css
-        /// A HyperText Markup Language file.
-        case html
         /// A JavaScript file.
         case js
         /// A Portable Network Graphics image.
@@ -59,7 +51,6 @@ extension StaticFile {
     var contentType: String {
         switch fileExtension {
         case .css: "text/css"
-        case .html: "text/html"
         case .js: "text/javascript"
         case .png: "image/png"
         case .ico: "image/vnd.microsoft.icon"
@@ -74,8 +65,6 @@ extension StaticFile {
         switch self {
         case .styleCSS: .css
         case .appJS: .js
-        case .errorHTML,
-             .indexHTML: .html
         case .faviconICO: .ico
         case .iconPNG: .png
         case .iconSVG: .svg
@@ -88,11 +77,9 @@ extension StaticFile {
     var fileName: String {
         switch self {
         case .appJS: "app"
-        case .errorHTML: "404"
         case .faviconICO: "favicon"
         case .iconPNG,
              .iconSVG: "icon"
-        case .indexHTML: "index"
         case .robotsTXT: "robots"
         case .siteWebmanifest: "site"
         case .styleCSS: "style"
@@ -103,18 +90,10 @@ extension StaticFile {
     ///
     /// This also matches the URL path the file is served at by `FileMiddleware`.
     var relativePath: String {
-        let file = String(
-            format: Constant.Format.file,
-            fileName,
-            fileExtension.rawValue
-        )
+        let file = "\(fileName).\(fileExtension.rawValue)"
 
         return subdirectory
-            .map { .init(
-                format: Constant.Format.path,
-                $0,
-                file
-            )} ?? file
+            .map { "\($0)/\(file)" } ?? file
     }
 
     // MARK: Methods
@@ -129,12 +108,8 @@ extension StaticFile {
         guard !basePath.isEmpty else {
             return relativePath
         }
-        
-        return .init(
-            format: Constant.Format.path,
-            basePath,
-            relativePath
-        )
+
+        return "\(basePath)/\(relativePath)"
     }
 
 }
@@ -155,12 +130,3 @@ private extension StaticFile {
     }
 
 }
-
-// MARK: - Constants
-
-private enum Constant {
-    enum Format {
-        static let file = "%@.%@"
-        static let path = "%@/%@"
-    }
-}
diff --git a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
new file mode 100644
index 0000000..b59df57
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
@@ -0,0 +1,79 @@
+import Elementary
+
+/// The HTML page rendered for a not-found response.
+struct ErrorPage: HTMLDocument, Sendable {
+
+    // MARK: Document
+
+    /// The page's content.
+    var body: some HTML {
+        h1 { "Page Not Found" }
+        p { "Sorry, but the page you were trying to view does not exist." }
+    }
+
+    /// The metadata and inline styles placed in the document head.
+    var head: some HTML {
+        meta(.charset(.utf8))
+        meta(
+            .name(.viewport),
+            .content("width=device-width, initial-scale=1")
+        )
+        style { Self.styles }
+    }
+
+    /// The document language.
+    var lang: String { "en" }
+
+    /// The document title.
+    var title: String { "Page Not Found" }
+
+}
+
+// MARK: - Constants
+
+private extension ErrorPage {
+    /// The inline CSS applied to the page.
+    static let styles = """
+        * {
+          line-height: 1.2;
+          margin: 0;
+        }
+
+        html {
+          color: #888;
+          display: table;
+          font-family: sans-serif;
+          height: 100%;
+          text-align: center;
+          width: 100%;
+        }
+
+        body {
+          display: table-cell;
+          vertical-align: middle;
+          margin: 2em auto;
+        }
+
+        h1 {
+          color: #555;
+          font-size: 2em;
+          font-weight: 400;
+        }
+
+        p {
+          margin: 0 auto;
+          width: 280px;
+        }
+
+        @media only screen and (max-width: 280px) {
+          body, p {
+            width: 95%;
+          }
+
+          h1 {
+            font-size: 1.5em;
+            margin: 0 0 0.3em;
+          }
+        }
+        """
+}
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
new file mode 100644
index 0000000..d55429b
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -0,0 +1,63 @@
+import Elementary
+
+/// The website's landing page.
+struct IndexPage: HTMLDocument, Sendable {
+
+    // MARK: Document
+
+    /// The page's content.
+    var body: some HTML {
+        p { "Hello world! This is HTML5 Boilerplate." }
+        script(.src("js/app.js")) {}
+    }
+
+    /// The metadata, stylesheet, icon, and manifest links placed in the document head.
+    var head: some HTML {
+        meta(.charset(.utf8))
+        meta(
+            .name(.viewport),
+            .content("width=device-width, initial-scale=1")
+        )
+        link(
+            .rel(.stylesheet),
+            .href("css/style.css")
+        )
+        link(
+            .rel(.icon),
+            .href("/favicon.ico"),
+            .custom(
+                name: "sizes",
+                value: "any"
+            )
+        )
+        link(
+            .rel(.icon),
+            .href("/icon.svg"),
+            .custom(
+                name: "type",
+                value: "image/svg+xml"
+            )
+        )
+        link(
+            .rel("apple-touch-icon"),
+            .href("icon.png")
+        )
+        link(
+            .rel("manifest"),
+            .href("site.webmanifest")
+        )
+        meta(
+            .name("theme-color"),
+            .content("#fafafa")
+        )
+    }
+
+    /// The document language.
+    var lang: String {
+        "en"
+    }
+
+    /// The document title.
+    var title: String { "" }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
new file mode 100644
index 0000000..0cd1ab6
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -0,0 +1,71 @@
+import Hummingbird
+import HummingbirdElementary
+
+/// Serves the website's root routes.
+///
+/// The controller exposes its routes as a `RouteCollection` so they can be added to a router
+/// (or a sub-group) by the application that composes it:
+///
+/// ```swift
+/// router.addRoutes(RootController<AppRequestContext>().routes)
+/// ```
+///
+/// - Note: `Context` is the request context the routes are resolved against, and must match the
+///   context of the router the routes are added to.
+public struct RootController<Context: RequestContext> : Sendable{
+
+    // MARK: Initializers
+
+    /// Creates a root controller.
+    public init() {}
+
+    // MARK: Properties
+
+    /// The routes served by the controller.
+    ///
+    /// Serves a `GET` request for the root path (`/`) by rendering the ``IndexPage``.
+    public var routes: RouteCollection<Context> {
+        let routes = RouteCollection(context: Context.self)
+
+        routes.get(
+            .Root.index,
+            use: index
+        )
+
+        return routes
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension RootController {
+    
+    // MARK: Methods
+
+    /// Handles a request for the landing page.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    /// - Returns: an HTML response that renders the ``IndexPage``.
+    @Sendable
+    func index(
+        request: Request,
+        context: some RequestContext
+    ) -> HTMLResponse {
+        .init {
+            IndexPage()
+        }
+    }
+    
+}
+
+// MARK: - Constants
+
+extension RouterPath {
+    /// A namespace for the ``RootController`` route paths.
+    enum Root {
+        /// The path of the landing page.
+        static let index: RouterPath = "/"
+    }
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigValue+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigValue+Constants.swift
index 58973bf..326e429 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigValue+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigValue+Constants.swift
@@ -3,16 +3,7 @@ import Configuration
 extension ConfigValue {
     /// A namespace for the HTTP server's default configuration values.
     public enum HTTP {
-        /// The default host the server binds to.
-        public static let host: ConfigValue = .init(stringLiteral: "127.0.0.1")
-        /// The default port the server listens on.
-        public static let port: ConfigValue = .init(stringLiteral: "0")
         /// The default server name.
         public static let serverName: ConfigValue = .init(stringLiteral: .Server.name)
     }
-    /// A namespace for the logging default configuration values.
-    enum Log {
-        /// The default minimum log level.
-        public static let level: ConfigValue = .init(stringLiteral: "trace")
-    }
 }
diff --git a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift b/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
index d82fbfe..6032f9f 100644
--- a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
+++ b/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
@@ -1,46 +1,19 @@
-import Foundation
+import Elementary
 import Hummingbird
-import NIOCore
+import HummingbirdElementary
 
 /// Serves a custom error page for requests that match neither a route nor a static file.
 ///
 /// Placed ahead of `FileMiddleware` in the middleware chain, it catches the `.notFound` error
-/// that bubbles up when no file exists for the requested path and responds with the preloaded
-/// error page and a `404 Not Found` status.
+/// that bubbles up when no file exists for the requested path and responds with the rendered
+/// ``ErrorPage`` and a `404 Not Found` status.
 public struct NotFoundMiddleware<Context: RequestContext> {
-    
-    // MARK: Properties
-    
-    /// The body of the error page served on a not-found response.
-    private let page: ByteBuffer
-    
+
     // MARK: Initializers
-    
-    /// Creates a middleware that serves the error page (`404.html`) from the static files folder.
-    ///
-    /// The page is read once, at construction. A minimal fallback body is used when the file is
-    /// missing.
-    /// - Parameter staticFilesPath: the folder, relative to the working directory, the static files are served from.
-    public init(
-        _ staticFilesPath: String
-    ) {
-        let path = StaticFile.errorHTML.path(relativeTo: staticFilesPath)
-        
-        if let data = try? Data(contentsOf: URL(fileURLWithPath: path)) {
-            self.init(page: .init(bytes: data))
-        } else {
-            self.init(page: .init(string: "404 Not Found"))
-        }
-    }
-    
-    /// Creates a middleware that serves the given error page on a not-found response.
-    /// - Parameter page: the body of the error page.
-    init(
-        page: ByteBuffer
-    ) {
-        self.page = page
-    }
-    
+
+    /// Creates a not-found middleware.
+    public init() {}
+
 }
 
 // MARK: - RouterMiddleware
@@ -49,6 +22,16 @@ extension NotFoundMiddleware: RouterMiddleware {
 
     // MARK: Functions
 
+    /// Passes the request down the chain, rendering the error page if it results in a not-found
+    /// response.
+    ///
+    /// Any error other than `.notFound` is rethrown unchanged.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response, or the rendered ``ErrorPage`` with a `404 Not Found` status.
+    /// - Throws: any non-not-found error thrown downstream.
     public func handle(
         _ request: Request,
         context: Context,
@@ -57,7 +40,6 @@ extension NotFoundMiddleware: RouterMiddleware {
         do {
             return try await next(request, context)
         } catch let error {
-            // Only intercept "not found"; let every other error propagate.
             guard
                 let responseError = error as? any HTTPResponseError,
                 responseError.status == .notFound
@@ -65,14 +47,14 @@ extension NotFoundMiddleware: RouterMiddleware {
                 throw error
             }
 
-            var headers = HTTPFields()
-
-            headers[.contentType] = StaticFile.errorHTML.contentType
-
-            return Response(
-                status: .notFound,
-                headers: headers,
-                body: .init(byteBuffer: page)
+            return HTMLResponse(
+                status: .notFound
+            ) {
+                ErrorPage()
+            }
+            .response(
+                from: request,
+                context: context
             )
         }
     }
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index ec7dfb1..fd64115 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -27,21 +27,16 @@ struct AppTests {
 
     @Test
     func `landing page to be served at root`() async throws {
-        let file: StaticFile = .indexHTML
-        let app = try await application(
-            reader: reader(
-                staticFilesPath: staticFilesPath
-            )
-        )
-
         try await app.test(.router) { client in
             try await client.execute(
                 uri: "/",
                 method: .get
             ) { response in
+                let body = String(buffer: response.body)
+
                 #expect(response.status == .ok)
-                #expect(response.headers[.contentType] == file.contentType)
-                #expect(response.body == data(of: file))
+                #expect(response.headers[.contentType]?.hasPrefix("text/html") == true)
+                #expect(body.contains("Hello world!"))
             }
         }
     }
@@ -50,12 +45,6 @@ struct AppTests {
     func `static files to be served`(
         staticFile file: StaticFile
     ) async throws {
-        let app = try await application(
-            reader: reader(
-                staticFilesPath: staticFilesPath
-            )
-        )
-
         try await app.test(.router) { client in
             try await client.execute(
                 uri: "/\(file.relativePath)",
@@ -69,21 +58,16 @@ struct AppTests {
 
     @Test
     func `error page to be served when not found`() async throws {
-        let file: StaticFile = .errorHTML
-        let app = try await application(
-            reader: reader(
-                staticFilesPath: staticFilesPath
-            )
-        )
-
         try await app.test(.router) { client in
             try await client.execute(
                 uri: "/this-path-does-not-exist",
                 method: .get
             ) { response in
+                let body = String(buffer: response.body)
+
                 #expect(response.status == .notFound)
-                #expect(response.headers[.contentType] == file.contentType)
-                #expect(response.body == data(of: file))
+                #expect(response.headers[.contentType]?.hasPrefix("text/html") == true)
+                #expect(body.contains("Page Not Found"))
             }
         }
     }
@@ -94,28 +78,28 @@ struct AppTests {
 
 private extension AppTests {
     
-    // MARK: Methods
+    // MARK: Computed
     
-    func data(
-        of file: StaticFile
-    ) -> ByteBuffer {
-        let url = URL(fileURLWithPath: file.path(relativeTo: staticFilesPath))
-        
-        guard let data = try? Data(contentsOf: url) else {
-            return ByteBuffer()
+    var app: some ApplicationProtocol {
+        get async {
+            await application(
+                reader: reader(
+                    staticFilesPath: staticFilesPath
+                )
+            )
         }
-        
-        return ByteBuffer(bytes: data)
     }
     
+    // MARK: Methods
+    
     func reader(
         staticFilesPath: String
     ) -> ConfigReader {
         ConfigReader(providers: [
             InMemoryProvider(values: [
-                .HTTP.host: .HTTP.host,
-                .HTTP.port: .HTTP.port,
-                .Log.level: .Log.level,
+                .HTTP.host: "127.0.0.1",
+                .HTTP.port: "0",
+                .Log.level: "trace",
                 .Path.staticFiles: .init(stringLiteral: staticFilesPath),
             ])
         ])
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index 1ac3872..ba7b26d 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -82,7 +82,7 @@ struct StaticFileTests {
     
     @Test
     func `all cases`() {
-        #expect(File.allCases.count == 9)
+        #expect(File.allCases.count == 7)
     }
     
 }
@@ -95,44 +95,36 @@ private extension StaticFileTests {
     
     static let contentTypes: [String] = [
         "text/javascript",
-        "text/html",
         "image/vnd.microsoft.icon",
         "image/png",
         "image/svg+xml",
-        "text/html",
         "text/plain",
         "application/manifest+json",
         "text/css"
     ]
     static let fileExtensions: [FileExtension] = [
         .js,
-        .html,
         .ico,
         .png,
         .svg,
-        .html,
         .txt,
         .webmanifest,
         .css
     ]
     static let fileNames: [String] = [
         "app",
-        "404",
         "favicon",
         "icon",
         "icon",
-        "index",
         "robots",
         "site",
         "style"
     ]
     static let relativePaths: [String] = [
         "js/app.js",
-        "404.html",
         "favicon.ico",
         "icon.png",
         "icon.svg",
-        "index.html",
         "robots.txt",
         "site.webmanifest",
         "css/style.css"
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
new file mode 100644
index 0000000..45d74cb
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
@@ -0,0 +1,20 @@
+import Elementary
+import Testing
+
+@testable import WebsiteCore
+
+@Suite("ErrorPage page")
+struct ErrorPageTests {
+    
+    // MARK: Functional tests
+
+    @Test
+    func `renders its markup`() {
+        let html = ErrorPage().render()
+
+        #expect(html.contains("<!DOCTYPE html>"))
+        #expect(html.contains("Page Not Found"))
+        #expect(html.contains("does not exist"))
+    }
+
+}
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
new file mode 100644
index 0000000..1e0233c
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -0,0 +1,21 @@
+import Elementary
+import Testing
+
+@testable import WebsiteCore
+
+@Suite("IndexPage page")
+struct IndexPageTests {
+    
+    // MARK: Functional tests
+
+    @Test
+    func `renders its markup`() {
+        let html = IndexPage().render()
+
+        #expect(html.contains("<!DOCTYPE html>"))
+        #expect(html.contains("Hello world!"))
+        #expect(html.contains("css/style.css"))
+        #expect(html.contains("js/app.js"))
+    }
+
+}
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
new file mode 100644
index 0000000..daa9e79
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
@@ -0,0 +1,39 @@
+import Hummingbird
+import HummingbirdTesting
+import NIOCore
+import Testing
+
+@testable import WebsiteCore
+
+@Suite("RootController controller")
+struct RootControllerTests {
+    
+    // MARK: Constants
+    
+    private let app: Application = .init(router: {
+        let router = Router()
+        
+        router.addRoutes(RootController<BasicRequestContext>().routes)
+        
+        return router
+    }())
+
+    // MARK: Functional tests
+
+    @Test
+    func `serves the landing page at the root path`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
+                #expect(body.contains("Hello world!"))
+            }
+        }
+    }
+
+}
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
new file mode 100644
index 0000000..b4646e3
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
@@ -0,0 +1,77 @@
+import Hummingbird
+import HummingbirdTesting
+import NIOCore
+import Testing
+
+@testable import WebsiteCore
+
+@Suite("NotFoundMiddleware middleware")
+struct NotFoundMiddlewareTests {
+    
+    // MARK: Constants
+    
+    private let app: Application = .init(router: {
+        let router = Router()
+        
+        router.addMiddleware {
+            NotFoundMiddleware()
+        }
+        
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        router.get("boom") { _, _ -> String in
+            throw HTTPError(.badRequest)
+        }
+
+        return router
+    }())
+    
+    // MARK: Functional tests
+
+    @Test
+    func `renders the error page for an unmatched request`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .notFound)
+                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
+                #expect(body.contains("Page Not Found"))
+            }
+        }
+    }
+
+    @Test
+    func `passes a matched response through untouched`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.body == ByteBuffer(string: "Hello!"))
+            }
+        }
+    }
+
+    @Test
+    func `rethrows a non-not-found error unchanged`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/boom",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+                
+                #expect(response.status == .badRequest)
+                #expect(!body.contains("Page Not Found"))
+            }
+        }
+    }
+
+}
-- 
2.54.0


From 6c1a0f713b2c74e06a0391c18e1a3cdb153562aa Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 28 Jun 2026 05:49:32 +0000
Subject: [PATCH 007/117] Static file caching for the Website service (#6)

This PR contains the work done to add cache-control headers to static file responses by configuring the `FileMiddleware` middleware to tag served static files with *Cache-Control* directives, tuned per media type.

To provide further details about the work done:

* Added a cache control that sets per-type policies: text assets (CSS/JS) get public, max-age, must-revalidate; images get public, max-age; everything else gets a default public, max-age.
* Files stay validated via `ETag/Last-Modified` header.
* Made the max-age values configurable, with defaults, via new cache constants.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/6
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .swift-format                                 |  2 +-
 Services/Website/Sources/App/App+build.swift  | 50 +++++++++++++++++--
 .../AbsoluteConfigKey+Constants.swift         |  9 ++++
 .../Extensions/ConfigKey+Constants.swift      |  9 ++++
 .../Public/Extensions/Int+Constants.swift     | 11 ++++
 Services/Website/Tests/App/AppTests.swift     | 19 ++++++-
 6 files changed, 94 insertions(+), 6 deletions(-)
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift

diff --git a/.swift-format b/.swift-format
index f015b36..fbd0fa3 100644
--- a/.swift-format
+++ b/.swift-format
@@ -39,7 +39,7 @@
     "NeverForceUnwrap": true,
     "NeverUseForceTry": true,
     "NeverUseImplicitlyUnwrappedOptionals": true,
-    "NoAccessLevelOnExtensionDeclaration": true,
+    "NoAccessLevelOnExtensionDeclaration": false,
     "NoAssignmentInExpressions": true,
     "NoBlockComments": true,
     "NoCasesWithOnlyFallthrough": true,
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
index 2358bb5..d79bf0f 100644
--- a/Services/Website/Sources/App/App+build.swift
+++ b/Services/Website/Sources/App/App+build.swift
@@ -12,6 +12,20 @@ import WebsiteCore
 func application(
     reader: ConfigReader
 ) async -> some ApplicationProtocol {
+    let cacheControl = cacheControl(
+        textMaxAge: reader.int(
+            forKey: .Cache.maxAgeText,
+            default: .Cache.maxAgeText
+        ),
+        imageMaxAge: reader.int(
+            forKey: .Cache.maxAgeImage,
+            default: .Cache.maxAgeImage
+        ),
+        defaultMaxAge: reader.int(
+            forKey: .Cache.maxAgeDefault,
+            default: .Cache.maxAgeDefault
+        )
+    )
     let logLevel = reader.string(
         forKey: .Log.level,
         as: Logger.Level.self,
@@ -29,6 +43,7 @@ func application(
     return Application(
         router: router(
             staticFilesPath: staticFilesPath,
+            cacheControl: cacheControl,
             logLevel: logLevel
         ),
         configuration: ApplicationConfiguration(
@@ -46,6 +61,29 @@ func application(
 // Request context used by application
 private typealias AppRequestContext = BasicRequestContext
 
+/// Builds the cache-control policy applied to the served static files.
+///
+/// Static files are public and validated by `FileMiddleware` through their `ETag` and
+/// `Last-Modified` headers, so each media type is given a `max-age` after which the browser
+/// revalidates. Text-based assets (CSS, JavaScript) are additionally marked `must-revalidate`
+/// since they change between deployments while keeping their filenames.
+/// - Parameters:
+///   - textMaxAge: the max-age, in seconds, applied to text-based static files (CSS, JavaScript, plain text).
+///   - imageMaxAge: the max-age, in seconds, applied to image static files (ICO, PNG, SVG).
+///   - defaultMaxAge: the max-age, in seconds, applied to all other static files (e.g. the web manifest).
+/// - Returns: the configured cache-control policy.
+private func cacheControl(
+    textMaxAge: Int,
+    imageMaxAge: Int,
+    defaultMaxAge: Int
+) -> CacheControl {
+    .init([
+        (.text, [.public, .maxAge(textMaxAge), .mustRevalidate]),
+        (.image, [.public, .maxAge(imageMaxAge)]),
+        (.init(type: .any), [.public, .maxAge(defaultMaxAge)]),
+    ])
+}
+
 /// Builds the application's logger.
 /// - Parameters:
 ///   - serverName: the label applied to the logger.
@@ -65,14 +103,17 @@ private func logger(
 /// Builds the application's router.
 ///
 /// Registers the request-logging middleware, the not-found middleware that serves the error
-/// page, and the static file middleware that serves the contents of `staticFilesPath`, then
-/// adds the `RootController` routes that render the landing page.
+/// page, and the static file middleware that serves the contents of `staticFilesPath` (tagging
+/// responses with the given `cacheControl` directives), then adds the `RootController` routes
+/// that render the landing page.
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
+///   - cacheControl: the cache-control directives applied to the served static files.
 ///   - logLevel: the level the request-logging middleware logs at.
 /// - Returns: the configured router.
 private func router(
     staticFilesPath: String,
+    cacheControl: CacheControl,
     logLevel: Logger.Level
 ) -> Router<AppRequestContext> {
     let router = Router(context: AppRequestContext.self)
@@ -80,7 +121,10 @@ private func router(
     router.addMiddleware {
         LogRequestsMiddleware(logLevel)
         NotFoundMiddleware()
-        FileMiddleware(staticFilesPath)
+        FileMiddleware(
+            staticFilesPath,
+            cacheControl: cacheControl
+        )
     }
 
     router.addRoutes(RootController<AppRequestContext>().routes)
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index 94a8cbf..93dec9c 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -1,6 +1,15 @@
 import Configuration
 
 extension AbsoluteConfigKey {
+    /// A namespace for the static files cache configuration keys, as absolute keys.
+    public enum Cache {
+        /// The absolute configuration key for the max-age, in seconds, applied to text-based static files.
+        public static let maxAgeText: AbsoluteConfigKey = .init(.Cache.maxAgeText)
+        /// The absolute configuration key for the max-age, in seconds, applied to image static files.
+        public static let maxAgeImage: AbsoluteConfigKey = .init(.Cache.maxAgeImage)
+        /// The absolute configuration key for the max-age, in seconds, applied to all other static files.
+        public static let maxAgeDefault: AbsoluteConfigKey = .init(.Cache.maxAgeDefault)
+    }
     /// A namespace for the HTTP server configuration keys, as absolute keys.
     public enum HTTP {
         /// The absolute configuration key for the host the server binds to.
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index 55c6f7d..225db80 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -1,6 +1,15 @@
 import Configuration
 
 extension ConfigKey {
+    /// A namespace for the static files cache configuration keys.
+    public enum Cache {
+        /// The configuration key for the max-age, in seconds, applied to text-based static files (CSS, JavaScript, plain text).
+        public static let maxAgeText: ConfigKey = "cache.maxAge.text"
+        /// The configuration key for the max-age, in seconds, applied to image static files (ICO, PNG, SVG).
+        public static let maxAgeImage: ConfigKey = "cache.maxAge.image"
+        /// The configuration key for the max-age, in seconds, applied to all other static files (e.g. the web manifest).
+        public static let maxAgeDefault: ConfigKey = "cache.maxAge.default"
+    }
     /// A namespace for the HTTP server configuration keys.
     public enum HTTP {
         /// The configuration key for the host the server binds to.
diff --git a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
new file mode 100644
index 0000000..489fa2a
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
@@ -0,0 +1,11 @@
+extension Int {
+    /// A namespace for the cache's default configuration values.
+    public enum Cache {
+        /// The default max-age, in seconds, applied to text-based static files (1 hour).
+        public static let maxAgeText = 3_600
+        /// The default max-age, in seconds, applied to image static files (1 week).
+        public static let maxAgeImage = 604_800
+        /// The default max-age, in seconds, applied to all other static files (1 day).
+        public static let maxAgeDefault = 86_400
+    }
+}
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index fd64115..15d0765 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -13,6 +13,12 @@ import Testing
 struct AppTests {
 
     // MARK: Constants
+    
+    private let textExtensions: [StaticFile.Extension] = [
+        .css,
+        .js,
+        .txt
+    ]
 
     // Absolute path to the package's "Resources/Static" folder, derived from this
     // file's location so the static files resolve regardless of the working directory.
@@ -35,7 +41,7 @@ struct AppTests {
                 let body = String(buffer: response.body)
 
                 #expect(response.status == .ok)
-                #expect(response.headers[.contentType]?.hasPrefix("text/html") == true)
+                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
                 #expect(body.contains("Hello world!"))
             }
         }
@@ -52,6 +58,15 @@ struct AppTests {
             ) { response in
                 #expect(response.status == .ok)
                 #expect(response.headers[.contentType] == file.contentType)
+                
+                let cacheControl = try #require(response.headers[.cacheControl])
+
+                #expect(cacheControl.contains("public") == true)
+                #expect(cacheControl.contains("max-age=") == true)
+                
+                if textExtensions.contains(file.fileExtension) {
+                    #expect(cacheControl.contains("must-revalidate") == true)
+                }
             }
         }
     }
@@ -66,7 +81,7 @@ struct AppTests {
                 let body = String(buffer: response.body)
 
                 #expect(response.status == .notFound)
-                #expect(response.headers[.contentType]?.hasPrefix("text/html") == true)
+                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
                 #expect(body.contains("Page Not Found"))
             }
         }
-- 
2.54.0


From 7c18cd9ec0c3c41df4223c5e6f3813213c8a4673 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 28 Jun 2026 06:15:05 +0000
Subject: [PATCH 008/117] Response compression for the Website service (#7)

This PR contains the work done to add response compression to the Website service by registering the `ResponseCompressionMiddleware` middleware so responses are compressed when the client advertises support and the body exceeds a minimum size.

To provide further details about the work done:

* Added the **HummingbirdCompression** package dependency.
* Integrated the `ResponseCompressionMiddleware` middleware into the router, ahead of the not-found and static file middleware.
* Made the `minimum-response-size-to-compress` threshold configurable, with a default.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/7
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/Package.swift                |  8 ++++++
 Services/Website/Sources/App/App+build.swift  | 24 ++++++++++++-----
 .../AbsoluteConfigKey+Constants.swift         |  5 ++++
 .../Extensions/ConfigKey+Constants.swift      |  5 ++++
 .../Public/Extensions/Int+Constants.swift     |  5 ++++
 Services/Website/Tests/App/AppTests.swift     | 27 +++++++++++++++++++
 6 files changed, 68 insertions(+), 6 deletions(-)

diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 8b81b82..937f6e0 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -31,6 +31,10 @@ let package = Package(
             url: "https://github.com/hummingbird-project/hummingbird.git",
             from: "2.25.0"
         ),
+        .package(
+            url: "https://github.com/hummingbird-project/hummingbird-compression.git",
+            from: "2.0.0"
+        ),
         .package(
             url: "https://github.com/apple/swift-configuration.git",
             from: "1.0.0",
@@ -53,6 +57,10 @@ let package = Package(
                     name: "Hummingbird",
                     package: "hummingbird"
                 ),
+                .product(
+                    name: "HummingbirdCompression",
+                    package: "hummingbird-compression"
+                ),
             ],
             path: "Sources/App"
         ),
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
index d79bf0f..67f9bf4 100644
--- a/Services/Website/Sources/App/App+build.swift
+++ b/Services/Website/Sources/App/App+build.swift
@@ -1,12 +1,13 @@
 import Configuration
 import Hummingbird
+import HummingbirdCompression
 import Logging
 import WebsiteCore
 
 /// Builds the website application.
 ///
-/// Reads the log level, server name, and static files location from the configuration,
-/// then assembles the router, server configuration, and logger.
+/// Reads the log level, server name, static files location, and minimum response size to
+/// compress from the configuration, then assembles the router, server configuration, and logger.
 /// - Parameter reader: the configuration reader the values are read from.
 /// - Returns: the configured application, ready to run as a service.
 func application(
@@ -26,6 +27,10 @@ func application(
             default: .Cache.maxAgeDefault
         )
     )
+    let compressionMinResponseSize = reader.int(
+        forKey: .Compression.minResponseSize,
+        default: .Compression.minResponseSize
+    )
     let logLevel = reader.string(
         forKey: .Log.level,
         as: Logger.Level.self,
@@ -44,6 +49,7 @@ func application(
         router: router(
             staticFilesPath: staticFilesPath,
             cacheControl: cacheControl,
+            compressionMinResponseSize: compressionMinResponseSize,
             logLevel: logLevel
         ),
         configuration: ApplicationConfiguration(
@@ -102,24 +108,30 @@ private func logger(
 
 /// Builds the application's router.
 ///
-/// Registers the request-logging middleware, the not-found middleware that serves the error
-/// page, and the static file middleware that serves the contents of `staticFilesPath` (tagging
-/// responses with the given `cacheControl` directives), then adds the `RootController` routes
-/// that render the landing page.
+/// Registers the request-logging middleware, the response-compression middleware that compresses
+/// responses larger than `minimumResponseSizeToCompress` when the client advertises support, the
+/// not-found middleware that serves the error page, and the static file middleware that serves the
+/// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then
+/// adds the `RootController` routes that render the landing page.
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
 ///   - cacheControl: the cache-control directives applied to the served static files.
+///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
 ///   - logLevel: the level the request-logging middleware logs at.
 /// - Returns: the configured router.
 private func router(
     staticFilesPath: String,
     cacheControl: CacheControl,
+    compressionMinResponseSize: Int,
     logLevel: Logger.Level
 ) -> Router<AppRequestContext> {
     let router = Router(context: AppRequestContext.self)
 
     router.addMiddleware {
         LogRequestsMiddleware(logLevel)
+        ResponseCompressionMiddleware(
+            minimumResponseSizeToCompress: compressionMinResponseSize
+        )
         NotFoundMiddleware()
         FileMiddleware(
             staticFilesPath,
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index 93dec9c..f1ab24d 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -10,6 +10,11 @@ extension AbsoluteConfigKey {
         /// The absolute configuration key for the max-age, in seconds, applied to all other static files.
         public static let maxAgeDefault: AbsoluteConfigKey = .init(.Cache.maxAgeDefault)
     }
+    /// A namespace for the response compression configuration keys, as absolute keys.
+    public enum Compression {
+        /// The absolute configuration key for the minimum response body size, in bytes, before compression is applied.
+        public static let minResponseSize: AbsoluteConfigKey = .init(.Compression.minResponseSize)
+    }
     /// A namespace for the HTTP server configuration keys, as absolute keys.
     public enum HTTP {
         /// The absolute configuration key for the host the server binds to.
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index 225db80..4a34574 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -10,6 +10,11 @@ extension ConfigKey {
         /// The configuration key for the max-age, in seconds, applied to all other static files (e.g. the web manifest).
         public static let maxAgeDefault: ConfigKey = "cache.maxAge.default"
     }
+    /// A namespace for the response compression configuration keys.
+    public enum Compression {
+        /// The configuration key for the minimum response body size, in bytes, before compression is applied.
+        public static let minResponseSize: ConfigKey = "compression.minimumResponseSize"
+    }
     /// A namespace for the HTTP server configuration keys.
     public enum HTTP {
         /// The configuration key for the host the server binds to.
diff --git a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
index 489fa2a..d6976ef 100644
--- a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
@@ -8,4 +8,9 @@ extension Int {
         /// The default max-age, in seconds, applied to all other static files (1 day).
         public static let maxAgeDefault = 86_400
     }
+    /// A namespace for the response compression's default configuration values.
+    public enum Compression {
+        /// The default minimum response body size, in bytes, before compression is applied (1 KB).
+        public static let minResponseSize = 1_024
+    }
 }
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 15d0765..13cce8c 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -71,6 +71,33 @@ struct AppTests {
         }
     }
 
+    @Test
+    func `response to be compressed when the client supports it`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get,
+                headers: [.acceptEncoding: "gzip"]
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentEncoding] == "gzip")
+            }
+        }
+    }
+
+    @Test
+    func `response to not be compressed when the client does not support it`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentEncoding] == nil)
+            }
+        }
+    }
+
     @Test
     func `error page to be served when not found`() async throws {
         try await app.test(.router) { client in
-- 
2.54.0


From 6b6389cb0fa0e03e84e5cc8d820592d35ceb8a34 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 28 Jun 2026 11:35:54 +0000
Subject: [PATCH 009/117] Security header setup for the Website service (#8)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR contains the work done to add a `SecurityHeadersMiddleware` middleware that stamps hardened security-related HTTP headers onto every response.

To provide further details about the work:

* Implemented the `SecurityHeadersMiddleware` middleware, which precomputes headers once from a `Configuration` object and applies them to every response:
  * _Content-Security-Policy_,
  * _X-Content-Type-Options_,
  * _X-Frame-Options_,
  * _Referrer-Policy_,
  * _Permissions-Policy_,
  * _Strict-Transport-Security_ (optional).
* Integrated this middleware into the router (near the top of the chain), reading each value from configuration with hardened defaults.
* The _Strict-Transport-Security_ has no default value — omitted unless explicitly set, so it stays off in plain-HTTP during development and on only behind TLS.
* Added security-header constants keys and values.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/8
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/Sources/App/App+build.swift  |  58 ++++++-
 .../Extensions/HTTPFieldName+Constants.swift  |  10 ++
 .../AbsoluteConfigKey+Constants.swift         |  15 ++
 .../Extensions/ConfigKey+Constants.swift      |  15 ++
 .../Public/Extensions/String+Constants.swift  |  20 +++
 .../SecurityHeadersMiddleware.swift           | 146 ++++++++++++++++++
 Services/Website/Tests/App/AppTests.swift     | 129 ++++++++++++----
 .../SecurityHeadersMiddlewareTests.swift      | 134 ++++++++++++++++
 Services/Website/docker-compose.yml           |   1 +
 9 files changed, 497 insertions(+), 31 deletions(-)
 create mode 100644 Services/Website/Sources/Library/Internal/Extensions/HTTPFieldName+Constants.swift
 create mode 100644 Services/Website/Sources/Library/Public/Middlewares/SecurityHeadersMiddleware.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift

diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
index 67f9bf4..6514a8e 100644
--- a/Services/Website/Sources/App/App+build.swift
+++ b/Services/Website/Sources/App/App+build.swift
@@ -6,8 +6,8 @@ import WebsiteCore
 
 /// Builds the website application.
 ///
-/// Reads the log level, server name, static files location, and minimum response size to
-/// compress from the configuration, then assembles the router, server configuration, and logger.
+/// Reads the log level, server name, static files location, minimum response size to compress, and
+/// security headers from the configuration, then assembles the router, server configuration, and logger.
 /// - Parameter reader: the configuration reader the values are read from.
 /// - Returns: the configured application, ready to run as a service.
 func application(
@@ -44,12 +44,16 @@ func application(
         forKey: .Path.staticFiles,
         default: .Path.staticResources
     )
+    let securityHeaders = securityHeaders(
+        reader: reader
+    )
 
     return Application(
         router: router(
             staticFilesPath: staticFilesPath,
             cacheControl: cacheControl,
             compressionMinResponseSize: compressionMinResponseSize,
+            securityHeaders: securityHeaders,
             logLevel: logLevel
         ),
         configuration: ApplicationConfiguration(
@@ -90,6 +94,44 @@ private func cacheControl(
     ])
 }
 
+/// Builds the security-headers configuration applied to every response.
+///
+/// Each header value falls back to the hardened default in `String.Security` when the matching
+/// configuration key is unset. `Strict-Transport-Security` has no default: it is read as an optional
+/// and omitted entirely unless explicitly configured, so it stays off in plain-HTTP development and
+/// is enabled only behind TLS in production.
+/// - Parameter reader: the configuration reader the header values are read from.
+/// - Returns: the configured security-headers configuration.
+private func securityHeaders(
+    reader: ConfigReader
+) -> SecurityHeadersMiddleware<AppRequestContext>.Configuration {
+    .init(
+        contentSecurityPolicy: reader.string(
+            forKey: .Security.contentSecurityPolicy,
+            default: .Security.contentSecurityPolicy
+        ),
+        contentTypeOptions: reader.string(
+            forKey: .Security.contentTypeOptions,
+            default: .Security.contentTypeOptions
+        ),
+        frameOptions: reader.string(
+            forKey: .Security.frameOptions,
+            default: .Security.frameOptions
+        ),
+        referrerPolicy: reader.string(
+            forKey: .Security.referrerPolicy,
+            default: .Security.referrerPolicy
+        ),
+        permissionsPolicy: reader.string(
+            forKey: .Security.permissionsPolicy,
+            default: .Security.permissionsPolicy
+        ),
+        strictTransportSecurity: reader.string(
+            forKey: .Security.strictTransportSecurity
+        )
+    )
+}
+
 /// Builds the application's logger.
 /// - Parameters:
 ///   - serverName: the label applied to the logger.
@@ -108,27 +150,37 @@ private func logger(
 
 /// Builds the application's router.
 ///
-/// Registers the request-logging middleware, the response-compression middleware that compresses
+/// Registers the request-logging middleware, the security-headers middleware that stamps the given
+/// `securityHeaders` onto every response, the response-compression middleware that compresses
 /// responses larger than `minimumResponseSizeToCompress` when the client advertises support, the
 /// not-found middleware that serves the error page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then
 /// adds the `RootController` routes that render the landing page.
+///
+/// The security-headers middleware sits just inside request logging so it covers every response that
+/// reaches a client — the landing page, the compressed responses, the rendered error page, and the
+/// served static files.
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
 ///   - cacheControl: the cache-control directives applied to the served static files.
 ///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
+///   - securityHeaders: the security headers applied to every response.
 ///   - logLevel: the level the request-logging middleware logs at.
 /// - Returns: the configured router.
 private func router(
     staticFilesPath: String,
     cacheControl: CacheControl,
     compressionMinResponseSize: Int,
+    securityHeaders: SecurityHeadersMiddleware<AppRequestContext>.Configuration,
     logLevel: Logger.Level
 ) -> Router<AppRequestContext> {
     let router = Router(context: AppRequestContext.self)
 
     router.addMiddleware {
         LogRequestsMiddleware(logLevel)
+        SecurityHeadersMiddleware(
+            configuration: securityHeaders
+        )
         ResponseCompressionMiddleware(
             minimumResponseSizeToCompress: compressionMinResponseSize
         )
diff --git a/Services/Website/Sources/Library/Internal/Extensions/HTTPFieldName+Constants.swift b/Services/Website/Sources/Library/Internal/Extensions/HTTPFieldName+Constants.swift
new file mode 100644
index 0000000..4ebf3bb
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Extensions/HTTPFieldName+Constants.swift
@@ -0,0 +1,10 @@
+import HTTPTypes
+
+extension HTTPField.Name {
+    /// The `Permissions-Policy` field name (not provided as a standard `HTTPField.Name`).
+    static let permissionsPolicy = Self("Permissions-Policy")!
+    /// The `Referrer-Policy` field name (not provided as a standard `HTTPField.Name`).
+    static let referrerPolicy = Self("Referrer-Policy")!
+    /// The `X-Frame-Options` field name (not provided as a standard `HTTPField.Name`).
+    static let frameOptions = Self("X-Frame-Options")!
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index f1ab24d..06afdd4 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -34,4 +34,19 @@ extension AbsoluteConfigKey {
         /// The absolute configuration key for the directory the static files are served from.
         public static let staticFiles: AbsoluteConfigKey = .init(.Path.staticFiles)
     }
+    /// A namespace for the security headers configuration keys, as absolute keys.
+    public enum Security {
+        /// The absolute configuration key for the `Content-Security-Policy` header value.
+        public static let contentSecurityPolicy: AbsoluteConfigKey = .init(.Security.contentSecurityPolicy)
+        /// The absolute configuration key for the `X-Content-Type-Options` header value.
+        public static let contentTypeOptions: AbsoluteConfigKey = .init(.Security.contentTypeOptions)
+        /// The absolute configuration key for the `X-Frame-Options` header value.
+        public static let frameOptions: AbsoluteConfigKey = .init(.Security.frameOptions)
+        /// The absolute configuration key for the `Referrer-Policy` header value.
+        public static let referrerPolicy: AbsoluteConfigKey = .init(.Security.referrerPolicy)
+        /// The absolute configuration key for the `Permissions-Policy` header value.
+        public static let permissionsPolicy: AbsoluteConfigKey = .init(.Security.permissionsPolicy)
+        /// The absolute configuration key for the `Strict-Transport-Security` header value.
+        public static let strictTransportSecurity: AbsoluteConfigKey = .init(.Security.strictTransportSecurity)
+    }
 }
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index 4a34574..5d27088 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -34,4 +34,19 @@ extension ConfigKey {
         /// The configuration key for the directory the static files are served from.
         public static let staticFiles: ConfigKey = "path.staticFiles"
     }
+    /// A namespace for the security headers configuration keys.
+    public enum Security {
+        /// The configuration key for the `Content-Security-Policy` header value.
+        public static let contentSecurityPolicy: ConfigKey = "security.contentSecurityPolicy"
+        /// The configuration key for the `X-Content-Type-Options` header value.
+        public static let contentTypeOptions: ConfigKey = "security.contentTypeOptions"
+        /// The configuration key for the `X-Frame-Options` header value.
+        public static let frameOptions: ConfigKey = "security.frameOptions"
+        /// The configuration key for the `Referrer-Policy` header value.
+        public static let referrerPolicy: ConfigKey = "security.referrerPolicy"
+        /// The configuration key for the `Permissions-Policy` header value.
+        public static let permissionsPolicy: ConfigKey = "security.permissionsPolicy"
+        /// The configuration key for the `Strict-Transport-Security` header value (omitted when unset).
+        public static let strictTransportSecurity: ConfigKey = "security.strictTransportSecurity"
+    }
 }
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 22a1e0f..63639d9 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -4,6 +4,26 @@ extension String {
         /// The directory, relative to the working directory, that the website's static files are served from.
         public static let staticResources = "Resources/Static"
     }
+    /// A namespace for the security headers' default configuration values.
+    ///
+    /// `Strict-Transport-Security` is intentionally absent: it is only safe over HTTPS and is
+    /// "sticky" in browsers, so it stays off unless explicitly configured in production.
+    public enum Security {
+        /// The default `Content-Security-Policy`.
+        ///
+        /// Restricts every resource to the site's own origin. `style-src` additionally allows
+        /// `'unsafe-inline'` because ``ErrorPage`` ships an inline `<style>` block; remove it once
+        /// the error page's styles move to an external stylesheet.
+        public static let contentSecurityPolicy = "default-src 'self'; style-src 'self' 'unsafe-inline'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
+        /// The default `X-Content-Type-Options` (disables MIME sniffing).
+        public static let contentTypeOptions = "nosniff"
+        /// The default `X-Frame-Options` (forbids framing the page).
+        public static let frameOptions = "DENY"
+        /// The default `Referrer-Policy`.
+        public static let referrerPolicy = "strict-origin-when-cross-origin"
+        /// The default `Permissions-Policy` (denies access to powerful browser features the site does not use).
+        public static let permissionsPolicy = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
+    }
     /// A namespace for the server string constants.
     public enum Server {
         /// The website server's name.
diff --git a/Services/Website/Sources/Library/Public/Middlewares/SecurityHeadersMiddleware.swift b/Services/Website/Sources/Library/Public/Middlewares/SecurityHeadersMiddleware.swift
new file mode 100644
index 0000000..4bd48e9
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Middlewares/SecurityHeadersMiddleware.swift
@@ -0,0 +1,146 @@
+import HTTPTypes
+import Hummingbird
+
+/// Stamps a set of security-related HTTP headers onto every response.
+///
+/// Placed at (or near) the top of the middleware chain, it adds the configured headers to whatever
+/// response bubbles back up — the rendered landing page, the ``ErrorPage`` produced by
+/// ``NotFoundMiddleware``, and every static file served by `FileMiddleware` — so the browser applies
+/// the strict, hardened interpretation of the content instead of its lenient legacy defaults.
+///
+/// The headers are precomputed once from the ``Configuration`` at initialization and reused for
+/// every request, so the per-request cost is a handful of header copies.
+public struct SecurityHeadersMiddleware<Context: RequestContext> {
+
+    // MARK: Properties
+
+    /// The precomputed headers applied to every response.
+    private let fields: HTTPFields
+
+    // MARK: Initializers
+
+    /// Creates a security-headers middleware.
+    /// - Parameter configuration: the headers applied to every response. Defaults to a hardened
+    ///   baseline suitable for a static site, with `Strict-Transport-Security` left off (see
+    ///   ``Configuration``).
+    public init(
+        configuration: Configuration = .init()
+    ) {
+        self.fields = configuration.fields
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension SecurityHeadersMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Passes the request down the chain and stamps the configured security headers onto the
+    /// response on the way back up.
+    ///
+    /// Existing values for the same header names are replaced so downstream middleware cannot leave
+    /// a weaker policy in place.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response with the security headers applied.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        var response = try await next(request, context)
+
+        for field in fields {
+            response.headers[field.name] = field.value
+        }
+
+        return response
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension SecurityHeadersMiddleware.Configuration {
+
+    // MARK: Computed
+
+    /// The configuration expressed as the headers to apply, omitting any whose value is `nil`.
+    var fields: HTTPFields {
+        var fields = HTTPFields()
+
+        fields[.contentSecurityPolicy] = contentSecurityPolicy
+        fields[.xContentTypeOptions] = contentTypeOptions
+        fields[.frameOptions] = frameOptions
+        fields[.referrerPolicy] = referrerPolicy
+        fields[.permissionsPolicy] = permissionsPolicy
+        fields[.strictTransportSecurity] = strictTransportSecurity
+
+        return fields
+    }
+
+}
+
+// MARK: - Configuration
+
+extension SecurityHeadersMiddleware {
+    /// The set of security headers a ``SecurityHeadersMiddleware`` applies.
+    ///
+    /// Each property maps to a single response header. A `nil` value omits that header entirely,
+    /// which is how `Strict-Transport-Security` stays disabled by default: it is only safe to send
+    /// over HTTPS and is "sticky" in browsers, so it must stay off in plain-HTTP development and be
+    /// switched on (via configuration) only in TLS-terminated production.
+    public struct Configuration: Sendable {
+        
+        // MARK: Properties
+        
+        /// The `Content-Security-Policy` value (controls which sources the browser will load).
+        public let contentSecurityPolicy: String?
+        /// The `X-Content-Type-Options` value (disables MIME sniffing when set to `nosniff`).
+        public let contentTypeOptions: String?
+        /// The `X-Frame-Options` value (controls whether the page may be framed).
+        public let frameOptions: String?
+        /// The `Referrer-Policy` value (controls how much referrer information is shared).
+        public let referrerPolicy: String?
+        /// The `Permissions-Policy` value (gates access to powerful browser features).
+        public let permissionsPolicy: String?
+        /// The `Strict-Transport-Security` value, or `nil` to omit the header (the default).
+        public let strictTransportSecurity: String?
+        
+        // MARK: Initializers
+        
+        /// Creates a security-headers configuration.
+        ///
+        /// Every parameter defaults to the hardened baseline defined in `String.Security`, except
+        /// `strictTransportSecurity`, which defaults to `nil` (omitted). Pass `nil` for any header
+        /// to drop it from the response.
+        /// - Parameters:
+        ///   - contentSecurityPolicy: the `Content-Security-Policy` value.
+        ///   - contentTypeOptions: the `X-Content-Type-Options` value.
+        ///   - frameOptions: the `X-Frame-Options` value.
+        ///   - referrerPolicy: the `Referrer-Policy` value.
+        ///   - permissionsPolicy: the `Permissions-Policy` value.
+        ///   - strictTransportSecurity: the `Strict-Transport-Security` value, or `nil` to omit it.
+        public init(
+            contentSecurityPolicy: String? = String.Security.contentSecurityPolicy,
+            contentTypeOptions: String? = String.Security.contentTypeOptions,
+            frameOptions: String? = String.Security.frameOptions,
+            referrerPolicy: String? = String.Security.referrerPolicy,
+            permissionsPolicy: String? = String.Security.permissionsPolicy,
+            strictTransportSecurity: String? = nil
+        ) {
+            self.contentSecurityPolicy = contentSecurityPolicy
+            self.contentTypeOptions = contentTypeOptions
+            self.frameOptions = frameOptions
+            self.referrerPolicy = referrerPolicy
+            self.permissionsPolicy = permissionsPolicy
+            self.strictTransportSecurity = strictTransportSecurity
+        }
+        
+    }
+}
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 13cce8c..8a968f9 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -33,7 +33,9 @@ struct AppTests {
 
     @Test
     func `landing page to be served at root`() async throws {
-        try await app.test(.router) { client in
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
             try await client.execute(
                 uri: "/",
                 method: .get
@@ -51,7 +53,9 @@ struct AppTests {
     func `static files to be served`(
         staticFile file: StaticFile
     ) async throws {
-        try await app.test(.router) { client in
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
             try await client.execute(
                 uri: "/\(file.relativePath)",
                 method: .get
@@ -73,7 +77,9 @@ struct AppTests {
 
     @Test
     func `response to be compressed when the client supports it`() async throws {
-        try await app.test(.router) { client in
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
             try await client.execute(
                 uri: "/",
                 method: .get,
@@ -87,7 +93,9 @@ struct AppTests {
 
     @Test
     func `response to not be compressed when the client does not support it`() async throws {
-        try await app.test(.router) { client in
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
             try await client.execute(
                 uri: "/",
                 method: .get
@@ -100,7 +108,9 @@ struct AppTests {
 
     @Test
     func `error page to be served when not found`() async throws {
-        try await app.test(.router) { client in
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
             try await client.execute(
                 uri: "/this-path-does-not-exist",
                 method: .get
@@ -114,37 +124,100 @@ struct AppTests {
         }
     }
 
+    @Test
+    func `security headers to be applied to the landing page`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentSecurityPolicy] == String.Security.contentSecurityPolicy)
+                #expect(response.headers[.xContentTypeOptions] == String.Security.contentTypeOptions)
+                #expect(response.headers[.frameOptions] == String.Security.frameOptions)
+                #expect(response.headers[.referrerPolicy] == String.Security.referrerPolicy)
+                #expect(response.headers[.permissionsPolicy] == String.Security.permissionsPolicy)
+                #expect(response.headers[.strictTransportSecurity] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `security headers to be applied to the error page`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                #expect(response.status == .notFound)
+                #expect(response.headers[.contentSecurityPolicy] == String.Security.contentSecurityPolicy)
+                #expect(response.headers[.xContentTypeOptions] == String.Security.contentTypeOptions)
+            }
+        }
+    }
+
+    @Test
+    func `strict-transport-security to be applied when configured`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath,
+            strictTransportSecurity: "max-age=31536000; includeSubDomains"
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.strictTransportSecurity] == "max-age=31536000; includeSubDomains")
+            }
+        }
+    }
+
 }
 
 // MARK: - Helpers
 
 private extension AppTests {
     
-    // MARK: Computed
-    
-    var app: some ApplicationProtocol {
-        get async {
-            await application(
-                reader: reader(
-                    staticFilesPath: staticFilesPath
-                )
-            )
-        }
-    }
-    
     // MARK: Methods
     
-    func reader(
-        staticFilesPath: String
-    ) -> ConfigReader {
-        ConfigReader(providers: [
-            InMemoryProvider(values: [
-                .HTTP.host: "127.0.0.1",
-                .HTTP.port: "0",
-                .Log.level: "trace",
-                .Path.staticFiles: .init(stringLiteral: staticFilesPath),
-            ])
-        ])
+    func app(
+        staticFilesPath: String,
+        strictTransportSecurity: String? = nil
+    ) async -> some ApplicationProtocol {
+        await application(
+            reader: reader(
+                staticFilesPath: staticFilesPath,
+                strictTransportSecurity: strictTransportSecurity
+            )
+        )
     }
     
+    func reader(
+        staticFilesPath: String,
+        strictTransportSecurity: String? = nil
+    ) -> ConfigReader {
+        ConfigReader(providers: [{
+            if let strictTransportSecurity {
+                InMemoryProvider(values: [
+                    .HTTP.host: "127.0.0.1",
+                    .HTTP.port: "0",
+                    .Log.level: "trace",
+                    .Path.staticFiles: .init(stringLiteral: staticFilesPath),
+                    .Security.strictTransportSecurity: .init(stringLiteral: strictTransportSecurity)
+                ])
+            } else {
+                InMemoryProvider(values: [
+                    .HTTP.host: "127.0.0.1",
+                    .HTTP.port: "0",
+                    .Log.level: "trace",
+                    .Path.staticFiles: .init(stringLiteral: staticFilesPath),
+                ])
+            }
+        }()])
+    }
+
 }
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
new file mode 100644
index 0000000..9ea5221
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
@@ -0,0 +1,134 @@
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import WebsiteCore
+
+@Suite("SecurityHeadersMiddleware middleware")
+struct SecurityHeadersMiddlewareTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `applies the default security headers to a response`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentSecurityPolicy] == String.Security.contentSecurityPolicy)
+                #expect(response.headers[.xContentTypeOptions] == String.Security.contentTypeOptions)
+                #expect(response.headers[.frameOptions] == String.Security.frameOptions)
+                #expect(response.headers[.referrerPolicy] == String.Security.referrerPolicy)
+                #expect(response.headers[.permissionsPolicy] == String.Security.permissionsPolicy)
+            }
+        }
+    }
+
+    @Test
+    func `omits strict-transport-security by default`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.headers[.strictTransportSecurity] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `applies strict-transport-security when configured`() async throws {
+        let value = "max-age=31536000; includeSubDomains"
+
+        try await app(
+            configuration: .init(strictTransportSecurity: value)
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.headers[.strictTransportSecurity] == value)
+            }
+        }
+    }
+
+    @Test
+    func `applies a custom header value`() async throws {
+        let value = "default-src 'none'"
+
+        try await app(
+            configuration: .init(contentSecurityPolicy: value)
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.headers[.contentSecurityPolicy] == value)
+            }
+        }
+    }
+
+    @Test
+    func `omits a header whose configured value is nil`() async throws {
+        try await app(
+            configuration: .init(contentTypeOptions: nil)
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.headers[.xContentTypeOptions] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `replaces an existing header value set downstream`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/weak",
+                method: .get
+            ) { response in
+                #expect(response.headers[.xContentTypeOptions] == String.Security.contentTypeOptions)
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension SecurityHeadersMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose router applies the security-headers middleware ahead of two
+    /// routes: `/hello` returns a plain body, and `/weak` returns a response that already carries a
+    /// deliberately weak `X-Content-Type-Options` value for the middleware to override.
+    func app(
+        configuration: SecurityHeadersMiddleware<BasicRequestContext>.Configuration = .init()
+    ) -> some ApplicationProtocol {
+        let router = Router()
+
+        router.addMiddleware {
+            SecurityHeadersMiddleware(configuration: configuration)
+        }
+
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        router.get("weak") { _, _ -> Response in
+            var response = Response(status: .ok)
+
+            response.headers[.xContentTypeOptions] = "weak"
+
+            return response
+        }
+
+        return Application(router: router)
+    }
+
+}
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index 8a29503..d3dc25e 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -20,3 +20,4 @@ services:
     environment:
       LOG_LEVEL: ${LOG_LEVEL:-info}
       HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-LoudWebsite}
+      SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
-- 
2.54.0


From 847058d642b28337f2d90105116fb8d80c4f67bb Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 28 Jun 2026 14:18:04 +0000
Subject: [PATCH 010/117] Optimizations for the Website service (#9)

This PR contains the work done to provide optimizations to the current service, such as a health-check endpoint, pre-renders static HTML pages, and hardens the error page's CSP.

To provide further details about the work:

* Added the `HealthController` controller serving GET `/health` with a static JSON payload.
* Added the `CachedHTMLResponse` response, which renders a static HTMLDocument to bytes once and reuses them per request (no Content-Length, so responses stay compressible).
* Integrated the response into the `RootController` and the  `NotFoundMiddleware` middleware to avoid re-rendering on hot paths.
* Added a `RouterMethods.addRoutes(_:)` extension and switched the router in App+build to use it.
* Moved the inline style from the `ErrorPage` page into a dedicated style file so the CSP needs no inline-style escape hatch.
* Fixed the `IndexPage` page path inconsistencies.
* Written the `README` file.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/9
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/README.md                    | 138 +++++++++++++++++-
 .../Website/Resources/Static/css/error.css    |  43 ++++++
 Services/Website/Sources/App/App+build.swift  |   8 +-
 .../Internal/Enumerations/StaticFile.swift    |  11 +-
 .../Library/Internal/Pages/ErrorPage.swift    |  56 +------
 .../Library/Internal/Pages/IndexPage.swift    |  12 +-
 .../Responses/CachedHTMLResponse.swift        |  54 +++++++
 .../Public/Controllers/HealthController.swift |  83 +++++++++++
 .../Public/Controllers/RootController.swift   |  28 ++--
 .../RouterMethods+RouteCollections.swift      |  80 ++++++++++
 .../Public/Extensions/String+Constants.swift  |   9 +-
 .../Middlewares/NotFoundMiddleware.swift      |  27 ++--
 .../Enumerations/StaticFileTests.swift        |   6 +-
 .../Cases/Internal/Pages/ErrorPageTests.swift |   1 +
 .../Cases/Internal/Pages/IndexPageTests.swift |   8 +-
 .../Controllers/HealthControllerTests.swift   |  39 +++++
 16 files changed, 508 insertions(+), 95 deletions(-)
 create mode 100644 Services/Website/Resources/Static/css/error.css
 create mode 100644 Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
 create mode 100644 Services/Website/Sources/Library/Public/Controllers/HealthController.swift
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/RouterMethods+RouteCollections.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift

diff --git a/Services/Website/README.md b/Services/Website/README.md
index eb5764d..0e0bacd 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -1,2 +1,136 @@
-# Website
-Hummingbird server framework project
\ No newline at end of file
+# Loud Website
+The **Loud** public website service — a [Hummingbird](https://github.com/hummingbird-project/hummingbird) server that renders a static landing page and serves the site's static assets.
+
+## Overview
+The service:
+- Serves the landing page at `GET /` (rendered once with [Elementary](https://github.com/elementary-swift/elementary) and cached).
+- Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`.
+- Returns a custom HTML 404 page for any request that matches neither a route nor a static file.
+- Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
+- Stamps a hardened set of security headers on every response.
+
+## Requirements
+- Swift 6.3 toolchain (`swift-tools-version:6.3`).
+- Docker (optional) for the containerized run/deploy workflow.
+
+## Architecture
+Two SwiftPM targets:
+| Target | Kind | Path | Role |
+| --- | --- | --- | --- |
+| `Website` | executable | `Sources/App` | Entry point: reads configuration, builds and runs the application. |
+| `WebsiteCore` | library | `Sources/Library` | Controllers, middlewares, pages, cached responses, and configuration helpers. |
+
+Requests pass through the middleware chain in this order (outermost first), then reach the routes:
+```
+LogRequestsMiddleware
+  → SecurityHeadersMiddleware      (security headers on every response)
+    → ResponseCompressionMiddleware (gzip/deflate above the size threshold)
+      → NotFoundMiddleware          (renders the 404 page on .notFound)
+        → FileMiddleware            (serves Resources/Static)
+RootController                      (GET / → landing page)
+```
+
+## Configuration
+Configuration is read through [swift-configuration](https://github.com/apple/swift-configuration) from
+the following sources, **highest precedence first**:
+1. Command-line arguments (e.g. `--http-host 0.0.0.0`)
+2. Process environment variables
+3. A `.env` file in the working directory (optional)
+4. Built-in defaults
+
+### Environment variable naming
+A dotted config key maps to an environment variable by upper-casing, splitting camelCase, and replacing separators with `_`. For example `http.serverName` → `HTTP_SERVER_NAME`,
+`security.strictTransportSecurity` → `SECURITY_STRICT_TRANSPORT_SECURITY`, `cache.maxAge.text` →` CACHE_MAX_AGE_TEXT`.
+> To disable a header or override a value, leave the variable **unset** to fall back to the default. A
+> variable that is set but **blank** is treated as an explicit empty value, not as "use the default".
+
+### Static file caching
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `cache.maxAge.text` | `CACHE_MAX_AGE_TEXT` | `3600` (1 hour) | `max-age` for text assets (CSS, JS, plain text); also marked `must-revalidate`. |
+| `cache.maxAge.image` | `CACHE_MAX_AGE_IMAGE` | `604800` (1 week) | `max-age` for images (ICO, PNG, SVG). |
+| `cache.maxAge.default` | `CACHE_MAX_AGE_DEFAULT` | `86400` (1 day) | `max-age` for everything else (e.g. the web manifest). |
+
+### Response compression
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `compression.minimumResponseSize` | `COMPRESSION_MINIMUM_RESPONSE_SIZE` | `1024` | Minimum response body size, in bytes, before compression is applied. |
+
+### HTTP server
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `http.host` | `HTTP_HOST` | _none_ | Host the server binds to. Supplied via the `--http-host` CLI flag (the Docker image passes `0.0.0.0`). |
+| `http.port` | `HTTP_PORT` | _none_ | Port the server listens on. Supplied via the `--http-port` CLI flag (the Docker image passes `8080`). |
+| `http.serverName` | `HTTP_SERVER_NAME` | `LoudWebsite` | Server name and logger label. |
+
+### Logging
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `log.level` | `LOG_LEVEL` | `info` | Minimum log level. |
+
+### Paths
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `path.staticFiles` | `PATH_STATIC_FILES` | `Resources/Static` | Directory, relative to the working directory, that static files are served from. |
+
+### Security headers
+| Config key | Environment variable | Default |
+| --- | --- | --- |
+| `security.contentSecurityPolicy` | `SECURITY_CONTENT_SECURITY_POLICY` | `default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'` |
+| `security.contentTypeOptions` | `SECURITY_CONTENT_TYPE_OPTIONS` | `nosniff` |
+| `security.frameOptions` | `SECURITY_FRAME_OPTIONS` | `DENY` |
+| `security.referrerPolicy` | `SECURITY_REFERRER_POLICY` | `strict-origin-when-cross-origin` |
+| `security.permissionsPolicy` | `SECURITY_PERMISSIONS_POLICY` | `accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()` |
+| `security.strictTransportSecurity` | `SECURITY_STRICT_TRANSPORT_SECURITY` | _none (omitted)_ |
+
+`Strict-Transport-Security` has **no default** and is omitted unless explicitly configured: it only takes effect over HTTPS (browsers ignore it on plain HTTP) and is "sticky" in browsers, so it must stay off in local HTTP development. It is enabled for production in `docker-compose.yml`, where it only has an effect once traffic is served over HTTPS behind a TLS-terminating proxy.
+
+## Running locally
+Directly with Swift:
+```sh
+swift run Website # binds to Hummingbird's default 127.0.0.1:8080
+swift run Website --http-host 0.0.0.0 --http-port 9000 --log-level debug
+```
+
+Or via the Makefile / Docker (uses `docker-compose.override.yml`, which builds from source and sets`LOG_LEVEL=debug`:
+```sh
+make pkg-build        # swift build
+make img-mount        # docker compose up --build --detach
+make img-unmount      # docker compose down + remove the local image
+```
+
+`make help` lists every available target.
+## Testing
+```sh
+make pkg-test
+# = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
+```
+
+Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The`Website.xctestplan` covers two targets: `WebsiteTests` (the executable/integration tests) and` WebsiteCoreTests` (the library unit tests).
+
+## Deployment
+The production image is built for `linux/amd64` in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080`(`ENTRYPOINT ./Website --http-host 0.0.0.0 --http-port 8080`).
+Build, tag, and push a release to the registry (an explicit version is required):
+```sh
+make img-release version=1.2.3
+```
+
+Pull and run the prebuilt image in production — the `-f docker-compose.yml` flag is important, as it skips the local-development override:
+```sh
+docker compose -f docker-compose.yml pull
+docker compose -f docker-compose.yml up -d
+```
+
+### Required variables
+The Makefile and Compose files read these from a `.env` file (or the environment). Provide your own values — do **not** commit secrets.
+| Variable | Used for |
+| --- | --- |
+| `HOST_CONTAINER` | Container registry host (e.g. `registry.example.com`). |
+| `HOST_OWNER` | Registry namespace / owner. |
+| `HOST_USER`, `HOST_PASSWORD` | Registry credentials for `make img-release`. |
+| `IMAGE_NAME`, `IMAGE_TAG` | Image name and tag. |
+| `IMAGE_PLATFORM` | Build platform (e.g. `linux/amd64`). |
+| `HOST_PORT` | Host port mapped to the container's `8080` (default `8080`). |
+| `LOG_LEVEL` | Runtime log level (default `info`). |
+| `HTTP_SERVER_NAME` | Runtime server name (default `LoudWebsite`). |
+| `SECURITY_STRICT_TRANSPORT_SECURITY` | HSTS header value (default `max-age=31536000; includeSubDomains`). |
diff --git a/Services/Website/Resources/Static/css/error.css b/Services/Website/Resources/Static/css/error.css
new file mode 100644
index 0000000..5a95a8d
--- /dev/null
+++ b/Services/Website/Resources/Static/css/error.css
@@ -0,0 +1,43 @@
+/* Styles for the not-found (404) error page. */
+
+* {
+  line-height: 1.2;
+  margin: 0;
+}
+
+html {
+  color: #888;
+  display: table;
+  font-family: sans-serif;
+  height: 100%;
+  text-align: center;
+  width: 100%;
+}
+
+body {
+  display: table-cell;
+  vertical-align: middle;
+  margin: 2em auto;
+}
+
+h1 {
+  color: #555;
+  font-size: 2em;
+  font-weight: 400;
+}
+
+p {
+  margin: 0 auto;
+  width: 280px;
+}
+
+@media only screen and (max-width: 280px) {
+  body, p {
+    width: 95%;
+  }
+
+  h1 {
+    font-size: 1.5em;
+    margin: 0 0 0.3em;
+  }
+}
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
index 6514a8e..c24d390 100644
--- a/Services/Website/Sources/App/App+build.swift
+++ b/Services/Website/Sources/App/App+build.swift
@@ -155,7 +155,8 @@ private func logger(
 /// responses larger than `minimumResponseSizeToCompress` when the client advertises support, the
 /// not-found middleware that serves the error page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then
-/// adds the `RootController` routes that render the landing page.
+/// adds the `RootController` routes that render the landing page and the `HealthController` routes
+/// that serve the health check.
 ///
 /// The security-headers middleware sits just inside request logging so it covers every response that
 /// reaches a client — the landing page, the compressed responses, the rendered error page, and the
@@ -191,7 +192,10 @@ private func router(
         )
     }
 
-    router.addRoutes(RootController<AppRequestContext>().routes)
+    router.addRoutes {
+        RootController<AppRequestContext>().routes
+        HealthController<AppRequestContext>().routes
+    }
 
     return router
 }
diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
index 0c72430..ef81f21 100644
--- a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
@@ -5,6 +5,8 @@
 enum StaticFile: CaseIterable, Sendable {
     /// The `js/app.js` script.
     case appJS
+    /// The `css/error.css` stylesheet for the not-found page.
+    case errorCSS
     /// The `favicon.ico` icon.
     case faviconICO
     /// The `icon.png` icon.
@@ -63,7 +65,8 @@ extension StaticFile {
     /// The file's extension.
     var fileExtension: Extension {
         switch self {
-        case .styleCSS: .css
+        case .errorCSS,
+             .styleCSS: .css
         case .appJS: .js
         case .faviconICO: .ico
         case .iconPNG: .png
@@ -77,6 +80,7 @@ extension StaticFile {
     var fileName: String {
         switch self {
         case .appJS: "app"
+        case .errorCSS: "error"
         case .faviconICO: "favicon"
         case .iconPNG,
              .iconSVG: "icon"
@@ -102,7 +106,7 @@ extension StaticFile {
     /// 
     /// - Parameter basePath: the directory the static files are served from.
     /// - Returns: the path to the file, relative to the `basePath` path.
-    public func path(
+    func path(
         relativeTo basePath: String
     ) -> String {
         guard !basePath.isEmpty else {
@@ -124,7 +128,8 @@ private extension StaticFile {
     var subdirectory: String? {
         switch self {
         case .appJS: "js"
-        case .styleCSS: "css"
+        case .errorCSS,
+             .styleCSS: "css"
         default: nil
         }
     }
diff --git a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
index b59df57..733ae1d 100644
--- a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
@@ -11,14 +11,17 @@ struct ErrorPage: HTMLDocument, Sendable {
         p { "Sorry, but the page you were trying to view does not exist." }
     }
 
-    /// The metadata and inline styles placed in the document head.
+    /// The metadata and stylesheet link placed in the document head.
     var head: some HTML {
         meta(.charset(.utf8))
         meta(
             .name(.viewport),
             .content("width=device-width, initial-scale=1")
         )
-        style { Self.styles }
+        link(
+            .rel(.stylesheet),
+            .href("/css/error.css")
+        )
     }
 
     /// The document language.
@@ -28,52 +31,3 @@ struct ErrorPage: HTMLDocument, Sendable {
     var title: String { "Page Not Found" }
 
 }
-
-// MARK: - Constants
-
-private extension ErrorPage {
-    /// The inline CSS applied to the page.
-    static let styles = """
-        * {
-          line-height: 1.2;
-          margin: 0;
-        }
-
-        html {
-          color: #888;
-          display: table;
-          font-family: sans-serif;
-          height: 100%;
-          text-align: center;
-          width: 100%;
-        }
-
-        body {
-          display: table-cell;
-          vertical-align: middle;
-          margin: 2em auto;
-        }
-
-        h1 {
-          color: #555;
-          font-size: 2em;
-          font-weight: 400;
-        }
-
-        p {
-          margin: 0 auto;
-          width: 280px;
-        }
-
-        @media only screen and (max-width: 280px) {
-          body, p {
-            width: 95%;
-          }
-
-          h1 {
-            font-size: 1.5em;
-            margin: 0 0 0.3em;
-          }
-        }
-        """
-}
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index d55429b..23630d2 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -8,7 +8,7 @@ struct IndexPage: HTMLDocument, Sendable {
     /// The page's content.
     var body: some HTML {
         p { "Hello world! This is HTML5 Boilerplate." }
-        script(.src("js/app.js")) {}
+        script(.src("/js/app.js")) {}
     }
 
     /// The metadata, stylesheet, icon, and manifest links placed in the document head.
@@ -20,7 +20,7 @@ struct IndexPage: HTMLDocument, Sendable {
         )
         link(
             .rel(.stylesheet),
-            .href("css/style.css")
+            .href("/css/style.css")
         )
         link(
             .rel(.icon),
@@ -40,11 +40,11 @@ struct IndexPage: HTMLDocument, Sendable {
         )
         link(
             .rel("apple-touch-icon"),
-            .href("icon.png")
+            .href("/icon.png")
         )
         link(
             .rel("manifest"),
-            .href("site.webmanifest")
+            .href("/site.webmanifest")
         )
         meta(
             .name("theme-color"),
@@ -58,6 +58,8 @@ struct IndexPage: HTMLDocument, Sendable {
     }
 
     /// The document title.
-    var title: String { "" }
+    var title: String {
+        "Index page"
+    }
 
 }
diff --git a/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift b/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
new file mode 100644
index 0000000..6b1dcfb
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
@@ -0,0 +1,54 @@
+import Elementary
+import Hummingbird
+import NIOCore
+
+/// A pre-rendered HTTP response for a fully static HTML page.
+///
+/// The document is rendered to bytes once, at initialization, and every ``response()`` reuses those
+/// bytes instead of re-rendering. This suits pages whose markup never changes between requests — the
+/// landing page and the not-found page — avoiding a per-request Elementary render on hot paths.
+///
+/// The body is written as an unsized stream (no `Content-Length`), mirroring `HTMLResponse`, so the
+/// response-compression middleware downstream treats it exactly as it would a freshly rendered page.
+struct CachedHTMLResponse: Sendable {
+
+    // MARK: Properties
+
+    /// The status applied to every response.
+    private let status: HTTPResponse.Status
+    /// The page rendered to bytes once.
+    private let buffer: ByteBuffer
+
+    // MARK: Initializers
+
+    /// Renders the given document to bytes once.
+    /// - Parameters:
+    ///   - status: the status applied to every response. Defaults to `.ok`.
+    ///   - document: the static HTML document to render and cache.
+    init(
+        status: HTTPResponse.Status = .ok,
+        _ document: some HTMLDocument
+    ) {
+        self.status = status
+        self.buffer = ByteBuffer(string: document.render())
+    }
+
+    // MARK: Methods
+
+    /// Builds a response from the cached, pre-rendered bytes.
+    ///
+    /// Mirrors the `text/html; charset=utf-8` content type `HTMLResponse` produces, and leaves the
+    /// `Content-Length` unset so small pages remain eligible for compression.
+    /// - Returns: the response carrying the cached HTML body.
+    func response() -> Response {
+        Response(
+            status: status,
+            headers: [.contentType: "text/html; charset=utf-8"],
+            body: .init { [buffer] writer in
+                try await writer.write(buffer)
+                try await writer.finish(nil)
+            }
+        )
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
new file mode 100644
index 0000000..f465d38
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
@@ -0,0 +1,83 @@
+import Hummingbird
+import NIOCore
+
+/// Serves the website's health-check route.
+///
+/// The controller exposes its routes as a `RouteCollection` so they can be added to a router
+/// (or a sub-group) by the application that composes it:
+///
+/// ```swift
+/// router.addRoutes(HealthController<AppRequestContext>().routes)
+/// ```
+///
+/// - Note: `Context` is the request context the routes are resolved against, and must match the
+///   context of the router the routes are added to.
+public struct HealthController<Context: RequestContext>: Sendable {
+    
+    // MARK: Properties
+    
+    /// The JSON payload returned for every health check.
+    private let payload: String
+
+    // MARK: Initializers
+
+    /// Creates a health controller.
+    public init() {
+        self.payload = #"{"status":"ok"}"#
+    }
+
+    // MARK: Computed
+
+    /// The routes served by the controller.
+    ///
+    /// Serves a `GET` request for the health path (`/health`) with a static JSON status payload.
+    public var routes: RouteCollection<Context> {
+        let routes = RouteCollection(context: Context.self)
+
+        routes.get(
+            .Health.check,
+            use: check
+        )
+
+        return routes
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension HealthController {
+
+    // MARK: Methods
+
+    /// Handles a request for the health check.
+    ///
+    /// Returns a constant JSON body built directly per request — the payload is a tiny literal with no
+    /// rendering step, so there is nothing to pre-render or cache.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    /// - Returns: a `200 OK` response carrying the static JSON status payload.
+    @Sendable
+    func check(
+        request: Request,
+        context: some RequestContext
+    ) -> Response {
+        Response(
+            status: .ok,
+            headers: [.contentType: "application/json"],
+            body: .init(byteBuffer: .init(string: payload))
+        )
+    }
+
+}
+
+// MARK: - Constants
+
+private extension RouterPath {
+    /// A namespace for the ``HealthController`` route paths.
+    enum Health {
+        /// The path of the health-check endpoint.
+        static let check: RouterPath = "/health"
+    }
+}
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index 0cd1ab6..811f696 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -1,5 +1,4 @@
 import Hummingbird
-import HummingbirdElementary
 
 /// Serves the website's root routes.
 ///
@@ -12,14 +11,21 @@ import HummingbirdElementary
 ///
 /// - Note: `Context` is the request context the routes are resolved against, and must match the
 ///   context of the router the routes are added to.
-public struct RootController<Context: RequestContext> : Sendable{
+public struct RootController<Context: RequestContext>: Sendable {
+
+    // MARK: Properties
+
+    /// The landing page, rendered once at initialization and reused for every request.
+    private let cache: CachedHTMLResponse
 
     // MARK: Initializers
 
     /// Creates a root controller.
-    public init() {}
+    public init() {
+        self.cache = .init(IndexPage())
+    }
 
-    // MARK: Properties
+    // MARK: Computed
 
     /// The routes served by the controller.
     ///
@@ -40,29 +46,27 @@ public struct RootController<Context: RequestContext> : Sendable{
 // MARK: - Helpers
 
 private extension RootController {
-    
+
     // MARK: Methods
 
     /// Handles a request for the landing page.
     /// - Parameters:
     ///   - request: the incoming request.
     ///   - context: the context the request is resolved against.
-    /// - Returns: an HTML response that renders the ``IndexPage``.
+    /// - Returns: the cached ``IndexPage`` response.
     @Sendable
     func index(
         request: Request,
         context: some RequestContext
-    ) -> HTMLResponse {
-        .init {
-            IndexPage()
-        }
+    ) -> Response {
+        cache.response()
     }
-    
+
 }
 
 // MARK: - Constants
 
-extension RouterPath {
+private extension RouterPath {
     /// A namespace for the ``RootController`` route paths.
     enum Root {
         /// The path of the landing page.
diff --git a/Services/Website/Sources/Library/Public/Extensions/RouterMethods+RouteCollections.swift b/Services/Website/Sources/Library/Public/Extensions/RouterMethods+RouteCollections.swift
new file mode 100644
index 0000000..038671d
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/RouterMethods+RouteCollections.swift
@@ -0,0 +1,80 @@
+import Hummingbird
+
+/// A result builder that collects ``RouteCollection`` values into a stack.
+///
+/// Mirrors the `MiddlewareFixedTypeBuilder` Hummingbird uses for `addMiddleware`, letting route
+/// collections be listed declaratively rather than added one statement at a time.
+@resultBuilder
+public enum RouteCollectionBuilder<Context: RequestContext> {
+
+    public static func buildExpression(
+        _ collection: RouteCollection<Context>
+    ) -> [RouteCollection<Context>] {
+        [collection]
+    }
+
+    public static func buildBlock(
+        _ collections: [RouteCollection<Context>]...
+    ) -> [RouteCollection<Context>] {
+        collections.flatMap { $0 }
+    }
+
+    public static func buildOptional(
+        _ collections: [RouteCollection<Context>]?
+    ) -> [RouteCollection<Context>] {
+        collections ?? []
+    }
+
+    public static func buildEither(
+        first collections: [RouteCollection<Context>]
+    ) -> [RouteCollection<Context>] {
+        collections
+    }
+
+    public static func buildEither(
+        second collections: [RouteCollection<Context>]
+    ) -> [RouteCollection<Context>] {
+        collections
+    }
+
+    public static func buildArray(
+        _ collections: [[RouteCollection<Context>]]
+    ) -> [RouteCollection<Context>] {
+        collections.flatMap { $0 }
+    }
+
+}
+
+// MARK: - Helpers
+
+public extension RouterMethods {
+
+    // MARK: Methods
+
+    /// Adds route collections to the router using the ``RouteCollectionBuilder`` result builder.
+    ///
+    /// Mirrors `addMiddleware`, letting controllers be listed declaratively:
+    ///
+    /// ```swift
+    /// router.addRoutes {
+    ///     RootController<AppRequestContext>().routes
+    ///     HealthController<AppRequestContext>().routes
+    /// }
+    /// ```
+    ///
+    /// Each collection is added at the router's root, exactly as a sequence of
+    /// `addRoutes(_:)` calls would.
+    /// - Parameter build: the route-collection stack result builder.
+    /// - Returns: the router, so calls can be chained.
+    @discardableResult
+    func addRoutes(
+        @RouteCollectionBuilder<Context> _ build: () -> [RouteCollection<Context>]
+    ) -> Self {
+        for collection in build() {
+            addRoutes(collection)
+        }
+
+        return self
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 63639d9..c9620ca 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -11,10 +11,11 @@ extension String {
     public enum Security {
         /// The default `Content-Security-Policy`.
         ///
-        /// Restricts every resource to the site's own origin. `style-src` additionally allows
-        /// `'unsafe-inline'` because ``ErrorPage`` ships an inline `<style>` block; remove it once
-        /// the error page's styles move to an external stylesheet.
-        public static let contentSecurityPolicy = "default-src 'self'; style-src 'self' 'unsafe-inline'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
+        /// Restricts every resource to the site's own origin (`default-src 'self'`), blocks plugins
+        /// (`object-src 'none'`), pins the document base URL (`base-uri 'self'`), and forbids framing
+        /// (`frame-ancestors 'none'`). Both pages link external stylesheets, so no inline-style
+        /// exception is required.
+        public static let contentSecurityPolicy = "default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
         /// The default `X-Content-Type-Options` (disables MIME sniffing).
         public static let contentTypeOptions = "nosniff"
         /// The default `X-Frame-Options` (forbids framing the page).
diff --git a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift b/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
index 6032f9f..abbbdfd 100644
--- a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
+++ b/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
@@ -1,6 +1,4 @@
-import Elementary
 import Hummingbird
-import HummingbirdElementary
 
 /// Serves a custom error page for requests that match neither a route nor a static file.
 ///
@@ -9,10 +7,20 @@ import HummingbirdElementary
 /// ``ErrorPage`` and a `404 Not Found` status.
 public struct NotFoundMiddleware<Context: RequestContext> {
 
+    // MARK: Properties
+
+    /// The error page, rendered once at initialization and reused for every not-found response.
+    private let cache: CachedHTMLResponse
+
     // MARK: Initializers
 
     /// Creates a not-found middleware.
-    public init() {}
+    public init() {
+        self.cache = .init(
+            status: .notFound,
+            ErrorPage()
+        )
+    }
 
 }
 
@@ -39,7 +47,8 @@ extension NotFoundMiddleware: RouterMiddleware {
     ) async throws -> Response {
         do {
             return try await next(request, context)
-        } catch let error {
+        }
+        catch let error {
             guard
                 let responseError = error as? any HTTPResponseError,
                 responseError.status == .notFound
@@ -47,15 +56,7 @@ extension NotFoundMiddleware: RouterMiddleware {
                 throw error
             }
 
-            return HTMLResponse(
-                status: .notFound
-            ) {
-                ErrorPage()
-            }
-            .response(
-                from: request,
-                context: context
-            )
+            return cache.response()
         }
     }
 
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index ba7b26d..284009c 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -82,7 +82,7 @@ struct StaticFileTests {
     
     @Test
     func `all cases`() {
-        #expect(File.allCases.count == 7)
+        #expect(File.allCases.count == 8)
     }
     
 }
@@ -95,6 +95,7 @@ private extension StaticFileTests {
     
     static let contentTypes: [String] = [
         "text/javascript",
+        "text/css",
         "image/vnd.microsoft.icon",
         "image/png",
         "image/svg+xml",
@@ -104,6 +105,7 @@ private extension StaticFileTests {
     ]
     static let fileExtensions: [FileExtension] = [
         .js,
+        .css,
         .ico,
         .png,
         .svg,
@@ -113,6 +115,7 @@ private extension StaticFileTests {
     ]
     static let fileNames: [String] = [
         "app",
+        "error",
         "favicon",
         "icon",
         "icon",
@@ -122,6 +125,7 @@ private extension StaticFileTests {
     ]
     static let relativePaths: [String] = [
         "js/app.js",
+        "css/error.css",
         "favicon.ico",
         "icon.png",
         "icon.svg",
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
index 45d74cb..c320657 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
@@ -15,6 +15,7 @@ struct ErrorPageTests {
         #expect(html.contains("<!DOCTYPE html>"))
         #expect(html.contains("Page Not Found"))
         #expect(html.contains("does not exist"))
+        #expect(html.contains("/css/error.css"))
     }
 
 }
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index 1e0233c..1594721 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -13,9 +13,13 @@ struct IndexPageTests {
         let html = IndexPage().render()
 
         #expect(html.contains("<!DOCTYPE html>"))
+        #expect(html.contains("/css/style.css"))
+        #expect(html.contains("/favicon.ico"))
+        #expect(html.contains("/icon.svg"))
+        #expect(html.contains("/icon.png"))
+        #expect(html.contains("/site.webmanifest"))
         #expect(html.contains("Hello world!"))
-        #expect(html.contains("css/style.css"))
-        #expect(html.contains("js/app.js"))
+        #expect(html.contains("/js/app.js"))
     }
 
 }
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
new file mode 100644
index 0000000..5a5d3c1
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -0,0 +1,39 @@
+import Hummingbird
+import HummingbirdTesting
+import NIOCore
+import Testing
+
+@testable import WebsiteCore
+
+@Suite("HealthController controller")
+struct HealthControllerTests {
+
+    // MARK: Constants
+
+    private let app: Application = .init(router: {
+        let router = Router()
+
+        router.addRoutes(HealthController<BasicRequestContext>().routes)
+
+        return router
+    }())
+
+    // MARK: Functional tests
+
+    @Test
+    func `serves the status payload at the health path`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/health",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == "application/json")
+                #expect(body == #"{"status":"ok"}"#)
+            }
+        }
+    }
+
+}
-- 
2.54.0


From 6c66ea74ccddce89dee7e5e8929f7d08b5027bc4 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 29 Jun 2026 23:08:36 +0000
Subject: [PATCH 011/117] Localization support for the Website service (#10)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR contains the work done to introduce server-side localization support to the **Website** service so the landing and error pages are served in the visitor's negotiated language, backed by a new reusable Localization package.

To provide further details about the work:

* Created the _Localization_ package — a bundle-bound `Localize` method and a `LanguageList` type.
* Language negotiation — `NegotiateLanguage` method picks the best supported language from the request's _Accept-Language_ header (falling back to the default); the `LocalizationMiddleware` middleware resolves it per request and stores it on a new `LocalizedRequestContext` / `WebsiteRequestContext` context.
* Localized responses — `LocalizedHTMLCollectionResponse` pre-renders each page once per language and caches the bytes (with `Content-Language` + `Vary: Accept-Language`), reused by the  `RootController` controller and `NotFoundMiddleware` middleware.
* The `CachedHTMLResponse` response gained custom-header support.
* Localized pages — the `IndexPage` and `ErrorPage` pages now resolve their strings via `Localize` method;
* Added `Localizable.xcstrings` catalogs.
* Wired the `LocalizationMiddleware` middlewaer into the router.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/10
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../xcschemes/Localization.xcscheme           | 77 +++++++++++++++++
 Packages/Localization/Package.swift           | 37 ++++++++
 .../Sources/Methods/Localize.swift            | 45 ++++++++++
 .../Sources/Types/LanguageList.swift          | 46 ++++++++++
 .../Tests/Cases/Methods/LocalizeTests.swift   | 45 ++++++++++
 .../Tests/Cases/Types/LanguageListTests.swift | 65 ++++++++++++++
 .../Tests/Catalogs/Localizable.xcstrings      | 23 +++++
 Services/Website/Package.swift                | 10 ++-
 Services/Website/Sources/App/App+build.swift  |  6 +-
 .../Library/Catalogs/Localizable.xcstrings    | 61 +++++++++++++
 .../Internal/Methods/NegotiateLanguage.swift  | 85 +++++++++++++++++++
 .../Library/Internal/Pages/ErrorPage.swift    | 46 ++++++++--
 .../Library/Internal/Pages/IndexPage.swift    | 38 +++++++--
 .../Responses/CachedHTMLResponse.swift        | 32 +++++--
 .../LocalizedHTMLCollectionResponse.swift     | 65 ++++++++++++++
 .../Contexts/LocalizedRequestContext.swift    | 42 +++++++++
 .../Public/Controllers/RootController.swift   | 20 +++--
 .../Middlewares/LocalizationMiddleware.swift  | 56 ++++++++++++
 .../Middlewares/NotFoundMiddleware.swift      | 22 +++--
 .../Cases/Internal/Pages/ErrorPageTests.swift |  8 +-
 .../Cases/Internal/Pages/IndexPageTests.swift |  6 +-
 .../Controllers/RootControllerTests.swift     | 12 ++-
 .../LocalizationMiddlewareTests.swift         | 55 ++++++++++++
 .../Middlewares/NotFoundMiddlewareTests.swift |  5 +-
 24 files changed, 858 insertions(+), 49 deletions(-)
 create mode 100644 Packages/Localization/.swiftpm/xcode/xcshareddata/xcschemes/Localization.xcscheme
 create mode 100644 Packages/Localization/Package.swift
 create mode 100644 Packages/Localization/Sources/Methods/Localize.swift
 create mode 100644 Packages/Localization/Sources/Types/LanguageList.swift
 create mode 100644 Packages/Localization/Tests/Cases/Methods/LocalizeTests.swift
 create mode 100644 Packages/Localization/Tests/Cases/Types/LanguageListTests.swift
 create mode 100644 Packages/Localization/Tests/Catalogs/Localizable.xcstrings
 create mode 100644 Services/Website/Sources/Library/Catalogs/Localizable.xcstrings
 create mode 100644 Services/Website/Sources/Library/Internal/Methods/NegotiateLanguage.swift
 create mode 100644 Services/Website/Sources/Library/Internal/Responses/LocalizedHTMLCollectionResponse.swift
 create mode 100644 Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift
 create mode 100644 Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift

diff --git a/Packages/Localization/.swiftpm/xcode/xcshareddata/xcschemes/Localization.xcscheme b/Packages/Localization/.swiftpm/xcode/xcshareddata/xcschemes/Localization.xcscheme
new file mode 100644
index 0000000..c25c6ee
--- /dev/null
+++ b/Packages/Localization/.swiftpm/xcode/xcshareddata/xcschemes/Localization.xcscheme
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "2700"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "Localization"
+               BuildableName = "Localization"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      shouldAutocreateTestPlan = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "LocalizationTests"
+               BuildableName = "LocalizationTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES"
+      queueDebuggingEnabled = "No">
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "Localization"
+            BuildableName = "Localization"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </MacroExpansion>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
diff --git a/Packages/Localization/Package.swift b/Packages/Localization/Package.swift
new file mode 100644
index 0000000..277db4a
--- /dev/null
+++ b/Packages/Localization/Package.swift
@@ -0,0 +1,37 @@
+// swift-tools-version:6.3
+
+import PackageDescription
+
+let package = Package(
+    name: "Localization",
+    defaultLocalization: "en",
+    platforms: [
+        .macOS(.v15),
+        .iOS(.v18),
+        .tvOS(.v18),
+    ],
+    products: [
+        .library(
+            name: "Localization",
+            targets: [
+                "Localization"
+            ]
+        )
+    ],
+    targets: [
+        .target(
+            name: "Localization",
+            path: "Sources",
+        ),
+        .testTarget(
+            name: "LocalizationTests",
+            dependencies: [
+                .byName(name: "Localization")
+            ],
+            path: "Tests",
+            resources: [
+                .process("Catalogs/Localizable.xcstrings")
+            ]
+        ),
+    ]
+)
diff --git a/Packages/Localization/Sources/Methods/Localize.swift b/Packages/Localization/Sources/Methods/Localize.swift
new file mode 100644
index 0000000..2acb900
--- /dev/null
+++ b/Packages/Localization/Sources/Methods/Localize.swift
@@ -0,0 +1,45 @@
+import Foundation
+
+/// A reusable, bundle-bound localizer that resolves String Catalog entries for an explicit locale.
+///
+/// A server has no single "current" locale, so each lookup must name the locale to use. An instance
+/// is bound to the bundle whose catalog holds the strings, then invoked like a function to resolve a
+/// key in a chosen locale.
+public struct Localize: Sendable {
+
+    // MARK: Properties
+
+    /// The bundle whose compiled String Catalog the keys are resolved against.
+    private let bundle: Bundle
+
+    // MARK: Initializers
+
+    /// Creates a localizer backed by the given bundle.
+    /// - Parameter bundle: the bundle whose String Catalog contains the keys to resolve.
+    public init(
+        bundle: Bundle
+    ) {
+        self.bundle = bundle
+    }
+
+    // MARK: Methods
+
+    /// Resolves a catalog key in the given locale.
+    ///
+    /// Invoked by calling the instance directly, for example `localize("index.title", locale: locale)`.
+    /// - Parameters:
+    ///   - key: the String Catalog key to look up.
+    ///   - locale: the locale to resolve the key in.
+    /// - Returns: the localized string for the locale, or the key itself when the bundle's catalog has no entry for it.
+    public func callAsFunction(
+        _ key: String.LocalizationValue,
+        locale: Locale
+    ) -> String {
+        .init(localized: .init(
+            key,
+            locale: locale,
+            bundle: .atURL(bundle.bundleURL)
+        ))
+    }
+
+}
diff --git a/Packages/Localization/Sources/Types/LanguageList.swift b/Packages/Localization/Sources/Types/LanguageList.swift
new file mode 100644
index 0000000..0b7f476
--- /dev/null
+++ b/Packages/Localization/Sources/Types/LanguageList.swift
@@ -0,0 +1,46 @@
+import Foundation
+
+/// The list of languages an app can serve, derived from a bundle's String Catalog.
+///
+/// The languages are read from the injected `bundle`'s compiled localizations, so the catalog that
+/// ships in that bundle is the single source of truth: adding a language is a translation-only
+/// change — once a locale exists in the catalog, it appears in ``all`` with no code change required.
+public struct LanguageList: Sendable {
+
+    // MARK: Properties
+
+    /// The language served when none of the supported languages match a request.
+    ///
+    /// Should match the catalog bundle's development localization.
+    public let `default`: String
+
+    /// The bundle whose compiled String Catalog defines the available languages.
+    private let bundle: Bundle
+
+    // MARK: Initializers
+
+    /// Creates a language list backed by the given bundle.
+    /// - Parameters:
+    ///   - bundle: the bundle whose String Catalog defines the available languages.
+    ///   - default: the language served when none of the supported languages match. Defaults to `"en"`.
+    public init(
+        bundle: Bundle,
+        `default`: String = "en"
+    ) {
+        self.bundle = bundle
+        self.`default` = `default`
+    }
+
+    // MARK: Computed
+
+    /// Every language the bundle's String Catalog provides a localization for.
+    ///
+    /// The `Base` internationalization is excluded, as it is a development placeholder rather than a
+    /// real language.
+    public var all: [String] {
+        bundle
+            .localizations
+            .filter { $0 != "Base" }
+    }
+
+}
diff --git a/Packages/Localization/Tests/Cases/Methods/LocalizeTests.swift b/Packages/Localization/Tests/Cases/Methods/LocalizeTests.swift
new file mode 100644
index 0000000..502d226
--- /dev/null
+++ b/Packages/Localization/Tests/Cases/Methods/LocalizeTests.swift
@@ -0,0 +1,45 @@
+import Foundation
+import Testing
+
+@testable import Localization
+
+@Suite("Localize method")
+struct LocalizeTests {
+    
+    // MARK: Constants
+    
+    private let localize = Localize(bundle: .module)
+
+    // MARK: Functional tests
+
+    @Test
+    func `resolves a key in the default locale`() {
+        let text = localize(
+            "test.greeting",
+            locale: Locale(identifier: "en")
+        )
+
+        #expect(text == "Hello")
+    }
+
+    @Test
+    func `resolves a key in another locale`() {
+        let text = localize(
+            "test.greeting",
+            locale: Locale(identifier: "de"),
+        )
+
+        #expect(text == "Hallo")
+    }
+
+    @Test
+    func `falls back to the key for an unknown entry`() {
+        let text = localize(
+            "unknown.key",
+            locale: Locale(identifier: "en"),
+        )
+
+        #expect(text == "unknown.key")
+    }
+
+}
diff --git a/Packages/Localization/Tests/Cases/Types/LanguageListTests.swift b/Packages/Localization/Tests/Cases/Types/LanguageListTests.swift
new file mode 100644
index 0000000..4e144e2
--- /dev/null
+++ b/Packages/Localization/Tests/Cases/Types/LanguageListTests.swift
@@ -0,0 +1,65 @@
+import Foundation
+import Testing
+
+@testable import Localization
+
+@Suite("LanguageList type")
+struct LanguageListTests {
+
+    // MARK: Properties tests
+
+    @Suite("default")
+    struct Default {
+        @Test
+        func `defaults to english`() {
+            let list = LanguageList(
+                bundle: .module
+            )
+
+            #expect(list.default == "en")
+        }
+
+        @Test
+        func `uses the provided default language`() {
+            let list = LanguageList(
+                bundle: .module,
+                default: "de"
+            )
+
+            #expect(list.default == "de")
+        }
+    }
+
+    @Suite("all")
+    struct All {
+        @Test
+        func `lists the catalog languages`() {
+            let list = LanguageList(
+                bundle: .module
+            )
+
+            #expect(list.all.contains("en"))
+            #expect(list.all.contains("de"))
+        }
+
+        @Test
+        func `excludes the base localization`() {
+            let list = LanguageList(
+                bundle: .module
+            )
+
+            #expect(!list.all.contains("Base"))
+        }
+
+        @Test
+        func `lists each language only once`() {
+            let list = LanguageList(
+                bundle: .module
+            )
+            let all = list.all
+
+            #expect(all.count == Set(all).count)
+        }
+    }
+
+}
diff --git a/Packages/Localization/Tests/Catalogs/Localizable.xcstrings b/Packages/Localization/Tests/Catalogs/Localizable.xcstrings
new file mode 100644
index 0000000..509d868
--- /dev/null
+++ b/Packages/Localization/Tests/Catalogs/Localizable.xcstrings
@@ -0,0 +1,23 @@
+{
+  "sourceLanguage" : "en",
+  "strings" : {
+    "test.greeting" : {
+      "comment" : "Fixture string used by the Localization test suite.",
+      "localizations" : {
+        "de" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hallo"
+          }
+        },
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hello"
+          }
+        }
+      }
+    }
+  },
+  "version" : "1.0"
+}
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 937f6e0..929c0d0 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -4,6 +4,7 @@ import PackageDescription
 
 let package = Package(
     name: "Website",
+    defaultLocalization: "en",
     platforms: [
         .macOS(.v15),
         .iOS(.v18),
@@ -19,6 +20,9 @@ let package = Package(
         )
     ],
     dependencies: [
+        .package(
+            path: "../Packages/Localization"
+        ),
         .package(
             url: "https://github.com/elementary-swift/elementary.git",
             from: "0.6.0"
@@ -67,6 +71,7 @@ let package = Package(
         .target(
             name: "WebsiteCore",
             dependencies: [
+                .byName(name: "Localization"),
                 .product(
                     name: "Configuration",
                     package: "swift-configuration"
@@ -84,7 +89,10 @@ let package = Package(
                     package: "hummingbird-elementary"
                 ),
             ],
-            path: "Sources/Library"
+            path: "Sources/Library",
+            resources: [
+                .process("Catalogs/Localizable.xcstrings")
+            ]
         ),
         .testTarget(
             name: "WebsiteTests",
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
index c24d390..3898109 100644
--- a/Services/Website/Sources/App/App+build.swift
+++ b/Services/Website/Sources/App/App+build.swift
@@ -69,7 +69,7 @@ func application(
 // MARK: - Helpers
 
 // Request context used by application
-private typealias AppRequestContext = BasicRequestContext
+private typealias AppRequestContext = WebsiteRequestContext
 
 /// Builds the cache-control policy applied to the served static files.
 ///
@@ -153,7 +153,8 @@ private func logger(
 /// Registers the request-logging middleware, the security-headers middleware that stamps the given
 /// `securityHeaders` onto every response, the response-compression middleware that compresses
 /// responses larger than `minimumResponseSizeToCompress` when the client advertises support, the
-/// not-found middleware that serves the error page, and the static file middleware that serves the
+/// localization middleware that negotiates the request's language from its `Accept-Language` header,
+/// the not-found middleware that serves the error page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then
 /// adds the `RootController` routes that render the landing page and the `HealthController` routes
 /// that serve the health check.
@@ -185,6 +186,7 @@ private func router(
         ResponseCompressionMiddleware(
             minimumResponseSizeToCompress: compressionMinResponseSize
         )
+        LocalizationMiddleware()
         NotFoundMiddleware()
         FileMiddleware(
             staticFilesPath,
diff --git a/Services/Website/Sources/Library/Catalogs/Localizable.xcstrings b/Services/Website/Sources/Library/Catalogs/Localizable.xcstrings
new file mode 100644
index 0000000..9a6ccec
--- /dev/null
+++ b/Services/Website/Sources/Library/Catalogs/Localizable.xcstrings
@@ -0,0 +1,61 @@
+{
+  "sourceLanguage" : "en",
+  "strings" : {
+    "error.heading" : {
+      "comment" : "The not-found page's main heading.",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Page Not Found"
+          }
+        }
+      }
+    },
+    "error.message" : {
+      "comment" : "The not-found page's body text.",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Sorry, but the page you were trying to view does not exist."
+          }
+        }
+      }
+    },
+    "error.title" : {
+      "comment" : "The not-found page's document title.",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Page Not Found"
+          }
+        }
+      }
+    },
+    "index.greeting" : {
+      "comment" : "The landing page's greeting paragraph.",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hello world! This is HTML5 Boilerplate."
+          }
+        }
+      }
+    },
+    "index.title" : {
+      "comment" : "The landing page's document title.",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Index page"
+          }
+        }
+      }
+    }
+  },
+  "version" : "1.0"
+}
diff --git a/Services/Website/Sources/Library/Internal/Methods/NegotiateLanguage.swift b/Services/Website/Sources/Library/Internal/Methods/NegotiateLanguage.swift
new file mode 100644
index 0000000..c7e8422
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Methods/NegotiateLanguage.swift
@@ -0,0 +1,85 @@
+import Foundation
+import Localization
+
+/// Negotiates the best supported language for a request from its `Accept-Language` header.
+///
+/// Bound to the module's catalog languages via ``LanguageList``, an instance is invoked like a
+/// function — through ``callAsFunction(forAcceptLanguage:)`` — to resolve a header value to a
+/// supported language identifier, falling back to the default language.
+struct NegotiateLanguage {
+
+    // MARK: Properties
+
+    /// The supported languages and default language, derived from the module's String Catalog.
+    private let list: LanguageList
+
+    // MARK: Initializers
+
+    /// Creates a language negotiator backed by the module's String Catalog.
+    init() {
+        self.list = .init(bundle: .module)
+    }
+
+    // MARK: Methods
+
+    /// Picks the best supported language for the given `Accept-Language` header value.
+    ///
+    /// Invoked by calling the instance directly, for example `negotiate(forAcceptLanguage: header)`.
+    /// The header is split into its language tags (dropping any `q` weights), then matched against
+    /// the supported languages with `Bundle.preferredLocalizations(from:forPreferences:)`. When the
+    /// header is absent or matches nothing, the default language is returned.
+    /// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
+    /// - Returns: the identifier of the supported language to serve.
+    func callAsFunction(
+        forAcceptLanguage acceptLanguage: String?
+    ) -> String {
+        guard let acceptLanguage else {
+            return list.default
+        }
+
+        let tags = tags(from: acceptLanguage)
+
+        guard !tags.isEmpty else {
+            return list.default
+        }
+
+        let preferred = Bundle.preferredLocalizations(
+            from: list.all,
+            forPreferences: tags
+        )
+
+        return preferred.first
+            ?? list.default
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension NegotiateLanguage {
+
+    // MARK: Methods
+
+    /// Extracts the ordered language tags from an `Accept-Language` header value.
+    ///
+    /// Each comma-separated entry is reduced to its language tag by dropping the `;q=` weight, and
+    /// blank entries are removed. The original order is kept, which mirrors descending preference
+    /// closely enough for `preferredLocalizations(from:forPreferences:)` to resolve correctly.
+    /// - Parameter acceptLanguage: the raw `Accept-Language` header value.
+    /// - Returns: the ordered, weight-stripped language tags.
+    func tags(
+        from acceptLanguage: String
+    ) -> [String] {
+        acceptLanguage
+            .split(separator: ",")
+            .map { entry in
+                entry
+                    .split(separator: ";")
+                    .first
+                    .map(String.init)?
+                    .trimmingCharacters(in: .whitespaces) ?? ""
+            }
+            .filter { !$0.isEmpty }
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
index 733ae1d..06f11b6 100644
--- a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
@@ -1,14 +1,39 @@
 import Elementary
+import Foundation
+import Localization
 
-/// The HTML page rendered for a not-found response.
+/// The HTML page rendered for a not-found response, with its text localized to a given locale.
 struct ErrorPage: HTMLDocument, Sendable {
 
+    // MARK: Properties
+
+    /// The locale the page content is localized to.
+    private let locale: Locale
+
+    /// Resolves the page's text from the bundled String Catalog for the page's ``locale``.
+    private let localize: Localize
+
+    // MARK: Initializers
+
+    /// Creates a not-found page localized to the given locale.
+    /// - Parameter locale: the locale the page content is localized to.
+    init(
+        locale: Locale
+    ) {
+        self.locale = locale
+        self.localize = .init(bundle: .module)
+    }
+
     // MARK: Document
 
-    /// The page's content.
+    /// The page's content: a localized heading and explanatory message.
     var body: some HTML {
-        h1 { "Page Not Found" }
-        p { "Sorry, but the page you were trying to view does not exist." }
+        h1 {
+            localize("error.heading", locale: locale)
+        }
+        p {
+            localize("error.message", locale: locale)
+        }
     }
 
     /// The metadata and stylesheet link placed in the document head.
@@ -24,10 +49,15 @@ struct ErrorPage: HTMLDocument, Sendable {
         )
     }
 
-    /// The document language.
-    var lang: String { "en" }
+    /// The document language, derived from the page's locale and falling back to the default language.
+    var lang: String {
+        locale.language.languageCode?.identifier
+            ?? LanguageList(bundle: .module).default
+    }
 
-    /// The document title.
-    var title: String { "Page Not Found" }
+    /// The localized document title.
+    var title: String {
+        localize("error.title", locale: locale)
+    }
 
 }
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index 23630d2..8d6c0c2 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -1,13 +1,36 @@
 import Elementary
+import Foundation
+import Localization
 
-/// The website's landing page.
+/// The website's landing page, with its text localized to a given locale.
 struct IndexPage: HTMLDocument, Sendable {
 
+    // MARK: Properties
+
+    /// The locale the page content is localized to.
+    private let locale: Locale
+
+    /// Resolves the page's text from the bundled String Catalog for the page's ``locale``.
+    private let localize: Localize
+
+    // MARK: Initializers
+
+    /// Creates a landing page localized to the given locale.
+    /// - Parameter locale: the locale the page content is localized to.
+    init(
+        locale: Locale
+    ) {
+        self.locale = locale
+        self.localize = .init(bundle: .module)
+    }
+
     // MARK: Document
 
-    /// The page's content.
+    /// The page's content: a localized greeting followed by the app script.
     var body: some HTML {
-        p { "Hello world! This is HTML5 Boilerplate." }
+        p {
+            localize("index.greeting", locale: locale)
+        }
         script(.src("/js/app.js")) {}
     }
 
@@ -52,14 +75,15 @@ struct IndexPage: HTMLDocument, Sendable {
         )
     }
 
-    /// The document language.
+    /// The document language, derived from the page's locale and falling back to the default language.
     var lang: String {
-        "en"
+        locale.language.languageCode?.identifier
+            ?? LanguageList(bundle: .module).default
     }
 
-    /// The document title.
+    /// The localized document title.
     var title: String {
-        "Index page"
+        localize("index.title", locale: locale)
     }
 
 }
diff --git a/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift b/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
index 6b1dcfb..8493813 100644
--- a/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
+++ b/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
@@ -1,12 +1,16 @@
 import Elementary
+import HTTPTypes
 import Hummingbird
 import NIOCore
 
 /// A pre-rendered HTTP response for a fully static HTML page.
 ///
 /// The document is rendered to bytes once, at initialization, and every ``response()`` reuses those
-/// bytes instead of re-rendering. This suits pages whose markup never changes between requests — the
-/// landing page and the not-found page — avoiding a per-request Elementary render on hot paths.
+/// bytes — along with a fixed status and precomputed headers — instead of re-rendering. This suits
+/// pages whose markup never changes between requests, such as the landing page and the not-found
+/// page, avoiding a per-request Elementary render on hot paths.
+///
+/// ``LocalizedHTMLResponses`` builds on this type, caching one instance per supported language.
 ///
 /// The body is written as an unsized stream (no `Content-Length`), mirroring `HTMLResponse`, so the
 /// response-compression middleware downstream treats it exactly as it would a freshly rendered page.
@@ -14,23 +18,37 @@ struct CachedHTMLResponse: Sendable {
 
     // MARK: Properties
 
-    /// The status applied to every response.
-    private let status: HTTPResponse.Status
     /// The page rendered to bytes once.
     private let buffer: ByteBuffer
+    /// The headers applied to every response, precomputed once.
+    private let headers: HTTPFields
+    /// The status applied to every response.
+    private let status: HTTPResponse.Status
 
     // MARK: Initializers
 
     /// Renders the given document to bytes once.
     /// - Parameters:
     ///   - status: the status applied to every response. Defaults to `.ok`.
+    ///   - additionalHeaders: extra headers merged onto every response, alongside the content type.
+    ///     Used to carry per-language signals such as `Content-Language` and `Vary`.
     ///   - document: the static HTML document to render and cache.
     init(
         status: HTTPResponse.Status = .ok,
-        _ document: some HTMLDocument
+        additionalHeaders: HTTPFields = [:],
+        document: some HTMLDocument
     ) {
+        var headers: HTTPFields = [
+            .contentType: "text/html; charset=utf-8"
+        ]
+
+        for field in additionalHeaders {
+            headers[field.name] = field.value
+        }
+
         self.status = status
-        self.buffer = ByteBuffer(string: document.render())
+        self.headers = headers
+        self.buffer = .init(string: document.render())
     }
 
     // MARK: Methods
@@ -43,7 +61,7 @@ struct CachedHTMLResponse: Sendable {
     func response() -> Response {
         Response(
             status: status,
-            headers: [.contentType: "text/html; charset=utf-8"],
+            headers: headers,
             body: .init { [buffer] writer in
                 try await writer.write(buffer)
                 try await writer.finish(nil)
diff --git a/Services/Website/Sources/Library/Internal/Responses/LocalizedHTMLCollectionResponse.swift b/Services/Website/Sources/Library/Internal/Responses/LocalizedHTMLCollectionResponse.swift
new file mode 100644
index 0000000..e6772d1
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Responses/LocalizedHTMLCollectionResponse.swift
@@ -0,0 +1,65 @@
+import Elementary
+import Foundation
+import HTTPTypes
+import Hummingbird
+import Localization
+
+/// A per-language collection of pre-rendered HTML responses.
+///
+/// At initialization it renders the document once for each language the bundle's ``LanguageList``
+/// reports and caches the bytes, mirroring ``CachedHTMLResponse``'s render-once model but keyed by
+/// language. Each cached response carries a `Content-Language` header and `Vary: Accept-Language`, so
+/// shared caches key on the negotiated language instead of serving one language to everyone.
+struct LocalizedHTMLCollectionResponse: Sendable {
+
+    // MARK: Properties
+
+    /// The supported languages and default language, derived from the module's String Catalog.
+    private let list: LanguageList
+
+    /// The pre-rendered responses, keyed by language identifier.
+    private let responses: [String: CachedHTMLResponse]
+
+    // MARK: Initializers
+
+    /// Renders the document once per supported language.
+    /// - Parameters:
+    ///   - status: the status applied to every response. Defaults to `.ok`.
+    ///   - document: builds the document to render for a given locale.
+    init<Document: HTMLDocument>(
+        status: HTTPResponse.Status = .ok,
+        document: (Locale) -> Document
+    ) {
+        self.list = .init(bundle: .module)
+        self.responses = list.all
+            .reduce(into: [:]) { responses, language in
+                responses[language] = CachedHTMLResponse(
+                    status: status,
+                    additionalHeaders: [
+                        .contentLanguage: language,
+                        .vary: "Accept-Language",
+                    ],
+                    document: document(.init(identifier: language))
+                )
+            }
+    }
+
+    // MARK: Methods
+
+    /// Builds the response for the given language, falling back to the default language.
+    /// - Parameter language: the negotiated language identifier.
+    /// - Returns: the cached response for the language, the default language's response when the
+    ///   language is unavailable, or a `500 Internal Server Error` if neither is cached.
+    func response(
+        for language: String
+    ) -> Response {
+        guard
+            let response = responses[language] ?? responses[list.default]
+        else {
+            return .init(status: .internalServerError)
+        }
+
+        return response.response()
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift b/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift
new file mode 100644
index 0000000..195196c
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift
@@ -0,0 +1,42 @@
+import Hummingbird
+import Localization
+
+/// A request context that carries the language negotiated for the request.
+///
+/// ``LocalizationMiddleware`` resolves the visitor's preferred language from the `Accept-Language`
+/// header and stores it here, so downstream controllers and middleware can serve the matching
+/// localization without re-reading the header.
+public protocol LocalizedRequestContext: RequestContext {
+
+    // MARK: Properties
+
+    /// The language identifier negotiated for the request.
+    var language: String { get set }
+
+}
+
+// MARK: - Context
+
+/// The website's request context.
+///
+/// Extends the core request storage with the negotiated language, defaulting to the default
+/// supported language until ``LocalizationMiddleware`` resolves it from the request.
+public struct WebsiteRequestContext: LocalizedRequestContext {
+
+    // MARK: Properties
+
+    /// The core request context storage Hummingbird requires.
+    public var coreContext: CoreRequestContextStorage
+    /// The language identifier negotiated for the request.
+    public var language: String
+
+    // MARK: Initializers
+
+    /// Creates a request context for the given source.
+    /// - Parameter source: the source the context is initialized from.
+    public init(source: Source) {
+        self.coreContext = .init(source: source)
+        self.language = LanguageList(bundle: .module).default
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index 811f696..d457c73 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -11,25 +11,26 @@ import Hummingbird
 ///
 /// - Note: `Context` is the request context the routes are resolved against, and must match the
 ///   context of the router the routes are added to.
-public struct RootController<Context: RequestContext>: Sendable {
+public struct RootController<Context: LocalizedRequestContext>: Sendable {
 
     // MARK: Properties
 
-    /// The landing page, rendered once at initialization and reused for every request.
-    private let cache: CachedHTMLResponse
+    /// The landing page, rendered once per supported language and reused for every request.
+    private let responses: LocalizedHTMLCollectionResponse
 
     // MARK: Initializers
 
     /// Creates a root controller.
     public init() {
-        self.cache = .init(IndexPage())
+        self.responses = .init { IndexPage(locale: $0) }
     }
 
     // MARK: Computed
 
     /// The routes served by the controller.
     ///
-    /// Serves a `GET` request for the root path (`/`) by rendering the ``IndexPage``.
+    /// Serves a `GET` request for the root path (`/`) by rendering the ``IndexPage`` in the
+    /// language negotiated for the request.
     public var routes: RouteCollection<Context> {
         let routes = RouteCollection(context: Context.self)
 
@@ -50,16 +51,19 @@ private extension RootController {
     // MARK: Methods
 
     /// Handles a request for the landing page.
+    ///
+    /// Renders the ``IndexPage`` in the language stored on the context by ``LocalizationMiddleware``,
+    /// falling back to the default language.
     /// - Parameters:
     ///   - request: the incoming request.
     ///   - context: the context the request is resolved against.
-    /// - Returns: the cached ``IndexPage`` response.
+    /// - Returns: the cached ``IndexPage`` response for the context's language.
     @Sendable
     func index(
         request: Request,
-        context: some RequestContext
+        context: Context
     ) -> Response {
-        cache.response()
+        responses.response(for: context.language)
     }
 
 }
diff --git a/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift b/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift
new file mode 100644
index 0000000..99725f5
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift
@@ -0,0 +1,56 @@
+import HTTPTypes
+import Hummingbird
+import Localization
+
+/// Resolves the visitor's preferred language and records it on the request context.
+///
+/// Placed ahead of the localized responders in the middleware chain, it reads the request's
+/// `Accept-Language` header, negotiates the best supported match (falling back to the default
+/// language), and stores it on the context's ``LocalizedRequestContext/language``.
+///
+/// The request is otherwise passed through untouched — the URL and routing are not affected — so
+/// each page is served at its existing path and varies its content by header.
+public struct LocalizationMiddleware<Context: LocalizedRequestContext> {
+
+    // MARK: Properties
+
+    /// Negotiates the request's language from its `Accept-Language` header.
+    private let negotiate: NegotiateLanguage
+
+    // MARK: Initializers
+
+    /// Creates a localization middleware.
+    public init() {
+        self.negotiate = .init()
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension LocalizationMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Negotiates the request's language and records it on the context before passing it down.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        var context = context
+
+        context.language = negotiate(
+            forAcceptLanguage: request.headers[.acceptLanguage]
+        )
+
+        return try await next(request, context)
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift b/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
index abbbdfd..6d053aa 100644
--- a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
+++ b/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
@@ -4,22 +4,24 @@ import Hummingbird
 ///
 /// Placed ahead of `FileMiddleware` in the middleware chain, it catches the `.notFound` error
 /// that bubbles up when no file exists for the requested path and responds with the rendered
-/// ``ErrorPage`` and a `404 Not Found` status.
-public struct NotFoundMiddleware<Context: RequestContext> {
+/// ``ErrorPage`` and a `404 Not Found` status. The page is served in the language stored on the
+/// context by ``LocalizationMiddleware``, falling back to the default language.
+public struct NotFoundMiddleware<Context: LocalizedRequestContext> {
 
     // MARK: Properties
 
-    /// The error page, rendered once at initialization and reused for every not-found response.
-    private let cache: CachedHTMLResponse
+    /// The error page, rendered once per supported language and reused for every not-found response.
+    private let responses: LocalizedHTMLCollectionResponse
 
     // MARK: Initializers
 
     /// Creates a not-found middleware.
     public init() {
-        self.cache = .init(
-            status: .notFound,
-            ErrorPage()
-        )
+        self.responses = .init(
+            status: .notFound
+        ) {
+            ErrorPage(locale: $0)
+        }
     }
 
 }
@@ -56,7 +58,9 @@ extension NotFoundMiddleware: RouterMiddleware {
                 throw error
             }
 
-            return cache.response()
+            return responses.response(
+                for: context.language
+            )
         }
     }
 
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
index c320657..463a357 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
@@ -1,4 +1,5 @@
 import Elementary
+import Foundation
 import Testing
 
 @testable import WebsiteCore
@@ -10,11 +11,14 @@ struct ErrorPageTests {
 
     @Test
     func `renders its markup`() {
-        let html = ErrorPage().render()
+        let html = ErrorPage(
+            locale: .init(identifier: "en")
+        ).render()
 
         #expect(html.contains("<!DOCTYPE html>"))
+        #expect(html.contains(#"lang="en""#))
         #expect(html.contains("Page Not Found"))
-        #expect(html.contains("does not exist"))
+        #expect(html.contains("Sorry, but the page you were trying to view does not exist."))
         #expect(html.contains("/css/error.css"))
     }
 
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index 1594721..be76e76 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -1,4 +1,5 @@
 import Elementary
+import Foundation
 import Testing
 
 @testable import WebsiteCore
@@ -10,9 +11,12 @@ struct IndexPageTests {
 
     @Test
     func `renders its markup`() {
-        let html = IndexPage().render()
+        let html = IndexPage(
+            locale: .init(identifier: "en")
+        ).render()
 
         #expect(html.contains("<!DOCTYPE html>"))
+        #expect(html.contains(#"lang="en""#))
         #expect(html.contains("/css/style.css"))
         #expect(html.contains("/favicon.ico"))
         #expect(html.contains("/icon.svg"))
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
index daa9e79..6f0cd7f 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
@@ -11,9 +11,13 @@ struct RootControllerTests {
     // MARK: Constants
     
     private let app: Application = .init(router: {
-        let router = Router()
-        
-        router.addRoutes(RootController<BasicRequestContext>().routes)
+        let router = Router(context: WebsiteRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware()
+        }
+
+        router.addRoutes(RootController<WebsiteRequestContext>().routes)
         
         return router
     }())
@@ -31,6 +35,8 @@ struct RootControllerTests {
 
                 #expect(response.status == .ok)
                 #expect(response.headers[.contentType] == "text/html; charset=utf-8")
+                #expect(response.headers[.contentLanguage] == "en")
+                #expect(response.headers[.vary] == "Accept-Language")
                 #expect(body.contains("Hello world!"))
             }
         }
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
new file mode 100644
index 0000000..09046af
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
@@ -0,0 +1,55 @@
+import HTTPTypes
+import Hummingbird
+import HummingbirdTesting
+import NIOCore
+import Testing
+
+@testable import WebsiteCore
+
+@Suite("LocalizationMiddleware middleware")
+struct LocalizationMiddlewareTests {
+
+    // MARK: Constants
+
+    private let app: Application = .init(router: {
+        let router = Router(context: WebsiteRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware()
+        }
+
+        router.get("language") { _, context in
+            context.language
+        }
+
+        return router
+    }())
+
+    // MARK: Functional tests
+
+    @Test
+    func `negotiates a supported language from the header`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language",
+                method: .get,
+                headers: [.acceptLanguage: "en-US,en;q=0.9"]
+            ) { response in
+                #expect(String(buffer: response.body) == "en")
+            }
+        }
+    }
+
+    @Test
+    func `falls back to the default without a header`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language",
+                method: .get
+            ) { response in
+                #expect(String(buffer: response.body) == "en")
+            }
+        }
+    }
+
+}
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
index b4646e3..8ac9e09 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
@@ -11,9 +11,10 @@ struct NotFoundMiddlewareTests {
     // MARK: Constants
     
     private let app: Application = .init(router: {
-        let router = Router()
+        let router = Router(context: WebsiteRequestContext.self)
         
         router.addMiddleware {
+            LocalizationMiddleware()
             NotFoundMiddleware()
         }
         
@@ -41,6 +42,8 @@ struct NotFoundMiddlewareTests {
 
                 #expect(response.status == .notFound)
                 #expect(response.headers[.contentType] == "text/html; charset=utf-8")
+                #expect(response.headers[.contentLanguage] == "en")
+                #expect(response.headers[.vary] == "Accept-Language")
                 #expect(body.contains("Page Not Found"))
             }
         }
-- 
2.54.0


From b6f9633420e21ad922929dc197c85df8f9e4d9d7 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 3 Jul 2026 03:48:25 +0000
Subject: [PATCH 012/117] Adjustments to the Localization package dependency
 (#11)

This PR contains the work done to refactor the _Localization_ package and tidy the project a little bit.

To provider further details about the work:

* The `Negotiate` function was moved to the _Localization_ package.
* The `WebsiteRequestContext` context no longer resolves a default language at creation; it starts empty and relies on the `LocalizationMiddleware` middleware to fill it in.
* Fixed the local dependency path to Packages/Localization for the **Website** package as it only resolved inside the Xcode workspace before, breaking swift build, the Makefile, and the Docker build).
* Updated the `README` file to document language negotiation, the GET /health route, and the full middleware chain; doc comments across the moved/renamed types were brought back in sync with the code.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/11
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Packages/Localization/Package.swift           |  2 +-
 .../Sources/Methods/Negotiate.swift           | 50 ++++++++----
 .../Tests/Cases/Methods/NegotiateTests.swift  | 78 +++++++++++++++++++
 .../xcshareddata/xcschemes/Website.xcscheme   | 12 +--
 .../xcschemes/WebsiteCoreTests.xcscheme       | 54 +++++++++++++
 Services/Website/Package.swift                |  4 +-
 Services/Website/README.md                    | 29 ++++---
 .../Responses/CachedHTMLResponse.swift        |  2 +-
 .../Contexts/LocalizedRequestContext.swift    | 13 +++-
 .../Extensions/HTTPFieldName+Constants.swift  |  6 +-
 .../Middlewares/LocalizationMiddleware.swift  |  8 +-
 11 files changed, 207 insertions(+), 51 deletions(-)
 rename Services/Website/Sources/Library/Internal/Methods/NegotiateLanguage.swift => Packages/Localization/Sources/Methods/Negotiate.swift (64%)
 create mode 100644 Packages/Localization/Tests/Cases/Methods/NegotiateTests.swift
 create mode 100644 Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteCoreTests.xcscheme
 rename Services/Website/Sources/Library/{Internal => Public}/Extensions/HTTPFieldName+Constants.swift (61%)

diff --git a/Packages/Localization/Package.swift b/Packages/Localization/Package.swift
index 277db4a..2323799 100644
--- a/Packages/Localization/Package.swift
+++ b/Packages/Localization/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:6.3
+// swift-tools-version: 6.3
 
 import PackageDescription
 
diff --git a/Services/Website/Sources/Library/Internal/Methods/NegotiateLanguage.swift b/Packages/Localization/Sources/Methods/Negotiate.swift
similarity index 64%
rename from Services/Website/Sources/Library/Internal/Methods/NegotiateLanguage.swift
rename to Packages/Localization/Sources/Methods/Negotiate.swift
index c7e8422..06cfe99 100644
--- a/Services/Website/Sources/Library/Internal/Methods/NegotiateLanguage.swift
+++ b/Packages/Localization/Sources/Methods/Negotiate.swift
@@ -1,43 +1,45 @@
 import Foundation
-import Localization
 
 /// Negotiates the best supported language for a request from its `Accept-Language` header.
 ///
-/// Bound to the module's catalog languages via ``LanguageList``, an instance is invoked like a
-/// function — through ``callAsFunction(forAcceptLanguage:)`` — to resolve a header value to a
+/// Bound to a bundle's catalog languages via ``LanguageList``, an instance is invoked like a
+/// function — through ``callAsFunction(acceptLanguage:)`` — to resolve a header value to a
 /// supported language identifier, falling back to the default language.
-struct NegotiateLanguage {
+public struct Negotiate: Sendable {
 
     // MARK: Properties
 
-    /// The supported languages and default language, derived from the module's String Catalog.
+    /// The supported languages and default language, derived from the bundle's String Catalog.
     private let list: LanguageList
 
     // MARK: Initializers
 
-    /// Creates a language negotiator backed by the module's String Catalog.
-    init() {
-        self.list = .init(bundle: .module)
+    /// Creates a language negotiator backed by the given bundle's String Catalog.
+    /// - Parameter bundle: the bundle whose String Catalog defines the supported languages.
+    public init(
+        bundle: Bundle
+    ) {
+        self.list = .init(bundle: bundle)
     }
 
     // MARK: Methods
 
     /// Picks the best supported language for the given `Accept-Language` header value.
     ///
-    /// Invoked by calling the instance directly, for example `negotiate(forAcceptLanguage: header)`.
+    /// Invoked by calling the instance directly, for example `negotiate(acceptLanguage: header)`.
     /// The header is split into its language tags (dropping any `q` weights), then matched against
     /// the supported languages with `Bundle.preferredLocalizations(from:forPreferences:)`. When the
     /// header is absent or matches nothing, the default language is returned.
     /// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
     /// - Returns: the identifier of the supported language to serve.
-    func callAsFunction(
-        forAcceptLanguage acceptLanguage: String?
+    public func callAsFunction(
+        acceptLanguage language: String?
     ) -> String {
-        guard let acceptLanguage else {
+        guard let language else {
             return list.default
         }
 
-        let tags = tags(from: acceptLanguage)
+        let tags = tags(from: language)
 
         guard !tags.isEmpty else {
             return list.default
@@ -56,7 +58,7 @@ struct NegotiateLanguage {
 
 // MARK: - Helpers
 
-private extension NegotiateLanguage {
+private extension Negotiate {
 
     // MARK: Methods
 
@@ -71,15 +73,29 @@ private extension NegotiateLanguage {
         from acceptLanguage: String
     ) -> [String] {
         acceptLanguage
-            .split(separator: ",")
+            .split(separator: .Separator.comma)
             .map { entry in
                 entry
-                    .split(separator: ";")
+                    .split(separator: .Separator.semicolon)
                     .first
                     .map(String.init)?
-                    .trimmingCharacters(in: .whitespaces) ?? ""
+                    .trimmingCharacters(in: .whitespaces)
+                ?? .empty
             }
             .filter { !$0.isEmpty }
     }
 
 }
+
+// MARK: - Constants
+
+private extension Character {
+    enum Separator {
+        static let comma: Character = ","
+        static let semicolon: Character = ";"
+    }
+}
+
+private extension String {
+    static let empty: String = ""
+}
diff --git a/Packages/Localization/Tests/Cases/Methods/NegotiateTests.swift b/Packages/Localization/Tests/Cases/Methods/NegotiateTests.swift
new file mode 100644
index 0000000..4ab3160
--- /dev/null
+++ b/Packages/Localization/Tests/Cases/Methods/NegotiateTests.swift
@@ -0,0 +1,78 @@
+import Foundation
+import Testing
+
+@testable import Localization
+
+@Suite("Negotiate method")
+struct NegotiateTests {
+
+    // MARK: Constants
+
+    private let negotiate = Negotiate(bundle: .module)
+
+    // MARK: Functional tests
+
+    @Test
+    func `matches an exact language tag`() {
+        let language = negotiate(acceptLanguage: "de")
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `matches a regional language tag`() {
+        let language = negotiate(acceptLanguage: "de-AT")
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `respects the header order of preference`() {
+        let language = negotiate(acceptLanguage: "de, en")
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `strips quality weights from the language tags`() {
+        let language = negotiate(acceptLanguage: "de;q=0.5, en;q=0.9")
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `trims whitespace around the language tags`() {
+        let language = negotiate(acceptLanguage: " de , en ")
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `falls back to the default for an unsupported language`() {
+        let language = negotiate(acceptLanguage: "fr")
+
+        #expect(language == "en")
+    }
+
+    @Test
+    func `falls back to the default for a missing header`() {
+        let language = negotiate(acceptLanguage: nil)
+
+        #expect(language == "en")
+    }
+
+    @Test
+    func `falls back to the default for an empty header`() {
+        let language = negotiate(acceptLanguage: "")
+
+        #expect(language == "en")
+    }
+
+    @Test
+    func `falls back to the default for a header without language tags`() {
+        let language = negotiate(acceptLanguage: " , ;q=0.5,")
+
+        #expect(language == "en")
+    }
+
+}
diff --git a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
index 24b3ac5..2700a30 100644
--- a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
+++ b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
@@ -26,13 +26,8 @@
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      shouldUseLaunchSchemeArgsEnv = "YES">
-      <TestPlans>
-         <TestPlanReference
-            reference = "container:Website.xctestplan"
-            default = "YES">
-         </TestPlanReference>
-      </TestPlans>
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      shouldAutocreateTestPlan = "YES">
       <Testables>
          <TestableReference
             skipped = "NO">
@@ -50,8 +45,7 @@
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
       launchStyle = "0"
-      useCustomWorkingDirectory = "YES"
-      customWorkingDirectory = "/Users/logan/Documents/Development/Platforms/Ro&#x308;ck+Co&#x308;de/Loud/Services/Website"
+      useCustomWorkingDirectory = "NO"
       ignoresPersistentStateOnLaunch = "NO"
       debugDocumentVersioning = "YES"
       debugServiceExtension = "internal"
diff --git a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteCoreTests.xcscheme b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteCoreTests.xcscheme
new file mode 100644
index 0000000..d5af719
--- /dev/null
+++ b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteCoreTests.xcscheme
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "2700"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      shouldAutocreateTestPlan = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "WebsiteCoreTests"
+               BuildableName = "WebsiteCoreTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES"
+      queueDebuggingEnabled = "No">
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 929c0d0..7e4b279 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -1,4 +1,4 @@
-// swift-tools-version:6.3
+// swift-tools-version: 6.3
 
 import PackageDescription
 
@@ -21,7 +21,7 @@ let package = Package(
     ],
     dependencies: [
         .package(
-            path: "../Packages/Localization"
+            path: "../../Packages/Localization"
         ),
         .package(
             url: "https://github.com/elementary-swift/elementary.git",
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 0e0bacd..614ab5e 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -3,9 +3,11 @@ The **Loud** public website service — a [Hummingbird](https://github.com/hummi
 
 ## Overview
 The service:
-- Serves the landing page at `GET /` (rendered once with [Elementary](https://github.com/elementary-swift/elementary) and cached).
+- Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
+- Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteCore` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
+- Answers health checks at `GET /health` with a static JSON payload.
 - Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`.
-- Returns a custom HTML 404 page for any request that matches neither a route nor a static file.
+- Returns a custom HTML 404 page, localized like the landing page, for any request that matches neither a route nor a static file.
 - Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
 - Stamps a hardened set of security headers on every response.
 
@@ -20,14 +22,18 @@ Two SwiftPM targets:
 | `Website` | executable | `Sources/App` | Entry point: reads configuration, builds and runs the application. |
 | `WebsiteCore` | library | `Sources/Library` | Controllers, middlewares, pages, cached responses, and configuration helpers. |
 
+`WebsiteCore` also depends on the local `Localization` package (`Packages/Localization`), which provides the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages.
+
 Requests pass through the middleware chain in this order (outermost first), then reach the routes:
 ```
 LogRequestsMiddleware
-  → SecurityHeadersMiddleware      (security headers on every response)
-    → ResponseCompressionMiddleware (gzip/deflate above the size threshold)
-      → NotFoundMiddleware          (renders the 404 page on .notFound)
-        → FileMiddleware            (serves Resources/Static)
-RootController                      (GET / → landing page)
+  → SecurityHeadersMiddleware       (security headers on every response)
+    → ResponseCompressionMiddleware  (gzip/deflate above the size threshold)
+      → LocalizationMiddleware       (negotiates the request's language)
+        → NotFoundMiddleware         (renders the localized 404 page on .notFound)
+          → FileMiddleware           (serves Resources/Static)
+RootController                       (GET / → landing page)
+HealthController                     (GET /health → health check)
 ```
 
 ## Configuration
@@ -40,7 +46,7 @@ the following sources, **highest precedence first**:
 
 ### Environment variable naming
 A dotted config key maps to an environment variable by upper-casing, splitting camelCase, and replacing separators with `_`. For example `http.serverName` → `HTTP_SERVER_NAME`,
-`security.strictTransportSecurity` → `SECURITY_STRICT_TRANSPORT_SECURITY`, `cache.maxAge.text` →` CACHE_MAX_AGE_TEXT`.
+`security.strictTransportSecurity` → `SECURITY_STRICT_TRANSPORT_SECURITY`, `cache.maxAge.text` → `CACHE_MAX_AGE_TEXT`.
 > To disable a header or override a value, leave the variable **unset** to fall back to the default. A
 > variable that is set but **blank** is treated as an explicit empty value, not as "use the default".
 
@@ -92,7 +98,7 @@ swift run Website # binds to Hummingbird's default 127.0.0.1:8080
 swift run Website --http-host 0.0.0.0 --http-port 9000 --log-level debug
 ```
 
-Or via the Makefile / Docker (uses `docker-compose.override.yml`, which builds from source and sets`LOG_LEVEL=debug`:
+Or via the Makefile / Docker (uses `docker-compose.override.yml`, which builds from source and sets `LOG_LEVEL=debug`):
 ```sh
 make pkg-build        # swift build
 make img-mount        # docker compose up --build --detach
@@ -100,16 +106,17 @@ make img-unmount      # docker compose down + remove the local image
 ```
 
 `make help` lists every available target.
+
 ## Testing
 ```sh
 make pkg-test
 # = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
 ```
 
-Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The`Website.xctestplan` covers two targets: `WebsiteTests` (the executable/integration tests) and` WebsiteCoreTests` (the library unit tests).
+Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Website.xctestplan` covers two targets: `WebsiteTests` (the executable/integration tests) and `WebsiteCoreTests` (the library unit tests).
 
 ## Deployment
-The production image is built for `linux/amd64` in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080`(`ENTRYPOINT ./Website --http-host 0.0.0.0 --http-port 8080`).
+The production image is built for `linux/amd64` in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080` (`ENTRYPOINT ./Website --http-host 0.0.0.0 --http-port 8080`).
 Build, tag, and push a release to the registry (an explicit version is required):
 ```sh
 make img-release version=1.2.3
diff --git a/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift b/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
index 8493813..f9da28a 100644
--- a/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
+++ b/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
@@ -10,7 +10,7 @@ import NIOCore
 /// pages whose markup never changes between requests, such as the landing page and the not-found
 /// page, avoiding a per-request Elementary render on hot paths.
 ///
-/// ``LocalizedHTMLResponses`` builds on this type, caching one instance per supported language.
+/// ``LocalizedHTMLCollectionResponse`` builds on this type, caching one instance per supported language.
 ///
 /// The body is written as an unsized stream (no `Content-Length`), mirroring `HTMLResponse`, so the
 /// response-compression middleware downstream treats it exactly as it would a freshly rendered page.
diff --git a/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift b/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift
index 195196c..0172f98 100644
--- a/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift
+++ b/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift
@@ -1,5 +1,4 @@
 import Hummingbird
-import Localization
 
 /// A request context that carries the language negotiated for the request.
 ///
@@ -34,9 +33,17 @@ public struct WebsiteRequestContext: LocalizedRequestContext {
 
     /// Creates a request context for the given source.
     /// - Parameter source: the source the context is initialized from.
-    public init(source: Source) {
+    public init(
+        source: Source,
+    ) {
         self.coreContext = .init(source: source)
-        self.language = LanguageList(bundle: .module).default
+        self.language = .empty
     }
 
 }
+
+// MARK: - Constants
+
+private extension String {
+    static let empty = ""
+}
diff --git a/Services/Website/Sources/Library/Internal/Extensions/HTTPFieldName+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift
similarity index 61%
rename from Services/Website/Sources/Library/Internal/Extensions/HTTPFieldName+Constants.swift
rename to Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift
index 4ebf3bb..b343f3c 100644
--- a/Services/Website/Sources/Library/Internal/Extensions/HTTPFieldName+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift
@@ -2,9 +2,9 @@ import HTTPTypes
 
 extension HTTPField.Name {
     /// The `Permissions-Policy` field name (not provided as a standard `HTTPField.Name`).
-    static let permissionsPolicy = Self("Permissions-Policy")!
+    public static let permissionsPolicy = Self("Permissions-Policy")!
     /// The `Referrer-Policy` field name (not provided as a standard `HTTPField.Name`).
-    static let referrerPolicy = Self("Referrer-Policy")!
+    public static let referrerPolicy = Self("Referrer-Policy")!
     /// The `X-Frame-Options` field name (not provided as a standard `HTTPField.Name`).
-    static let frameOptions = Self("X-Frame-Options")!
+    public static let frameOptions = Self("X-Frame-Options")!
 }
diff --git a/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift b/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift
index 99725f5..db18270 100644
--- a/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift
+++ b/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift
@@ -15,13 +15,13 @@ public struct LocalizationMiddleware<Context: LocalizedRequestContext> {
     // MARK: Properties
 
     /// Negotiates the request's language from its `Accept-Language` header.
-    private let negotiate: NegotiateLanguage
+    private let negotiate: Negotiate
 
     // MARK: Initializers
 
-    /// Creates a localization middleware.
+    /// Creates a localization middleware that negotiates against the module's String Catalog languages.
     public init() {
-        self.negotiate = .init()
+        self.negotiate = .init(bundle: .module)
     }
 
 }
@@ -47,7 +47,7 @@ extension LocalizationMiddleware: RouterMiddleware {
         var context = context
 
         context.language = negotiate(
-            forAcceptLanguage: request.headers[.acceptLanguage]
+            acceptLanguage: request.headers[.acceptLanguage]
         )
 
         return try await next(request, context)
-- 
2.54.0


From 9774454bbaf93e2855732b6962cf658c0dcc2b5f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 9 Jul 2026 23:00:55 +0000
Subject: [PATCH 013/117] Website service Makefile and Localization package
 fixes (#12)

This PR contains the work done to get the Website service building and running correctly in its Linux container. The service depends on the local _Localization_ package, whose String-Catalog localization was Darwin-only and broke the Docker build. Thus the localization internals have been reworked to be platform-agnostic and fixes the container build context so the local package is actually available during the build.

* Localization package
  * Replaced the Darwin-only `String.LocalizationValue` / `String(localized:)` path with a StringCatalog type that reads raw JSON from a given `.xcstrings` file, so lookups resolve identically on macOS and Linux.
  * The `LanguageList` now derives available languages from the catalog instead of `Bundle.localizations`
  * The `Negotiate` does explicit _Accept-Language_ matching (exact tag, then primary subtag) instead of the Linux-broken `Bundle.preferredLocalizations`.
  * Switched the catalog resource rule from `.process` to `.copy` (in both Localization and Website manifests) so the raw `.xcstrings` ships verbatim on every platform.
  * Introduced a `CatalogResolving` protocol as a seam between the localizers and the storage backend, enabling test injection and a future native-Apple backend without changing callers.

* Website Docker build
  * Build context moved to the repository root so the relative-path `Localization` package is inside the context; `Dockerfile`, `docker-compose.override.yml`, and the _img-release_ make target updated to the new context/paths.
  *  Added a root `.dockerignore` to keep the context lean.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/12
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .dockerignore                                 |  28 ++++
 Packages/Localization/Package.swift           |   4 +-
 .../Sources/Methods/Localize.swift            |  42 ++++--
 .../Sources/Methods/Negotiate.swift           |  67 +++++++--
 .../Sources/Protocols/CatalogResolving.swift  |  37 +++++
 .../Sources/Types/LanguageList.swift          |  36 +++--
 .../Sources/Types/StringCatalog.swift         | 133 ++++++++++++++++++
 Services/Website/Dockerfile                   |  19 +--
 Services/Website/Makefile                     |   3 +-
 Services/Website/Package.swift                |   4 +-
 .../Extensions/HTTPFieldName+Constants.swift  |   6 +-
 Services/Website/docker-compose.override.yml  |   6 +-
 12 files changed, 332 insertions(+), 53 deletions(-)
 create mode 100644 .dockerignore
 create mode 100644 Packages/Localization/Sources/Protocols/CatalogResolving.swift
 create mode 100644 Packages/Localization/Sources/Types/StringCatalog.swift

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..a60105d
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,28 @@
+# Build context is the repo root (see Services/Website/Dockerfile). Keep the
+# context lean: exclude build artifacts, VCS, IDE cruft, secrets and anything
+# not needed to compile the Swift package.
+
+# Version control
+.git
+**/.git
+
+# Swift / SPM build artifacts
+**/.build
+**/.swiftpm
+
+# Xcode project (not used by the Linux build)
+*.xcodeproj
+
+# OS / editor cruft
+**/.DS_Store
+.vscode
+
+# Local environment overrides and secrets (Compose still reads these from the
+# host at runtime; ignoring them here only keeps them out of the image build).
+**/.env
+**/.env.local
+
+# Compose / tooling / docs not needed inside the image
+**/docker-compose.*
+**/Makefile
+**/README.md
diff --git a/Packages/Localization/Package.swift b/Packages/Localization/Package.swift
index 2323799..99625f3 100644
--- a/Packages/Localization/Package.swift
+++ b/Packages/Localization/Package.swift
@@ -30,7 +30,9 @@ let package = Package(
             ],
             path: "Tests",
             resources: [
-                .process("Catalogs/Localizable.xcstrings")
+                // Copied verbatim rather than processed: the String Catalog is read as raw JSON at runtime so it
+                // resolves identically on Darwin and Linux (which cannot compile it).
+                .copy("Catalogs/Localizable.xcstrings")
             ]
         ),
     ]
diff --git a/Packages/Localization/Sources/Methods/Localize.swift b/Packages/Localization/Sources/Methods/Localize.swift
index 2acb900..e2c18a6 100644
--- a/Packages/Localization/Sources/Methods/Localize.swift
+++ b/Packages/Localization/Sources/Methods/Localize.swift
@@ -9,17 +9,33 @@ public struct Localize: Sendable {
 
     // MARK: Properties
 
-    /// The bundle whose compiled String Catalog the keys are resolved against.
-    private let bundle: Bundle
+    /// The backend that resolves keys against the catalog.
+    private let resolver: any CatalogResolving
 
     // MARK: Initializers
 
-    /// Creates a localizer backed by the given bundle.
-    /// - Parameter bundle: the bundle whose String Catalog contains the keys to resolve.
+    /// Creates a localizer backed by the String Catalog in the given bundle.
+    /// - Parameters:
+    ///   - bundle: the bundle whose String Catalog contains the keys to resolve.
+    ///   - table: the name of the String Catalog resource, without the `.xcstrings` extension.
     public init(
-        bundle: Bundle
+        bundle: Bundle,
+        table: String = "Localizable"
     ) {
-        self.bundle = bundle
+        self.init(resolver: StringCatalog(
+            bundle: bundle,
+            table: table
+        ))
+    }
+
+    /// Creates a localizer backed by the given resolver.
+    ///
+    /// The seam for tests and alternative backends; the public API resolves against a bundled catalog.
+    /// - Parameter resolver: the backend that resolves keys to localized strings.
+    init(
+        resolver: any CatalogResolving
+    ) {
+        self.resolver = resolver
     }
 
     // MARK: Methods
@@ -30,16 +46,16 @@ public struct Localize: Sendable {
     /// - Parameters:
     ///   - key: the String Catalog key to look up.
     ///   - locale: the locale to resolve the key in.
-    /// - Returns: the localized string for the locale, or the key itself when the bundle's catalog has no entry for it.
+    /// - Returns: the localized string for the locale, the source-language string when the locale has no
+    ///   entry, or the key itself when the catalog has no entry for it.
     public func callAsFunction(
-        _ key: String.LocalizationValue,
+        _ key: String,
         locale: Locale
     ) -> String {
-        .init(localized: .init(
-            key,
-            locale: locale,
-            bundle: .atURL(bundle.bundleURL)
-        ))
+        resolver.string(
+            for: key,
+            in: locale
+        )
     }
 
 }
diff --git a/Packages/Localization/Sources/Methods/Negotiate.swift b/Packages/Localization/Sources/Methods/Negotiate.swift
index 06cfe99..878b649 100644
--- a/Packages/Localization/Sources/Methods/Negotiate.swift
+++ b/Packages/Localization/Sources/Methods/Negotiate.swift
@@ -27,9 +27,10 @@ public struct Negotiate: Sendable {
     /// Picks the best supported language for the given `Accept-Language` header value.
     ///
     /// Invoked by calling the instance directly, for example `negotiate(acceptLanguage: header)`.
-    /// The header is split into its language tags (dropping any `q` weights), then matched against
-    /// the supported languages with `Bundle.preferredLocalizations(from:forPreferences:)`. When the
-    /// header is absent or matches nothing, the default language is returned.
+    /// The header is split into its language tags (dropping any `q` weights), then each tag is matched
+    /// against the supported languages in order of preference — first by an exact match, then by its
+    /// primary language subtag, so `de-AT` resolves to a supported `de`. When the header is absent or
+    /// matches nothing, the default language is returned.
     /// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
     /// - Returns: the identifier of the supported language to serve.
     public func callAsFunction(
@@ -45,13 +46,15 @@ public struct Negotiate: Sendable {
             return list.default
         }
 
-        let preferred = Bundle.preferredLocalizations(
-            from: list.all,
-            forPreferences: tags
-        )
+        let supported = list.all
 
-        return preferred.first
-            ?? list.default
+        for tag in tags {
+            if let match = match(tag: tag, in: supported) {
+                return match
+            }
+        }
+
+        return list.default
     }
 
 }
@@ -85,6 +88,47 @@ private extension Negotiate {
             .filter { !$0.isEmpty }
     }
 
+    /// Finds the supported language that best matches a single `Accept-Language` tag.
+    ///
+    /// An exact, case-insensitive match wins; otherwise the tag's primary subtag is matched against the
+    /// supported languages' primary subtags, so a regional tag such as `de-AT` resolves to `de`.
+    /// - Parameters:
+    ///   - tag: a single language tag from the header.
+    ///   - supported: the supported language identifiers.
+    /// - Returns: the matching supported language, or `nil` when the tag matches none.
+    func match(
+        tag: String,
+        in supported: [String]
+    ) -> String? {
+        let tag = tag.lowercased()
+
+        if let exact = supported.first(
+            where: { $0.lowercased() == tag }
+        ) {
+            return exact
+        }
+
+        let primary = tag.primarySubtag
+
+        return supported.first {
+            $0.lowercased().primarySubtag == primary
+        }
+    }
+
+}
+
+// MARK: - String+Extensions
+
+private extension String {
+    static let empty: String = ""
+
+    /// The primary language subtag, i.e. everything before the first `-` (`de-AT` becomes `de`).
+    var primarySubtag: String {
+        split(separator: .Separator.dash)
+            .first
+            .map(String.init)
+        ?? self
+    }
 }
 
 // MARK: - Constants
@@ -92,10 +136,7 @@ private extension Negotiate {
 private extension Character {
     enum Separator {
         static let comma: Character = ","
+        static let dash: Character = "-"
         static let semicolon: Character = ";"
     }
 }
-
-private extension String {
-    static let empty: String = ""
-}
diff --git a/Packages/Localization/Sources/Protocols/CatalogResolving.swift b/Packages/Localization/Sources/Protocols/CatalogResolving.swift
new file mode 100644
index 0000000..bb003fd
--- /dev/null
+++ b/Packages/Localization/Sources/Protocols/CatalogResolving.swift
@@ -0,0 +1,37 @@
+import Foundation
+
+/// A backend that resolves localized strings for an explicit locale and reports the languages it serves.
+///
+/// This is the seam that decouples ``Localize`` and ``LanguageList`` from *how* localizations are stored
+/// and resolved. The shipping implementation, ``StringCatalog``, reads a raw `.xcstrings` catalog so it
+/// behaves identically on Darwin and Linux. A future backend — for example one built on
+/// `String(localized:)` for a native Apple app that needs plural and device variations — can conform
+/// without changing any caller.
+///
+/// Resolution never fails: an implementation returns the key itself when it has no localization for it,
+/// mirroring Foundation's `String(localized:)`. This is the contract both a dictionary lookup and the
+/// native API can honour, since the native API cannot distinguish a missing key from a translation that
+/// happens to equal the key.
+protocol CatalogResolving: Sendable {
+
+    // MARK: Properties
+
+    /// The source (development) language, used as the final fallback when a locale has no localization.
+    var sourceLanguage: String { get }
+
+    /// Every language the backend can resolve strings for, including the source language.
+    var languages: Set<String> { get }
+
+    // MARK: Methods
+
+    /// Resolves a catalog key in the given locale.
+    /// - Parameters:
+    ///   - key: the catalog key to look up.
+    ///   - locale: the locale to resolve the key in.
+    /// - Returns: the localized string, falling back to the source language, then to the key itself.
+    func string(
+        for key: String,
+        in locale: Locale
+    ) -> String
+
+}
diff --git a/Packages/Localization/Sources/Types/LanguageList.swift b/Packages/Localization/Sources/Types/LanguageList.swift
index 0b7f476..eff831a 100644
--- a/Packages/Localization/Sources/Types/LanguageList.swift
+++ b/Packages/Localization/Sources/Types/LanguageList.swift
@@ -2,9 +2,8 @@ import Foundation
 
 /// The list of languages an app can serve, derived from a bundle's String Catalog.
 ///
-/// The languages are read from the injected `bundle`'s compiled localizations, so the catalog that
-/// ships in that bundle is the single source of truth: adding a language is a translation-only
-/// change — once a locale exists in the catalog, it appears in ``all`` with no code change required.
+/// The languages are read from the injected `bundle`'s String Catalog, so the catalog that ships in that bundle is the single source of truth: adding
+/// a language is a translation-only change — once a locale exists in the catalog, it appears in ``all`` with no code change required.
 public struct LanguageList: Sendable {
 
     // MARK: Properties
@@ -14,8 +13,8 @@ public struct LanguageList: Sendable {
     /// Should match the catalog bundle's development localization.
     public let `default`: String
 
-    /// The bundle whose compiled String Catalog defines the available languages.
-    private let bundle: Bundle
+    /// The backend that reports the available languages.
+    private let resolver: any CatalogResolving
 
     // MARK: Initializers
 
@@ -27,7 +26,23 @@ public struct LanguageList: Sendable {
         bundle: Bundle,
         `default`: String = "en"
     ) {
-        self.bundle = bundle
+        self.init(
+            resolver: StringCatalog(bundle: bundle),
+            default: `default`
+        )
+    }
+
+    /// Creates a language list backed by the given resolver.
+    ///
+    /// The seam for tests and alternative backends; the public API derives languages from a bundled catalog.
+    /// - Parameters:
+    ///   - resolver: the backend that reports the available languages.
+    ///   - default: the language served when none of the supported languages match.
+    init(
+        resolver: any CatalogResolving,
+        `default`: String = "en"
+    ) {
+        self.resolver = resolver
         self.`default` = `default`
     }
 
@@ -35,12 +50,13 @@ public struct LanguageList: Sendable {
 
     /// Every language the bundle's String Catalog provides a localization for.
     ///
-    /// The `Base` internationalization is excluded, as it is a development placeholder rather than a
-    /// real language.
+    /// The `Base` internationalization is excluded, as it is a development placeholder rather than a real language.
+    /// The result is sorted for a stable order.
     public var all: [String] {
-        bundle
-            .localizations
+        resolver
+            .languages
             .filter { $0 != "Base" }
+            .sorted()
     }
 
 }
diff --git a/Packages/Localization/Sources/Types/StringCatalog.swift b/Packages/Localization/Sources/Types/StringCatalog.swift
new file mode 100644
index 0000000..477c33c
--- /dev/null
+++ b/Packages/Localization/Sources/Types/StringCatalog.swift
@@ -0,0 +1,133 @@
+import Foundation
+
+/// A decoded `.xcstrings` String Catalog, read directly from a bundle's resources.
+///
+/// The catalog is parsed from raw JSON rather than through Foundation's compiled-catalog APIs (`String(localized:)`,
+/// `Bundle.localizations`, `Bundle.preferredLocalizations`). Those are either unavailable or non-functional on non-Darwin platforms
+/// (Linux), where the toolchain ships no `xcstringstool` and so copies the raw `.xcstrings` into the resource bundle instead of compiling it.
+/// Reading the catalog ourselves gives identical behaviour on every platform the service builds for.
+///
+/// Only simple `stringUnit` values are decoded; plural and device variations are not represented.
+struct StringCatalog: Sendable {
+
+    // MARK: Properties
+
+    /// The source language of the catalog, used as the fallback when a key lacks a requested localization.
+    let sourceLanguage: String
+
+    /// The resolved entries, keyed by catalog key then by language code.
+    let entries: [String: [String: String]]
+
+    // MARK: Computed
+
+    /// Every language the catalog provides a localization for, including the source language.
+    var languages: Set<String> {
+        var languages = Set(entries.values.flatMap(\.keys))
+
+        languages.insert(sourceLanguage)
+
+        return languages
+    }
+
+    // MARK: Initializers
+
+    /// Reads the catalog named `table` from `bundle`.
+    ///
+    /// Falls back to an empty catalog (source language `"en"`, no entries) when the resource is missing or cannot be decoded, so lookups degrade
+    /// to returning the key and the language list to the default.
+    /// - Parameters:
+    ///   - bundle: the bundle whose resources contain the String Catalog.
+    ///   - table: the name of the String Catalog resource, without the `.xcstrings` extension.
+    init(
+        bundle: Bundle,
+        table: String = "Localizable"
+    ) {
+        guard let url = bundle.url(
+            forResource: table,
+            withExtension: .Extension.stringCatalog
+        ) else {
+            self.sourceLanguage = "en"
+            self.entries = [:]
+            return
+        }
+
+        do {
+            let decoder = JSONDecoder()
+            let data = try Data(contentsOf: url)
+            let decoded = try decoder.decode(
+                Decoded.self,
+                from: data
+            )
+
+            self.sourceLanguage = decoded.sourceLanguage
+            self.entries = decoded.strings
+                .mapValues { entry in
+                    (entry.localizations ?? [:])
+                        .compactMapValues { $0.stringUnit?.value }
+                }
+        } catch {
+            self.sourceLanguage = "en"
+            self.entries = [:]
+        }
+    }
+
+}
+
+// MARK: - CatalogResolving
+
+extension StringCatalog: CatalogResolving {
+
+    func string(
+        for key: String,
+        in locale: Locale
+    ) -> String {
+        guard let byLanguage = entries[key] else {
+            return key
+        }
+
+        let language = locale
+            .language
+            .languageCode?
+            .identifier
+            ?? sourceLanguage
+
+        return byLanguage[language]
+            ?? byLanguage[sourceLanguage]
+            ?? key
+    }
+
+}
+
+// MARK: - Decoding Types
+
+private extension StringCatalog {
+
+    /// The subset of the `.xcstrings` format needed to resolve simple string entries.
+    struct Decoded: Decodable {
+
+        let sourceLanguage: String
+        let strings: [String: Entry]
+
+        struct Entry: Decodable {
+            let localizations: [String: Localization]?
+        }
+
+        struct Localization: Decodable {
+            let stringUnit: StringUnit?
+        }
+
+        struct StringUnit: Decodable {
+            let value: String
+        }
+
+    }
+
+}
+
+// MARK: - String+Constants
+
+private extension String {
+    enum Extension {
+        static let stringCatalog = "xcstrings"
+    }
+}
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index e3f71bf..db51f45 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -14,17 +14,18 @@ RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
 WORKDIR /build
 
 # First just resolve dependencies.
-# This creates a cached layer that can be reused
-# as long as your Package.swift/Package.resolved
-# files do not change.
-COPY ./Package.* ./
-RUN swift package resolve
+# This creates a cached layer that can be reused as long as the manifests do
+# not change. The Website package depends on the local Localization package via
+# a relative path, so its manifest must be present for resolution to succeed.
+COPY ./Packages/Localization/Package.swift ./Packages/Localization/
+COPY ./Services/Website/Package.swift ./Services/Website/Package.resolved ./Services/Website/
+RUN swift package --package-path ./Services/Website resolve
 
 # Copy entire repo into container
 COPY . .
 
 # Build the application, with optimizations, with static linking, and using jemalloc
-RUN swift build -c release \
+RUN swift build --package-path ./Services/Website -c release \
     --product "Website" \
     --static-swift-stdlib \
     -Xlinker -ljemalloc
@@ -33,17 +34,17 @@ RUN swift build -c release \
 WORKDIR /staging
 
 # Copy main executable to staging area
-RUN cp "$(swift build --package-path /build -c release --show-bin-path)/Website" ./
+RUN cp "$(swift build --package-path /build/Services/Website -c release --show-bin-path)/Website" ./
 
 # Copy static swift backtracer binary to staging area
 RUN cp "/usr/libexec/swift/linux/swift-backtrace-static" ./
 
 # Copy resources bundled by SPM to staging area
-RUN find -L "$(swift build --package-path /build -c release --show-bin-path)/" -regex '.*\.resources$' -exec cp -Ra {} ./ \;
+RUN find -L "$(swift build --package-path /build/Services/Website -c release --show-bin-path)/" -regex '.*\.resources$' -exec cp -Ra {} ./ \;
 
 # Copy the static files directory (served by FileMiddleware) if it exists
 # Ensure that by default, neither the directory nor any of its contents are writable.
-RUN [ -d /build/Resources ] && { mv /build/Resources ./Resources && chmod -R a-w ./Resources; } || true
+RUN [ -d /build/Services/Website/Resources ] && { mv /build/Services/Website/Resources ./Resources && chmod -R a-w ./Resources; } || true
 
 # ================================
 # Run image
diff --git a/Services/Website/Makefile b/Services/Website/Makefile
index 30aa03f..a086c67 100644
--- a/Services/Website/Makefile
+++ b/Services/Website/Makefile
@@ -76,7 +76,8 @@ img-release: ## Build the production (amd64) image, tag with version + latest, p
 		--platform $(IMAGE_PLATFORM) \
 		--tag $(IMAGE_URL):$(version) \
 		--tag $(IMAGE_URL):latest \
-		.
+		--file Dockerfile \
+		../..
 	@echo "${HOST_PASSWORD}" \
 		| docker login $(HOST_CONTAINER) \
 			--username $(HOST_USER) \
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 7e4b279..b8e1f07 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -91,7 +91,9 @@ let package = Package(
             ],
             path: "Sources/Library",
             resources: [
-                .process("Catalogs/Localizable.xcstrings")
+                // Copied verbatim rather than processed: the String Catalog is read as raw JSON at
+                // runtime so it resolves identically on Darwin and Linux (which cannot compile it).
+                .copy("Catalogs/Localizable.xcstrings")
             ]
         ),
         .testTarget(
diff --git a/Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift
index b343f3c..4ebf3bb 100644
--- a/Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift
@@ -2,9 +2,9 @@ import HTTPTypes
 
 extension HTTPField.Name {
     /// The `Permissions-Policy` field name (not provided as a standard `HTTPField.Name`).
-    public static let permissionsPolicy = Self("Permissions-Policy")!
+    static let permissionsPolicy = Self("Permissions-Policy")!
     /// The `Referrer-Policy` field name (not provided as a standard `HTTPField.Name`).
-    public static let referrerPolicy = Self("Referrer-Policy")!
+    static let referrerPolicy = Self("Referrer-Policy")!
     /// The `X-Frame-Options` field name (not provided as a standard `HTTPField.Name`).
-    public static let frameOptions = Self("X-Frame-Options")!
+    static let frameOptions = Self("X-Frame-Options")!
 }
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
index 22467b1..24390a3 100644
--- a/Services/Website/docker-compose.override.yml
+++ b/Services/Website/docker-compose.override.yml
@@ -12,7 +12,9 @@ services:
     image: ${IMAGE_NAME}:${IMAGE_TAG:-latest}
     platform: linux/arm64
     build:
-      context: .
-      dockerfile: Dockerfile
+      # The build context is the repo root so the local Localization package
+      # (referenced via ../../Packages/Localization) is inside the context.
+      context: ../..
+      dockerfile: Services/Website/Dockerfile
     environment:
       LOG_LEVEL: debug
-- 
2.54.0


From dc6b22e6482346f6d38b37aeecc5fe747a26a67f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 11 Jul 2026 09:15:58 +0000
Subject: [PATCH 014/117] Database setup for the Website service (#13)

This PR contains the work done to introduce a _Fluent_-based persistence layer for the Website service, selectable at runtime alongside the existing in-memory default, plus the local dev tooling and docs to support it.

To provide further details about the work:

* Persistence package
  * The `Driver` and `TLS` enumerations
  * The `Configuration` type
  * The `Service` factory that builds the  service
  * `PrepareDB` for migrations registration
  * The `Probe` for readiness checks.

* App integration
  *  Builds the driver, registers migrations, and attaches `Fluent` to the service lifecycle so it starts/stops with the HTTP server.
  * Migrate-on-boot is gated to the in-memory backend; MySQL/MariaDB is migrated out of band via --database-migrate so shared databases never race on startup.
  * The `ConfigReader+Properties` extension maps database.* config keys onto the driver.

* Library
  * Added database configuration constants.
  * The `HealthController` controller gains a readiness probe: `GET /health/ready` checks whether the database is reachable, separate from the existing liveness check.

* Others
  * Updated the `docker-compose` files to support a database service behind a database profile, and hardened for local development
  * New database targets on the `Makefile` file and overall documentation updated
  * Updated the `.env.local`, `Dockerfile`, and `README` files to document the persistence workflow, config keys, and local DB commands

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/13
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .gitignore                                    |   3 +
 Packages/Localization/Package.swift           |   2 -
 .../Protocols/CatalogResolving.swift          |   0
 .../{ => Internal}/Types/StringCatalog.swift  |   0
 .../{ => Public}/Methods/Localize.swift       |   0
 .../{ => Public}/Methods/Negotiate.swift      |   0
 .../{ => Public}/Types/LanguageList.swift     |   0
 .../{ => Public}/Methods/LocalizeTests.swift  |   0
 .../{ => Public}/Methods/NegotiateTests.swift |   0
 .../Types/LanguageListTests.swift             |   0
 .../xcschemes/Persistence.xcscheme            |  77 +++++++
 Packages/Persistence/Package.swift            |  67 ++++++
 .../Migrations/CreateExampleRecord.swift      |  28 +++
 .../Internal/Models/ExampleRecord.swift       |  45 ++++
 .../Repositories/ExampleRepository.swift      |  63 ++++++
 .../Sources/Public/Enumerations/Driver.swift  |  20 ++
 .../Sources/Public/Enumerations/TLS.swift     |  42 ++++
 .../Sources/Public/Methods/PrepareDB.swift    |  29 +++
 .../Sources/Public/Methods/Probe.swift        |  49 +++++
 .../Sources/Public/Methods/Service.swift      |  78 +++++++
 .../Sources/Public/Types/Configuration.swift  |  60 ++++++
 .../Cases/Public/Enumerations/TLSTests.swift  |  28 +++
 .../Cases/Public/Methods/ProbeTests.swift     |  77 +++++++
 .../Cases/Public/Methods/ServiceTests.swift   | 165 ++++++++++++++
 .../Utils/Fakes/NotSQLConfiguration.swift     |  13 ++
 .../Tests/Utils/Fakes/NotSQLDatabase.swift    |  44 ++++
 .../Tests/Utils/Fakes/NotSQLDriver.swift      |  13 ++
 Services/Website/.env.local                   |  25 +++
 Services/Website/Dockerfile                   |   1 +
 Services/Website/Makefile                     |  72 +++++--
 Services/Website/Package.swift                |   5 +
 Services/Website/README.md                    |  81 ++++++-
 Services/Website/Sources/App/App+build.swift  | 203 ------------------
 Services/Website/Sources/App/App.swift        |  21 ++
 .../Sources/App/Extensions/App+Build.swift    | 166 ++++++++++++++
 .../Extensions/ConfigReader+Properties.swift  | 182 ++++++++++++++++
 .../Public/Controllers/HealthController.swift | 108 ++++++++--
 .../AbsoluteConfigKey+Constants.swift         |  21 ++
 .../Extensions/ConfigKey+Constants.swift      |  21 ++
 .../Public/Extensions/Int+Constants.swift     |   7 +
 .../Public/Extensions/String+Constants.swift  |  19 ++
 Services/Website/Tests/App/AppTests.swift     |  38 ++++
 .../Controllers/HealthControllerTests.swift   | 125 ++++++++++-
 Services/Website/docker-compose.override.yml  |  37 +++-
 Services/Website/docker-compose.yml           |  10 +
 45 files changed, 1791 insertions(+), 254 deletions(-)
 rename Packages/Localization/Sources/{ => Internal}/Protocols/CatalogResolving.swift (100%)
 rename Packages/Localization/Sources/{ => Internal}/Types/StringCatalog.swift (100%)
 rename Packages/Localization/Sources/{ => Public}/Methods/Localize.swift (100%)
 rename Packages/Localization/Sources/{ => Public}/Methods/Negotiate.swift (100%)
 rename Packages/Localization/Sources/{ => Public}/Types/LanguageList.swift (100%)
 rename Packages/Localization/Tests/Cases/{ => Public}/Methods/LocalizeTests.swift (100%)
 rename Packages/Localization/Tests/Cases/{ => Public}/Methods/NegotiateTests.swift (100%)
 rename Packages/Localization/Tests/Cases/{ => Public}/Types/LanguageListTests.swift (100%)
 create mode 100644 Packages/Persistence/.swiftpm/xcode/xcshareddata/xcschemes/Persistence.xcscheme
 create mode 100644 Packages/Persistence/Package.swift
 create mode 100644 Packages/Persistence/Sources/Internal/Migrations/CreateExampleRecord.swift
 create mode 100644 Packages/Persistence/Sources/Internal/Models/ExampleRecord.swift
 create mode 100644 Packages/Persistence/Sources/Internal/Repositories/ExampleRepository.swift
 create mode 100644 Packages/Persistence/Sources/Public/Enumerations/Driver.swift
 create mode 100644 Packages/Persistence/Sources/Public/Enumerations/TLS.swift
 create mode 100644 Packages/Persistence/Sources/Public/Methods/PrepareDB.swift
 create mode 100644 Packages/Persistence/Sources/Public/Methods/Probe.swift
 create mode 100644 Packages/Persistence/Sources/Public/Methods/Service.swift
 create mode 100644 Packages/Persistence/Sources/Public/Types/Configuration.swift
 create mode 100644 Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
 create mode 100644 Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
 create mode 100644 Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
 create mode 100644 Packages/Persistence/Tests/Utils/Fakes/NotSQLConfiguration.swift
 create mode 100644 Packages/Persistence/Tests/Utils/Fakes/NotSQLDatabase.swift
 create mode 100644 Packages/Persistence/Tests/Utils/Fakes/NotSQLDriver.swift
 delete mode 100644 Services/Website/Sources/App/App+build.swift
 create mode 100644 Services/Website/Sources/App/Extensions/App+Build.swift
 create mode 100644 Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift

diff --git a/.gitignore b/.gitignore
index e33ea89..6ca7d7a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,6 +51,9 @@ playground.xcworkspace
 .env
 !.env.local
 
+## Local MariaDB data files
+Services/Website/Tests/DB/
+
 # Fastlane
 fastlane/report.xml
 fastlane/Preview.html
diff --git a/Packages/Localization/Package.swift b/Packages/Localization/Package.swift
index 99625f3..8778c92 100644
--- a/Packages/Localization/Package.swift
+++ b/Packages/Localization/Package.swift
@@ -7,8 +7,6 @@ let package = Package(
     defaultLocalization: "en",
     platforms: [
         .macOS(.v15),
-        .iOS(.v18),
-        .tvOS(.v18),
     ],
     products: [
         .library(
diff --git a/Packages/Localization/Sources/Protocols/CatalogResolving.swift b/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
similarity index 100%
rename from Packages/Localization/Sources/Protocols/CatalogResolving.swift
rename to Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
diff --git a/Packages/Localization/Sources/Types/StringCatalog.swift b/Packages/Localization/Sources/Internal/Types/StringCatalog.swift
similarity index 100%
rename from Packages/Localization/Sources/Types/StringCatalog.swift
rename to Packages/Localization/Sources/Internal/Types/StringCatalog.swift
diff --git a/Packages/Localization/Sources/Methods/Localize.swift b/Packages/Localization/Sources/Public/Methods/Localize.swift
similarity index 100%
rename from Packages/Localization/Sources/Methods/Localize.swift
rename to Packages/Localization/Sources/Public/Methods/Localize.swift
diff --git a/Packages/Localization/Sources/Methods/Negotiate.swift b/Packages/Localization/Sources/Public/Methods/Negotiate.swift
similarity index 100%
rename from Packages/Localization/Sources/Methods/Negotiate.swift
rename to Packages/Localization/Sources/Public/Methods/Negotiate.swift
diff --git a/Packages/Localization/Sources/Types/LanguageList.swift b/Packages/Localization/Sources/Public/Types/LanguageList.swift
similarity index 100%
rename from Packages/Localization/Sources/Types/LanguageList.swift
rename to Packages/Localization/Sources/Public/Types/LanguageList.swift
diff --git a/Packages/Localization/Tests/Cases/Methods/LocalizeTests.swift b/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift
similarity index 100%
rename from Packages/Localization/Tests/Cases/Methods/LocalizeTests.swift
rename to Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift
diff --git a/Packages/Localization/Tests/Cases/Methods/NegotiateTests.swift b/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
similarity index 100%
rename from Packages/Localization/Tests/Cases/Methods/NegotiateTests.swift
rename to Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
diff --git a/Packages/Localization/Tests/Cases/Types/LanguageListTests.swift b/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift
similarity index 100%
rename from Packages/Localization/Tests/Cases/Types/LanguageListTests.swift
rename to Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift
diff --git a/Packages/Persistence/.swiftpm/xcode/xcshareddata/xcschemes/Persistence.xcscheme b/Packages/Persistence/.swiftpm/xcode/xcshareddata/xcschemes/Persistence.xcscheme
new file mode 100644
index 0000000..1bd174b
--- /dev/null
+++ b/Packages/Persistence/.swiftpm/xcode/xcshareddata/xcschemes/Persistence.xcscheme
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "2700"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "Persistence"
+               BuildableName = "Persistence"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      shouldAutocreateTestPlan = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "PersistenceTests"
+               BuildableName = "PersistenceTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES"
+      queueDebuggingEnabled = "No">
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "Persistence"
+            BuildableName = "Persistence"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </MacroExpansion>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
diff --git a/Packages/Persistence/Package.swift b/Packages/Persistence/Package.swift
new file mode 100644
index 0000000..ca63107
--- /dev/null
+++ b/Packages/Persistence/Package.swift
@@ -0,0 +1,67 @@
+// swift-tools-version: 6.3
+
+import PackageDescription
+
+let package = Package(
+    name: "Persistence",
+    platforms: [
+        .macOS(.v15),
+    ],
+    products: [
+        .library(
+            name: "Persistence",
+            targets: [
+                "Persistence"
+            ]
+        )
+    ],
+    dependencies: [
+        .package(
+            url: "https://github.com/hummingbird-project/hummingbird-fluent.git",
+            from: "2.0.0"
+        ),
+        .package(
+            url: "https://github.com/vapor/fluent-mysql-driver.git",
+            from: "4.8.0"
+        ),
+        .package(
+            url: "https://github.com/vapor/fluent-sqlite-driver.git",
+            from: "4.9.0"
+        ),
+        .package(
+            url: "https://github.com/vapor/sql-kit.git",
+            from: "3.36.0"
+        ),
+    ],
+    targets: [
+        .target(
+            name: "Persistence",
+            dependencies: [
+                .product(
+                    name: "HummingbirdFluent",
+                    package: "hummingbird-fluent"
+                ),
+                .product(
+                    name: "FluentMySQLDriver",
+                    package: "fluent-mysql-driver"
+                ),
+                .product(
+                    name: "FluentSQLiteDriver",
+                    package: "fluent-sqlite-driver"
+                ),
+                .product(
+                    name: "SQLKit",
+                    package: "sql-kit"
+                ),
+            ],
+            path: "Sources"
+        ),
+        .testTarget(
+            name: "PersistenceTests",
+            dependencies: [
+                .byName(name: "Persistence")
+            ],
+            path: "Tests"
+        ),
+    ]
+)
diff --git a/Packages/Persistence/Sources/Internal/Migrations/CreateExampleRecord.swift b/Packages/Persistence/Sources/Internal/Migrations/CreateExampleRecord.swift
new file mode 100644
index 0000000..ef06d99
--- /dev/null
+++ b/Packages/Persistence/Sources/Internal/Migrations/CreateExampleRecord.swift
@@ -0,0 +1,28 @@
+import FluentKit
+
+/// Creates and drops the `example_records` table backing ``ExampleRecord``.
+///
+/// Reference scaffolding paired with ``ExampleRecord``; replace it with the first real migration once a
+/// domain model is defined. Migrations are append-only in production — add a new migration to alter the
+/// schema rather than editing one that has already run.
+struct CreateExampleRecord: AsyncMigration {
+
+    // MARK: Methods
+
+    /// Creates the `example_records` table with an `id` primary key and a required `name` column.
+    /// - Parameter database: the database the schema change is applied to.
+    func prepare(on database: Database) async throws {
+        try await database.schema(ExampleRecord.schema)
+            .id()
+            .field("name", .string, .required)
+            .create()
+    }
+
+    /// Drops the `example_records` table, reverting ``prepare(on:)``.
+    /// - Parameter database: the database the schema change is applied to.
+    func revert(on database: Database) async throws {
+        try await database.schema(ExampleRecord.schema)
+            .delete()
+    }
+
+}
diff --git a/Packages/Persistence/Sources/Internal/Models/ExampleRecord.swift b/Packages/Persistence/Sources/Internal/Models/ExampleRecord.swift
new file mode 100644
index 0000000..350a8b1
--- /dev/null
+++ b/Packages/Persistence/Sources/Internal/Models/ExampleRecord.swift
@@ -0,0 +1,45 @@
+import FluentKit
+import Foundation
+
+/// A FluentKit model of a single `example_records` row.
+///
+/// This is reference scaffolding: it demonstrates the model → migration → repository pattern the rest of
+/// the package is built around, and is what the tests exercise. Replace it with the first real domain model
+/// (paired with its own migration and repository) once one is defined.
+///
+/// FluentKit models are mutable reference types whose property wrappers are not `Sendable`; the model never
+/// crosses a concurrency boundary (repositories map it to a `Sendable` snapshot before returning), so the
+/// conformance is declared `@unchecked Sendable`.
+final class ExampleRecord: Model, @unchecked Sendable {
+
+    // MARK: Properties
+
+    /// The name of the backing table.
+    static let schema = "example_records"
+
+    /// The row's primary key, assigned on first save.
+    @ID(key: .id)
+    var id: UUID?
+
+    /// The row's name column.
+    @Field(key: "name")
+    var name: String
+
+    // MARK: Initializers
+
+    /// Creates an empty record, as required by FluentKit to hydrate query results.
+    init() {}
+
+    /// Creates a record with the given values.
+    /// - Parameters:
+    ///   - id: the primary key, or `nil` to have one assigned on save.
+    ///   - name: the value of the name column.
+    init(
+        id: UUID? = nil,
+        name: String
+    ) {
+        self.id = id
+        self.name = name
+    }
+
+}
diff --git a/Packages/Persistence/Sources/Internal/Repositories/ExampleRepository.swift b/Packages/Persistence/Sources/Internal/Repositories/ExampleRepository.swift
new file mode 100644
index 0000000..081dea1
--- /dev/null
+++ b/Packages/Persistence/Sources/Internal/Repositories/ExampleRepository.swift
@@ -0,0 +1,63 @@
+import FluentKit
+import Foundation
+import HummingbirdFluent
+
+/// A `Sendable` snapshot of an ``ExampleRecord``, safe to return across concurrency boundaries.
+///
+/// Repositories return these value-type snapshots rather than FluentKit models, which are mutable reference
+/// types that must not escape the database's execution context.
+public struct Example: Sendable, Equatable {
+
+    // MARK: Properties
+
+    /// The record's primary key, or `nil` if it has never been saved.
+    public let id: UUID?
+    /// The record's name.
+    public let name: String
+
+}
+
+/// Reads and writes ``ExampleRecord`` rows through the default database.
+///
+/// This is the shape every real repository takes: it holds the `Sendable` `Fluent` service, resolves the
+/// default database per call, and maps FluentKit models to `Sendable` snapshots before returning — so no
+/// model ever escapes across an async boundary. It is reference scaffolding paired with ``ExampleRecord``;
+/// replace it with the first real repository once a domain model is defined.
+public struct ExampleRepository: Sendable {
+
+    // MARK: Properties
+
+    /// The service providing the default database the repository reads and writes through.
+    private let fluent: Fluent
+
+    // MARK: Initializers
+
+    /// Creates a repository backed by the given `Fluent` service.
+    /// - Parameter fluent: the service whose default database the repository operates on.
+    public init(fluent: Fluent) {
+        self.fluent = fluent
+    }
+
+    // MARK: Methods
+
+    /// Inserts a record with the given name.
+    /// - Parameter name: the name of the record to insert.
+    /// - Returns: a `Sendable` snapshot of the inserted record, including its assigned identifier.
+    public func create(name: String) async throws -> Example {
+        let record = ExampleRecord(name: name)
+
+        try await record.save(on: fluent.db())
+
+        return Example(id: record.id, name: record.name)
+    }
+
+    /// Fetches every record, ordered by name.
+    /// - Returns: a `Sendable` snapshot of each record, sorted by name.
+    public func all() async throws -> [Example] {
+        try await ExampleRecord.query(on: fluent.db())
+            .sort(\.$name)
+            .all()
+            .map { Example(id: $0.id, name: $0.name) }
+    }
+
+}
diff --git a/Packages/Persistence/Sources/Public/Enumerations/Driver.swift b/Packages/Persistence/Sources/Public/Enumerations/Driver.swift
new file mode 100644
index 0000000..c52b9ef
--- /dev/null
+++ b/Packages/Persistence/Sources/Public/Enumerations/Driver.swift
@@ -0,0 +1,20 @@
+/// The persistence backend the service runs against.
+///
+/// The executable picks a driver at startup and hands it to ``Service``, which registers the
+/// matching database as the default one. Repositories resolve that default and stay agnostic
+/// of which backend is in use.
+public enum Driver: Sendable {
+
+    /// A MySQL/MariaDB server, reached with the given connection parameters.
+    ///
+    /// - Parameter configuration: the host, credentials, TLS posture, and pooling limits the
+    ///   connection is opened with.
+    case mysql(Configuration)
+
+    /// An ephemeral, in-process SQLite database held entirely in memory.
+    ///
+    /// Nothing is written to disk, and all data is lost when the service stops — intended for
+    /// local development and tests.
+    case inMemory
+
+}
diff --git a/Packages/Persistence/Sources/Public/Enumerations/TLS.swift b/Packages/Persistence/Sources/Public/Enumerations/TLS.swift
new file mode 100644
index 0000000..1efaa16
--- /dev/null
+++ b/Packages/Persistence/Sources/Public/Enumerations/TLS.swift
@@ -0,0 +1,42 @@
+import NIOSSL
+
+/// The TLS posture used when connecting to the database.
+///
+/// The executable derives a posture from its `database.tls` configuration and passes it along as
+/// part of ``Configuration``; the MySQL driver receives the resulting `TLSConfiguration` through
+/// ``tlsConfiguration``.
+public enum TLS: Sendable {
+
+    /// Connect without TLS, in plaintext.
+    case off
+
+    /// Connect over TLS when the server offers it, falling back to plaintext otherwise.
+    case prefer
+
+    /// Connect only over TLS, refusing the connection when the server offers none.
+    case require
+
+}
+
+// MARK: - Properties
+
+extension TLS {
+
+    /// The NIO TLS configuration passed to the MySQL driver for this posture.
+    ///
+    /// Returns `nil` for ``off`` (connect in plaintext) and the default client configuration for
+    /// ``prefer`` and ``require``.
+    ///
+    /// - Note: `prefer` and `require` currently map to the same client configuration — both enable TLS.
+    ///   The distinction (fall back to plaintext vs. fail when the server offers no TLS) is not yet
+    ///   enforced here; tighten this mapping if that guarantee becomes required.
+    var tlsConfiguration: TLSConfiguration? {
+        switch self {
+        case .off:
+            return nil
+        case .prefer, .require:
+            return .makeClientConfiguration()
+        }
+    }
+
+}
diff --git a/Packages/Persistence/Sources/Public/Methods/PrepareDB.swift b/Packages/Persistence/Sources/Public/Methods/PrepareDB.swift
new file mode 100644
index 0000000..43283b3
--- /dev/null
+++ b/Packages/Persistence/Sources/Public/Methods/PrepareDB.swift
@@ -0,0 +1,29 @@
+import HummingbirdFluent
+
+/// A registrar declaring every migration against a `Fluent` service.
+///
+/// Built once around the application's `Fluent` service and called as a function — `await migrate()` —
+/// during startup, before the migrations are applied.
+public struct PrepareDB {
+
+    // MARK: Initializers
+
+    /// Creates a registrar for the migrations for a `Fluent` service.
+    public init() {}
+
+    // MARK: Methods
+
+    /// Registers every migration against the `Fluent` service, in order.
+    ///
+    /// This is the single place migrations are declared: add each new migration here, in the order it must
+    /// run (migrations are applied in registration order and are append-only). Registering does not apply
+    /// them — the caller runs `fluent.migrate()` (or the executable's migrate-and-exit mode) to do that.
+    public func callAsFunction(
+        for fluent: Fluent
+    ) async {
+        await fluent.migrations.add([
+            CreateExampleRecord()
+        ])
+    }
+
+}
diff --git a/Packages/Persistence/Sources/Public/Methods/Probe.swift b/Packages/Persistence/Sources/Public/Methods/Probe.swift
new file mode 100644
index 0000000..cdbda36
--- /dev/null
+++ b/Packages/Persistence/Sources/Public/Methods/Probe.swift
@@ -0,0 +1,49 @@
+import HummingbirdFluent
+import SQLKit
+
+/// A readiness probe reporting whether the database behind a `Fluent` service is reachable.
+///
+/// Built once around the application's `Fluent` service and called as a function whenever a fresh
+/// answer is needed — typically from a readiness endpoint: `let ready = await probe()`.
+public struct Probe: Sendable {
+
+    // MARK: Properties
+
+    /// The `Fluent` service whose default database is probed.
+    private let fluent: Fluent
+
+    // MARK: Initializers
+
+    /// Creates a probe for the default database of the given `Fluent` service.
+    /// - Parameter fluent: the `Fluent` service whose default database is probed.
+    public init(
+        fluent: Fluent
+    ) {
+        self.fluent = fluent
+    }
+
+    // MARK: Methods
+
+    /// Reports whether the database behind the `Fluent` service is reachable.
+    ///
+    /// Runs a trivial `SELECT 1` against the default database — the cheapest statement both the MySQL/MariaDB
+    /// and SQLite backends understand — so a readiness check does not depend on any particular schema or model.
+    /// Any failure (connection refused, authentication error, pool exhausted) is reported as not reachable
+    /// rather than thrown, so callers can map it straight onto a readiness response. A default database that
+    /// is not an SQL database is likewise reported as not reachable.
+    /// - Returns: `true` when the database answers the probe, `false` otherwise.
+    public func callAsFunction() async -> Bool {
+        guard let database = fluent.db() as? any SQLDatabase else {
+            return false
+        }
+        
+        do {
+            try await database.raw("SELECT 1").run()
+            
+            return true
+        } catch {
+            return false
+        }
+
+    }
+}
diff --git a/Packages/Persistence/Sources/Public/Methods/Service.swift b/Packages/Persistence/Sources/Public/Methods/Service.swift
new file mode 100644
index 0000000..033adcf
--- /dev/null
+++ b/Packages/Persistence/Sources/Public/Methods/Service.swift
@@ -0,0 +1,78 @@
+import FluentMySQLDriver
+import FluentSQLiteDriver
+import HummingbirdFluent
+import Logging
+
+/// A factory building the `Fluent` service the application persists through.
+///
+/// Built once around the driver the executable picks at startup and called as a function to produce
+/// the configured service: `let fluent = service()`.
+public struct Service: Sendable {
+
+    // MARK: Properties
+
+    /// The persistence backend to register.
+    private let driver: Driver
+
+    /// The logger the database emits through.
+    private let logger: Logger
+
+    // MARK: Initializers
+
+    /// Creates a factory for a `Fluent` service backed by the given driver.
+    /// - Parameters:
+    ///   - driver: the persistence backend to register.
+    ///   - logger: the logger the database emits through.
+    public init(
+        driver: Driver,
+        logger: Logger
+    ) {
+        self.driver = driver
+        self.logger = logger
+    }
+
+    // MARK: Methods
+
+    /// Builds a `Fluent` service configured for the driver.
+    ///
+    /// The selected backend is registered as the *default* database, so repositories resolve it with a plain
+    /// `fluent.db()` and stay agnostic of which driver is in use. The returned service is not yet running; add
+    /// it to the application's service group (`app.addServices(_:)`) so it starts and shuts its connection pool
+    /// down alongside the server.
+    /// - Returns: the configured `Fluent` service, ready to be added to the service group.
+    public func callAsFunction() -> Fluent {
+        let fluent = Fluent(
+            logger: logger
+        )
+
+        switch driver {
+        case .mysql(let configuration):
+            fluent.databases.use(
+                .mysql(
+                    configuration: .init(
+                        hostname: configuration.host,
+                        port: configuration.port,
+                        username: configuration.username,
+                        password: configuration.password,
+                        database: configuration.name,
+                        tlsConfiguration: configuration.tls.tlsConfiguration
+                    ),
+                    maxConnectionsPerEventLoop: configuration.maxConnectionsPerEventLoop
+                ),
+                as: .mysql,
+                isDefault: true
+            )
+        case .inMemory:
+            // A single connection keeps every query pointed at the same in-memory store,
+            // rather than each pooled connection getting its own private database.
+            fluent.databases.use(
+                .sqlite(.memory, maxConnectionsPerEventLoop: 1),
+                as: .sqlite,
+                isDefault: true
+            )
+        }
+
+        return fluent
+    }
+
+}
diff --git a/Packages/Persistence/Sources/Public/Types/Configuration.swift b/Packages/Persistence/Sources/Public/Types/Configuration.swift
new file mode 100644
index 0000000..a60408e
--- /dev/null
+++ b/Packages/Persistence/Sources/Public/Types/Configuration.swift
@@ -0,0 +1,60 @@
+/// The connection parameters for the MySQL/MariaDB backend.
+///
+/// The executable builds this from its `database.*` configuration; the package itself reads no
+/// configuration, so these values arrive as plain data.
+public struct Configuration: Sendable {
+
+    // MARK: Properties
+
+    /// The host the database server is reached at.
+    let host: String
+
+    /// The maximum number of pooled connections opened per event loop.
+    let maxConnectionsPerEventLoop: Int
+
+    /// The name of the database to open.
+    let name: String
+
+    /// The password the connection authenticates with.
+    let password: String
+
+    /// The port the database server listens on.
+    let port: Int
+
+    /// The TLS posture used when connecting.
+    let tls: TLS
+
+    /// The username the connection authenticates as.
+    let username: String
+
+    // MARK: Initializers
+
+    /// Creates a set of MySQL/MariaDB connection parameters.
+    /// - Parameters:
+    ///   - host: the host the database server is reached at.
+    ///   - port: the port the database server listens on.
+    ///   - name: the name of the database to open.
+    ///   - username: the username the connection authenticates as.
+    ///   - password: the password the connection authenticates with.
+    ///   - tls: the TLS posture used when connecting.
+    ///   - maxConnectionsPerEventLoop: the maximum number of pooled connections opened per event loop.
+    public init(
+        host: String,
+        port: Int,
+        name: String,
+        username: String,
+        password: String,
+        tls: TLS,
+        maxConnectionsPerEventLoop: Int
+    ) {
+        self.host = host
+        self.port = port
+        self.name = name
+        self.username = username
+        self.password = password
+        self.tls = tls
+        self.maxConnectionsPerEventLoop = maxConnectionsPerEventLoop
+    }
+
+}
+
diff --git a/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift b/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
new file mode 100644
index 0000000..aa12a00
--- /dev/null
+++ b/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
@@ -0,0 +1,28 @@
+import NIOSSL
+import Testing
+
+@testable import Persistence
+
+@Suite("TLS enumeration")
+struct TLSTests {
+
+    // MARK: Properties tests
+
+    @Test
+    func `off has no TLS configuration`() {
+        #expect(TLS.off.tlsConfiguration == nil)
+    }
+
+    @Test(arguments: [
+        TLS.prefer,
+        TLS.require
+    ])
+    func `maps to the default client configuration`(
+        for tls: TLS
+    ) throws {
+        let configuration = try #require(tls.tlsConfiguration)
+
+        #expect(configuration.bestEffortEquals(.makeClientConfiguration()))
+    }
+
+}
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
new file mode 100644
index 0000000..92ff75e
--- /dev/null
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
@@ -0,0 +1,77 @@
+import FluentKit
+import HummingbirdFluent
+import Logging
+import NIOCore
+import Testing
+
+@testable import Persistence
+
+@Suite("Probe method")
+struct ProbeTests {
+
+    // MARK: Methods tests
+
+    @Test
+    func `reports a reachable database`() async throws {
+        let service = Service(
+            driver: .inMemory,
+            logger: Logger(label: "test")
+        )
+        let fluent = service()
+        let probe = Probe(fluent: fluent)
+
+        let isReachable = await probe()
+
+        try await fluent.shutdown()
+
+        #expect(isReachable)
+    }
+
+    @Test
+    func `reports an unreachable database`() async throws {
+        // Port 1 on the loopback interface has nothing listening, so the connection is refused
+        // immediately instead of timing out.
+        let service = Service(
+            driver: .mysql(
+                .init(
+                    host: "127.0.0.1",
+                    port: 1,
+                    name: "unreachable",
+                    username: "nobody",
+                    password: "nothing",
+                    tls: .off,
+                    maxConnectionsPerEventLoop: 1
+                )
+            ),
+            logger: Logger(label: "test")
+        )
+        let fluent = service()
+        let probe = Probe(fluent: fluent)
+
+        let isReachable = await probe()
+
+        try await fluent.shutdown()
+
+        #expect(!isReachable)
+    }
+
+    @Test
+    func `reports a default database that is not an SQL database`() async throws {
+        let fluent = Fluent(logger: Logger(label: "test"))
+
+        fluent.databases.use(
+            .init(make: { NotSQLConfiguration() }),
+            as: .init(string: "not-sql"),
+            isDefault: true
+        )
+
+        let probe = Probe(fluent: fluent)
+
+        let isReachable = await probe()
+
+        try await fluent.shutdown()
+
+        #expect(!isReachable)
+    }
+
+}
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
new file mode 100644
index 0000000..8066f4d
--- /dev/null
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
@@ -0,0 +1,165 @@
+import Foundation
+import Logging
+import SQLKit
+import Testing
+
+@testable import Persistence
+
+@Suite("Service method")
+struct ServiceTests {
+
+    // MARK: Methods tests
+
+    @Test
+    func `registers an SQLite database as the default for the in-memory driver`() async throws {
+        let service = Service(
+            driver: .inMemory,
+            logger: Logger(label: "test")
+        )
+
+        let fluent = service()
+        let database = fluent.db() as? any SQLDatabase
+
+        try await fluent.shutdown()
+
+        let dialect = try #require(database?.dialect)
+
+        #expect(dialect.name == "sqlite")
+    }
+
+    @Test
+    func `registers a MySQL database as the default for the mysql driver`() async throws {
+        // Resolving the default database opens no connection — pooling is lazy — so no server
+        // needs to be listening on the configured host and port.
+        let service = Service(
+            driver: .mysql(
+                .init(
+                    host: "127.0.0.1",
+                    port: 3306,
+                    name: "loud",
+                    username: "loud",
+                    password: "loud",
+                    tls: .off,
+                    maxConnectionsPerEventLoop: 1
+                )
+            ),
+            logger: Logger(label: "test")
+        )
+
+        let fluent = service()
+        let database = fluent.db() as? any SQLDatabase
+
+        try await fluent.shutdown()
+
+        let dialect = try #require(database?.dialect)
+
+        #expect(dialect.name == "mysql")
+    }
+
+    @Test
+    func `builds a usable in-memory database`() async throws {
+        let service = Service(
+            driver: .inMemory,
+            logger: Logger(label: "test")
+        )
+
+        let fluent = service()
+
+        do {
+            let database = try #require(fluent.db() as? any SQLDatabase)
+
+            try await database.raw("SELECT 1").run()
+        } catch {
+            try? await fluent.shutdown()
+
+            throw error
+        }
+
+        try await fluent.shutdown()
+    }
+
+    @Test("in-memory: migrate, insert, read back")
+    func inMemoryRoundTrip() async throws {
+        try await roundTrip(driver: .inMemory)
+    }
+
+    @Test(
+        "mysql: migrate, insert, read back",
+        .enabled(if: mysqlDriver != nil)
+    )
+    func mysqlRoundTrip() async throws {
+        try await roundTrip(
+            driver: mysqlDriver!,
+            revertAfter: true
+        )
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension ServiceTests {
+
+    /// Migrates, inserts, and reads back a record against the given driver, shutting the pool down after.
+    ///
+    /// The `Fluent` service normally owns pool shutdown via its `run()` in the service group; outside that,
+    /// the test must shut it down explicitly — even on failure — or the pool asserts on `deinit`.
+    /// - Parameters:
+    ///   - driver: the persistence backend to exercise.
+    ///   - revertAfter: whether to revert the migrations afterwards; set for a shared database (the
+    ///     in-memory database is discarded on shutdown, so it needs no revert).
+    func roundTrip(
+        driver: Persistence.Driver,
+        revertAfter: Bool = false
+    ) async throws {
+        let service = Service(
+            driver: driver,
+            logger: Logger(label: "test")
+        )
+        let fluent = service()
+
+        do {
+            await registerMigrations(fluent)
+            try await fluent.migrate()
+
+            let repository = ExampleRepository(fluent: fluent)
+            let created = try await repository.create(name: "loud")
+
+            #expect(try await repository.all().contains(created))
+
+            if revertAfter {
+                try await fluent.revert()
+            }
+        } catch {
+            try? await fluent.shutdown()
+
+            throw error
+        }
+
+        try await fluent.shutdown()
+    }
+
+}
+
+/// The MySQL/MariaDB driver built from the `MYSQL_TEST_*` environment variables, or `nil` when the gate
+/// variable `MYSQL_TEST_HOST` is unset — in which case the MySQL integration test is skipped, so the suite
+/// stays runnable with no database available.
+private let mysqlDriver: Persistence.Driver? = {
+    let environment = ProcessInfo.processInfo.environment
+
+    guard let host = environment["MYSQL_TEST_HOST"] else {
+        return nil
+    }
+
+    return .mysql(
+        .init(
+            host: host,
+            port: environment["MYSQL_TEST_PORT"].flatMap(Int.init) ?? 3306,
+            name: environment["MYSQL_TEST_NAME"] ?? "loud",
+            username: environment["MYSQL_TEST_USERNAME"] ?? "loud",
+            password: environment["MYSQL_TEST_PASSWORD"] ?? "loud",
+            tls: .off,
+            maxConnectionsPerEventLoop: 2
+        )
+    )
+}()
diff --git a/Packages/Persistence/Tests/Utils/Fakes/NotSQLConfiguration.swift b/Packages/Persistence/Tests/Utils/Fakes/NotSQLConfiguration.swift
new file mode 100644
index 0000000..ed276e5
--- /dev/null
+++ b/Packages/Persistence/Tests/Utils/Fakes/NotSQLConfiguration.swift
@@ -0,0 +1,13 @@
+import FluentKit
+
+struct NotSQLConfiguration: DatabaseConfiguration {
+
+    var middleware: [any AnyModelMiddleware] = []
+
+    func makeDriver(
+        for databases: Databases
+    ) -> any DatabaseDriver {
+        NotSQLDriver()
+    }
+
+}
diff --git a/Packages/Persistence/Tests/Utils/Fakes/NotSQLDatabase.swift b/Packages/Persistence/Tests/Utils/Fakes/NotSQLDatabase.swift
new file mode 100644
index 0000000..a612808
--- /dev/null
+++ b/Packages/Persistence/Tests/Utils/Fakes/NotSQLDatabase.swift
@@ -0,0 +1,44 @@
+import FluentKit
+
+/// A Fluent database that is not an `SQLDatabase`, so the probe's downcast fails.
+///
+/// Every query succeeds, proving the probe reports "not reachable" because of the failed downcast
+/// rather than a failing backend.
+struct NotSQLDatabase: Database {
+
+    let context: DatabaseContext
+
+    var inTransaction: Bool { false }
+
+    func execute(
+        query: DatabaseQuery,
+        onOutput: @escaping @Sendable (any DatabaseOutput) -> Void
+    ) -> EventLoopFuture<Void> {
+        context.eventLoop.makeSucceededVoidFuture()
+    }
+
+    func execute(
+        schema: DatabaseSchema
+    ) -> EventLoopFuture<Void> {
+        context.eventLoop.makeSucceededVoidFuture()
+    }
+
+    func execute(
+        enum: DatabaseEnum
+    ) -> EventLoopFuture<Void> {
+        context.eventLoop.makeSucceededVoidFuture()
+    }
+
+    func transaction<T>(
+        _ closure: @escaping @Sendable (any Database) -> EventLoopFuture<T>
+    ) -> EventLoopFuture<T> {
+        closure(self)
+    }
+
+    func withConnection<T>(
+        _ closure: @escaping @Sendable (any Database) -> EventLoopFuture<T>
+    ) -> EventLoopFuture<T> {
+        closure(self)
+    }
+
+}
diff --git a/Packages/Persistence/Tests/Utils/Fakes/NotSQLDriver.swift b/Packages/Persistence/Tests/Utils/Fakes/NotSQLDriver.swift
new file mode 100644
index 0000000..82b8ff4
--- /dev/null
+++ b/Packages/Persistence/Tests/Utils/Fakes/NotSQLDriver.swift
@@ -0,0 +1,13 @@
+import FluentKit
+
+struct NotSQLDriver: DatabaseDriver {
+
+    func makeDatabase(
+        with context: DatabaseContext
+    ) -> any Database {
+        NotSQLDatabase(context: context)
+    }
+
+    func shutdown() {}
+
+}
diff --git a/Services/Website/.env.local b/Services/Website/.env.local
index a3d7faa..1987239 100644
--- a/Services/Website/.env.local
+++ b/Services/Website/.env.local
@@ -40,3 +40,28 @@ HTTP_SERVER_NAME=LoudWebsite
 
 # Log verbosity: trace | debug | info | notice | warning | error | critical
 LOG_LEVEL=info
+
+# --- Persistence ----------------------------------------------------------------
+
+# Persistence driver: inMemory (default, no infrastructure) or mysql.
+DATABASE_DRIVER=inMemory
+
+# MySQL/MariaDB connection, used when DATABASE_DRIVER=mysql.
+# `mariadb` is the local database's Compose service name; use 127.0.0.1 when
+# running the app directly with `swift run`.
+DATABASE_HOST=localhost
+
+# Port of the database to connect to.
+DATABASE_PORT=3306
+
+# Name of the database to connect to.
+DATABASE_NAME=loud-ams
+
+# Username of the database to connect as.
+DATABASE_USERNAME=loud-ams
+
+# Provide the real password via the environment or a secret — never commit it.
+DATABASE_PASSWORD=loud-ams
+
+# TLS posture when connecting: off | prefer | require (use `require` in production).
+DATABASE_TLS=off
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index db51f45..ec87365 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -18,6 +18,7 @@ WORKDIR /build
 # not change. The Website package depends on the local Localization package via
 # a relative path, so its manifest must be present for resolution to succeed.
 COPY ./Packages/Localization/Package.swift ./Packages/Localization/
+COPY ./Packages/Persistence/Package.swift ./Packages/Persistence/
 COPY ./Services/Website/Package.swift ./Services/Website/Package.resolved ./Services/Website/
 RUN swift package --package-path ./Services/Website resolve
 
diff --git a/Services/Website/Makefile b/Services/Website/Makefile
index a086c67..47d91c8 100644
--- a/Services/Website/Makefile
+++ b/Services/Website/Makefile
@@ -38,36 +38,84 @@ pkg-clean: ## Remove the Swift build artifacts
 	@swift package clean
 
 .PHONY: pkg-reset
-pkg-reset: ## Resets the complete SPM cache/build folder
+pkg-reset: ## Reset the SPM cache and build folder
 	@swift package reset
 
 .PHONY: pkg-outdated
-pkg-outdated: ## Lists the SPM package dependencies that can be updated
+pkg-outdated: ## List the SPM dependencies that can be updated
 	@swift package update --dry-run
 
 .PHONY: pkg-update
-pkg-update: ## Updates the SPM package dependencies
+pkg-update: ## Update the SPM dependencies
 	@swift package update
 
 # --- Local development --------------------------------------------------------
 
-.PHONY: img-build
-img-build: ## Build the local dev image
-	@docker compose build
+.PHONY: site-run
+site-run: ## Run the website locally, rebuilding on source changes
+	@hb watch
 
-.PHONY: img-mount
-img-mount: ## Mount the service locally (build if needed)
-	@docker compose up --build --detach
+.PHONY: site-mount
+site-mount: ## Mount the website locally
+	@docker compose up \
+		--build \
+		--detach
 
-.PHONY: img-unmount
-img-unmount: ## Unmount and remove the local service
+.PHONY: site-unmount
+site-unmount: ## Unmount and remove the local website
 	@docker compose down
 	@$(MAKE) img-remove
 
+# --- Local database -----------------------------------------------------------
+
+.PHONY: db-mount
+db-mount: ## Start the local database instance
+	@docker compose \
+		--profile database up \
+		--detach \
+		--wait mariadb
+
+.PHONY: db-migrate
+db-migrate: ## Run the migrations against the local database instance
+	@DATABASE_DRIVER=mysql \
+	DATABASE_HOST=127.0.0.1 \
+	DATABASE_TLS=off \
+	swift run \
+		Website \
+		--database-migrate
+
+.PHONY: db-shell
+db-shell: ## Open a SQL shell on the local database instance
+	@docker compose \
+		--profile database \
+		exec mariadb \
+		mariadb \
+			--user=$(or $(DATABASE_USERNAME),loud) \
+			--password=$(or $(DATABASE_PASSWORD),loud) \
+			$(or $(DATABASE_NAME),loud)
+
+.PHONY: db-unmount
+db-unmount: ## Stop and remove the local database instance (keeps the data volume)
+	@docker compose \
+		--profile database down mariadb
+
+.PHONY: db-reset
+db-reset: ## Stop and remove the local database instance and delete its data volume
+	@docker compose \
+		--profile database down mariadb \
+		--volumes
+
 # --- Registry deployment ------------------------------------------------------
 
+.PHONY: img-check
+img-check: ## Check the production image builds
+	@docker build \
+		--platform linux/amd64 \
+		--file Dockerfile \
+		../..
+
 .PHONY: img-release
-img-release: ## Build the production (amd64) image, tag with version + latest, push both
+img-release: ## Build and push the production image into the container registry
 	@if [ -z "$(version)" ] || [ "$(version)" = "latest" ]; then \
 		echo "Error: 'version' must be an explicit tag — e.g. make img-release version=1.2.3"; \
 		exit 1; \
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index b8e1f07..5f7eeea 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -23,6 +23,9 @@ let package = Package(
         .package(
             path: "../../Packages/Localization"
         ),
+        .package(
+            path: "../../Packages/Persistence"
+        ),
         .package(
             url: "https://github.com/elementary-swift/elementary.git",
             from: "0.6.0"
@@ -52,6 +55,7 @@ let package = Package(
         .executableTarget(
             name: "Website",
             dependencies: [
+                .byName(name: "Persistence"),
                 .byName(name: "WebsiteCore"),
                 .product(
                     name: "Configuration",
@@ -72,6 +76,7 @@ let package = Package(
             name: "WebsiteCore",
             dependencies: [
                 .byName(name: "Localization"),
+                .byName(name: "Persistence"),
                 .product(
                     name: "Configuration",
                     package: "swift-configuration"
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 614ab5e..5bccb5c 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -5,24 +5,30 @@ The **Loud** public website service — a [Hummingbird](https://github.com/hummi
 The service:
 - Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
 - Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteCore` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
-- Answers health checks at `GET /health` with a static JSON payload.
+- Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
 - Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`.
 - Returns a custom HTML 404 page, localized like the landing page, for any request that matches neither a route nor a static file.
 - Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
 - Stamps a hardened set of security headers on every response.
+- Persists data through [Fluent](https://github.com/hummingbird-project/hummingbird-fluent), against either an ephemeral in-memory SQLite database (the default — no external infrastructure) or a MySQL/MariaDB server, selected by a single configuration key.
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
 - Docker (optional) for the containerized run/deploy workflow.
+- The [Hummingbird](https://github.com/hummingbird-project/hummingbird) CLI (`hb`) — optional, only for `make site-run` (watch and rebuild on change).
 
 ## Architecture
 Two SwiftPM targets:
 | Target | Kind | Path | Role |
 | --- | --- | --- | --- |
-| `Website` | executable | `Sources/App` | Entry point: reads configuration, builds and runs the application. |
+| `Website` | executable | `Sources/App` | Entry point: reads configuration, builds the persistence service, and either serves the website or runs the migrate-and-exit mode. |
 | `WebsiteCore` | library | `Sources/Library` | Controllers, middlewares, pages, cached responses, and configuration helpers. |
 
-`WebsiteCore` also depends on the local `Localization` package (`Packages/Localization`), which provides the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages.
+The `Website` executable depends on two local packages:
+- `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteCore`).
+- `Persistence` (`Packages/Persistence`) — the Fluent-based data layer: the `Driver` selector, the `Service` factory that builds the `Fluent` service, the `PrepareDB` registrar that declares the migrations, and the `Probe` consulted by the readiness check; the models, migrations, and repositories stay internal to the package. It has no dependency on `swift-configuration`; the executable maps the `database.*` keys onto the driver.
+
+The persistence backend runs as a `Fluent` service inside the application's ServiceLifecycle group, so it starts and stops alongside the HTTP server (which owns its connection-pool shutdown on graceful termination).
 
 Requests pass through the middleware chain in this order (outermost first), then reach the routes:
 ```
@@ -33,7 +39,7 @@ LogRequestsMiddleware
         → NotFoundMiddleware         (renders the localized 404 page on .notFound)
           → FileMiddleware           (serves Resources/Static)
 RootController                       (GET / → landing page)
-HealthController                     (GET /health → health check)
+HealthController                     (GET /health → liveness, GET /health/ready → readiness)
 ```
 
 ## Configuration
@@ -74,6 +80,21 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 | --- | --- | --- | --- |
 | `log.level` | `LOG_LEVEL` | `info` | Minimum log level. |
 
+### Persistence
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `database.driver` | `DATABASE_DRIVER` | `inMemory` | Backend: `inMemory` (ephemeral SQLite, no infrastructure) or `mysql` (MySQL/MariaDB). |
+| `database.migrate` | `DATABASE_MIGRATE` (flag `--database-migrate`) | `false` | When set, run the migrations and exit instead of serving. |
+| `database.host` | `DATABASE_HOST` | `localhost` | MySQL/MariaDB host. Ignored for `inMemory`. |
+| `database.port` | `DATABASE_PORT` | `3306` | MySQL/MariaDB port. Ignored for `inMemory`. |
+| `database.name` | `DATABASE_NAME` | `loud` | Database name. Ignored for `inMemory`. |
+| `database.username` | `DATABASE_USERNAME` | `loud` | Database username. Ignored for `inMemory`. |
+| `database.password` | `DATABASE_PASSWORD` | _(empty)_ | Database password. Provide via the environment/a secret — never commit it. |
+| `database.tls` | `DATABASE_TLS` | `prefer` | TLS posture when connecting: `off`, `prefer`, or `require`. Ignored for `inMemory`. |
+| `database.pool.maxPerEventLoop` | `DATABASE_POOL_MAX_PER_EVENT_LOOP` | `4` | Maximum pooled connections per event loop. Ignored for `inMemory`. |
+
+See [Persistence](#persistence-1) below for the workflow.
+
 ### Paths
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
@@ -101,12 +122,42 @@ swift run Website --http-host 0.0.0.0 --http-port 9000 --log-level debug
 Or via the Makefile / Docker (uses `docker-compose.override.yml`, which builds from source and sets `LOG_LEVEL=debug`):
 ```sh
 make pkg-build        # swift build
-make img-mount        # docker compose up --build --detach
-make img-unmount      # docker compose down + remove the local image
+make site-run         # run locally with hot reload (hb watch)
+make site-mount       # docker compose up --build --detach
+make site-unmount     # docker compose down + remove the local image
 ```
 
 `make help` lists every available target.
 
+## Persistence
+The service persists data through Fluent and selects its backend at runtime with `database.driver`.
+
+### In-memory (default)
+With no configuration, the service uses an ephemeral in-memory SQLite database. It is created and **migrated on startup** every launch, so `swift run Website` and `docker compose up` work with no external database — ideal for local development and tests.
+
+### MySQL / MariaDB
+Set `DATABASE_DRIVER=mysql` and the connection values (`DATABASE_HOST`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, …). Unlike the in-memory backend, a MySQL/MariaDB database is **not** migrated on boot — a shared database is migrated out of band so multiple instances never race:
+```sh
+# Run the registered migrations against the configured database, then exit.
+swift run Website --database-migrate
+# In a container (production), against the managed database:
+docker compose -f docker-compose.yml run --rm website --database-migrate
+```
+
+A local MariaDB for development lives behind the `database` Compose profile (so a plain `docker compose up` still runs in-memory). Its data directory is bind-mounted to `Tests/DB` (git-ignored), so the database survives `db-unmount` and container restarts:
+```sh
+make db-mount     # start MariaDB (docker compose --profile database up --wait mariadb)
+make db-migrate   # run migrations against it
+make db-shell     # open a SQL shell on it
+make db-unmount   # stop and remove the container (data kept in Tests/DB)
+make db-reset     # stop and remove the container
+DATABASE_DRIVER=mysql make site-mount   # run the site against MariaDB
+```
+> **Note:** because the data lives in the bind-mounted `Tests/DB` folder rather than a named volume, `db-reset`'s `--volumes` flag does **not** clear it. To start from an empty database, delete `Tests/DB` by hand.
+
+### Health checks
+`GET /health` is a liveness check (process is up, no dependency check). `GET /health/ready` is a readiness check that runs `SELECT 1` against the database and returns `200` when reachable or `503` otherwise — so an orchestrator restarts on liveness failure but only withholds traffic on readiness failure.
+
 ## Testing
 ```sh
 make pkg-test
@@ -115,8 +166,21 @@ make pkg-test
 
 Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Website.xctestplan` covers two targets: `WebsiteTests` (the executable/integration tests) and `WebsiteCoreTests` (the library unit tests).
 
+The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the MySQL integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
+```sh
+cd ../../Packages/Persistence && swift test                      # in-memory only
+# With the local MariaDB up (make db-mount):
+cd ../../Packages/Persistence && MYSQL_TEST_HOST=127.0.0.1 swift test
+```
+
 ## Deployment
 The production image is built for `linux/amd64` in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080` (`ENTRYPOINT ./Website --http-host 0.0.0.0 --http-port 8080`).
+
+Verify the image builds for its `linux/amd64` target without tagging or publishing:
+```sh
+make img-check
+```
+
 Build, tag, and push a release to the registry (an explicit version is required):
 ```sh
 make img-release version=1.2.3
@@ -141,3 +205,8 @@ The Makefile and Compose files read these from a `.env` file (or the environment
 | `LOG_LEVEL` | Runtime log level (default `info`). |
 | `HTTP_SERVER_NAME` | Runtime server name (default `LoudWebsite`). |
 | `SECURITY_STRICT_TRANSPORT_SECURITY` | HSTS header value (default `max-age=31536000; includeSubDomains`). |
+| `DATABASE_DRIVER` | `inMemory` (default) or `mysql`. Set to `mysql` in production to use a managed database. |
+| `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` | MySQL/MariaDB connection (when `DATABASE_DRIVER=mysql`). Provide the password via a secret. |
+| `DATABASE_TLS` | TLS posture when connecting: `off`, `prefer`, or `require` (default `require` in production). |
+
+Run the migrations against the production database once before (or during) rollout: `docker compose -f docker-compose.yml run --rm website --database-migrate`.
diff --git a/Services/Website/Sources/App/App+build.swift b/Services/Website/Sources/App/App+build.swift
deleted file mode 100644
index 3898109..0000000
--- a/Services/Website/Sources/App/App+build.swift
+++ /dev/null
@@ -1,203 +0,0 @@
-import Configuration
-import Hummingbird
-import HummingbirdCompression
-import Logging
-import WebsiteCore
-
-/// Builds the website application.
-///
-/// Reads the log level, server name, static files location, minimum response size to compress, and
-/// security headers from the configuration, then assembles the router, server configuration, and logger.
-/// - Parameter reader: the configuration reader the values are read from.
-/// - Returns: the configured application, ready to run as a service.
-func application(
-    reader: ConfigReader
-) async -> some ApplicationProtocol {
-    let cacheControl = cacheControl(
-        textMaxAge: reader.int(
-            forKey: .Cache.maxAgeText,
-            default: .Cache.maxAgeText
-        ),
-        imageMaxAge: reader.int(
-            forKey: .Cache.maxAgeImage,
-            default: .Cache.maxAgeImage
-        ),
-        defaultMaxAge: reader.int(
-            forKey: .Cache.maxAgeDefault,
-            default: .Cache.maxAgeDefault
-        )
-    )
-    let compressionMinResponseSize = reader.int(
-        forKey: .Compression.minResponseSize,
-        default: .Compression.minResponseSize
-    )
-    let logLevel = reader.string(
-        forKey: .Log.level,
-        as: Logger.Level.self,
-        default: .info
-    )
-    let serverName = reader.string(
-        forKey: .HTTP.serverName,
-        default: .Server.name
-    )
-    let staticFilesPath = reader.string(
-        forKey: .Path.staticFiles,
-        default: .Path.staticResources
-    )
-    let securityHeaders = securityHeaders(
-        reader: reader
-    )
-
-    return Application(
-        router: router(
-            staticFilesPath: staticFilesPath,
-            cacheControl: cacheControl,
-            compressionMinResponseSize: compressionMinResponseSize,
-            securityHeaders: securityHeaders,
-            logLevel: logLevel
-        ),
-        configuration: ApplicationConfiguration(
-            reader: reader.scoped(to: "http")
-        ),
-        logger: logger(
-            serverName: serverName,
-            logLevel: logLevel
-        )
-    )
-}
-
-// MARK: - Helpers
-
-// Request context used by application
-private typealias AppRequestContext = WebsiteRequestContext
-
-/// Builds the cache-control policy applied to the served static files.
-///
-/// Static files are public and validated by `FileMiddleware` through their `ETag` and
-/// `Last-Modified` headers, so each media type is given a `max-age` after which the browser
-/// revalidates. Text-based assets (CSS, JavaScript) are additionally marked `must-revalidate`
-/// since they change between deployments while keeping their filenames.
-/// - Parameters:
-///   - textMaxAge: the max-age, in seconds, applied to text-based static files (CSS, JavaScript, plain text).
-///   - imageMaxAge: the max-age, in seconds, applied to image static files (ICO, PNG, SVG).
-///   - defaultMaxAge: the max-age, in seconds, applied to all other static files (e.g. the web manifest).
-/// - Returns: the configured cache-control policy.
-private func cacheControl(
-    textMaxAge: Int,
-    imageMaxAge: Int,
-    defaultMaxAge: Int
-) -> CacheControl {
-    .init([
-        (.text, [.public, .maxAge(textMaxAge), .mustRevalidate]),
-        (.image, [.public, .maxAge(imageMaxAge)]),
-        (.init(type: .any), [.public, .maxAge(defaultMaxAge)]),
-    ])
-}
-
-/// Builds the security-headers configuration applied to every response.
-///
-/// Each header value falls back to the hardened default in `String.Security` when the matching
-/// configuration key is unset. `Strict-Transport-Security` has no default: it is read as an optional
-/// and omitted entirely unless explicitly configured, so it stays off in plain-HTTP development and
-/// is enabled only behind TLS in production.
-/// - Parameter reader: the configuration reader the header values are read from.
-/// - Returns: the configured security-headers configuration.
-private func securityHeaders(
-    reader: ConfigReader
-) -> SecurityHeadersMiddleware<AppRequestContext>.Configuration {
-    .init(
-        contentSecurityPolicy: reader.string(
-            forKey: .Security.contentSecurityPolicy,
-            default: .Security.contentSecurityPolicy
-        ),
-        contentTypeOptions: reader.string(
-            forKey: .Security.contentTypeOptions,
-            default: .Security.contentTypeOptions
-        ),
-        frameOptions: reader.string(
-            forKey: .Security.frameOptions,
-            default: .Security.frameOptions
-        ),
-        referrerPolicy: reader.string(
-            forKey: .Security.referrerPolicy,
-            default: .Security.referrerPolicy
-        ),
-        permissionsPolicy: reader.string(
-            forKey: .Security.permissionsPolicy,
-            default: .Security.permissionsPolicy
-        ),
-        strictTransportSecurity: reader.string(
-            forKey: .Security.strictTransportSecurity
-        )
-    )
-}
-
-/// Builds the application's logger.
-/// - Parameters:
-///   - serverName: the label applied to the logger.
-///   - logLevel: the minimum level the logger emits.
-/// - Returns: the configured logger.
-private func logger(
-    serverName: String,
-    logLevel: Logger.Level
-) -> Logger {
-    var logger = Logger(label: serverName)
-
-    logger.logLevel = logLevel
-
-    return logger
-}
-
-/// Builds the application's router.
-///
-/// Registers the request-logging middleware, the security-headers middleware that stamps the given
-/// `securityHeaders` onto every response, the response-compression middleware that compresses
-/// responses larger than `minimumResponseSizeToCompress` when the client advertises support, the
-/// localization middleware that negotiates the request's language from its `Accept-Language` header,
-/// the not-found middleware that serves the error page, and the static file middleware that serves the
-/// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then
-/// adds the `RootController` routes that render the landing page and the `HealthController` routes
-/// that serve the health check.
-///
-/// The security-headers middleware sits just inside request logging so it covers every response that
-/// reaches a client — the landing page, the compressed responses, the rendered error page, and the
-/// served static files.
-/// - Parameters:
-///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
-///   - cacheControl: the cache-control directives applied to the served static files.
-///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
-///   - securityHeaders: the security headers applied to every response.
-///   - logLevel: the level the request-logging middleware logs at.
-/// - Returns: the configured router.
-private func router(
-    staticFilesPath: String,
-    cacheControl: CacheControl,
-    compressionMinResponseSize: Int,
-    securityHeaders: SecurityHeadersMiddleware<AppRequestContext>.Configuration,
-    logLevel: Logger.Level
-) -> Router<AppRequestContext> {
-    let router = Router(context: AppRequestContext.self)
-
-    router.addMiddleware {
-        LogRequestsMiddleware(logLevel)
-        SecurityHeadersMiddleware(
-            configuration: securityHeaders
-        )
-        ResponseCompressionMiddleware(
-            minimumResponseSizeToCompress: compressionMinResponseSize
-        )
-        LocalizationMiddleware()
-        NotFoundMiddleware()
-        FileMiddleware(
-            staticFilesPath,
-            cacheControl: cacheControl
-        )
-    }
-
-    router.addRoutes {
-        RootController<AppRequestContext>().routes
-        HealthController<AppRequestContext>().routes
-    }
-
-    return router
-}
diff --git a/Services/Website/Sources/App/App.swift b/Services/Website/Sources/App/App.swift
index cf3e8bf..4736863 100644
--- a/Services/Website/Sources/App/App.swift
+++ b/Services/Website/Sources/App/App.swift
@@ -2,8 +2,17 @@ import Configuration
 import Hummingbird
 import Logging
 
+/// The entry point of the website executable.
+///
+/// Loads the configuration, then either serves the website or — when the `database.migrate` flag is set — runs the registered migrations against the
+/// configured backend and exits.
 @main
 struct App {
+
+    /// Loads the configuration and runs the mode it selects.
+    ///
+    /// The configuration is read from the providers in precedence order: command-line arguments first, then process environment variables, then a
+    /// `.env` file when one is present, and finally the in-memory defaults (currently just the server name).
     static func main() async throws {
         let reader = try await ConfigReader(
             providers: [
@@ -19,10 +28,22 @@ struct App {
             ]
         )
 
+        // Migrate-and-exit mode runs the registered migrations against the configured backend and returns,
+        // so a shared database is migrated by a single deliberate invocation (`--database-migrate`) rather
+        // than by every booting instance.
+        guard !reader.migrate else {
+            try await migration(
+                reader: reader
+            )
+
+            return
+        }
+
         let app = await application(
             reader: reader
         )
 
         try await app.runService()
     }
+
 }
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
new file mode 100644
index 0000000..06a167b
--- /dev/null
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -0,0 +1,166 @@
+import Configuration
+import Hummingbird
+import HummingbirdCompression
+import Logging
+import Persistence
+import WebsiteCore
+
+/// Builds the website application.
+///
+/// Reads the log level, server name, static files location, minimum response size to compress, and security headers from the configuration, then assembles
+/// the router, server configuration, and logger. It also builds the persistence driver, registers its migrations, and attaches the `Fluent` service so it starts
+/// and stops alongside the HTTP server; the ephemeral in-memory backend is migrated on startup, while a MySQL/MariaDB backend is migrated out of
+/// band (so a shared database is never migrated on boot).
+/// - Parameter reader: the configuration reader the values are read from.
+/// - Returns: the configured application, ready to run as a service.
+func application(
+    reader: ConfigReader
+) async -> some ApplicationProtocol {
+    let logger = logger(
+        serverName: reader.serverName,
+        logLevel: reader.logLevel
+    )
+    let persistence = Service(
+        driver: reader.driver,
+        logger: logger
+    )
+    let fluent = persistence()
+    let prepareDB = PrepareDB()
+
+    await prepareDB(for: fluent)
+
+    var app = Application(
+        router: router(
+            staticFilesPath: reader.staticFilesPath,
+            cacheControl: reader.cacheControl,
+            compressionMinResponseSize: reader.compressionMinResponseSize,
+            securityHeaders: reader.securityHeaders,
+            logLevel: reader.logLevel,
+            probe: Probe(fluent: fluent)
+        ),
+        configuration: ApplicationConfiguration(
+            reader: reader.scoped(to: "http")
+        ),
+        logger: logger
+    )
+
+    app.addServices(fluent)
+
+    // The in-memory backend is recreated on every launch, so it is migrated on startup. The MySQL/MariaDB
+    // backend is left untouched here: a shared database is migrated out of band to avoid multi-instance races.
+    if case .inMemory = reader.driver {
+        app.beforeServerStarts {
+            try await fluent.migrate()
+        }
+    }
+
+    return app
+}
+
+/// Runs every registered migration against the configured backend, then exits.
+///
+/// This is the out-of-band migration path selected by the `database.migrate` flag: it builds the same driver the service would run against, applies the
+/// migrations, and shuts the database down — so a shared MySQL/MariaDB database is migrated by a single deliberate invocation rather than by every
+/// booting instance.
+/// - Parameter reader: the configuration reader the values are read from.
+func migration(
+    reader: ConfigReader
+) async throws {
+    let logger = logger(
+        serverName: reader.serverName,
+        logLevel: reader.logLevel
+    )
+    let service = Service(
+        driver: reader.driver,
+        logger: logger
+    )
+
+    let fluent = service()
+    let prepareDB = PrepareDB()
+
+    await prepareDB(for: fluent)
+
+    do {
+        try await fluent.migrate()
+    }
+    catch {
+        try? await fluent.shutdown()
+
+        throw error
+    }
+
+    try await fluent.shutdown()
+}
+
+// MARK: - Helpers
+
+/// The request context type the application serves its routes with.
+private typealias AppRequestContext = WebsiteRequestContext
+
+/// Builds the application's logger.
+/// - Parameters:
+///   - serverName: the label applied to the logger.
+///   - logLevel: the minimum level the logger emits.
+/// - Returns: the configured logger.
+private func logger(
+    serverName: String,
+    logLevel: Logger.Level
+) -> Logger {
+    var logger = Logger(label: serverName)
+
+    logger.logLevel = logLevel
+
+    return logger
+}
+
+/// Builds the application's router.
+///
+/// Registers the request-logging middleware, the security-headers middleware that stamps the given `securityHeaders` onto every response, the
+/// response-compression middleware that compresses responses larger than `minimumResponseSizeToCompress` when the client advertises support,
+/// the localization middleware that negotiates the request's language from its `Accept-Language` header, the not-found middleware that serves the
+/// error page, and the static file middleware that serves the contents of `staticFilesPath` (tagging responses with the given `cacheControl`
+/// directives), then adds the `RootController` routes that render the landing page and the `HealthController` routes that serve the health check.
+///
+/// The security-headers middleware sits just inside request logging so it covers every response that reaches a client — the landing page, the compressed
+/// responses, the rendered error page, and the served static files.
+/// - Parameters:
+///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
+///   - cacheControl: the cache-control directives applied to the served static files.
+///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
+///   - securityHeaders: the security headers applied to every response.
+///   - logLevel: the level the request-logging middleware logs at.
+///   - probe: the probe consulted by the `HealthController` readiness route.
+/// - Returns: the configured router.
+private func router(
+    staticFilesPath: String,
+    cacheControl: CacheControl,
+    compressionMinResponseSize: Int,
+    securityHeaders: SecurityHeadersMiddleware<AppRequestContext>.Configuration,
+    logLevel: Logger.Level,
+    probe: Probe
+) -> Router<AppRequestContext> {
+    let router = Router(context: AppRequestContext.self)
+
+    router.addMiddleware {
+        LogRequestsMiddleware(logLevel)
+        SecurityHeadersMiddleware(
+            configuration: securityHeaders
+        )
+        ResponseCompressionMiddleware(
+            minimumResponseSizeToCompress: compressionMinResponseSize
+        )
+        LocalizationMiddleware()
+        NotFoundMiddleware()
+        FileMiddleware(
+            staticFilesPath,
+            cacheControl: cacheControl
+        )
+    }
+
+    router.addRoutes {
+        RootController<AppRequestContext>().routes
+        HealthController<AppRequestContext>(probe: probe).routes
+    }
+
+    return router
+}
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
new file mode 100644
index 0000000..0ddb7a8
--- /dev/null
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -0,0 +1,182 @@
+import Configuration
+import Hummingbird
+import Logging
+import Persistence
+import WebsiteCore
+
+package extension ConfigReader {
+
+    // MARK: Type aliases
+
+    /// The request context type the application serves its routes with; the security headers configuration is generic over it.
+    typealias AppRequestContext = WebsiteRequestContext
+
+    // MARK: Computed
+
+    /// The `Cache-Control` policy applied to static files, grouped by media type.
+    ///
+    /// The max-ages are read from the `cache.maxAge.text`, `cache.maxAge.image`, and `cache.maxAge.default` keys. Text files (CSS,
+    /// JavaScript, plain text) additionally require revalidation once stale; images and everything else are served public with their max-age alone.
+    var cacheControl: CacheControl {
+        let maxAgeDefault = int(
+            forKey: .Cache.maxAgeDefault,
+            default: .Cache.maxAgeDefault
+        )
+        let maxAgeImage = int(
+            forKey: .Cache.maxAgeImage,
+            default: .Cache.maxAgeImage
+        )
+        let maxAgeText = int(
+            forKey: .Cache.maxAgeText,
+            default: .Cache.maxAgeText
+        )
+
+        return .init([
+            (.text, [.public, .maxAge(maxAgeText), .mustRevalidate]),
+            (.image, [.public, .maxAge(maxAgeImage)]),
+            (.init(type: .any), [.public, .maxAge(maxAgeDefault)]),
+        ])
+    }
+
+    /// The minimum response body size, in bytes, before a response is compressed — read from the `compression.minimumResponseSize` key.
+    var compressionMinResponseSize: Int {
+        int(
+            forKey: .Compression.minResponseSize,
+            default: .Compression.minResponseSize
+        )
+    }
+
+    /// The persistence backend the service runs against, derived from the `database.*` keys.
+    ///
+    /// When `database.driver` selects MySQL, the connection parameters are assembled from the `database.host`, `database.port`,
+    /// `database.name`, `database.username`, `database.password` (empty when unset), `database.tls`, and
+    /// `database.pool.maxPerEventLoop` keys. Any other driver value falls back to the in-memory database.
+    var driver: Driver {
+        switch string(
+            forKey: .Database.driver,
+            default: .Database.driver
+        ) {
+        case .Database.driverMySQL:
+            return .mysql(
+                .init(
+                    host: string(
+                        forKey: .Database.host,
+                        default: .Database.host
+                    ),
+                    port: int(
+                        forKey: .Database.port,
+                        default: .Database.port
+                    ),
+                    name: string(
+                        forKey: .Database.name,
+                        default: .Database.name
+                    ),
+                    username: string(
+                        forKey: .Database.username,
+                        default: .Database.username
+                    ),
+                    password: string(
+                        forKey: .Database.password,
+                        default: ""
+                    ),
+                    tls: tls,
+                    maxConnectionsPerEventLoop: int(
+                        forKey: .Database.poolMaxPerEventLoop,
+                        default: .Database.poolMaxPerEventLoop
+                    )
+                )
+            )
+        default:
+            return .inMemory
+        }
+    }
+
+    /// The minimum log level the application emits at, read from the `log.level` key.
+    ///
+    /// Falls back to `.info` when the key is unset or its value names no `Logger.Level` case.
+    var logLevel: Logger.Level {
+        string(
+            forKey: .Log.level,
+            as: Logger.Level.self,
+            default: .info
+        )
+    }
+
+    /// Whether the executable runs in migrate-and-exit mode instead of serving, read from the `database.migrate` flag; off by default.
+    var migrate: Bool {
+        bool(
+            forKey: .Database.migrate,
+            default: false
+        )
+    }
+
+    /// The security headers middleware configuration, built from the `security.*` keys.
+    ///
+    /// Every header value has a default except `Strict-Transport-Security`, which is only sent when `security.strictTransportSecurity`
+    /// is set — the header is a commitment browsers cache, so it must be opted into for deployments actually served over HTTPS.
+    var securityHeaders: SecurityHeadersMiddleware<AppRequestContext>.Configuration {
+        .init(
+            contentSecurityPolicy: string(
+                forKey: .Security.contentSecurityPolicy,
+                default: .Security.contentSecurityPolicy
+            ),
+            contentTypeOptions: string(
+                forKey: .Security.contentTypeOptions,
+                default: .Security.contentTypeOptions
+            ),
+            frameOptions: string(
+                forKey: .Security.frameOptions,
+                default: .Security.frameOptions
+            ),
+            referrerPolicy: string(
+                forKey: .Security.referrerPolicy,
+                default: .Security.referrerPolicy
+            ),
+            permissionsPolicy: string(
+                forKey: .Security.permissionsPolicy,
+                default: .Security.permissionsPolicy
+            ),
+            strictTransportSecurity: string(
+                forKey: .Security.strictTransportSecurity
+            )
+        )
+    }
+
+    /// The name the server reports in its `Server` response header, read from the `http.serverName` key.
+    var serverName: String {
+        string(
+            forKey: .HTTP.serverName,
+            default: .Server.name
+        )
+    }
+
+    /// The directory the static files are served from, read from the `path.staticFiles` key.
+    var staticFilesPath: String {
+        string(
+            forKey: .Path.staticFiles,
+            default: .Path.staticResources
+        )
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension ConfigReader {
+
+    // MARK: Properties
+
+    /// The TLS posture for the MySQL connection, mapped from the `database.tls` key: `off` and `require` map to their postures, and any
+    /// other value falls back to `prefer`.
+    var tls: TLS {
+        switch string(
+            forKey: .Database.tls,
+            default: .Database.tls
+        ) {
+        case .Database.tlsOff: .off
+        case .Database.tlsRequire: .require
+        default: .prefer
+        }
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
index f465d38..ed37869 100644
--- a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
@@ -1,36 +1,45 @@
 import Hummingbird
 import NIOCore
+import Persistence
 
-/// Serves the website's health-check route.
+/// Serves the website's health-check routes.
 ///
-/// The controller exposes its routes as a `RouteCollection` so they can be added to a router
-/// (or a sub-group) by the application that composes it:
+/// The controller exposes its routes as a `RouteCollection` so they can be added to a router (or a sub-group) by the application that composes it:
 ///
 /// ```swift
-/// router.addRoutes(HealthController<AppRequestContext>().routes)
+/// router.addRoutes(HealthController<AppRequestContext>(probe: probe).routes)
 /// ```
 ///
-/// - Note: `Context` is the request context the routes are resolved against, and must match the
-///   context of the router the routes are added to.
+/// It always serves a liveness check at `/health`; when a `Probe` is supplied it also serves a readiness check at `/health/ready` that reports
+/// whether the service's database is reachable. The two are kept distinct so an orchestrator can restart on liveness failure but only withhold traffic on
+/// readiness failure.
+///
+/// - Note: `Context` is the request context the routes are resolved against, and must match the context of the router the routes are added to.
 public struct HealthController<Context: RequestContext>: Sendable {
-    
+
     // MARK: Properties
-    
-    /// The JSON payload returned for every health check.
-    private let payload: String
+
+    /// The probe consulted for the readiness check, or `nil` when only liveness is served.
+    private let probe: Probe?
 
     // MARK: Initializers
 
     /// Creates a health controller.
-    public init() {
-        self.payload = #"{"status":"ok"}"#
+    /// - Parameter probe: the probe consulted by the readiness route; when `nil`, only the liveness
+    ///   route is served.
+    public init(
+        probe: Probe? = nil
+    ) {
+        self.probe = probe
     }
 
     // MARK: Computed
 
     /// The routes served by the controller.
     ///
-    /// Serves a `GET` request for the health path (`/health`) with a static JSON status payload.
+    /// Serves a `GET` request for the liveness path (`/health`) with a static JSON status payload, and —
+    /// when a `Probe` was supplied — a `GET` request for the readiness path (`/health/ready`)
+    /// that consults the probe.
     public var routes: RouteCollection<Context> {
         let routes = RouteCollection(context: Context.self)
 
@@ -39,6 +48,13 @@ public struct HealthController<Context: RequestContext>: Sendable {
             use: check
         )
 
+        if probe != nil {
+            routes.get(
+                .Health.ready,
+                use: ready
+            )
+        }
+
         return routes
     }
 
@@ -50,10 +66,12 @@ private extension HealthController {
 
     // MARK: Methods
 
-    /// Handles a request for the health check.
+    /// Handles a request for the liveness check.
     ///
     /// Returns a constant JSON body built directly per request — the payload is a tiny literal with no
-    /// rendering step, so there is nothing to pre-render or cache.
+    /// rendering step, so there is nothing to pre-render or cache. It reports only that the process is up,
+    /// with no dependency check, so an orchestrator restarts the process only when the process itself is
+    /// unresponsive.
     /// - Parameters:
     ///   - request: the incoming request.
     ///   - context: the context the request is resolved against.
@@ -63,8 +81,50 @@ private extension HealthController {
         request: Request,
         context: some RequestContext
     ) -> Response {
-        Response(
+        json(
             status: .ok,
+            payload: .Payload.live
+        )
+    }
+
+    /// Handles a request for the readiness check.
+    ///
+    /// Consults the `Probe` supplied at initialization and reports `200 OK` when the service's
+    /// database is reachable, or `503 Service Unavailable` otherwise, so a load balancer withholds
+    /// traffic from an instance that cannot yet serve it without restarting the process.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    /// - Returns: a `200 OK` response when ready, or `503 Service Unavailable` when not.
+    @Sendable
+    func ready(
+        request: Request,
+        context: some RequestContext
+    ) async -> Response {
+        guard await probe?() == true else {
+            return json(
+                status: .serviceUnavailable,
+                payload: .Payload.unavailable
+            )
+        }
+
+        return json(
+            status: .ok,
+            payload: .Payload.ready
+        )
+    }
+
+    /// Builds a JSON response carrying the given status and payload.
+    /// - Parameters:
+    ///   - status: the HTTP status of the response.
+    ///   - payload: the JSON body of the response.
+    /// - Returns: the configured JSON response.
+    func json(
+        status: HTTPResponse.Status,
+        payload: String
+    ) -> Response {
+        Response(
+            status: status,
             headers: [.contentType: "application/json"],
             body: .init(byteBuffer: .init(string: payload))
         )
@@ -72,12 +132,24 @@ private extension HealthController {
 
 }
 
-// MARK: - Constants
+// MARK: - RouterPath+Constants
 
 private extension RouterPath {
     /// A namespace for the ``HealthController`` route paths.
     enum Health {
-        /// The path of the health-check endpoint.
+        /// The path of the liveness endpoint.
         static let check: RouterPath = "/health"
+        /// The path of the readiness endpoint.
+        static let ready: RouterPath = "/health/ready"
+    }
+}
+
+// MARK: - String+Constants
+
+private extension String {
+    enum Payload {
+        static let live = #"{"status":"ok"}"#
+        static let ready = #"{"status":"ready"}"#
+        static let unavailable = #"{"status":"unavailable"}"#
     }
 }
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index 06afdd4..9e3ac7d 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -15,6 +15,27 @@ extension AbsoluteConfigKey {
         /// The absolute configuration key for the minimum response body size, in bytes, before compression is applied.
         public static let minResponseSize: AbsoluteConfigKey = .init(.Compression.minResponseSize)
     }
+    /// A namespace for the persistence configuration keys, as absolute keys.
+    public enum Database {
+        /// The absolute configuration key selecting migrate-and-exit mode.
+        public static let migrate: AbsoluteConfigKey = .init(.Database.migrate)
+        /// The absolute configuration key for the persistence driver.
+        public static let driver: AbsoluteConfigKey = .init(.Database.driver)
+        /// The absolute configuration key for the MySQL/MariaDB host.
+        public static let host: AbsoluteConfigKey = .init(.Database.host)
+        /// The absolute configuration key for the MySQL/MariaDB port.
+        public static let port: AbsoluteConfigKey = .init(.Database.port)
+        /// The absolute configuration key for the database name.
+        public static let name: AbsoluteConfigKey = .init(.Database.name)
+        /// The absolute configuration key for the database username.
+        public static let username: AbsoluteConfigKey = .init(.Database.username)
+        /// The absolute configuration key for the database password.
+        public static let password: AbsoluteConfigKey = .init(.Database.password)
+        /// The absolute configuration key for the TLS posture used when connecting.
+        public static let tls: AbsoluteConfigKey = .init(.Database.tls)
+        /// The absolute configuration key for the maximum pooled connections per event loop.
+        public static let poolMaxPerEventLoop: AbsoluteConfigKey = .init(.Database.poolMaxPerEventLoop)
+    }
     /// A namespace for the HTTP server configuration keys, as absolute keys.
     public enum HTTP {
         /// The absolute configuration key for the host the server binds to.
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index 5d27088..cef6a42 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -15,6 +15,27 @@ extension ConfigKey {
         /// The configuration key for the minimum response body size, in bytes, before compression is applied.
         public static let minResponseSize: ConfigKey = "compression.minimumResponseSize"
     }
+    /// A namespace for the persistence configuration keys.
+    public enum Database {
+        /// The configuration key selecting migrate-and-exit mode (run migrations, then exit) instead of serving.
+        public static let migrate: ConfigKey = "database.migrate"
+        /// The configuration key for the persistence driver (`inMemory` or `mysql`).
+        public static let driver: ConfigKey = "database.driver"
+        /// The configuration key for the MySQL/MariaDB host.
+        public static let host: ConfigKey = "database.host"
+        /// The configuration key for the MySQL/MariaDB port.
+        public static let port: ConfigKey = "database.port"
+        /// The configuration key for the database name.
+        public static let name: ConfigKey = "database.name"
+        /// The configuration key for the database username.
+        public static let username: ConfigKey = "database.username"
+        /// The configuration key for the database password.
+        public static let password: ConfigKey = "database.password"
+        /// The configuration key for the TLS posture used when connecting (`off`, `prefer`, or `require`).
+        public static let tls: ConfigKey = "database.tls"
+        /// The configuration key for the maximum pooled connections per event loop.
+        public static let poolMaxPerEventLoop: ConfigKey = "database.pool.maxPerEventLoop"
+    }
     /// A namespace for the HTTP server configuration keys.
     public enum HTTP {
         /// The configuration key for the host the server binds to.
diff --git a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
index d6976ef..201068a 100644
--- a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
@@ -13,4 +13,11 @@ extension Int {
         /// The default minimum response body size, in bytes, before compression is applied (1 KB).
         public static let minResponseSize = 1_024
     }
+    /// A namespace for the persistence's default configuration values.
+    public enum Database {
+        /// The default MySQL/MariaDB port.
+        public static let port = 3_306
+        /// The default maximum pooled connections per event loop.
+        public static let poolMaxPerEventLoop = 4
+    }
 }
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index c9620ca..23fa620 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -1,4 +1,23 @@
 extension String {
+    /// A namespace for the persistence's default configuration values and recognized tokens.
+    public enum Database {
+        /// The default persistence driver: in-memory SQLite, which needs no external infrastructure.
+        public static let driver = "inMemory"
+        /// The driver token selecting the MySQL/MariaDB backend.
+        public static let driverMySQL = "mysql"
+        /// The default MySQL/MariaDB host.
+        public static let host = "localhost"
+        /// The default database name.
+        public static let name = "loud"
+        /// The default database username.
+        public static let username = "loud"
+        /// The default TLS posture token.
+        public static let tls = "prefer"
+        /// The TLS token disabling TLS.
+        public static let tlsOff = "off"
+        /// The TLS token requiring TLS.
+        public static let tlsRequire = "require"
+    }
     /// A namespace for well-known path string constants.
     public enum Path {
         /// The directory, relative to the working directory, that the website's static files are served from.
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 8a968f9..e5ed3a7 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -49,6 +49,44 @@ struct AppTests {
         }
     }
 
+    @Test
+    func `health check to be served at the health path`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/health",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == "application/json")
+                #expect(body == #"{"status":"ok"}"#)
+            }
+        }
+    }
+
+    @Test
+    func `readiness check to be served at the readiness path`() async throws {
+        // Live mode runs the application's service group, so the `Fluent` service starts before the
+        // request and shuts its connection pool down after — the router-only mode never would.
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.live) { client in
+            try await client.execute(
+                uri: "/health/ready",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == "application/json")
+                #expect(body == #"{"status":"ready"}"#)
+            }
+        }
+    }
+
     @Test(arguments: StaticFile.allCases)
     func `static files to be served`(
         staticFile file: StaticFile
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
index 5a5d3c1..5b3c547 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -1,6 +1,8 @@
 import Hummingbird
 import HummingbirdTesting
+import Logging
 import NIOCore
+import Persistence
 import Testing
 
 @testable import WebsiteCore
@@ -8,21 +10,13 @@ import Testing
 @Suite("HealthController controller")
 struct HealthControllerTests {
 
-    // MARK: Constants
-
-    private let app: Application = .init(router: {
-        let router = Router()
-
-        router.addRoutes(HealthController<BasicRequestContext>().routes)
-
-        return router
-    }())
-
     // MARK: Functional tests
 
     @Test
     func `serves the status payload at the health path`() async throws {
-        try await app.test(.router) { client in
+        try await app(
+            probe: nil
+        ).test(.router) { client in
             try await client.execute(
                 uri: "/health",
                 method: .get
@@ -36,4 +30,113 @@ struct HealthControllerTests {
         }
     }
 
+    @Test
+    func `serves ready at the readiness path when the database is reachable`() async throws {
+        let service = Service(
+            driver: .inMemory,
+            logger: Logger(label: "test")
+        )
+        let fluent = service()
+
+        do {
+            try await app(
+                probe: Probe(fluent: fluent)
+            ).test(.router) { client in
+                try await client.execute(
+                    uri: "/health/ready",
+                    method: .get
+                ) { response in
+                    let body = String(buffer: response.body)
+
+                    #expect(response.status == .ok)
+                    #expect(response.headers[.contentType] == "application/json")
+                    #expect(body == #"{"status":"ready"}"#)
+                }
+            }
+        } catch {
+            try? await fluent.shutdown()
+
+            throw error
+        }
+
+        try await fluent.shutdown()
+    }
+
+    @Test
+    func `serves unavailable at the readiness path when the database is unreachable`() async throws {
+        // Port 1 on the loopback interface has nothing listening, so the probe's connection is refused
+        // immediately instead of timing out.
+        let service = Service(
+            driver: .mysql(
+                .init(
+                    host: "127.0.0.1",
+                    port: 1,
+                    name: "unreachable",
+                    username: "nobody",
+                    password: "nothing",
+                    tls: .off,
+                    maxConnectionsPerEventLoop: 1
+                )
+            ),
+            logger: Logger(label: "test")
+        )
+        let fluent = service()
+
+        do {
+            try await app(
+                probe: Probe(fluent: fluent)
+            ).test(.router) { client in
+                try await client.execute(
+                    uri: "/health/ready",
+                    method: .get
+                ) { response in
+                    let body = String(buffer: response.body)
+
+                    #expect(response.status == .serviceUnavailable)
+                    #expect(response.headers[.contentType] == "application/json")
+                    #expect(body == #"{"status":"unavailable"}"#)
+                }
+            }
+        } catch {
+            try? await fluent.shutdown()
+
+            throw error
+        }
+
+        try await fluent.shutdown()
+    }
+
+    @Test
+    func `does not serve the readiness path without a probe`() async throws {
+        try await app(probe: nil).test(.router) { client in
+            try await client.execute(
+                uri: "/health/ready",
+                method: .get
+            ) { response in
+                #expect(response.status == .notFound)
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension HealthControllerTests {
+
+    /// Builds a test application serving the ``HealthController`` routes for the given probe.
+    /// - Parameter probe: the probe supplied to the controller, or `nil` for liveness only.
+    /// - Returns: the configured test application.
+    func app(
+        probe: Probe?
+    ) -> some ApplicationProtocol {
+        Application(router: {
+            let router = Router()
+
+            router.addRoutes(HealthController<BasicRequestContext>(probe: probe).routes)
+
+            return router
+        }())
+    }
+
 }
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
index 24390a3..c297e23 100644
--- a/Services/Website/docker-compose.override.yml
+++ b/Services/Website/docker-compose.override.yml
@@ -12,9 +12,42 @@ services:
     image: ${IMAGE_NAME}:${IMAGE_TAG:-latest}
     platform: linux/arm64
     build:
-      # The build context is the repo root so the local Localization package
-      # (referenced via ../../Packages/Localization) is inside the context.
       context: ../..
       dockerfile: Services/Website/Dockerfile
     environment:
       LOG_LEVEL: debug
+      DATABASE_DRIVER: ${DATABASE_DRIVER:-inMemory}
+      DATABASE_HOST: ${DATABASE_HOST:-localhost}
+      DATABASE_TLS: ${DATABASE_TLS:-off}
+
+  # Local development database, started only with the `database` profile so a plain
+  # `docker compose up` still runs the in-memory backend:
+  #
+  #   docker compose --profile database up mariadb
+  mariadb:
+    image: mariadb:11
+    container_name: ${HOST_OWNER:-loud}-db
+    restart: unless-stopped
+    profiles:
+      - database
+    ports:
+      - "127.0.0.1:${DATABASE_PORT:-3306}:3306"
+    environment:
+      MARIADB_RANDOM_ROOT_PASSWORD: "yes"
+      MARIADB_DATABASE: ${DATABASE_NAME:-loud-ams}
+      MARIADB_USER: ${DATABASE_USERNAME:-loud-ams}
+      MARIADB_PASSWORD: ${DATABASE_PASSWORD:-loud-ams}
+      MARIADB_AUTO_UPGRADE: "1"
+    command:
+      - "--character-set-server=utf8mb4"
+      - "--collation-server=utf8mb4_unicode_ci"
+    security_opt:
+      - no-new-privileges:true
+    healthcheck:
+      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+    volumes:
+      - ./Tests/DB:/var/lib/mysql
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index d3dc25e..81c40d5 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -21,3 +21,13 @@ services:
       LOG_LEVEL: ${LOG_LEVEL:-info}
       HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-LoudWebsite}
       SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
+      # Persistence: in-memory by default; set DATABASE_DRIVER=mysql to run against a
+      # managed MySQL/MariaDB database. Provide the password via the environment or a
+      # secret — never commit it.
+      DATABASE_DRIVER: ${DATABASE_DRIVER:-mysql}
+      DATABASE_HOST: ${DATABASE_HOST:-localhost}
+      DATABASE_PORT: ${DATABASE_PORT:-3306}
+      DATABASE_NAME: ${DATABASE_NAME:-loud-ams}
+      DATABASE_USERNAME: ${DATABASE_USERNAME:-loud-ams}
+      DATABASE_PASSWORD: ${DATABASE_PASSWORD:-}
+      DATABASE_TLS: ${DATABASE_TLS:-require}
-- 
2.54.0


From a0f5c79434454eb0e02b400c5d424b52dfebbe19 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 11 Jul 2026 09:41:21 +0000
Subject: [PATCH 015/117] Renamed the WebsiteCore target in the Website service
 package as WebsiteLibrary. (#14)

This PR contains the work done to rename the _Website_ service's library SwiftPM target from `WebsiteCore` to `WebsiteLibrary`, updating every reference across the manifest, source, tests, Xcode schemes, and documentations.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/14
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../xcode/xcshareddata/xcschemes/Website.xcscheme      |  9 +++++++--
 ...CoreTests.xcscheme => WebsiteLibraryTests.xcscheme} |  4 ++--
 Services/Website/Package.swift                         | 10 +++++-----
 Services/Website/README.md                             |  8 ++++----
 .../Website/Sources/App/Extensions/App+Build.swift     |  2 +-
 .../App/Extensions/ConfigReader+Properties.swift       |  2 +-
 Services/Website/Tests/App/AppTests.swift              |  2 +-
 .../Cases/Internal/Enumerations/StaticFileTests.swift  |  2 +-
 .../Library/Cases/Internal/Pages/ErrorPageTests.swift  |  2 +-
 .../Library/Cases/Internal/Pages/IndexPageTests.swift  |  2 +-
 .../Public/Controllers/HealthControllerTests.swift     |  2 +-
 .../Cases/Public/Controllers/RootControllerTests.swift |  2 +-
 .../Middlewares/LocalizationMiddlewareTests.swift      |  2 +-
 .../Public/Middlewares/NotFoundMiddlewareTests.swift   |  2 +-
 .../Middlewares/SecurityHeadersMiddlewareTests.swift   |  2 +-
 Services/Website/{ => Tests}/Website.xctestplan        |  4 ++--
 16 files changed, 31 insertions(+), 26 deletions(-)
 rename Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/{WebsiteCoreTests.xcscheme => WebsiteLibraryTests.xcscheme} (93%)
 rename Services/Website/{ => Tests}/Website.xctestplan (88%)

diff --git a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
index 2700a30..fe904d8 100644
--- a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
+++ b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
@@ -26,8 +26,13 @@
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      shouldUseLaunchSchemeArgsEnv = "YES"
-      shouldAutocreateTestPlan = "YES">
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <TestPlans>
+         <TestPlanReference
+            reference = "container:Tests/Website.xctestplan"
+            default = "YES">
+         </TestPlanReference>
+      </TestPlans>
       <Testables>
          <TestableReference
             skipped = "NO">
diff --git a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteCoreTests.xcscheme b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteLibraryTests.xcscheme
similarity index 93%
rename from Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteCoreTests.xcscheme
rename to Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteLibraryTests.xcscheme
index d5af719..c86f644 100644
--- a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteCoreTests.xcscheme
+++ b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteLibraryTests.xcscheme
@@ -18,8 +18,8 @@
             skipped = "NO">
             <BuildableReference
                BuildableIdentifier = "primary"
-               BlueprintIdentifier = "WebsiteCoreTests"
-               BuildableName = "WebsiteCoreTests"
+               BlueprintIdentifier = "WebsiteLibraryTests"
+               BuildableName = "WebsiteLibraryTests"
                ReferencedContainer = "container:">
             </BuildableReference>
          </TestableReference>
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 5f7eeea..fdd8c5d 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -15,7 +15,7 @@ let package = Package(
             name: "Website",
             targets: [
                 "Website",
-                "WebsiteCore",
+                "WebsiteLibrary",
             ]
         )
     ],
@@ -56,7 +56,7 @@ let package = Package(
             name: "Website",
             dependencies: [
                 .byName(name: "Persistence"),
-                .byName(name: "WebsiteCore"),
+                .byName(name: "WebsiteLibrary"),
                 .product(
                     name: "Configuration",
                     package: "swift-configuration"
@@ -73,7 +73,7 @@ let package = Package(
             path: "Sources/App"
         ),
         .target(
-            name: "WebsiteCore",
+            name: "WebsiteLibrary",
             dependencies: [
                 .byName(name: "Localization"),
                 .byName(name: "Persistence"),
@@ -113,9 +113,9 @@ let package = Package(
             path: "Tests/App"
         ),
         .testTarget(
-            name: "WebsiteCoreTests",
+            name: "WebsiteLibraryTests",
             dependencies: [
-                .byName(name: "WebsiteCore"),
+                .byName(name: "WebsiteLibrary"),
                 .product(
                     name: "Elementary",
                     package: "elementary"
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 5bccb5c..c705916 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -4,7 +4,7 @@ The **Loud** public website service — a [Hummingbird](https://github.com/hummi
 ## Overview
 The service:
 - Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
-- Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteCore` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
+- Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
 - Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
 - Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`.
 - Returns a custom HTML 404 page, localized like the landing page, for any request that matches neither a route nor a static file.
@@ -22,10 +22,10 @@ Two SwiftPM targets:
 | Target | Kind | Path | Role |
 | --- | --- | --- | --- |
 | `Website` | executable | `Sources/App` | Entry point: reads configuration, builds the persistence service, and either serves the website or runs the migrate-and-exit mode. |
-| `WebsiteCore` | library | `Sources/Library` | Controllers, middlewares, pages, cached responses, and configuration helpers. |
+| `WebsiteLibrary` | library | `Sources/Library` | Controllers, middlewares, pages, cached responses, and configuration helpers. |
 
 The `Website` executable depends on two local packages:
-- `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteCore`).
+- `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteLibrary`).
 - `Persistence` (`Packages/Persistence`) — the Fluent-based data layer: the `Driver` selector, the `Service` factory that builds the `Fluent` service, the `PrepareDB` registrar that declares the migrations, and the `Probe` consulted by the readiness check; the models, migrations, and repositories stay internal to the package. It has no dependency on `swift-configuration`; the executable maps the `database.*` keys onto the driver.
 
 The persistence backend runs as a `Fluent` service inside the application's ServiceLifecycle group, so it starts and stops alongside the HTTP server (which owns its connection-pool shutdown on graceful termination).
@@ -164,7 +164,7 @@ make pkg-test
 # = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
 ```
 
-Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Website.xctestplan` covers two targets: `WebsiteTests` (the executable/integration tests) and `WebsiteCoreTests` (the library unit tests).
+Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Website.xctestplan` covers two targets: `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests).
 
 The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the MySQL integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
 ```sh
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 06a167b..dad5ec7 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -3,7 +3,7 @@ import Hummingbird
 import HummingbirdCompression
 import Logging
 import Persistence
-import WebsiteCore
+import WebsiteLibrary
 
 /// Builds the website application.
 ///
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index 0ddb7a8..2f9fdc2 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -2,7 +2,7 @@ import Configuration
 import Hummingbird
 import Logging
 import Persistence
-import WebsiteCore
+import WebsiteLibrary
 
 package extension ConfigReader {
 
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index e5ed3a7..a677a32 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -7,7 +7,7 @@ import NIOCore
 import Testing
 
 @testable import Website
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("App executable")
 struct AppTests {
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index 284009c..110bca2 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -1,7 +1,7 @@
 import Foundation
 import Testing
 
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("StaticFile enumeration")
 struct StaticFileTests {
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
index 463a357..7e03844 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
@@ -2,7 +2,7 @@ import Elementary
 import Foundation
 import Testing
 
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("ErrorPage page")
 struct ErrorPageTests {
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index be76e76..254b6e3 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -2,7 +2,7 @@ import Elementary
 import Foundation
 import Testing
 
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("IndexPage page")
 struct IndexPageTests {
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
index 5b3c547..f27ec95 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -5,7 +5,7 @@ import NIOCore
 import Persistence
 import Testing
 
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("HealthController controller")
 struct HealthControllerTests {
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
index 6f0cd7f..9fb321f 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
@@ -3,7 +3,7 @@ import HummingbirdTesting
 import NIOCore
 import Testing
 
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("RootController controller")
 struct RootControllerTests {
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
index 09046af..607bc3a 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
@@ -4,7 +4,7 @@ import HummingbirdTesting
 import NIOCore
 import Testing
 
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("LocalizationMiddleware middleware")
 struct LocalizationMiddlewareTests {
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
index 8ac9e09..5aadb6b 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
@@ -3,7 +3,7 @@ import HummingbirdTesting
 import NIOCore
 import Testing
 
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("NotFoundMiddleware middleware")
 struct NotFoundMiddlewareTests {
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
index 9ea5221..224f303 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
@@ -2,7 +2,7 @@ import Hummingbird
 import HummingbirdTesting
 import Testing
 
-@testable import WebsiteCore
+@testable import WebsiteLibrary
 
 @Suite("SecurityHeadersMiddleware middleware")
 struct SecurityHeadersMiddlewareTests {
diff --git a/Services/Website/Website.xctestplan b/Services/Website/Tests/Website.xctestplan
similarity index 88%
rename from Services/Website/Website.xctestplan
rename to Services/Website/Tests/Website.xctestplan
index 5156232..1d7b818 100644
--- a/Services/Website/Website.xctestplan
+++ b/Services/Website/Tests/Website.xctestplan
@@ -28,8 +28,8 @@
     {
       "target" : {
         "containerPath" : "container:",
-        "identifier" : "WebsiteCoreTests",
-        "name" : "WebsiteCoreTests"
+        "identifier" : "WebsiteLibraryTests",
+        "name" : "WebsiteLibraryTests"
       }
     }
   ],
-- 
2.54.0


From 4c57e15991d342884cc902847399dcee782bc18f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 11 Jul 2026 10:34:59 +0000
Subject: [PATCH 016/117] Fixed test case for the Persistence package. (#15)

This PR contains the work done to amend a test case within the Persistence tests target that was failing.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/15
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../Cases/Public/Methods/ServiceTests.swift   |  5 +-
 .../xcschemes/WebsiteLibraryTests.xcscheme    | 54 -------------------
 Services/Website/Tests/Website.xctestplan     | 14 +++++
 3 files changed, 18 insertions(+), 55 deletions(-)
 delete mode 100644 Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteLibraryTests.xcscheme

diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
index 8066f4d..0ef5fb1 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
@@ -112,14 +112,17 @@ private extension ServiceTests {
         driver: Persistence.Driver,
         revertAfter: Bool = false
     ) async throws {
+        let prepareDB = PrepareDB()
         let service = Service(
             driver: driver,
             logger: Logger(label: "test")
         )
+        
         let fluent = service()
 
         do {
-            await registerMigrations(fluent)
+            await prepareDB(for: fluent)
+
             try await fluent.migrate()
 
             let repository = ExampleRepository(fluent: fluent)
diff --git a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteLibraryTests.xcscheme b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteLibraryTests.xcscheme
deleted file mode 100644
index c86f644..0000000
--- a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/WebsiteLibraryTests.xcscheme
+++ /dev/null
@@ -1,54 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<Scheme
-   LastUpgradeVersion = "2700"
-   version = "1.7">
-   <BuildAction
-      parallelizeBuildables = "YES"
-      buildImplicitDependencies = "YES"
-      buildArchitectures = "Automatic">
-   </BuildAction>
-   <TestAction
-      buildConfiguration = "Debug"
-      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
-      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      shouldUseLaunchSchemeArgsEnv = "YES"
-      shouldAutocreateTestPlan = "YES">
-      <Testables>
-         <TestableReference
-            skipped = "NO">
-            <BuildableReference
-               BuildableIdentifier = "primary"
-               BlueprintIdentifier = "WebsiteLibraryTests"
-               BuildableName = "WebsiteLibraryTests"
-               ReferencedContainer = "container:">
-            </BuildableReference>
-         </TestableReference>
-      </Testables>
-   </TestAction>
-   <LaunchAction
-      buildConfiguration = "Debug"
-      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
-      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      launchStyle = "0"
-      useCustomWorkingDirectory = "NO"
-      ignoresPersistentStateOnLaunch = "NO"
-      debugDocumentVersioning = "YES"
-      debugServiceExtension = "internal"
-      allowLocationSimulation = "YES"
-      queueDebuggingEnabled = "No">
-   </LaunchAction>
-   <ProfileAction
-      buildConfiguration = "Release"
-      shouldUseLaunchSchemeArgsEnv = "YES"
-      savedToolIdentifier = ""
-      useCustomWorkingDirectory = "NO"
-      debugDocumentVersioning = "YES">
-   </ProfileAction>
-   <AnalyzeAction
-      buildConfiguration = "Debug">
-   </AnalyzeAction>
-   <ArchiveAction
-      buildConfiguration = "Release"
-      revealArchiveInOrganizer = "YES">
-   </ArchiveAction>
-</Scheme>
diff --git a/Services/Website/Tests/Website.xctestplan b/Services/Website/Tests/Website.xctestplan
index 1d7b818..1711555 100644
--- a/Services/Website/Tests/Website.xctestplan
+++ b/Services/Website/Tests/Website.xctestplan
@@ -31,6 +31,20 @@
         "identifier" : "WebsiteLibraryTests",
         "name" : "WebsiteLibraryTests"
       }
+    },
+    {
+      "target" : {
+        "containerPath" : "container:..\/Localization",
+        "identifier" : "LocalizationTests",
+        "name" : "LocalizationTests"
+      }
+    },
+    {
+      "target" : {
+        "containerPath" : "container:",
+        "identifier" : "PersistenceTests",
+        "name" : "PersistenceTests"
+      }
     }
   ],
   "version" : 1
-- 
2.54.0


From a4906f8f267609618fd63516dfe80c50399c22ba Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 11 Jul 2026 10:43:27 +0000
Subject: [PATCH 017/117] Fixed container paths for the Packages test targets
 in the Website test plan. (#16)

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/16
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/Tests/Website.xctestplan | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Services/Website/Tests/Website.xctestplan b/Services/Website/Tests/Website.xctestplan
index 1711555..7b0061e 100644
--- a/Services/Website/Tests/Website.xctestplan
+++ b/Services/Website/Tests/Website.xctestplan
@@ -34,16 +34,16 @@
     },
     {
       "target" : {
-        "containerPath" : "container:..\/Localization",
-        "identifier" : "LocalizationTests",
-        "name" : "LocalizationTests"
+        "containerPath" : "container:..\/..\/Packages\/Persistence",
+        "identifier" : "PersistenceTests",
+        "name" : "PersistenceTests"
       }
     },
     {
       "target" : {
-        "containerPath" : "container:",
-        "identifier" : "PersistenceTests",
-        "name" : "PersistenceTests"
+        "containerPath" : "container:..\/..\/Packages\/Localization",
+        "identifier" : "LocalizationTests",
+        "name" : "LocalizationTests"
       }
     }
   ],
-- 
2.54.0


From 4a8413359fd639c10fddd61452b9902702a2197f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 11 Jul 2026 16:09:28 +0200
Subject: [PATCH 018/117] Converted the website service project into a reusable
 template.

---
 Makefile                                      |  13 ++
 .../Cases/Public/Methods/ServiceTests.swift   |  14 +-
 README.md                                     |  86 ++++++++++
 Scripts/bootstrap                             | 159 ++++++++++++++++++
 Services/Website/.env.local                   |  10 +-
 Services/Website/Makefile                     |   6 +-
 Services/Website/README.md                    |  12 +-
 .../Public/Extensions/String+Constants.swift  |   6 +-
 Services/Website/docker-compose.override.yml  |   8 +-
 Services/Website/docker-compose.yml           |   8 +-
 .../project.pbxproj                           |  12 +-
 .../contents.xcworkspacedata                  |   0
 12 files changed, 296 insertions(+), 38 deletions(-)
 create mode 100644 Makefile
 create mode 100644 README.md
 create mode 100755 Scripts/bootstrap
 rename {Loud.xcodeproj => Site.xcodeproj}/project.pbxproj (95%)
 rename {Loud.xcodeproj => Site.xcodeproj}/project.xcworkspace/contents.xcworkspacedata (100%)

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..4f0b966
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,13 @@
+# Template root Makefile — bootstrap convenience only.
+# This file is removed by `Tools/bootstrap` once the template is generated.
+
+.DEFAULT_GOAL := help
+
+.PHONY: bootstrap
+bootstrap: ## Generate a concrete website from this template (interactive)
+	@./Scripts/bootstrap
+
+.PHONY: help
+help: ## Show available commands
+	@grep -hE '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
index 0ef5fb1..da8bef7 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
@@ -36,9 +36,9 @@ struct ServiceTests {
                 .init(
                     host: "127.0.0.1",
                     port: 3306,
-                    name: "loud",
-                    username: "loud",
-                    password: "loud",
+                    name: "site",
+                    username: "site",
+                    password: "site",
                     tls: .off,
                     maxConnectionsPerEventLoop: 1
                 )
@@ -126,7 +126,7 @@ private extension ServiceTests {
             try await fluent.migrate()
 
             let repository = ExampleRepository(fluent: fluent)
-            let created = try await repository.create(name: "loud")
+            let created = try await repository.create(name: "site")
 
             #expect(try await repository.all().contains(created))
 
@@ -158,9 +158,9 @@ private let mysqlDriver: Persistence.Driver? = {
         .init(
             host: host,
             port: environment["MYSQL_TEST_PORT"].flatMap(Int.init) ?? 3306,
-            name: environment["MYSQL_TEST_NAME"] ?? "loud",
-            username: environment["MYSQL_TEST_USERNAME"] ?? "loud",
-            password: environment["MYSQL_TEST_PASSWORD"] ?? "loud",
+            name: environment["MYSQL_TEST_NAME"] ?? "site",
+            username: environment["MYSQL_TEST_USERNAME"] ?? "site",
+            password: environment["MYSQL_TEST_PASSWORD"] ?? "site",
             tls: .off,
             maxConnectionsPerEventLoop: 2
         )
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..63eb852
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+# Website Template
+
+This repository is a **template** for the platform's websites. It ships as a
+complete, buildable reference site whose identity is the neutral placeholder
+**`Site`** / **`site`**. You generate a real site from it in two steps:
+generate a fresh repository, then run the bootstrap script to stamp in your
+site's name and slug.
+
+## What's in here
+
+| Path | Role |
+| --- | --- |
+| `Services/Website` | The Hummingbird website service (the engine + placeholder content). |
+| `Packages/Localization`, `Packages/Persistence` | Reusable packages, **vendored** into every site — each generated repo owns its own copy. |
+| `Site.xcodeproj` | The umbrella Xcode project (renamed to your site by bootstrap). |
+| `Scripts/bootstrap` | The generator. Rewrites placeholders, then deletes itself. |
+
+The engine is intentionally copied into each site rather than shared as a
+remote dependency: a generated site is fully self-contained and can diverge
+freely. Engine fixes are propagated to existing sites by hand (or by
+re-generating and porting content).
+
+## Generating a new site
+
+### 1. Create a repository from this template
+
+On Gitea, mark this repository as a template once (repository **Settings →
+Template → “Template” checkbox**). New sites are then created with the
+**“Use this template”** button, which produces a fresh repository with its own
+history — no template commits carried over.
+
+> No Gitea button? Just clone this repo, `rm -rf .git`, and continue — the
+> bootstrap script offers to re-initialise git for you.
+
+### 2. Bootstrap
+
+Clone the new repository, then from its root run:
+
+```sh
+make bootstrap        # or: ./Scripts/bootstrap
+```
+
+You'll be asked for:
+
+| Prompt | Example | Rewrites |
+| --- | --- | --- |
+| **Site display name** (PascalCase) | `Loud` | Server name (`LoudWebsite`), `Loud.xcodeproj`, README title. |
+| **Project slug** (lowercase) | `loud-ams` | Container owner, database name/user, Compose project name. |
+
+The script rewrites the placeholder occurrences in place, renames
+`Site.xcodeproj`, optionally starts a fresh git history, and then removes
+itself along with this file and the root `Makefile`.
+
+### 3. Fill in the content
+
+Bootstrap leaves reminders, but in short:
+
+1. **Copy & localization** — `Services/Website/Sources/Library/Catalogs/Localizable.xcstrings`
+   and the landing / 404 pages under `Services/Website/Sources/Library`.
+2. **Static assets** — `Services/Website/Resources/Static` (CSS, JS, favicon, icons, manifest).
+3. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
+   `Services/Website/.env` (the committed `.env.local` is an example only).
+4. **Domain models** — the `Persistence` package ships a sample
+   `ExampleRecord` / `ExampleRepository`; replace it when you add real data.
+
+### 4. Build & run
+
+```sh
+cd Services/Website
+make site-run          # watch + rebuild
+# or
+make site-mount        # docker compose up --build
+```
+
+## What bootstrap does NOT change
+
+- Organisation (`Röck+Cöde VoF`) and Xcode `DEVELOPMENT_TEAM` — shared across all sites.
+- The package architecture, middleware, security headers, and persistence layer.
+- The generic `website` image name and `Makefile` command names (`site-run`, `site-mount`, …).
+
+## Maintaining the template itself
+
+Edit and test the reference site directly — it builds and its tests pass with
+the `Site` / `site` placeholders in place. Keep the placeholders intact so the
+bootstrap script's targeted replacements keep matching; if you introduce a new
+site-specific value, add a matching rewrite line in `Scripts/bootstrap`.
diff --git a/Scripts/bootstrap b/Scripts/bootstrap
new file mode 100755
index 0000000..10aba68
--- /dev/null
+++ b/Scripts/bootstrap
@@ -0,0 +1,159 @@
+#!/usr/bin/env sh
+#
+# bootstrap — turn this template into a concrete website.
+#
+# The template ships as a fully buildable reference site whose identity is the
+# neutral placeholder "Site" / "site". This script rewrites those placeholders,
+# in place, to the values you provide — then removes itself.
+#
+# Run once, from the repository root:
+#
+#   ./Tools/bootstrap
+#
+# It is idempotent only in the sense that it self-destructs: once run, the
+# placeholders are gone and the script (and its scaffolding) are deleted.
+
+set -eu
+
+# --- Preconditions ------------------------------------------------------------
+
+if [ ! -d "Services/Website" ]; then
+	echo "error: run this from the repository root (Services/Website not found)." >&2
+	exit 1
+fi
+
+XCODEPROJ="./Site.xcodeproj"
+
+# --- Prompts ------------------------------------------------------------------
+
+printf 'Site display name (PascalCase, e.g. Berlin) [Site]: '
+read -r NAME
+NAME="${NAME:-Site}"
+
+DEFAULT_SLUG="$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]')"
+printf 'Project slug (lowercase, used for owner/db/compose, e.g. loud-berlin) [%s]: ' "$DEFAULT_SLUG"
+read -r SLUG
+SLUG="${SLUG:-$DEFAULT_SLUG}"
+
+echo
+echo "  display name : $NAME       (server name \"${NAME}Website\", ${NAME}.xcodeproj)"
+echo "  slug         : $SLUG       (container owner, database name/user, compose project)"
+echo
+printf 'Apply these values? [y/N]: '
+read -r CONFIRM
+case "$CONFIRM" in
+	y | Y | yes | YES) ;;
+	*)
+		echo "Aborted. Nothing was changed."
+		exit 1
+		;;
+esac
+
+# --- Helpers ------------------------------------------------------------------
+
+# Portable in-place sed (works on both BSD/macOS and GNU/Linux).
+rewrite() {
+	file="$1"
+	shift
+	[ -f "$file" ] || return 0
+	tmp="${file}.bootstrap.tmp"
+	sed "$@" "$file" >"$tmp" && mv "$tmp" "$file"
+}
+
+W="Services/Website"
+
+# --- Rewrites -----------------------------------------------------------------
+
+# Swift constants: server name + database name/username.
+rewrite "$W/Sources/Library/Public/Extensions/String+Constants.swift" \
+	-e "s/SiteWebsite/${NAME}Website/g" \
+	-e "s/= \"site\"/= \"${SLUG}\"/g"
+
+# Local env example.
+rewrite "$W/.env.local" \
+	-e "s/SiteWebsite/${NAME}Website/g" \
+	-e "s/^HOST_OWNER=site\$/HOST_OWNER=${SLUG}/" \
+	-e "s/^DATABASE_NAME=site\$/DATABASE_NAME=${SLUG}/" \
+	-e "s/^DATABASE_USERNAME=site\$/DATABASE_USERNAME=${SLUG}/" \
+	-e "s/^DATABASE_PASSWORD=site\$/DATABASE_PASSWORD=${SLUG}/"
+
+# Production compose.
+rewrite "$W/docker-compose.yml" \
+	-e "s/SiteWebsite/${NAME}Website/g" \
+	-e "s/^name: site-platform\$/name: ${SLUG}-platform/" \
+	-e "s/DATABASE_NAME:-site}/DATABASE_NAME:-${SLUG}}/" \
+	-e "s/DATABASE_USERNAME:-site}/DATABASE_USERNAME:-${SLUG}}/"
+
+# Local override compose.
+rewrite "$W/docker-compose.override.yml" \
+	-e "s/HOST_OWNER:-site}/HOST_OWNER:-${SLUG}}/" \
+	-e "s/DATABASE_NAME:-site}/DATABASE_NAME:-${SLUG}}/" \
+	-e "s/DATABASE_USERNAME:-site}/DATABASE_USERNAME:-${SLUG}}/" \
+	-e "s/DATABASE_PASSWORD:-site}/DATABASE_PASSWORD:-${SLUG}}/"
+
+# Makefile db-shell fallbacks.
+rewrite "$W/Makefile" \
+	-e "s/),site)/),${SLUG})/g"
+
+# Service README.
+rewrite "$W/README.md" \
+	-e "s/^# Site Website\$/# ${NAME} Website/" \
+	-e "s/\*\*Site\*\*/**${NAME}**/" \
+	-e "s/SiteWebsite/${NAME}Website/g" \
+	-e "s/\`site\`/\`${SLUG}\`/g"
+
+# Xcode project: PBXProject name + directory.
+if [ -d "$XCODEPROJ" ]; then
+	rewrite "$XCODEPROJ/project.pbxproj" -e "s/\"Site\"/\"${NAME}\"/g"
+	if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+		git mv "$XCODEPROJ" "./${NAME}.xcodeproj" 2>/dev/null || mv "$XCODEPROJ" "./${NAME}.xcodeproj"
+	else
+		mv "$XCODEPROJ" "./${NAME}.xcodeproj"
+	fi
+fi
+
+# --- Optional: fresh git history ---------------------------------------------
+
+echo
+printf 'Start a fresh git history (drops the template history)? [y/N]: '
+read -r FRESH
+case "$FRESH" in
+	y | Y | yes | YES)
+		if command -v git >/dev/null 2>&1; then
+			rm -rf .git
+			git init -q
+			echo "Reinitialised git. Remember to add your remote and commit."
+		fi
+		;;
+	*) ;;
+esac
+
+# --- Self-cleanup -------------------------------------------------------------
+
+rm -f Scripts/bootstrap
+rmdir Scripts 2>/dev/null || true
+rm -f Makefile          # root convenience Makefile (bootstrap only)
+rm -f README.md       # template usage docs
+rm -rf .gitea           # Gitea template metadata
+
+# --- Done ---------------------------------------------------------------------
+
+cat <<EOF
+
+Done. "${NAME}" (slug "${SLUG}") is ready.
+
+Next steps:
+  1. Replace the placeholder content:
+       - $W/Sources/Library/Catalogs/Localizable.xcstrings   (copy)
+       - $W/Sources/Library                                   (landing / 404 pages)
+       - $W/Resources/Static                                  (css, js, favicon, icons)
+  2. Set a real database password in a git-ignored $W/.env
+     (the committed .env.local defaults the password to the slug — do NOT ship that).
+  3. Point the git remote at your new repository:
+       git remote set-url origin <new-repo-url>     # or 'git remote add origin ...'
+  4. Build and run:
+       cd $W && make site-run
+
+The Persistence package still ships an ExampleRecord / ExampleRepository sample
+model — replace it with your real domain models when you add persistence.
+EOF
diff --git a/Services/Website/.env.local b/Services/Website/.env.local
index 1987239..860ce02 100644
--- a/Services/Website/.env.local
+++ b/Services/Website/.env.local
@@ -12,7 +12,7 @@
 HOST_CONTAINER=containers.rock-n-code.com
 
 # Owner of the container running the Website service.
-HOST_OWNER=loud
+HOST_OWNER=site
 
 # Password for authenticating to the container registry.
 HOST_PASSWORD=
@@ -36,7 +36,7 @@ IMAGE_TAG=latest
 # --- Application config -------------------------------------------------------
 
 # Server name reported by the HTTP service.
-HTTP_SERVER_NAME=LoudWebsite
+HTTP_SERVER_NAME=SiteWebsite
 
 # Log verbosity: trace | debug | info | notice | warning | error | critical
 LOG_LEVEL=info
@@ -55,13 +55,13 @@ DATABASE_HOST=localhost
 DATABASE_PORT=3306
 
 # Name of the database to connect to.
-DATABASE_NAME=loud-ams
+DATABASE_NAME=site
 
 # Username of the database to connect as.
-DATABASE_USERNAME=loud-ams
+DATABASE_USERNAME=site
 
 # Provide the real password via the environment or a secret — never commit it.
-DATABASE_PASSWORD=loud-ams
+DATABASE_PASSWORD=site
 
 # TLS posture when connecting: off | prefer | require (use `require` in production).
 DATABASE_TLS=off
diff --git a/Services/Website/Makefile b/Services/Website/Makefile
index 47d91c8..49351b1 100644
--- a/Services/Website/Makefile
+++ b/Services/Website/Makefile
@@ -90,9 +90,9 @@ db-shell: ## Open a SQL shell on the local database instance
 		--profile database \
 		exec mariadb \
 		mariadb \
-			--user=$(or $(DATABASE_USERNAME),loud) \
-			--password=$(or $(DATABASE_PASSWORD),loud) \
-			$(or $(DATABASE_NAME),loud)
+			--user=$(or $(DATABASE_USERNAME),site) \
+			--password=$(or $(DATABASE_PASSWORD),site) \
+			$(or $(DATABASE_NAME),site)
 
 .PHONY: db-unmount
 db-unmount: ## Stop and remove the local database instance (keeps the data volume)
diff --git a/Services/Website/README.md b/Services/Website/README.md
index c705916..2c67df3 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -1,5 +1,5 @@
-# Loud Website
-The **Loud** public website service — a [Hummingbird](https://github.com/hummingbird-project/hummingbird) server that renders a static landing page and serves the site's static assets.
+# Site Website
+The **Site** public website service — a [Hummingbird](https://github.com/hummingbird-project/hummingbird) server that renders a static landing page and serves the site's static assets.
 
 ## Overview
 The service:
@@ -73,7 +73,7 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 | --- | --- | --- | --- |
 | `http.host` | `HTTP_HOST` | _none_ | Host the server binds to. Supplied via the `--http-host` CLI flag (the Docker image passes `0.0.0.0`). |
 | `http.port` | `HTTP_PORT` | _none_ | Port the server listens on. Supplied via the `--http-port` CLI flag (the Docker image passes `8080`). |
-| `http.serverName` | `HTTP_SERVER_NAME` | `LoudWebsite` | Server name and logger label. |
+| `http.serverName` | `HTTP_SERVER_NAME` | `SiteWebsite` | Server name and logger label. |
 
 ### Logging
 | Config key | Environment variable | Default | Description |
@@ -87,8 +87,8 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 | `database.migrate` | `DATABASE_MIGRATE` (flag `--database-migrate`) | `false` | When set, run the migrations and exit instead of serving. |
 | `database.host` | `DATABASE_HOST` | `localhost` | MySQL/MariaDB host. Ignored for `inMemory`. |
 | `database.port` | `DATABASE_PORT` | `3306` | MySQL/MariaDB port. Ignored for `inMemory`. |
-| `database.name` | `DATABASE_NAME` | `loud` | Database name. Ignored for `inMemory`. |
-| `database.username` | `DATABASE_USERNAME` | `loud` | Database username. Ignored for `inMemory`. |
+| `database.name` | `DATABASE_NAME` | `site` | Database name. Ignored for `inMemory`. |
+| `database.username` | `DATABASE_USERNAME` | `site` | Database username. Ignored for `inMemory`. |
 | `database.password` | `DATABASE_PASSWORD` | _(empty)_ | Database password. Provide via the environment/a secret — never commit it. |
 | `database.tls` | `DATABASE_TLS` | `prefer` | TLS posture when connecting: `off`, `prefer`, or `require`. Ignored for `inMemory`. |
 | `database.pool.maxPerEventLoop` | `DATABASE_POOL_MAX_PER_EVENT_LOOP` | `4` | Maximum pooled connections per event loop. Ignored for `inMemory`. |
@@ -203,7 +203,7 @@ The Makefile and Compose files read these from a `.env` file (or the environment
 | `IMAGE_PLATFORM` | Build platform (e.g. `linux/amd64`). |
 | `HOST_PORT` | Host port mapped to the container's `8080` (default `8080`). |
 | `LOG_LEVEL` | Runtime log level (default `info`). |
-| `HTTP_SERVER_NAME` | Runtime server name (default `LoudWebsite`). |
+| `HTTP_SERVER_NAME` | Runtime server name (default `SiteWebsite`). |
 | `SECURITY_STRICT_TRANSPORT_SECURITY` | HSTS header value (default `max-age=31536000; includeSubDomains`). |
 | `DATABASE_DRIVER` | `inMemory` (default) or `mysql`. Set to `mysql` in production to use a managed database. |
 | `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` | MySQL/MariaDB connection (when `DATABASE_DRIVER=mysql`). Provide the password via a secret. |
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 23fa620..eedb8f0 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -8,9 +8,9 @@ extension String {
         /// The default MySQL/MariaDB host.
         public static let host = "localhost"
         /// The default database name.
-        public static let name = "loud"
+        public static let name = "site"
         /// The default database username.
-        public static let username = "loud"
+        public static let username = "site"
         /// The default TLS posture token.
         public static let tls = "prefer"
         /// The TLS token disabling TLS.
@@ -47,6 +47,6 @@ extension String {
     /// A namespace for the server string constants.
     public enum Server {
         /// The website server's name.
-        public static let name = "LoudWebsite"
+        public static let name = "SiteWebsite"
     }
 }
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
index c297e23..e83e081 100644
--- a/Services/Website/docker-compose.override.yml
+++ b/Services/Website/docker-compose.override.yml
@@ -26,7 +26,7 @@ services:
   #   docker compose --profile database up mariadb
   mariadb:
     image: mariadb:11
-    container_name: ${HOST_OWNER:-loud}-db
+    container_name: ${HOST_OWNER:-site}-db
     restart: unless-stopped
     profiles:
       - database
@@ -34,9 +34,9 @@ services:
       - "127.0.0.1:${DATABASE_PORT:-3306}:3306"
     environment:
       MARIADB_RANDOM_ROOT_PASSWORD: "yes"
-      MARIADB_DATABASE: ${DATABASE_NAME:-loud-ams}
-      MARIADB_USER: ${DATABASE_USERNAME:-loud-ams}
-      MARIADB_PASSWORD: ${DATABASE_PASSWORD:-loud-ams}
+      MARIADB_DATABASE: ${DATABASE_NAME:-site}
+      MARIADB_USER: ${DATABASE_USERNAME:-site}
+      MARIADB_PASSWORD: ${DATABASE_PASSWORD:-site}
       MARIADB_AUTO_UPGRADE: "1"
     command:
       - "--character-set-server=utf8mb4"
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index 81c40d5..957c544 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -1,4 +1,4 @@
-name: loud-platform
+name: site-platform
 
 # Production base configuration.
 # Deploys a pre-built image pulled from a registry — no build step.
@@ -19,7 +19,7 @@ services:
       - "${HOST_PORT:-8080}:8080"
     environment:
       LOG_LEVEL: ${LOG_LEVEL:-info}
-      HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-LoudWebsite}
+      HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-SiteWebsite}
       SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
       # Persistence: in-memory by default; set DATABASE_DRIVER=mysql to run against a
       # managed MySQL/MariaDB database. Provide the password via the environment or a
@@ -27,7 +27,7 @@ services:
       DATABASE_DRIVER: ${DATABASE_DRIVER:-mysql}
       DATABASE_HOST: ${DATABASE_HOST:-localhost}
       DATABASE_PORT: ${DATABASE_PORT:-3306}
-      DATABASE_NAME: ${DATABASE_NAME:-loud-ams}
-      DATABASE_USERNAME: ${DATABASE_USERNAME:-loud-ams}
+      DATABASE_NAME: ${DATABASE_NAME:-site}
+      DATABASE_USERNAME: ${DATABASE_USERNAME:-site}
       DATABASE_PASSWORD: ${DATABASE_PASSWORD:-}
       DATABASE_TLS: ${DATABASE_TLS:-require}
diff --git a/Loud.xcodeproj/project.pbxproj b/Site.xcodeproj/project.pbxproj
similarity index 95%
rename from Loud.xcodeproj/project.pbxproj
rename to Site.xcodeproj/project.pbxproj
index 9b48f17..9e1191a 100644
--- a/Loud.xcodeproj/project.pbxproj
+++ b/Site.xcodeproj/project.pbxproj
@@ -44,7 +44,7 @@
 				LastUpgradeCheck = 2700;
 				ORGANIZATIONNAME = "Röck+Cöde VoF";
 			};
-			buildConfigurationList = 02642FD42FEEB9A5007FA466 /* Build configuration list for PBXProject "Loud" */;
+			buildConfigurationList = 02642FD42FEEB9A5007FA466 /* Build configuration list for PBXProject "Site" */;
 			developmentRegion = en;
 			hasScannedForEncodings = 0;
 			knownRegions = (
@@ -62,14 +62,14 @@
 /* End PBXProject section */
 
 /* Begin XCBuildConfiguration section */
-		02642FD52FEEB9A5007FA466 /* Debug configuration for PBXProject "Loud" */ = {
+		02642FD52FEEB9A5007FA466 /* Debug configuration for PBXProject "Site" */ = {
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				DEVELOPMENT_TEAM = 7FMNM89WKG;
 			};
 			name = Debug;
 		};
-		02642FD62FEEB9A5007FA466 /* Release configuration for PBXProject "Loud" */ = {
+		02642FD62FEEB9A5007FA466 /* Release configuration for PBXProject "Site" */ = {
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				DEVELOPMENT_TEAM = 7FMNM89WKG;
@@ -79,11 +79,11 @@
 /* End XCBuildConfiguration section */
 
 /* Begin XCConfigurationList section */
-		02642FD42FEEB9A5007FA466 /* Build configuration list for PBXProject "Loud" */ = {
+		02642FD42FEEB9A5007FA466 /* Build configuration list for PBXProject "Site" */ = {
 			isa = XCConfigurationList;
 			buildConfigurations = (
-				02642FD52FEEB9A5007FA466 /* Debug configuration for PBXProject "Loud" */,
-				02642FD62FEEB9A5007FA466 /* Release configuration for PBXProject "Loud" */,
+				02642FD52FEEB9A5007FA466 /* Debug configuration for PBXProject "Site" */,
+				02642FD62FEEB9A5007FA466 /* Release configuration for PBXProject "Site" */,
 			);
 			defaultConfigurationName = Release;
 		};
diff --git a/Loud.xcodeproj/project.xcworkspace/contents.xcworkspacedata b/Site.xcodeproj/project.xcworkspace/contents.xcworkspacedata
similarity index 100%
rename from Loud.xcodeproj/project.xcworkspace/contents.xcworkspacedata
rename to Site.xcodeproj/project.xcworkspace/contents.xcworkspacedata
-- 
2.54.0


From a045a235196f9f7d0a1f4c78482cbeca9c5784b2 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 19 Jul 2026 00:47:49 +0000
Subject: [PATCH 019/117] Web support for the Website service (#17)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR contains the work done to introduce a new Web Swift package that provides a reusable, declarative way to register route controllers on a Hummingbird router, then adopt it in the Website service.

To provide further details about the work:

* Web package
  * The `RouterController` protocol — a Sendable protocol to group controllers behind one `routes` property.
  * The `RouteCollectionBuilder`  — a result builder that collects controllers' route collections into a stack, with full support for optionals, conditionals, and arrays.
  * The `addController(_:)` method — a `RouterMethods` extension letting controllers be listed declaratively and adding each one's routes at the router root.

* Website service
  * Added Web as a dependency of the _WebsiteLibrary_ target.
  * Conformed the `RootController` and `HealthController`controllers to the `RouterController` protocol.
  * Updated the `App+Build` extension to to use the cleaner `router.addController { … }` instead.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/17
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../xcode/xcshareddata/xcschemes/Web.xcscheme |  77 +++++++++
 Packages/Web/Package.swift                    |  47 ++++++
 .../Builders/RouteCollectionBuilder.swift     |  46 ++++++
 .../RouterMethods+RouteCollections.swift      |  34 ++++
 .../Public/Protocols/RouterController.swift   |  32 ++++
 .../RouterMethods+RouteCollectionsTests.swift | 155 ++++++++++++++++++
 .../Utils/Controllers/StubController.swift    |  30 ++++
 Services/Website/Package.swift                |   6 +
 Services/Website/README.md                    |  18 +-
 .../Sources/App/Extensions/App+Build.swift    |   8 +-
 .../Public/Controllers/HealthController.swift |  22 ++-
 .../Public/Controllers/RootController.swift   |  23 ++-
 .../RouterMethods+RouteCollections.swift      |  80 ---------
 Services/Website/Tests/Website.xctestplan     |   7 +
 14 files changed, 480 insertions(+), 105 deletions(-)
 create mode 100644 Packages/Web/.swiftpm/xcode/xcshareddata/xcschemes/Web.xcscheme
 create mode 100644 Packages/Web/Package.swift
 create mode 100644 Packages/Web/Sources/Public/Builders/RouteCollectionBuilder.swift
 create mode 100644 Packages/Web/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
 create mode 100644 Packages/Web/Sources/Public/Protocols/RouterController.swift
 create mode 100644 Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
 create mode 100644 Packages/Web/Tests/Utils/Controllers/StubController.swift
 delete mode 100644 Services/Website/Sources/Library/Public/Extensions/RouterMethods+RouteCollections.swift

diff --git a/Packages/Web/.swiftpm/xcode/xcshareddata/xcschemes/Web.xcscheme b/Packages/Web/.swiftpm/xcode/xcshareddata/xcschemes/Web.xcscheme
new file mode 100644
index 0000000..5212084
--- /dev/null
+++ b/Packages/Web/.swiftpm/xcode/xcshareddata/xcschemes/Web.xcscheme
@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "2700"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES"
+      buildArchitectures = "Automatic">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "Web"
+               BuildableName = "Web"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      shouldAutocreateTestPlan = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "WebTests"
+               BuildableName = "WebTests"
+               ReferencedContainer = "container:">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES"
+      queueDebuggingEnabled = "No">
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <MacroExpansion>
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "Web"
+            BuildableName = "Web"
+            ReferencedContainer = "container:">
+         </BuildableReference>
+      </MacroExpansion>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>
diff --git a/Packages/Web/Package.swift b/Packages/Web/Package.swift
new file mode 100644
index 0000000..c0c94e8
--- /dev/null
+++ b/Packages/Web/Package.swift
@@ -0,0 +1,47 @@
+// swift-tools-version: 6.3
+
+import PackageDescription
+
+let package = Package(
+    name: "Web",
+    platforms: [
+        .macOS(.v15),
+    ],
+    products: [
+        .library(
+            name: "Web",
+            targets: [
+                "Web"
+            ]
+        ),
+    ],
+    dependencies: [
+        .package(
+            url: "https://github.com/hummingbird-project/hummingbird.git",
+            from: "2.25.0"
+        ),
+    ],
+    targets: [
+        .target(
+            name: "Web",
+            dependencies: [
+                .product(
+                    name: "Hummingbird",
+                    package: "hummingbird"
+                ),
+            ],
+            path: "Sources"
+        ),
+        .testTarget(
+            name: "WebTests",
+            dependencies: [
+                .byName(name: "Web"),
+                .product(
+                    name: "HummingbirdTesting",
+                    package: "hummingbird"
+                ),
+            ],
+            path: "Tests"
+        ),
+    ]
+)
diff --git a/Packages/Web/Sources/Public/Builders/RouteCollectionBuilder.swift b/Packages/Web/Sources/Public/Builders/RouteCollectionBuilder.swift
new file mode 100644
index 0000000..548bc46
--- /dev/null
+++ b/Packages/Web/Sources/Public/Builders/RouteCollectionBuilder.swift
@@ -0,0 +1,46 @@
+import Hummingbird
+
+/// A result builder that collects the route collections of ``RouterController`` values into a stack.
+///
+/// Mirrors the `MiddlewareFixedTypeBuilder` Hummingbird uses for `addMiddleware`, letting
+/// controllers be listed declaratively rather than having their routes added one statement at a time.
+@resultBuilder
+public enum RouteCollectionBuilder<Context: RequestContext> {
+
+    public static func buildExpression(
+        _ controller: some RouterController<Context>
+    ) -> [RouteCollection<Context>] {
+        [controller.routes]
+    }
+
+    public static func buildBlock(
+        _ collections: [RouteCollection<Context>]...
+    ) -> [RouteCollection<Context>] {
+        collections.flatMap { $0 }
+    }
+
+    public static func buildOptional(
+        _ collections: [RouteCollection<Context>]?
+    ) -> [RouteCollection<Context>] {
+        collections ?? []
+    }
+
+    public static func buildEither(
+        first collections: [RouteCollection<Context>]
+    ) -> [RouteCollection<Context>] {
+        collections
+    }
+
+    public static func buildEither(
+        second collections: [RouteCollection<Context>]
+    ) -> [RouteCollection<Context>] {
+        collections
+    }
+
+    public static func buildArray(
+        _ collections: [[RouteCollection<Context>]]
+    ) -> [RouteCollection<Context>] {
+        collections.flatMap { $0 }
+    }
+
+}
diff --git a/Packages/Web/Sources/Public/Extensions/RouterMethods+RouteCollections.swift b/Packages/Web/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
new file mode 100644
index 0000000..d753351
--- /dev/null
+++ b/Packages/Web/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
@@ -0,0 +1,34 @@
+import Hummingbird
+
+public extension RouterMethods {
+
+    // MARK: Methods
+    
+    /// Adds the routes of ``RouterController`` values to the router using the
+    /// ``RouteCollectionBuilder`` result builder.
+    ///
+    /// Mirrors `addMiddleware`, letting controllers be listed declaratively:
+    ///
+    /// ```swift
+    /// router.addController {
+    ///     RootController<AppRequestContext>()
+    ///     HealthController<AppRequestContext>()
+    /// }
+    /// ```
+    ///
+    /// Each controller's route collection is added at the router's root, exactly as a
+    /// sequence of `addRoutes(_:)` calls would.
+    /// - Parameter build: the controller stack result builder.
+    /// - Returns: the router, so calls can be chained.
+    @discardableResult
+    func addController(
+        @RouteCollectionBuilder<Context> _ build: () -> [RouteCollection<Context>]
+    ) -> Self {
+        for collection in build() {
+            addRoutes(collection)
+        }
+
+        return self
+    }
+
+}
diff --git a/Packages/Web/Sources/Public/Protocols/RouterController.swift b/Packages/Web/Sources/Public/Protocols/RouterController.swift
new file mode 100644
index 0000000..819ec82
--- /dev/null
+++ b/Packages/Web/Sources/Public/Protocols/RouterController.swift
@@ -0,0 +1,32 @@
+import Hummingbird
+
+/// A type exposing its endpoints as a route collection ready to be added to a router.
+///
+/// Conforming controllers group related endpoints behind a single ``routes`` property,
+/// so the application composes them declaratively with ``Hummingbird/RouterMethods/addController(_:)``:
+///
+/// ```swift
+/// struct HealthController<Context: RequestContext>: RouterController {
+///     var routes: RouteCollection<Context> {
+///         RouteCollection(context: Context.self)
+///             .get("health") { _, _ in HTTPResponse.Status.ok }
+///     }
+/// }
+///
+/// router.addController {
+///     HealthController<AppRequestContext>()
+/// }
+/// ```
+public protocol RouterController<Context>: Sendable {
+    
+    // MARK: Associated types
+    
+    /// The request context the controller's routes operate on.
+    associatedtype Context: RequestContext
+    
+    // MARK: Properties
+    
+    /// The collection of routes the controller exposes.
+    var routes: RouteCollection<Context> { get }
+    
+}
diff --git a/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift b/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
new file mode 100644
index 0000000..1808834
--- /dev/null
+++ b/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
@@ -0,0 +1,155 @@
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import Web
+
+@Suite("addController method")
+struct RouterMethodsTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `adds the routes of every listed controller`() async throws {
+        let router = Router()
+
+        router.addController {
+            StubController(path: "first")
+            StubController(path: "second")
+        }
+
+        try await Application(router: router).test(.router) { client in
+            try await client.execute(
+                uri: "/first",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(String(buffer: response.body) == "first")
+            }
+
+            try await client.execute(
+                uri: "/second",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(String(buffer: response.body) == "second")
+            }
+        }
+    }
+
+    @Test(arguments: [true, false])
+    func `adds a controller behind a condition only when the condition holds`(
+        condition: Bool
+    ) async throws {
+        let router = Router()
+
+        router.addController {
+            StubController(path: "always")
+
+            if condition {
+                StubController(path: "conditional")
+            }
+        }
+
+        try await Application(router: router).test(.router) { client in
+            try await client.execute(
+                uri: "/always",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+            }
+
+            try await client.execute(
+                uri: "/conditional",
+                method: .get
+            ) { response in
+                #expect(response.status == (condition ? .ok : .notFound))
+            }
+        }
+    }
+
+    @Test(arguments: [true, false])
+    func `adds only the taken branch of a condition`(
+        takesFirst: Bool
+    ) async throws {
+        let router = Router()
+
+        router.addController {
+            if takesFirst {
+                StubController(path: "first")
+            } else {
+                StubController(path: "second")
+            }
+        }
+
+        try await Application(router: router).test(.router) { client in
+            try await client.execute(
+                uri: "/first",
+                method: .get
+            ) { response in
+                #expect(response.status == (takesFirst ? .ok : .notFound))
+            }
+
+            try await client.execute(
+                uri: "/second",
+                method: .get
+            ) { response in
+                #expect(response.status == (takesFirst ? .notFound : .ok))
+            }
+        }
+    }
+
+    @Test
+    func `adds a controller for every iteration of a loop`() async throws {
+        let paths = ["one", "two", "three"]
+        let router = Router()
+
+        router.addController {
+            for path in paths {
+                StubController(path: path)
+            }
+        }
+
+        try await Application(router: router).test(.router) { client in
+            for path in paths {
+                try await client.execute(
+                    uri: "/\(path)",
+                    method: .get
+                ) { response in
+                    #expect(response.status == .ok)
+                    #expect(String(buffer: response.body) == path)
+                }
+            }
+        }
+    }
+
+    @Test
+    func `returns the router so calls can be chained`() async throws {
+        let router = Router()
+
+        router
+            .addController {
+                StubController(path: "first")
+            }
+            .addController {
+                StubController(path: "second")
+            }
+
+        try await Application(router: router).test(.router) { client in
+            try await client.execute(
+                uri: "/first",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+            }
+
+            try await client.execute(
+                uri: "/second",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+            }
+        }
+    }
+
+}
diff --git a/Packages/Web/Tests/Utils/Controllers/StubController.swift b/Packages/Web/Tests/Utils/Controllers/StubController.swift
new file mode 100644
index 0000000..75b7586
--- /dev/null
+++ b/Packages/Web/Tests/Utils/Controllers/StubController.swift
@@ -0,0 +1,30 @@
+import Hummingbird
+import Web
+
+/// A controller serving its path back as plain text, used to observe route registration.
+struct StubController {
+
+    // MARK: Properties
+
+    /// The path the controller serves, also returned as the response body.
+    let path: String
+
+}
+
+// MARK: - RouterController
+
+extension StubController: RouterController {
+
+    // MARK: Properties
+
+    var routes: RouteCollection<BasicRequestContext> {
+        let routes = RouteCollection(context: BasicRequestContext.self)
+
+        routes.get(.init(path)) { _, _ in
+            self.path
+        }
+
+        return routes
+    }
+
+}
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index fdd8c5d..39c5aad 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -26,6 +26,9 @@ let package = Package(
         .package(
             path: "../../Packages/Persistence"
         ),
+        .package(
+            path: "../../Packages/Web"
+        ),
         .package(
             url: "https://github.com/elementary-swift/elementary.git",
             from: "0.6.0"
@@ -77,6 +80,7 @@ let package = Package(
             dependencies: [
                 .byName(name: "Localization"),
                 .byName(name: "Persistence"),
+                .byName(name: "Web"),
                 .product(
                     name: "Configuration",
                     package: "swift-configuration"
@@ -115,6 +119,8 @@ let package = Package(
         .testTarget(
             name: "WebsiteLibraryTests",
             dependencies: [
+                .byName(name: "Persistence"),
+                .byName(name: "Web"),
                 .byName(name: "WebsiteLibrary"),
                 .product(
                     name: "Elementary",
diff --git a/Services/Website/README.md b/Services/Website/README.md
index c705916..4293024 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -5,6 +5,7 @@ The **Loud** public website service — a [Hummingbird](https://github.com/hummi
 The service:
 - Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
 - Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
+- Registers newsletter subscriptions at `POST /subscribe`: the landing page's form-encoded submission is validated and normalized, guarded by a hidden honeypot field against bots, and stored tagged with the request's negotiated language.
 - Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
 - Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`.
 - Returns a custom HTML 404 page, localized like the landing page, for any request that matches neither a route nor a static file.
@@ -24,8 +25,9 @@ Two SwiftPM targets:
 | `Website` | executable | `Sources/App` | Entry point: reads configuration, builds the persistence service, and either serves the website or runs the migrate-and-exit mode. |
 | `WebsiteLibrary` | library | `Sources/Library` | Controllers, middlewares, pages, cached responses, and configuration helpers. |
 
-The `Website` executable depends on two local packages:
+The `Website` executable depends on three local packages:
 - `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteLibrary`).
+- `Web` (`Packages/Web`) — the `RouterController` protocol the controllers conform to and the `addController` result-builder extension that registers their routes on the router declaratively.
 - `Persistence` (`Packages/Persistence`) — the Fluent-based data layer: the `Driver` selector, the `Service` factory that builds the `Fluent` service, the `PrepareDB` registrar that declares the migrations, and the `Probe` consulted by the readiness check; the models, migrations, and repositories stay internal to the package. It has no dependency on `swift-configuration`; the executable maps the `database.*` keys onto the driver.
 
 The persistence backend runs as a `Fluent` service inside the application's ServiceLifecycle group, so it starts and stops alongside the HTTP server (which owns its connection-pool shutdown on graceful termination).
@@ -39,6 +41,7 @@ LogRequestsMiddleware
         → NotFoundMiddleware         (renders the localized 404 page on .notFound)
           → FileMiddleware           (serves Resources/Static)
 RootController                       (GET / → landing page)
+SubscriptionController               (POST /subscribe → newsletter subscription)
 HealthController                     (GET /health → liveness, GET /health/ready → readiness)
 ```
 
@@ -47,8 +50,13 @@ Configuration is read through [swift-configuration](https://github.com/apple/swi
 the following sources, **highest precedence first**:
 1. Command-line arguments (e.g. `--http-host 0.0.0.0`)
 2. Process environment variables
-3. A `.env` file in the working directory (optional)
-4. Built-in defaults
+3. A `.env.local` file in the working directory (optional)
+4. A `.env` file in the working directory (optional)
+5. Built-in defaults
+
+The two files play different roles:
+- **`.env`** (git-ignored) holds your deployment values — it is the file the Makefile and Compose read for the `${VAR}` placeholders, and typically selects the MySQL/MariaDB backend.
+- **`.env.local`** (tracked) holds the local development overrides — the in-memory database and `debug` logging. Because it sits *above* `.env`, a direct launch (`swift run` or a debugger) runs against the local values even when `.env` points at a deployment, the same way `docker-compose.override.yml` overrides the base Compose file. Compose itself never reads it, and the production image does not ship it — only the executable, its resources, and the static files are staged into the final stage.
 
 ### Environment variable naming
 A dotted config key maps to an environment variable by upper-casing, splitting camelCase, and replacing separators with `_`. For example `http.serverName` → `HTTP_SERVER_NAME`,
@@ -119,6 +127,8 @@ swift run Website # binds to Hummingbird's default 127.0.0.1:8080
 swift run Website --http-host 0.0.0.0 --http-port 9000 --log-level debug
 ```
 
+A direct run picks up the local development overrides from `.env.local` (in-memory database, `debug` logging) over whatever `.env` configures. To run against another backend, override per launch — e.g. `DATABASE_DRIVER=mysql swift run Website` — since process environment variables outrank both files.
+
 Or via the Makefile / Docker (uses `docker-compose.override.yml`, which builds from source and sets `LOG_LEVEL=debug`):
 ```sh
 make pkg-build        # swift build
@@ -164,7 +174,7 @@ make pkg-test
 # = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
 ```
 
-Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Website.xctestplan` covers two targets: `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests).
+Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Website.xctestplan` covers the service's two targets — `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests) — plus the local packages' suites: `WebTests`, `PersistenceTests`, and `LocalizationTests`.
 
 The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the MySQL integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
 ```sh
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index dad5ec7..2bb0d52 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -157,9 +157,11 @@ private func router(
         )
     }
 
-    router.addRoutes {
-        RootController<AppRequestContext>().routes
-        HealthController<AppRequestContext>(probe: probe).routes
+    router.addController {
+        RootController<AppRequestContext>()
+        HealthController<AppRequestContext>(
+            probe: probe
+        )
     }
 
     return router
diff --git a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
index ed37869..55f732e 100644
--- a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
@@ -1,13 +1,16 @@
 import Hummingbird
 import NIOCore
 import Persistence
+import Web
 
 /// Serves the website's health-check routes.
 ///
-/// The controller exposes its routes as a `RouteCollection` so they can be added to a router (or a sub-group) by the application that composes it:
+/// The controller exposes its routes through its `RouterController` conformance, so the application that composes it registers them declaratively:
 ///
 /// ```swift
-/// router.addRoutes(HealthController<AppRequestContext>(probe: probe).routes)
+/// router.addController {
+///     HealthController<AppRequestContext>(probe: probe)
+/// }
 /// ```
 ///
 /// It always serves a liveness check at `/health`; when a `Probe` is supplied it also serves a readiness check at `/health/ready` that reports
@@ -15,7 +18,7 @@ import Persistence
 /// readiness failure.
 ///
 /// - Note: `Context` is the request context the routes are resolved against, and must match the context of the router the routes are added to.
-public struct HealthController<Context: RequestContext>: Sendable {
+public struct HealthController<Context: RequestContext> {
 
     // MARK: Properties
 
@@ -33,13 +36,14 @@ public struct HealthController<Context: RequestContext>: Sendable {
         self.probe = probe
     }
 
-    // MARK: Computed
+}
+
+// MARK: - RouterController
+
+extension HealthController: RouterController {
+
+    // MARK: Properties
 
-    /// The routes served by the controller.
-    ///
-    /// Serves a `GET` request for the liveness path (`/health`) with a static JSON status payload, and —
-    /// when a `Probe` was supplied — a `GET` request for the readiness path (`/health/ready`)
-    /// that consults the probe.
     public var routes: RouteCollection<Context> {
         let routes = RouteCollection(context: Context.self)
 
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index d457c73..de32221 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -1,17 +1,20 @@
 import Hummingbird
+import Web
 
 /// Serves the website's root routes.
 ///
-/// The controller exposes its routes as a `RouteCollection` so they can be added to a router
-/// (or a sub-group) by the application that composes it:
+/// The controller exposes its routes through its `RouterController` conformance, so the
+/// application that composes it registers them declaratively:
 ///
 /// ```swift
-/// router.addRoutes(RootController<AppRequestContext>().routes)
+/// router.addController {
+///     RootController<AppRequestContext>()
+/// }
 /// ```
 ///
 /// - Note: `Context` is the request context the routes are resolved against, and must match the
 ///   context of the router the routes are added to.
-public struct RootController<Context: LocalizedRequestContext>: Sendable {
+public struct RootController<Context: LocalizedRequestContext> {
 
     // MARK: Properties
 
@@ -25,12 +28,14 @@ public struct RootController<Context: LocalizedRequestContext>: Sendable {
         self.responses = .init { IndexPage(locale: $0) }
     }
 
-    // MARK: Computed
+}
+
+// MARK: - RouteController
+
+extension RootController: RouterController {
+
+    // MARK: Properties
 
-    /// The routes served by the controller.
-    ///
-    /// Serves a `GET` request for the root path (`/`) by rendering the ``IndexPage`` in the
-    /// language negotiated for the request.
     public var routes: RouteCollection<Context> {
         let routes = RouteCollection(context: Context.self)
 
diff --git a/Services/Website/Sources/Library/Public/Extensions/RouterMethods+RouteCollections.swift b/Services/Website/Sources/Library/Public/Extensions/RouterMethods+RouteCollections.swift
deleted file mode 100644
index 038671d..0000000
--- a/Services/Website/Sources/Library/Public/Extensions/RouterMethods+RouteCollections.swift
+++ /dev/null
@@ -1,80 +0,0 @@
-import Hummingbird
-
-/// A result builder that collects ``RouteCollection`` values into a stack.
-///
-/// Mirrors the `MiddlewareFixedTypeBuilder` Hummingbird uses for `addMiddleware`, letting route
-/// collections be listed declaratively rather than added one statement at a time.
-@resultBuilder
-public enum RouteCollectionBuilder<Context: RequestContext> {
-
-    public static func buildExpression(
-        _ collection: RouteCollection<Context>
-    ) -> [RouteCollection<Context>] {
-        [collection]
-    }
-
-    public static func buildBlock(
-        _ collections: [RouteCollection<Context>]...
-    ) -> [RouteCollection<Context>] {
-        collections.flatMap { $0 }
-    }
-
-    public static func buildOptional(
-        _ collections: [RouteCollection<Context>]?
-    ) -> [RouteCollection<Context>] {
-        collections ?? []
-    }
-
-    public static func buildEither(
-        first collections: [RouteCollection<Context>]
-    ) -> [RouteCollection<Context>] {
-        collections
-    }
-
-    public static func buildEither(
-        second collections: [RouteCollection<Context>]
-    ) -> [RouteCollection<Context>] {
-        collections
-    }
-
-    public static func buildArray(
-        _ collections: [[RouteCollection<Context>]]
-    ) -> [RouteCollection<Context>] {
-        collections.flatMap { $0 }
-    }
-
-}
-
-// MARK: - Helpers
-
-public extension RouterMethods {
-
-    // MARK: Methods
-
-    /// Adds route collections to the router using the ``RouteCollectionBuilder`` result builder.
-    ///
-    /// Mirrors `addMiddleware`, letting controllers be listed declaratively:
-    ///
-    /// ```swift
-    /// router.addRoutes {
-    ///     RootController<AppRequestContext>().routes
-    ///     HealthController<AppRequestContext>().routes
-    /// }
-    /// ```
-    ///
-    /// Each collection is added at the router's root, exactly as a sequence of
-    /// `addRoutes(_:)` calls would.
-    /// - Parameter build: the route-collection stack result builder.
-    /// - Returns: the router, so calls can be chained.
-    @discardableResult
-    func addRoutes(
-        @RouteCollectionBuilder<Context> _ build: () -> [RouteCollection<Context>]
-    ) -> Self {
-        for collection in build() {
-            addRoutes(collection)
-        }
-
-        return self
-    }
-
-}
diff --git a/Services/Website/Tests/Website.xctestplan b/Services/Website/Tests/Website.xctestplan
index 7b0061e..0a36976 100644
--- a/Services/Website/Tests/Website.xctestplan
+++ b/Services/Website/Tests/Website.xctestplan
@@ -45,6 +45,13 @@
         "identifier" : "LocalizationTests",
         "name" : "LocalizationTests"
       }
+    },
+    {
+      "target" : {
+        "containerPath" : "container:..\/..\/Packages\/Web",
+        "identifier" : "WebTests",
+        "name" : "WebTests"
+      }
     }
   ],
   "version" : 1
-- 
2.54.0


From daf275b121463bc11dfe129bf1f16e615cfdb258 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 19 Jul 2026 02:08:59 +0000
Subject: [PATCH 020/117] Improved the static assets definitions in the Website
 service (#18)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR contains the work done to overhaul the static asset definitions for the Website service.

To provide further details about the work:

* Website library
  * Overhauled the `StateFile` enumeration to reduce the number of cases to one case per logical file name, each exposing a `fileExtensions` list.
  * Wired everything into the pages with a consistent ordering convention: stylesheets load shared-first so the page sheet wins the CSS cascade; scripts load page-first with shared.js last. The error page also gained the shared stylesheet and its scripts; the index page gained its page CSS/JS and the new touch icon link.
  * Used the `StaticFile` enumeration as a single source of truth for every _href_/_src_ in the `IndexPage` and the `ErrorPage` pages, eliminating hardcoded asset paths.

* Website service
  * Added new assets to the Resources folder:
    * `apple-touch-icon.png`
    * `css/index.css`
    * `js/index.js`
    * `js/error.js`
    * `sitemap.xml`
  * Renamed existing assets within the Resources folder:
    * `css/style.css` → `css/shared.css`
    * `js/app.js` → `js/shared.js`
  * Fixed the working-directory location for the scheme in the Xcode project.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/18
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../xcshareddata/xcschemes/Website.xcscheme   |   3 +-
 .../Resources/Static/apple-touch-icon.png     | Bin 0 -> 9066 bytes
 .../Static/{js/app.js => css/index.css}       |   0
 .../Static/css/{style.css => shared.css}      |   0
 Services/Website/Resources/Static/js/error.js |   0
 Services/Website/Resources/Static/js/index.js |   0
 .../Website/Resources/Static/js/shared.js     |   0
 Services/Website/Resources/Static/robots.txt  |   2 +
 Services/Website/Resources/Static/sitemap.xml |   6 +
 .../Internal/Enumerations/StaticFile.swift    | 189 ++++++++++--------
 .../Library/Internal/Pages/ErrorPage.swift    |  12 +-
 .../Library/Internal/Pages/IndexPage.swift    |  19 +-
 Services/Website/Tests/App/AppTests.swift     |  28 +--
 .../Enumerations/StaticFileTests.swift        | 181 +++++++++++------
 .../Cases/Internal/Pages/ErrorPageTests.swift |   3 +
 .../Cases/Internal/Pages/IndexPageTests.swift |   8 +-
 16 files changed, 279 insertions(+), 172 deletions(-)
 create mode 100644 Services/Website/Resources/Static/apple-touch-icon.png
 rename Services/Website/Resources/Static/{js/app.js => css/index.css} (100%)
 rename Services/Website/Resources/Static/css/{style.css => shared.css} (100%)
 create mode 100644 Services/Website/Resources/Static/js/error.js
 create mode 100644 Services/Website/Resources/Static/js/index.js
 create mode 100644 Services/Website/Resources/Static/js/shared.js
 create mode 100644 Services/Website/Resources/Static/sitemap.xml

diff --git a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
index fe904d8..5ce7121 100644
--- a/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
+++ b/Services/Website/.swiftpm/xcode/xcshareddata/xcschemes/Website.xcscheme
@@ -50,7 +50,8 @@
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
       launchStyle = "0"
-      useCustomWorkingDirectory = "NO"
+      useCustomWorkingDirectory = "YES"
+      customWorkingDirectory = "/Users/logan/Documents/Development/Platforms/Ro&#x308;ck+Co&#x308;de/Loud/Services/Website"
       ignoresPersistentStateOnLaunch = "NO"
       debugDocumentVersioning = "YES"
       debugServiceExtension = "internal"
diff --git a/Services/Website/Resources/Static/apple-touch-icon.png b/Services/Website/Resources/Static/apple-touch-icon.png
new file mode 100644
index 0000000000000000000000000000000000000000..56d1ff21c4d3c8caf95f98823bb10fa6679fab1d
GIT binary patch
literal 9066
zcmb_?ML--%uq|Y886-Hv5Hz?3cbEhV8U}Zl;2PZBCAeE)aCi6M?i$>JJG|V@|I4>|
zi_=wIeX6>9S5@6%it>_}Xe4NGaB!H?QV`{TvhF{iy!$uSRK}V76Y!48lHza`<DkQT
z6Nrhrw5gmN9K$~y1r9#M0uJFn%0H0&0~{P62ObXaPs0Ca%X#<zR_k&A|6l))s5<xa
z2OJ#btTaSS#SQ*6)1u6H(0K!9<GQil*jQO>Pp2%QTtJ{)0~(1oK}G?6K*2+hf_soa
z5MYnJZ-w_^)BkAK2477kX7_Fo371Gd<HJvD-eAfI4tk5G@K&j*3<|ULj!y4(*2YWN
zS?XZpO?!L$*~*K}Mcm0*D>U<Q!%;qyKcda$H0^Jiq+czae#TAyUAiQ^96S~X3`|q*
z0!V(Fc0(4lb0adB`Dc@p-XZ(jwPlb)k0@yOi6+Xm3lI|GSA_SsYbx>6`hQMH|MyNT
zAl_LoWja{V>{jDbr~8|TxF0$K(04PT=Q>Pt42@>SXh8&wBFO}!6$}Nz_f5rgIPrU3
zKcV;_0lq0+G|M`iifX)0-UF}(i}v5;+VLfqLr27=mQk=e19Be(noOlws}qT0hI||(
z&i10xT{-KO+4;FhL;JR8u9l+eN2gDf&qPUtu_!~XJd}8mzxQ58kT+9zUWcv@N0`|{
zslwFRvOYa~cM_uwypJo<;QaZE;Hq9(4DI!zDYS`g6T1rYVgj77FlbUisjH>7lowtw
z_>vo|{PPn=HZjHk?!{rVz95vDfT3TU3`|HuNr(vgiJct3y`L2?Bh^W<z_A@A5On{?
zn2ki_PaX;$5$ZD)Hz%Qd5v)+TKDKj+>5sT?fV0dHtM_Hgy+?ACgB-Q^b`Et`yAFDa
zDP0m0cF6r^Kyc`U*}!)7(!<cAak*v*frF$%6K^)_fU;_s8@BNf8b;tD;r4P$h8#)i
z*o`Ipg?+<`=xpF1?H<_2;jvmFl`SQral0LRQ~$Df=d#*D2^NrV8750_&u5JX1j?ie
zL19bm0Q&b=$q84<QKFl9TRY;uR7BW%O_UgbAPJuNy0D!4`@m4d7i3b{oWrngwIUaz
zAUi&aBx~Ad=j(3x4?W%&*EAY@Js<SJ3M}ExfurATYCMIsDpvPDGMR~o;e}gr!aKe7
zDLuU%1O(vdN{7LW(hNWiX}B?Rzx(S{>SYW(V5%@MnExsOmw|(Q7d@CI(U{oF?jGY}
z2TMx5e=6947#ONB8miKltf5uSfbTI($;8MXZ5-wspMOVuI+2eB6#YvT@lMq~uexaW
zZa8K1{2c1Q=ke3GVGCW-e>ibVpy5o&egfx-e|u9u>2c{ZA8B&&LT;HhI4w3iB~C1R
zQSY&<lwX<vHc-=Vi^LkO`Hu+qUa!r?7SZFe{>!|lw^9MsK=(iz)Wm4MK|_-nvu_*t
zZs-==>ui_U?MF=<p}*eL=r1J1UZ$6&9h<<e1pDczr4`NOHz(s{xLnL!T3j%D*oyVW
zN`(n5BnI$H)(&7u%3U1t5pzWa)YIffTa_2H)G{%0bM0RlVG1~Z$MYdFvCDxz_c<f4
zAdKz|Rt~Ex61X%nMtji7AX3KZTSlHHD<Sj_vqznLsJ7IW{(Wrp5!rKFz;ZB3+MbW5
zu*TsSc56jY0sYzI^A)@S6R@9%d*H9x^tFCogyMX+-g*dvQ5uhoj@0BY`_+Hq=i5O~
zp$dRY_lsoWRqqq_`i!JWq_>3YLq2R6?m(fox>8M{x`R#nI8{Q7Y`^Q4Y`~j~xQ*G%
zCV!37aB)zV5>;P!WZWzOCQula%2v^2wyp{AxkqV|^>h)t_YCQbJPMgYK(^eA(Mh71
zr!Qw_ER|_}*KO)RB*<2{!c*uUrowg^ho1U!*z4hh&<zjv?Kj)|JhVW`y~sC(6m#*b
z%5v^xK!%Z0f-^?RmI@`>a;@$&p1;e3Wi!tC^|c9a)JR1+uih^_%M#Fy*H0yckV2t%
zN^A<}#fzed-dFFjHa*JzVlwVKM&JJp>5Z#KO(%`+%2fg&??pL5)>Blz7uOfruBJm`
zue+Ms(rDFdT&h|E0VOjhc|Tbg5T*|r{!v-_vUMi47_2Gs**mqb`mJhI%Xb^Os}cp|
zS}=+Sy}EN|EF?TVXS*m8`^?!1g!k^|wx6qlU$y}p_{xxpJ)VUyr<zXe<efjyNjRop
z;7((4^h$IMrI)@oGV9jMoJK^5zTlTa?coaM_Z@~l@7tvXgm%mct2@KeV_alDt3{V6
z<7f9aN8no^ix&!0c2amBi7Az6_6M}f2p=~UarG+I@bQwY=}0s0%SQouC+U`?yO}=`
zAAvxz`4vA$WU5m(R_zj*%1qhaVvz?@rzPA54txQuQ<6o045x=5tp%j*GR#E<y`TgU
zNhkAZJC^E?o^cnb*_~s~wbtaTj&@F6xe`hQeP6Y6emKpL;3z8R`~>6Ox{{@Y;0kl%
zWoDQ*Hl&BNTrK0kBXiK;Vv}db_w_ZHJn;)LDjL(WhzPNUKltm`^4{OjHJs;jUQsoh
z664r)F%u*hvgf)=w|v)Uw5hQ*ON`ik9#@Uhm)3HmmthPO8g+BHo}K;|^Y{C<<~>}q
zzT&zF{6O3%7lqN0>R(K|j?LDy%B^xF<9Ems)g?<{xZ1UjtgDB7IG{BLRv76FKdNLh
zN1>RtO%L#NMlI5lMGp?tkP#qhh#3*7z;FI>UodXp{z(ZAxs*<DC!sbk&O6_O13ubV
z@gsHsF&-AjobuHAG@`qdAR#y%#6D((*VRoFOOK^66m6~d@oxc55XEAkhg}bysUwrt
z$(-^#^Ef7indp>d_Up~AHg<xkhDx}Vsx@ZA81cXrdB~p_-Je08xlXb6`lwO_og#@O
z0Lu20z9}H)_SIxS!0xb9WEZvlr<X5xiL>!E)ZpwSoNs?z8=YRIZ@1X0xZbWL^QOY+
zk%^o)YK7NxxfWi8U4E5IuI;~Fj-)UNAc!|Q8+mc?WGjpent4^)*wC2WMfzHp(b^WI
z$`<sEtTkl+nMWVT0SRqh$S<+!lX9YxsZVAZDOe@=p+AX>5B3WAG}b-zHa>UXokGzt
zz|hS7-UG``c?nbK+8mOYm62`695=7xWB6Q={jnsuT&!hsFN##T^x~&^dUVu>VLoX6
z$yXe1*DAg~P;G+bsP=3ksTQ(uYBgV~gj+7si}E(hBt1V70Cr(YwN)|6xtS1D!=Gu>
z*I}DUmb6fzV|6UU-S@Uzj9GJm&j|eFE2HBN2ts*Ecrh|GU2B|pEok`S_Q&{9?^mdn
zK=@tmQU+Pp`0!@$Lt8KU_+!rbWC0>ZCc~9aTW*Jk<i(cmNF0mw>K~1$>=h*B%1eoa
z?cXuKvs+lM@P!=5f*pmgoE<)yNB@nvvck?bv94v$ay$Eh*__qnWuf=7#dx&R=p3vw
zt4l?+T^YZ&0FK)S#5Ht_DWqWC4~n>}dq1F#?Z%Gj3aFteQtgFkZHqjY_xs?`1=o01
zyO~>pe>465b$M&b)v7lr89`)IUu#|5xcAV7mvwR5a&{50qn_qr>SbBKK)5F;6%~Is
zb~k4$SS-9a=SiYOnvnvOAKzLTJz7RVc&QE)!L4O5f!a&`T4q^VMv~lt7ezqXSR<?~
zGnc&r7-hP7G_EW}xClS07SX*v!H%q08H97Zh)vl9Tg{6G?K$`hf`dbeuLr;3c`NS5
zQ#NbF6nqWY%rQ#~LaElmW@R~6xk^@^_BOHSB|4X2#Pc<HUTe6&n^50yd&`>Qij@j6
zC48A$Oic#h=+X7?ErY+&$2mWY&MZGxJKB8$1HMclXFn;P;140fysSkd7g}=Rs7=BG
zw;vccYR*oM@v+~NOZi740(>CMT4~&vaaF;grO@Hdl|trDExS)Gr~pq#owkM|(;Y*G
zB8|{Blr-RJ9{Fawf4mmo#h`8I#!FVe)}R`%n4KXl#N6h0Pad#H#a9q+mY<rh_SV->
zeA(OD0{}Elx>@Jmtrm{m^34ddFk`?XxAr3g<qWhpGJ7BM-KdGE6e(;O|B2`mpSki=
zX|V>2PUXUhsafc;y@Omw#{^4xl$&jCR=c}t_WjEAPf-{OGe_39uDqji<Sr4bF_CN0
zdun)WCF2O9JH$#EuKs)C&kDKMUAc0P;rLFNE_P;w5TM#zRw`d28U4O4d2@5zPS|*)
zRcjkL-H?*jEN}VU8Y54{ju3gA?O*p%A{g?v!iKV*hb~#75(ggf{c)bL>iaqmNdy~1
zqEgLLd~|E2^1)4WK~kLBBtq8JxuG01d4|<#-LG0N;HZQf;YeIt>(C7!rI&tzzuvo?
z1tMuEa^q?Iu@&Ef?WHnX(v%sEWsez?Ue<cEwVv%*HaC|-Q<UY}>L_byqGC!?iu{X%
zK$-XuRL|{Hts@v~sG1u79?SGbTA5n$zPkOjuR#~HWxb3kq46w#sqtdN!}GykkVpVh
zUF-uwgUf{iIoG6e33QVSg4%NzAavoeQLC#?u#1-0hlahuCcImmqRk3H9r;d^K!0wd
z>WEBY=1efnvO5vs_~~&<J>6hU0#Rd~&{0|pKEQG9qm}FPi-=yOJm$r8&Es17b|H-}
z_+JjE@6N%?H?~}W{8F-$)7GxEtXYYV=4@oL60!J&XPgieWhM&rytg?Gcjc+?>=~rJ
zwz=xZV>dTCX?QztoLkUUJU_2eGDP$jBY^EKBD7Ms<It#<x77oAua^s`g6&Zzy?p~h
z4&@oDQwb|8t=^*~3A_m1APa+H(nWkDqcZMK_sc3f^R2~0ac@WcQ`onqM^)S1bf{ZC
z+gq2UEzJc-oyEe_JRw9Q2_G=8G;iqPGa_$qNlS+fMAVK1d3Ds}dEXFUEQhPkX%wei
z;I*1}=r{5Bs^+ydLbbITWNvOO7lsZPc}b{qCJqWhQ<Bx3>=#niL$<4U5KdQg67L^d
zj~YAj=O=+dmk*xZ)rXtc-z(#xHSe{w^-51{mYYQzMHXM}qkB92u<(FozcxC`F)6;^
z_1a3-`@MXXetxVy@@X&GO!Ewa2JRD#t<UZL+N<r~U77P-_g1I?pkcv*u5n2&25WYM
zXqbbgGjrPG1P(ePSf_fsyXxt^AJWk{k)CKFtU0=nJ=Qy!#2j@Mmqs+0>`8YPG7S<S
zx;IW#tc@V66IKx;`);8MJ!*gf=`7UnV*k8!!&AQ8<d`*JgB+BOF~(%RR{IouQ>RH^
zvHp4DfUlSLWX-o*OeAMVSLu0-86Q1fU!pcP*M=@@(?jT^_j%D{!UD89vRZxq^KhYP
z__U}_Kz5Co474_NdnA*ju<*l1bA5L}KrXvz)7e<-q>2#Rm)swjIQdo#S)^lW8$^Q{
z%FtH%JYzv0<cOxr2QPS4nycgsymLQdfE|>vFf(d;FPwm8KMdo`A)1}J=WL@9HhX2c
z^rgETgbSTGFNo#E%sCvHFdg=G_@lmVP!~3iQuulJ+7k<c%Ij-@S5F+kT*u$aE15Ob
z)v47rb%2Rs#96F?;_yS5#a^!e=h5pxpC3lU+S`8mQA|f=s1*AB#Y~v_jG1K{^2-AL
zLD|T91Gf?0F~yotQ^^(cDkAU^J!xySvNHUpY<--@KWoo45YBx0*lN48qwIA83vcG&
z?g=n#Y;M_2IIvN2+#xHy2oH<LEn&6ddRf1Q4ZHMGJk78ZA@Oa}Qf>dvP84~GrT&&9
z(0DA0l*I_a%25p1%TYKSo4ZC3CSJD6MfOyH-rmWqkS?G77$+GxOm!yPH+NFvv@F?q
zU0<4=?aY|gv|KpfJlt}<LI3vl8vPivfxppGe!zev6zfM<Vq4Lp&~nV0SD<QQR^L`@
zkrW{`skuyU_2#DX<TWFY)z|<0fORd4s=7KaYF9)jh6L6wIz*3@Loy>ctCVRG4<6r(
z6&PamQD0v({K0{3EPC4TjqUnJa0(oU>fqWScMiadN{P(7rV7)uNtyF%8Uw%XG&eWI
zNrqv*S0LRvSP9Ga4?DoJVh=Ql0NuIJU<cdp)~KR}2YFe_8y1v68QI?Y{y1?6fgvSl
zUspu$%I45uu9HH{@jE~u0p_O`GSKzE5;*QC54-1~-B}9gnJnyqitt;rS$lQGgj=H8
z&B2|8o%;(o`Syb$(f3^ZpEkLE+fRIU#-coG5%|vvl|{Sa%4Waq&F0YR@+4{F+`}V{
zlMHiHmN01sQWg|H*?cjaGo)y2{bs>@RM1u*9K5AHcl+GseKh{>$W_OZ#eK%3NgTVv
z^wqO*PE|$JigYL2k7{Z-i+(h>Lb!5cW5t65fSgthBdBu8pJZVsn+C=6rX{)Y{ky$P
z;q3i-XSLCN9@8P@<sW@&S~16)#wroN=(9AttVo8H8E{D*JX7-;5A&<9R}E``aS0a{
zGEm^HqpK|xtLg8364`apLUNN@nJ<P)6r(g5cJSD2X4C`5H*k2}F?_CNUfM*r$aDAR
zVOv1Ad1R*pMe@p8x#mgJ!hK_1bFfkdmdzxa{I|vS3;;Sk`_oJ{g%o2FFaT?q)}k=B
za?vI~-JoemoFns#4zo>Jjc$3bxqiglj4$tFghzMx@u%cT4@PsajZGj^{Bg>*5SMJc
zIQgD|z??f<E`&pv+jKVLk{#&2$byJWO<j3C$KE~A{$zYnEuHV-bTehat*V#-Wv|s^
zPCo5NpoN~kCS=)FazM%RWV^d5UHBPnzG6xuaF-c!Fo<x|Pm!TL2_zZ57Ht2(knhrY
z_?nQGe@n#gJq6d%ObF`J-AJ)({c15v)WT^wxWl<jqB?St|6{g2`K0(8Qje0)&>Wc2
z20_xu%gsnezCVO2tPn|3%F|LeST0|+U!~<6ED@9vVv<_jL@cXbo;q~m=OQn;h5|H~
z!!MT%h7_%)6G{92bhE>VGr)6gB#RKJ&W$l<&#!)rhRH&0c>Mn*`EKgM96|^Yi@j<;
z@3KFs{VIeS=%c}K*Ux4r1^qAZZam~kKWDI<&e$*b0aE?vB5*ao=_D4MzrTnUL=w$+
z@$^*InvmX9<6m5`c>dl9?MCR&e799)wO~{MKsE(TLxi{;doa9=!7WciBRwu7{G9?-
z<^{tNHF!?;#qs6cfbP6WzIO&aL1gkLZ3=5Thx~S3e2Qmu$C^SRAkk5BAZ0U0Nn;Du
ziiTS4n7ksQ{FPl~&$w#+pOaX>=@I|ij;lot9<l@5ebIumf!?|}+9QXWy9o8Vj%2mj
z&R5Rk<c{2RO*NsI^)EGwUk!y(&8E-Db_0YWKK;3s)5yJc>ngVlY3+hv`B0DE0o5s<
z65#%5XI<m@+Nd_m`dUAJDGed%9%E&?r~~uFzWfa&qO$)Lo5=q$V@@~NqMj<XXLD-D
z`})A;>{1x{{XwptcaMIfKce*=rutv;&Q8YHHO~1rFNKYSKby}9%%x@`lN2BD3QQ#G
z)uINctPIr~E(=;122J-~OebIWn!FMt9+U@|*YzYlj#=zPSC8LcnhDc;#5-YQQmNr=
zv=n;p+TzWLcy3aXM2+guVu_cllqJG=&O-$}wq-PHCJ#{2g9r^IKeA#jSwIT$h_g9{
zf#w_7;=yqn>k!<fm9Z0BN3f(00&tzLVd=HonOU_3!{8mkYSbTPpT9MatgK34#rt>g
zhEYAW$pssqMioC~RmsrwGHfhY58?P%hzk3>Q)t;&bxT?wI{=OErg1xdRvxs>&tMNK
z)98sid1UZ-0rQUMOtfboIeQzB?!;A;?U|<qx&L~qd?|liCksk176DOceL{>r)562+
z|Nf5sMLwS&jAuFFDXJZrA$Kr#X9KV7%INK!H2b+F(L95n2>wWak;~$q;ejcB*Zb~7
z{%oI}&>k2ZRr;2sKulI?U_kUMkXrWPQQ*k6LzXU)1HcauH!srd-GelkXPSM?t#yFH
z5P<DfWvaLR;>yVPJVXj+GjQkKZL&=F(;dH(A}$V>MCrEmhbEmXOuVghJP5NBaEkJ~
zn@~V)+yA<bop$vSsqdJiE~J+Tl|5gVR!Ws?NA1+jL{ridyb%U8a3xR;GhepoHvi6z
zke_L6=uHKWr#3|*@$1RfZo1n_nlVwrTYta<CcOTpe_SGuG+y}0SeOT+j?n7ro~0;%
z>)+wW&JA!z>&m-6)@y@xxWD&QpDp{eQ$6_y^kWIMPW<@-ZH7F`AFRQAzHh~oOg|dt
zK^do#c^x=-aS8ZFEsI22QcAN&fCIW+V|#v`?$+f?=OgXACCpw?YV-|&=OBOEbF^k9
z!G`}jU<EsZO&nhnc_1?40TGK$#e%0w8xc%wF?5XBK{Rg78LVwBv<4JqFnUSrc-dQ~
zA|p;JZC=9Ujb;f$X=x|V@9xoST*yDVNd)xwxK%yWJ0^-kn86O{yrBuNQ@>jngiOQc
zNn6bR_30j>A17E#7F2I+KGP-rD<AXBu&b6UY^2vn7&eH6^~zIL#!DJ`oU^w2@xGMb
zx_^EfCKel`!LVUUe7A){`d$7~{2^fL<Va_m6r?}P@7y9h!@Q}V_V%!Yo1k*M_~GV*
z%!ZmR!|cSamnscX(4>02B6an*nh%E0+Gjix>hzcWM;<Ge^U-eR+N@41jw2<qKa-P}
z2I2Em4bS4=^9F8RC1c&nBB#2ruN~@VRyzK>!RvivHm4$)ro|9W7i0>y@fw|1AX{Os
zv=kcHrOtu9t`lwz!C3F?V}}{8E5{ql+m;_M|5_YTWSp3_nmDMPc6;<Whgn-QFv9~&
zCA009hqF~|jO0S9oAR3xK|~$ij|Lb8<Cru7Bp8X@luz?(LgQ-Pka&NXpLtv6lGWu0
z|M$b^%^li8ld8z=6^WWnRb&bD5h1jiaz@B+Mq`%)E%$Z`l^XsR5VknW%c0(Ed>IAP
zhv@Y<dr3z`-V}dUA<HV0-9>$(#=E{s@85=Ifpt^D*%(m@A;tT3xzZEHu2E|$+pEdv
z*r&Q!tMfdwe{&|SpbLN>jyfM_`h%+RUvn!<5Ae<lOV2bsP1mbKehCzg+5}zlotam_
zA=fwhY+c3Ye0vI}2@p3|ahAl=FF(Kvy7_`?!c~8^WNj3X$U)N|Wl~c+ckYZ~`IU7F
zw;;>w4Dk8KEu%V1G?~cGq5FGw+P6m`#84dNFxiDgBY~Z^9TAFe4(V3Rx##ym`xn-K
zt83bV$VmrF&3X7~4H=8CJZhk-eZCBsoT=0E<y16lrxlGNUq<lW{aHwMqNv*w6zhDI
z*}r<b*`G}(-8K_p-dS8u=Q)G)oE`7*Gv}Gig|Cn*rAS^q9ShLolVywVm(&-(aGyh5
zC6OlhuqWQ`gP$P@{=eP7B)Zv4t1<jYQi)guNKsad5pinv9<+3`m3jzJ&rGE{X<A)}
zcyS%s34NkRy$R0dvf4xy!JTL7tJN=#Q5fSExccjAaUT)*nPNeEQX4)x`>iY^G{bnt
zb3caX21{2-&qK+25AVCidGmzc9Q3lq*6wfkywGm}(q-CZ`Fx`l#EY>zC|i!K|0d4b
zcf>3-t6_0=%mV1qG*q%aKsWY*KE~KyjI>I9i&^_?cn~DO%m;!+&F>=ZgiZjftfZG<
z@aa-8+1>o}mGu(_?Lw*XU6`Yqn>&9g7WvI_zQXD|<|K}8kySjsAIjqcN8bB`>^;~7
zxbB#3S~){v%~g$L;B=>0CUMBeq6Q2-+uui?v*#|tm?@6>qR$~%!xN*&eezLAQ`J8W
z1>A2XbliNSaAztpv9=C>xJ(_b7Gz#zI<rJTGa1~;Toe*fu}-SED*A9o#FJ0GQ^;2&
zK7K#V2};9OVF}<O_U7ad(t5E+$aLooSILUcW`=ZRwA2lXV1Pk-50UU!=GbYe+cEwy
zpUdFKm*l=L^Jr<WqLlc#1SHWv<&B+lFi*njeELE3-=rdQ73MKuD_=qy9kyFt>x}&n
z2NdSqsCPE?+Ka6@3;bl6wCz2?UOk+A3LM9}P7@dQ+#fNN%l^jW(6}&{!*{p!3jPIp
zUQ|5p@HqX*s?tLYfOqud_vM6=HVo4S%*~fG?539VTH!~uk9~+X;L#)Sxel*Ddc0DQ
zt^z8OFa_GjUD<F~*jVqVXwsS8jS+=dr-mfrxEZs~@5`A_9ZduvAam?;I`SLfVm>N^
zusk>szt00zs6QCsr}R#7sw?s;&e&HmsiHqzu5<f5s<x}|Ww_A}nf6?$(MZfCgOe1-
zkDG*$q;~F#3F=-0OQ<{RiDe3u_!P9gw;2uWy4CX%*UrO;gzT^8JAuk&iU&t}LMDQ|
z6-kk{ZN=XEMUTH-?S3of#tx5Lnmf!7miE2UID&qSf3S(`kE^Rx;hBznTy^8xh70}h
z-oQha_;jJd2=8b&$sW_dRZ+t{wZ88ee^AVx5x4D6!@Qla3uyZxlZ|a0es1V4=z&p9
z+2`Ji;dALO2G=^C7WKV{av9`m?(Dl53Ka&@?!PC$SJ90l5YfP4n4dxHY1%I1>zT+^
z;PbOd6hcoO!TXb1MY&>8B5O8+g_Fr5;xERYJ@!-!dq_fjpV-Fz{BIK$oSVtodOLrh
zC+VhoTSUusa~_$<w2+cHCB<WG7h1>0%~|d@vq#R5eGbYiH$@1Z{VpxYPj$i4g`c&i
z15DjA=M_4G16J^muqOpLfj~sON4<m_tyJsllTSarX9@&4X)dn`(q6O*>1|gq01@9T
z9Glx(%SV9HD&K8qAG(7>msl;5vsYTfXEB(Z;+P6B1N><A2;)fPU6T<OupL+4OH|F&
zjtdL3+5H6?z-=mYer>V4^Jm39_X|xzYCTPC&7%$?pz$&$Dn^ZD>3>9j@TV}Qps}&7
zO^6gz_(EIk<&As?EF)8-s(s%2jDTDKIkH5Y+UFT84iy)WTjlndN@WjEhlR$^^T;fF
zLRN}7Mb-P{b=#_gC8^>(HRrl$gyOU8Vwr|M7dlaEo9M^c0d_#-am4t-$^BvQB7B*V
zIkiRTxk;Cd<f^Ec4ttB4LixQgY<5wEeYZ>%e`4hBRsrKT)IbUTg8m{Ld?+2>T?2Bz
zpf()vSFbE2s`W&8Pxkw0G=<^E!xGNW^TSN&*Kt4+)kguBKTlKMxps+HOD9JhN(#nb
z%-WpsZ-<s{Vw}JJ8XX}U912cQyFF+X=$azJ2=;YArJ_B1cGH&efg3;K{pzG}gjp3-
z<khIjyKxchCE&NEoJZ4IK_T8%v?ai|-lDIB$gIIo9-Fr><ocfX3=0^l!Ud6mh<qc5
z(d#T8j+$IDx>_}VopC(dm??Z);N~wFb#bvq-RTg)yT}azyR*$z>kcR6_;H8;s)Czw
zKv7|JG7p!+x*Y^0jGi}vtA$@s3$3olO9jG7oDqe~L)H5;%TET-P68n!ycL@Y;dQ&6
zKcPbET72x!72t)-{xd{Li7!=@bEdXK5QqVQQf6yHZLuq|nk)9M#ALa_m2w7)P%L!T
zODc#J4<ZrbYWO-~YrSbY>63eCXg6yCD<)Uy`2J;uIWSu559iG)vtjg;A<)(~xK)t!
zFch&;bIiJu&~=fj50P5`-m5;I1$+LDr~7o%Tv2Ps7q@K*BVyelxQws#tx_rZYJFf=
z6yck0GejBbSvrnM^Pno{v~`)iDyoq?)cIT`bjQe=qpZa&9WdWppg-}-0w15~O)_NZ
z0>^KcuEOvAsK~4u<Jz8J>pWF*=OEDBbZixj3DUuGqqAkpQR@K=D&`f6WZrg7k@I8i
zeiO9A*sZ%Mo&obdO6=!)h9gJkW;DDyEdwNd4g?bwF1pwgXXdlzJvI-pGD9xu!Mwo^
z%a1b_SfH2OD@Eb{f6?T%eE3iO@<p7$BgJl;L?af*3dKTp*CFE)4|rH02|nwW!#d>X
p*U2Ar+1q|bbj9WW>*kMdfYBy1aw)`=@&Eq0NPm`xREX>Q{||9Uk0$^C

literal 0
HcmV?d00001

diff --git a/Services/Website/Resources/Static/js/app.js b/Services/Website/Resources/Static/css/index.css
similarity index 100%
rename from Services/Website/Resources/Static/js/app.js
rename to Services/Website/Resources/Static/css/index.css
diff --git a/Services/Website/Resources/Static/css/style.css b/Services/Website/Resources/Static/css/shared.css
similarity index 100%
rename from Services/Website/Resources/Static/css/style.css
rename to Services/Website/Resources/Static/css/shared.css
diff --git a/Services/Website/Resources/Static/js/error.js b/Services/Website/Resources/Static/js/error.js
new file mode 100644
index 0000000..e69de29
diff --git a/Services/Website/Resources/Static/js/index.js b/Services/Website/Resources/Static/js/index.js
new file mode 100644
index 0000000..e69de29
diff --git a/Services/Website/Resources/Static/js/shared.js b/Services/Website/Resources/Static/js/shared.js
new file mode 100644
index 0000000..e69de29
diff --git a/Services/Website/Resources/Static/robots.txt b/Services/Website/Resources/Static/robots.txt
index 51d2d2e..e7c9f38 100644
--- a/Services/Website/Resources/Static/robots.txt
+++ b/Services/Website/Resources/Static/robots.txt
@@ -3,3 +3,5 @@
 # Allow crawling of all content
 User-agent: *
 Disallow:
+
+Sitemap: https://loud.amsterdam/sitemap.xml
diff --git a/Services/Website/Resources/Static/sitemap.xml b/Services/Website/Resources/Static/sitemap.xml
new file mode 100644
index 0000000..8bfaeae
--- /dev/null
+++ b/Services/Website/Resources/Static/sitemap.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://loud.amsterdam/</loc>
+  </url>
+</urlset>
diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
index ef81f21..aed99f7 100644
--- a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
@@ -1,24 +1,27 @@
 /// A static file shipped with the website service.
 ///
-/// Each case identifies a file stored under the static files root (the `Resources/Static`
-/// directory) and served by Hummingbird's `FileMiddleware` middleware.
+/// Each case identifies a file name stored under the static files root (the `Resources/Static`
+/// directory) and served by Hummingbird's `FileMiddleware` middleware. A name can be available
+/// with more than one extension (see ``fileExtensions``), each resolving to its own file.
 enum StaticFile: CaseIterable, Sendable {
-    /// The `js/app.js` script.
-    case appJS
-    /// The `css/error.css` stylesheet for the not-found page.
-    case errorCSS
+    /// The `apple-touch-icon.png` icon.
+    case appleTouchIcon
+    /// The `css/error.css` stylesheet and `js/error.js` script for the not-found page.
+    case error
     /// The `favicon.ico` icon.
-    case faviconICO
-    /// The `icon.png` icon.
-    case iconPNG
-    /// The `icon.svg` icon.
-    case iconSVG
+    case favicon
+    /// The `icon.png` and `icon.svg` icons.
+    case icon
+    /// The `css/index.css` stylesheet and `js/index.js` script for the landing page.
+    case index
     /// The `robots.txt` crawler directives.
-    case robotsTXT
+    case robots
+    /// The `css/shared.css` stylesheet and `js/shared.js` script shared across pages.
+    case shared
     /// The `site.webmanifest` web application manifest.
-    case siteWebmanifest
-    /// The `css/style.css` stylesheet.
-    case styleCSS
+    case site
+    /// The `sitemap.xml` crawler sitemap.
+    case sitemap
 }
 
 // MARK: - Enumerations
@@ -40,6 +43,8 @@ extension StaticFile {
         case txt
         /// A web application manifest file.
         case webmanifest
+        /// An Extensible Markup Language file.
+        case xml
     }
 }
 
@@ -49,9 +54,91 @@ extension StaticFile {
 
     // MARK: Computed
     
+    /// The file extensions the file is available with.
+    var fileExtensions: [Extension] {
+        switch self {
+        case .appleTouchIcon: [.png]
+        case .error,
+             .index,
+             .shared: [.css, .js]
+        case .favicon: [.ico]
+        case .icon: [.png, .svg]
+        case .robots: [.txt]
+        case .site: [.webmanifest]
+        case .sitemap: [.xml]
+        }
+    }
+
+    /// The file's name, without extension.
+    var fileName: String {
+        switch self {
+        case .appleTouchIcon: "apple-touch-icon"
+        case .error: "error"
+        case .favicon: "favicon"
+        case .icon: "icon"
+        case .index: "index"
+        case .robots: "robots"
+        case .shared: "shared"
+        case .site: "site"
+        case .sitemap: "sitemap"
+        }
+    }
+
+    // MARK: Methods
+
+    /// Resolves the file's path against the given base directory.
+    ///
+    /// - Parameters:
+    ///   - basePath: the directory the static files are served from.
+    ///   - fileExtension: the extension of the file to resolve.
+    /// - Returns: the path to the file, relative to the `basePath` path.
+    func path(
+        relativeTo basePath: String,
+        for fileExtension: Extension
+    ) -> String {
+        let relativePath = relativePath(for: fileExtension)
+
+        guard !basePath.isEmpty else {
+            return relativePath
+        }
+
+        return "\(basePath)/\(relativePath)"
+    }
+    
+    /// Resolves the file's path relative to the static files root (e.g. `"css/shared.css"`).
+    ///
+    /// This also matches the URL path the file is served at by `FileMiddleware`.
+    ///
+    /// - Parameter fileExtension: the extension of the file to resolve.
+    /// - Returns: the path to the file, relative to the static files root.
+    func relativePath(
+        for fileExtension: Extension
+    ) -> String {
+        let file = "\(fileName).\(fileExtension.rawValue)"
+
+        return fileExtension.subdirectory
+            .map { "\($0)/\(file)" } ?? file
+    }
+
+    /// Resolves the absolute URL path the file is served at (e.g. `"/css/shared.css"`).
+    ///
+    /// - Parameter fileExtension: the extension of the file to resolve.
+    /// - Returns: the path to use in `href` and `src` attributes.
+    func urlPath(
+        for fileExtension: Extension
+    ) -> String {
+        "/\(relativePath(for: fileExtension))"
+    }
+
+}
+
+extension StaticFile.Extension {
+    
+    // MARK: Computed
+
     /// The file's content type.
     var contentType: String {
-        switch fileExtension {
+        switch self {
         case .css: "text/css"
         case .js: "text/javascript"
         case .png: "image/png"
@@ -59,77 +146,15 @@ extension StaticFile {
         case .svg: "image/svg+xml"
         case .txt: "text/plain"
         case .webmanifest: "application/manifest+json"
+        case .xml: "application/xml"
         }
     }
 
-    /// The file's extension.
-    var fileExtension: Extension {
-        switch self {
-        case .errorCSS,
-             .styleCSS: .css
-        case .appJS: .js
-        case .faviconICO: .ico
-        case .iconPNG: .png
-        case .iconSVG: .svg
-        case .robotsTXT: .txt
-        case .siteWebmanifest: .webmanifest
-        }
-    }
-
-    /// The file's name, without extension.
-    var fileName: String {
-        switch self {
-        case .appJS: "app"
-        case .errorCSS: "error"
-        case .faviconICO: "favicon"
-        case .iconPNG,
-             .iconSVG: "icon"
-        case .robotsTXT: "robots"
-        case .siteWebmanifest: "site"
-        case .styleCSS: "style"
-        }
-    }
-
-    /// The path relative to the static files root (e.g. `"css/style.css"`).
-    ///
-    /// This also matches the URL path the file is served at by `FileMiddleware`.
-    var relativePath: String {
-        let file = "\(fileName).\(fileExtension.rawValue)"
-
-        return subdirectory
-            .map { "\($0)/\(file)" } ?? file
-    }
-
-    // MARK: Methods
-
-    /// Resolves the file's path against the given base directory.
-    /// 
-    /// - Parameter basePath: the directory the static files are served from.
-    /// - Returns: the path to the file, relative to the `basePath` path.
-    func path(
-        relativeTo basePath: String
-    ) -> String {
-        guard !basePath.isEmpty else {
-            return relativePath
-        }
-
-        return "\(basePath)/\(relativePath)"
-    }
-
-}
-
-// MARK: - Helpers
-
-private extension StaticFile {
-
-    // MARK: Computed
-
-    /// The sub-directory within the static root that holds the file, if any.
+    /// The sub-directory within the static root that holds files with this extension, if any.
     var subdirectory: String? {
         switch self {
-        case .appJS: "js"
-        case .errorCSS,
-             .styleCSS: "css"
+        case .css: "css"
+        case .js: "js"
         default: nil
         }
     }
diff --git a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
index 06f11b6..79a1f53 100644
--- a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
@@ -26,7 +26,7 @@ struct ErrorPage: HTMLDocument, Sendable {
 
     // MARK: Document
 
-    /// The page's content: a localized heading and explanatory message.
+    /// The page's content: a localized heading and explanatory message, followed by the error and shared scripts.
     var body: some HTML {
         h1 {
             localize("error.heading", locale: locale)
@@ -34,9 +34,11 @@ struct ErrorPage: HTMLDocument, Sendable {
         p {
             localize("error.message", locale: locale)
         }
+        script(.src(StaticFile.error.urlPath(for: .js))) {}
+        script(.src(StaticFile.shared.urlPath(for: .js))) {}
     }
 
-    /// The metadata and stylesheet link placed in the document head.
+    /// The metadata and stylesheet links placed in the document head.
     var head: some HTML {
         meta(.charset(.utf8))
         meta(
@@ -45,7 +47,11 @@ struct ErrorPage: HTMLDocument, Sendable {
         )
         link(
             .rel(.stylesheet),
-            .href("/css/error.css")
+            .href(StaticFile.shared.urlPath(for: .css))
+        )
+        link(
+            .rel(.stylesheet),
+            .href(StaticFile.error.urlPath(for: .css))
         )
     }
 
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index 8d6c0c2..7f8bf19 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -26,12 +26,13 @@ struct IndexPage: HTMLDocument, Sendable {
 
     // MARK: Document
 
-    /// The page's content: a localized greeting followed by the app script.
+    /// The page's content: a localized greeting followed by the shared and index scripts.
     var body: some HTML {
         p {
             localize("index.greeting", locale: locale)
         }
-        script(.src("/js/app.js")) {}
+        script(.src(StaticFile.index.urlPath(for: .js))) {}
+        script(.src(StaticFile.shared.urlPath(for: .js))) {}
     }
 
     /// The metadata, stylesheet, icon, and manifest links placed in the document head.
@@ -43,11 +44,15 @@ struct IndexPage: HTMLDocument, Sendable {
         )
         link(
             .rel(.stylesheet),
-            .href("/css/style.css")
+            .href(StaticFile.shared.urlPath(for: .css))
+        )
+        link(
+            .rel(.stylesheet),
+            .href(StaticFile.index.urlPath(for: .css))
         )
         link(
             .rel(.icon),
-            .href("/favicon.ico"),
+            .href(StaticFile.favicon.urlPath(for: .ico)),
             .custom(
                 name: "sizes",
                 value: "any"
@@ -55,7 +60,7 @@ struct IndexPage: HTMLDocument, Sendable {
         )
         link(
             .rel(.icon),
-            .href("/icon.svg"),
+            .href(StaticFile.icon.urlPath(for: .svg)),
             .custom(
                 name: "type",
                 value: "image/svg+xml"
@@ -63,11 +68,11 @@ struct IndexPage: HTMLDocument, Sendable {
         )
         link(
             .rel("apple-touch-icon"),
-            .href("/icon.png")
+            .href(StaticFile.appleTouchIcon.urlPath(for: .png))
         )
         link(
             .rel("manifest"),
-            .href("/site.webmanifest")
+            .href(StaticFile.site.urlPath(for: .webmanifest))
         )
         meta(
             .name("theme-color"),
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index a677a32..e665763 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -94,20 +94,22 @@ struct AppTests {
         try await app(
             staticFilesPath: staticFilesPath
         ).test(.router) { client in
-            try await client.execute(
-                uri: "/\(file.relativePath)",
-                method: .get
-            ) { response in
-                #expect(response.status == .ok)
-                #expect(response.headers[.contentType] == file.contentType)
-                
-                let cacheControl = try #require(response.headers[.cacheControl])
+            for fileExtension in file.fileExtensions {
+                try await client.execute(
+                    uri: "/\(file.relativePath(for: fileExtension))",
+                    method: .get
+                ) { response in
+                    #expect(response.status == .ok)
+                    #expect(response.headers[.contentType] == fileExtension.contentType)
 
-                #expect(cacheControl.contains("public") == true)
-                #expect(cacheControl.contains("max-age=") == true)
-                
-                if textExtensions.contains(file.fileExtension) {
-                    #expect(cacheControl.contains("must-revalidate") == true)
+                    let cacheControl = try #require(response.headers[.cacheControl])
+
+                    #expect(cacheControl.contains("public") == true)
+                    #expect(cacheControl.contains("max-age=") == true)
+
+                    if textExtensions.contains(fileExtension) {
+                        #expect(cacheControl.contains("must-revalidate") == true)
+                    }
                 }
             }
         }
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index 110bca2..4cb579f 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -5,36 +5,25 @@ import Testing
 
 @Suite("StaticFile enumeration")
 struct StaticFileTests {
-    
+
     // MARK: Type aliases
-    
+
     typealias File = StaticFile
     typealias FileExtension = StaticFile.Extension
-    
+
     // MARK: Computed tests
-    
-    @Test(arguments: zip(
-        File.allCases,
-        Self.contentTypes
-    ))
-    func `content type`(
-        for file: File,
-        expects contentType: String
-    ) {
-        #expect(file.contentType == contentType)
-    }
-    
+
     @Test(arguments: zip(
         File.allCases,
         Self.fileExtensions
     ))
-    func `file extension`(
+    func `file extensions`(
         for file: File,
-        expects `extension`: FileExtension
+        expects extensions: [FileExtension]
     ) {
-        #expect(file.fileExtension == `extension`)
+        #expect(file.fileExtensions == extensions)
     }
-    
+
     @Test(arguments: zip(
         File.allCases,
         Self.fileNames
@@ -45,20 +34,57 @@ struct StaticFileTests {
     ) {
         #expect(file.fileName == fileName)
     }
-    
+
+    @Test(arguments: zip(
+        Self.extensions,
+        Self.contentTypes
+    ))
+    func `content type`(
+        for fileExtension: FileExtension,
+        expects contentType: String
+    ) {
+        #expect(fileExtension.contentType == contentType)
+    }
+
+    @Test(arguments: zip(
+        Self.extensions,
+        Self.subdirectories
+    ))
+    func `subdirectory`(
+        for fileExtension: FileExtension,
+        expects subdirectory: String?
+    ) {
+        #expect(fileExtension.subdirectory == subdirectory)
+    }
+
+    // MARK: Method tests
+
     @Test(arguments: zip(
         File.allCases,
         Self.relativePaths
     ))
-    func `relative path`(
+    func `relative path for`(
         for file: File,
-        expects relativePath: String
+        expects relativePaths: [String]
     ) {
-        #expect(file.relativePath == relativePath)
+        for (fileExtension, relativePath) in zip(file.fileExtensions, relativePaths) {
+            #expect(file.relativePath(for: fileExtension) == relativePath)
+        }
     }
-    
-    // MARK: Method tests
-    
+
+    @Test(arguments: zip(
+        File.allCases,
+        Self.relativePaths
+    ))
+    func `url path for`(
+        for file: File,
+        expects relativePaths: [String]
+    ) {
+        for (fileExtension, relativePath) in zip(file.fileExtensions, relativePaths) {
+            #expect(file.urlPath(for: fileExtension) == "/\(relativePath)")
+        }
+    }
+
     @Test(arguments: [
         "",
         ".",
@@ -68,70 +94,99 @@ struct StaticFileTests {
         _ basePath: String
     ) {
         for file in File.allCases {
-            let pathRelativeToBasePath = file.path(relativeTo: basePath)
+            for fileExtension in file.fileExtensions {
+                let pathRelativeToBasePath = file.path(
+                    relativeTo: basePath,
+                    for: fileExtension
+                )
+                let relativePath = file.relativePath(for: fileExtension)
 
-            if basePath.isEmpty {
-                #expect(pathRelativeToBasePath == file.relativePath)
-            } else {
-                #expect(pathRelativeToBasePath == "\(basePath)/\(file.relativePath)")
+                if basePath.isEmpty {
+                    #expect(pathRelativeToBasePath == relativePath)
+                } else {
+                    #expect(pathRelativeToBasePath == "\(basePath)/\(relativePath)")
+                }
             }
         }
     }
 
     // MARK: CaseIterable tests
-    
+
     @Test
     func `all cases`() {
-        #expect(File.allCases.count == 8)
+        #expect(File.allCases.count == 9)
     }
-    
+
 }
 
 // MARK: - Helpers
 
 private extension StaticFileTests {
-    
+
     // MARK: Constants
-    
-    static let contentTypes: [String] = [
-        "text/javascript",
-        "text/css",
-        "image/vnd.microsoft.icon",
-        "image/png",
-        "image/svg+xml",
-        "text/plain",
-        "application/manifest+json",
-        "text/css"
-    ]
-    static let fileExtensions: [FileExtension] = [
-        .js,
+
+    static let extensions: [FileExtension] = [
         .css,
-        .ico,
+        .js,
         .png,
+        .ico,
         .svg,
         .txt,
         .webmanifest,
-        .css
+        .xml
+    ]
+    static let contentTypes: [String] = [
+        "text/css",
+        "text/javascript",
+        "image/png",
+        "image/vnd.microsoft.icon",
+        "image/svg+xml",
+        "text/plain",
+        "application/manifest+json",
+        "application/xml"
+    ]
+    static let subdirectories: [String?] = [
+        "css",
+        "js",
+        nil,
+        nil,
+        nil,
+        nil,
+        nil,
+        nil
+    ]
+    static let fileExtensions: [[FileExtension]] = [
+        [.png],
+        [.css, .js],
+        [.ico],
+        [.png, .svg],
+        [.css, .js],
+        [.txt],
+        [.css, .js],
+        [.webmanifest],
+        [.xml]
     ]
     static let fileNames: [String] = [
-        "app",
+        "apple-touch-icon",
         "error",
         "favicon",
         "icon",
-        "icon",
+        "index",
         "robots",
+        "shared",
         "site",
-        "style"
+        "sitemap"
     ]
-    static let relativePaths: [String] = [
-        "js/app.js",
-        "css/error.css",
-        "favicon.ico",
-        "icon.png",
-        "icon.svg",
-        "robots.txt",
-        "site.webmanifest",
-        "css/style.css"
+    static let relativePaths: [[String]] = [
+        ["apple-touch-icon.png"],
+        ["css/error.css", "js/error.js"],
+        ["favicon.ico"],
+        ["icon.png", "icon.svg"],
+        ["css/index.css", "js/index.js"],
+        ["robots.txt"],
+        ["css/shared.css", "js/shared.js"],
+        ["site.webmanifest"],
+        ["sitemap.xml"]
     ]
-    
+
 }
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
index 7e03844..6a148e9 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
@@ -19,7 +19,10 @@ struct ErrorPageTests {
         #expect(html.contains(#"lang="en""#))
         #expect(html.contains("Page Not Found"))
         #expect(html.contains("Sorry, but the page you were trying to view does not exist."))
+        #expect(html.contains("/css/shared.css"))
         #expect(html.contains("/css/error.css"))
+        #expect(html.contains("/js/error.js"))
+        #expect(html.contains("/js/shared.js"))
     }
 
 }
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index 254b6e3..89dd952 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -17,13 +17,15 @@ struct IndexPageTests {
 
         #expect(html.contains("<!DOCTYPE html>"))
         #expect(html.contains(#"lang="en""#))
-        #expect(html.contains("/css/style.css"))
+        #expect(html.contains("/css/shared.css"))
+        #expect(html.contains("/css/index.css"))
         #expect(html.contains("/favicon.ico"))
         #expect(html.contains("/icon.svg"))
-        #expect(html.contains("/icon.png"))
+        #expect(html.contains("/apple-touch-icon.png"))
         #expect(html.contains("/site.webmanifest"))
         #expect(html.contains("Hello world!"))
-        #expect(html.contains("/js/app.js"))
+        #expect(html.contains("/js/shared.js"))
+        #expect(html.contains("/js/index.js"))
     }
 
 }
-- 
2.54.0


From 79ecf311f4ad6a08079a8de5751c2ca1830c7aad Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 19 Jul 2026 02:28:05 +0000
Subject: [PATCH 021/117] Local environment configuration support for the
 Website service (#19)

This PR contains the work done to amend the `.env.local` handling for the Website service, plus other small fixes.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/19
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/.env.local                            | 10 ++--------
 Services/Website/Dockerfile                            |  1 +
 Services/Website/README.md                             |  4 +---
 Services/Website/Sources/App/App.swift                 |  6 +++++-
 .../Library/Cases/Internal/Pages/ErrorPageTests.swift  |  2 +-
 .../Library/Cases/Internal/Pages/IndexPageTests.swift  |  2 +-
 .../Public/Controllers/HealthControllerTests.swift     |  2 +-
 .../Cases/Public/Controllers/RootControllerTests.swift |  2 +-
 .../Middlewares/LocalizationMiddlewareTests.swift      |  2 +-
 .../Public/Middlewares/NotFoundMiddlewareTests.swift   |  2 +-
 .../Middlewares/SecurityHeadersMiddlewareTests.swift   |  2 +-
 .../Tests/Library/Utils/Extensions/Tag+Constants.swift | 10 ++++++++++
 12 files changed, 26 insertions(+), 19 deletions(-)
 create mode 100644 Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift

diff --git a/Services/Website/.env.local b/Services/Website/.env.local
index 1987239..865548e 100644
--- a/Services/Website/.env.local
+++ b/Services/Website/.env.local
@@ -1,10 +1,4 @@
-# Copy this file to `.env` and adjust values as needed.
-#   cp .env.example .env
-#
-# Compose reads `.env` automatically to fill the ${VAR} placeholders in
-# docker-compose.yml. The Website app ALSO reads a `.env` file at runtime via
-# swift-configuration (allowMissing: true), so any extra app config keys placed
-# here are picked up by the running service too.
+# Local `.env` file used solely for Development purposes.
 
 # --- Image / deployment -------------------------------------------------------
 
@@ -39,7 +33,7 @@ IMAGE_TAG=latest
 HTTP_SERVER_NAME=LoudWebsite
 
 # Log verbosity: trace | debug | info | notice | warning | error | critical
-LOG_LEVEL=info
+LOG_LEVEL=debug
 
 # --- Persistence ----------------------------------------------------------------
 
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index ec87365..b2ed87f 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -19,6 +19,7 @@ WORKDIR /build
 # a relative path, so its manifest must be present for resolution to succeed.
 COPY ./Packages/Localization/Package.swift ./Packages/Localization/
 COPY ./Packages/Persistence/Package.swift ./Packages/Persistence/
+COPY ./Packages/Web/Package.swift ./Packages/Web/
 COPY ./Services/Website/Package.swift ./Services/Website/Package.resolved ./Services/Website/
 RUN swift package --package-path ./Services/Website resolve
 
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 4293024..27d7fa6 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -5,7 +5,6 @@ The **Loud** public website service — a [Hummingbird](https://github.com/hummi
 The service:
 - Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
 - Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
-- Registers newsletter subscriptions at `POST /subscribe`: the landing page's form-encoded submission is validated and normalized, guarded by a hidden honeypot field against bots, and stored tagged with the request's negotiated language.
 - Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
 - Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`.
 - Returns a custom HTML 404 page, localized like the landing page, for any request that matches neither a route nor a static file.
@@ -41,7 +40,6 @@ LogRequestsMiddleware
         → NotFoundMiddleware         (renders the localized 404 page on .notFound)
           → FileMiddleware           (serves Resources/Static)
 RootController                       (GET / → landing page)
-SubscriptionController               (POST /subscribe → newsletter subscription)
 HealthController                     (GET /health → liveness, GET /health/ready → readiness)
 ```
 
@@ -56,7 +54,7 @@ the following sources, **highest precedence first**:
 
 The two files play different roles:
 - **`.env`** (git-ignored) holds your deployment values — it is the file the Makefile and Compose read for the `${VAR}` placeholders, and typically selects the MySQL/MariaDB backend.
-- **`.env.local`** (tracked) holds the local development overrides — the in-memory database and `debug` logging. Because it sits *above* `.env`, a direct launch (`swift run` or a debugger) runs against the local values even when `.env` points at a deployment, the same way `docker-compose.override.yml` overrides the base Compose file. Compose itself never reads it, and the production image does not ship it — only the executable, its resources, and the static files are staged into the final stage.
+- **`.env.local`** (tracked) holds the local development values — the in-memory database and `debug` logging, plus the image/deployment placeholders the Makefile falls back to when no `.env` exists. Because it sits *above* `.env`, a direct launch (`swift run` or a debugger) runs against the local values even when `.env` points at a deployment, the same way `docker-compose.override.yml` overrides the base Compose file. Compose itself never reads it, and the production image does not ship it — only the executable, its resources, and the static files are staged into the final stage.
 
 ### Environment variable naming
 A dotted config key maps to an environment variable by upper-casing, splitting camelCase, and replacing separators with `_`. For example `http.serverName` → `HTTP_SERVER_NAME`,
diff --git a/Services/Website/Sources/App/App.swift b/Services/Website/Sources/App/App.swift
index 4736863..ee99ab9 100644
--- a/Services/Website/Sources/App/App.swift
+++ b/Services/Website/Sources/App/App.swift
@@ -12,12 +12,16 @@ struct App {
     /// Loads the configuration and runs the mode it selects.
     ///
     /// The configuration is read from the providers in precedence order: command-line arguments first, then process environment variables, then a
-    /// `.env` file when one is present, and finally the in-memory defaults (currently just the server name).
+    /// `.env.local` file when one is present, then a `.env` file when one is present, and finally the in-memory defaults.
     static func main() async throws {
         let reader = try await ConfigReader(
             providers: [
                 CommandLineArgumentsProvider(),
                 EnvironmentVariablesProvider(),
+                EnvironmentVariablesProvider(
+                    environmentFilePath: ".env.local",
+                    allowMissing: true
+                ),
                 EnvironmentVariablesProvider(
                     environmentFilePath: ".env",
                     allowMissing: true
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
index 6a148e9..3268b64 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
@@ -4,7 +4,7 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("ErrorPage page")
+@Suite("ErrorPage page", .tags(.page))
 struct ErrorPageTests {
     
     // MARK: Functional tests
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index 89dd952..a754d77 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -4,7 +4,7 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("IndexPage page")
+@Suite("IndexPage page", .tags(.page))
 struct IndexPageTests {
     
     // MARK: Functional tests
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
index f27ec95..9d565bf 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -7,7 +7,7 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("HealthController controller")
+@Suite("HealthController controller", .tags(.controller))
 struct HealthControllerTests {
 
     // MARK: Functional tests
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
index 9fb321f..54c3a4f 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
@@ -5,7 +5,7 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("RootController controller")
+@Suite("RootController controller", .tags(.controller))
 struct RootControllerTests {
     
     // MARK: Constants
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
index 607bc3a..9b71671 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
@@ -6,7 +6,7 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("LocalizationMiddleware middleware")
+@Suite("LocalizationMiddleware middleware", .tags(.middleware))
 struct LocalizationMiddlewareTests {
 
     // MARK: Constants
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
index 5aadb6b..3cffe32 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
@@ -5,7 +5,7 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("NotFoundMiddleware middleware")
+@Suite("NotFoundMiddleware middleware", .tags(.middleware))
 struct NotFoundMiddlewareTests {
     
     // MARK: Constants
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
index 224f303..e987adc 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
@@ -4,7 +4,7 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("SecurityHeadersMiddleware middleware")
+@Suite("SecurityHeadersMiddleware middleware", .tags(.middleware))
 struct SecurityHeadersMiddlewareTests {
 
     // MARK: Functional tests
diff --git a/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift b/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
new file mode 100644
index 0000000..2dee5a2
--- /dev/null
+++ b/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
@@ -0,0 +1,10 @@
+import Testing
+
+extension Tag {
+    /// Tests exercising a controller of the Website library.
+    @Tag static var controller: Tag
+    /// Tests exercising a middleware of the Website library.
+    @Tag static var middleware: Tag
+    /// Tests exercising a page of the Website library.
+    @Tag static var page: Tag
+}
-- 
2.54.0


From 698cd60521d5a840bef5fd20ca85879d3b228c3f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 19 Jul 2026 03:02:17 +0000
Subject: [PATCH 022/117] Static asset magnification for the Website service
 (#20)

This PR contains the work done for build-time optimization of the static assets served by the Website service. The production Docker image now ships minified JS/CSS and losslessly recompressed images, while the sources in the repository stay readable and un-minified.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/20
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/Dockerfile | 31 ++++++++++++++++++++++++++++++-
 Services/Website/Makefile   | 11 +++++++++++
 Services/Website/README.md  | 15 ++++++++++++++-
 3 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index b2ed87f..6f3f1d4 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -1,3 +1,27 @@
+# ================================
+# Asset image
+# ================================
+FROM node:22-alpine AS assets
+
+# Install the minifiers in their own layer, so they are cached across asset changes
+RUN apk add --no-cache oxipng \
+    && npm install --global esbuild svgo
+
+# Copy the static files and minify the JS/CSS/SVG sources and losslessly recompress
+# the PNG images in place, keeping their names so the URL paths derived from the
+# StaticFile enumeration stay unchanged.
+WORKDIR /static
+COPY ./Services/Website/Resources/Static .
+RUN esbuild --minify --allow-overwrite --outdir=css css/*.css \
+    && esbuild --minify --allow-overwrite --outdir=js js/*.js \
+    && oxipng --opt max --strip safe *.png \
+    && svgo icon.svg
+
+# Export stage: `docker build --target assets-export --output <dir>` writes the
+# minified static files to <dir> for local inspection.
+FROM scratch AS assets-export
+COPY --from=assets /static /
+
 # ================================
 # Build image
 # ================================
@@ -45,8 +69,13 @@ RUN cp "/usr/libexec/swift/linux/swift-backtrace-static" ./
 RUN find -L "$(swift build --package-path /build/Services/Website -c release --show-bin-path)/" -regex '.*\.resources$' -exec cp -Ra {} ./ \;
 
 # Copy the static files directory (served by FileMiddleware) if it exists
+RUN [ -d /build/Services/Website/Resources ] && mv /build/Services/Website/Resources ./Resources || true
+
+# Overwrite the static files with the minified copies from the assets stage
+COPY --from=assets /static ./Resources/Static
+
 # Ensure that by default, neither the directory nor any of its contents are writable.
-RUN [ -d /build/Services/Website/Resources ] && { mv /build/Services/Website/Resources ./Resources && chmod -R a-w ./Resources; } || true
+RUN chmod -R a-w ./Resources
 
 # ================================
 # Run image
diff --git a/Services/Website/Makefile b/Services/Website/Makefile
index 47d91c8..2ed486e 100644
--- a/Services/Website/Makefile
+++ b/Services/Website/Makefile
@@ -105,6 +105,17 @@ db-reset: ## Stop and remove the local database instance and delete its data vol
 		--profile database down mariadb \
 		--volumes
 
+# --- Assets minification ------------------------------------------------------
+
+.PHONY: ast-minify
+ast-minify: ## Preview the minified JS/CSS assets in .build/minified
+	@docker build \
+		--target assets-export \
+		--output .build/minified \
+		--file Dockerfile \
+		../..
+	@echo "Minified assets written to .build/minified"
+
 # --- Registry deployment ------------------------------------------------------
 
 .PHONY: img-check
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 27d7fa6..5f85d3a 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -6,7 +6,7 @@ The service:
 - Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
 - Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
 - Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
-- Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`.
+- Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`; the production image ships minified copies (see [Static assets](#static-assets)).
 - Returns a custom HTML 404 page, localized like the landing page, for any request that matches neither a route nor a static file.
 - Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
 - Stamps a hardened set of security headers on every response.
@@ -200,6 +200,19 @@ docker compose -f docker-compose.yml pull
 docker compose -f docker-compose.yml up -d
 ```
 
+### Static assets
+The image build optimizes the files under `Resources/Static` in its `assets` stage, in place:
+- CSS and JS are minified with [esbuild](https://esbuild.github.io).
+- PNG images are losslessly recompressed with [oxipng](https://github.com/oxipng/oxipng) — the output is pixel-identical, only encoded smaller.
+- The SVG icon is minified with [svgo](https://github.com/svg/svgo).
+
+Files keep their names and paths, so the URLs derived from the `StaticFile` enumeration are unaffected. The sources in the repository stay readable and unminified: a direct `swift run` serves them as-is, while any image build — including the local `make site-mount` one, which builds the same Dockerfile — serves the optimized copies.
+
+Preview the optimized output locally — requires only Docker and writes to the git-ignored `.build/minified`:
+```sh
+make ast-minify
+```
+
 ### Required variables
 The Makefile and Compose files read these from a `.env` file (or the environment). Provide your own values — do **not** commit secrets.
 | Variable | Used for |
-- 
2.54.0


From 6bdc127057a426a03d70320f564d95acd84a4f09 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 19 Jul 2026 03:35:50 +0000
Subject: [PATCH 023/117] Improvements to Icons for the Website service (#21)

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/21
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/README.md                    |  21 ++++++++++++++++++
 Services/Website/Resources/Static/favicon.ico | Bin 766 -> 700 bytes
 .../Website/Resources/Static/icon-192.png     | Bin 0 -> 4501 bytes
 .../Website/Resources/Static/icon-512.png     | Bin 0 -> 13856 bytes
 Services/Website/Resources/Static/icon.png    | Bin 4029 -> 0 bytes
 Services/Website/Resources/Static/icon.svg    |   2 +-
 .../Website/Resources/Static/site.webmanifest |   6 ++++-
 .../Internal/Enumerations/StaticFile.swift    |  14 +++++++++---
 .../Library/Internal/Pages/IndexPage.swift    |   8 +++++++
 .../Enumerations/StaticFileTests.swift        |  12 +++++++---
 .../Cases/Internal/Pages/IndexPageTests.swift |   1 +
 11 files changed, 56 insertions(+), 8 deletions(-)
 create mode 100644 Services/Website/Resources/Static/icon-192.png
 create mode 100644 Services/Website/Resources/Static/icon-512.png
 delete mode 100644 Services/Website/Resources/Static/icon.png

diff --git a/Services/Website/README.md b/Services/Website/README.md
index 5f85d3a..7e410c7 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -213,6 +213,27 @@ Preview the optimized output locally — requires only Docker and writes to the
 make ast-minify
 ```
 
+### Icons
+All icons are renditions of the star mark in `icon.svg`, which is the canonical source — there is no external design file to regenerate from.
+
+| File | Size | Used by | Dark mode |
+| --- | --- | --- | --- |
+| `icon.svg` | vector | Tab icon in modern browsers (preferred over the ICO) | Adapts: an embedded `prefers-color-scheme` style flips the accent paths from `#000` to `#f3ecf5`. |
+| `favicon.ico` | 32×32 | Tab icon in browsers without SVG favicon support (Safari) | Theme-neutral **by design**: it is the orange star *without* the accent paths, so one raster reads on both themes. Keep it accent-free when regenerating. |
+| `icon-192.png`, `icon-512.png` | 192/512 | `site.webmanifest` install icons and splash screens | None (no platform mechanism); full artwork, light rendering, on a transparent background. |
+| `apple-touch-icon.png` | 180×180 | iOS home-screen bookmarks | None (fetched once, outside any page context); full artwork, deliberately opaque — iOS fills transparent regions with black. |
+
+The landing page pairs the icons with two `theme-color` metas: `#0c0710` (media-qualified for dark, listed first — the first matching entry wins) and `#fafafa` as the fallback.
+
+The raster icons are committed binaries, regenerated from `icon.svg` on demand via a throwaway container (no local toolchain needed) — e.g. for the 512px rendition:
+```sh
+docker run --rm -v "$PWD/Resources/Static:/work" alpine sh -c '
+  apk add --no-cache imagemagick librsvg oxipng &&
+  magick -background none -density 256 /work/icon.svg -depth 8 PNG32:/work/icon-512.png &&
+  oxipng --opt max --strip safe /work/icon-512.png'
+```
+(`-density` scales the 192px viewBox: `96 × target ÷ 192`. For `favicon.ico`, rasterize a star-only copy of the SVG at 32px and pack it with `icotool -c --raw`.)
+
 ### Required variables
 The Makefile and Compose files read these from a `.env` file (or the environment). Provide your own values — do **not** commit secrets.
 | Variable | Used for |
diff --git a/Services/Website/Resources/Static/favicon.ico b/Services/Website/Resources/Static/favicon.ico
index be74abd69ad6a32de7375df13cab9354798e328f..2b5bcda7da4eb605b59c7837ef35b2c7204f30cc 100644
GIT binary patch
literal 700
zcmV;t0z>@(0096203aX$0096X0Hy)}02TlM0EtjeM-2)Z3IG5A4M|8uQUCw|AOHXW
zAP5Ek0047(dh`GQ010qNS#tmY0AK(B0AK*{YeLTe00LM^L_t(|+U?iBYZGA@!133%
zwj~u6{L#TdX>zTIsL%>obnplI59lb;ZZ2XG9V#fMxgb(-a1j&~!Lb$>Emgt6A47C<
z5G3aAvQ;#LrAno~ez`suuGbtna_K>#FMPP=y?dT}-uIroQEPTs`HagJ$p#-^3htO0
z^?GDb>8b51(NQWaC4i&oh5BY1iI=|{lQ;{7WP;mLejLJ2JVtwB2~=+Oc?n#GhJ$`6
z8%dSF2d|*T1*j6$S>51ft^8S3p~W;(P{n(LtNZriI<!v}*`_z6?L8Rfyb(&~Y{5I|
zfN?M{(lbKeteZ(Ny6Q5G4(6Q1FX(_z*u}igu={11I_f4+&bbMk#w2DiUB`2LhOT1)
zZ}B4J-WlYvV?_dvuL3v^2fD?cz_8q9NULSztL$!{A-sfcfmw_q1tkeI*yX@Z+`)W|
z;6<FU3CPt|L4!|CCIcHW+{BVB;1Tvfc_I(1AU8o0%Hjib1oOD+mAp)Mv`q;fr$68}
zbOco#hH~Z7E$M!n@CG`fOHkJ6{&>M{v$h`&U=})}r|3ki`2N;8f`8Bf4(6Z(Ec8K@
z3j=Y>Z?tiJ2<`I+53m>KP=faPi!-u`W3PX2p#7FGj4mi~5YMm(E$&uw235?&JNe=m
zeq#|+5==qVmT4=l;RiH6VjE(g{chkpu3&SpvDlITklw)c6pEO`5h%nu`HtbZmFxHa
z8EMqUcjG=TN@C3&ztAq{KP4J`w%*UWD}{Y%V;?k|0Jz!7rz4+uD-+T?gdXcr?<a;-
i;^WJ$fo0Z5*!U0ox}BKceR?YZ0000<MNUMnLSTX%usNLo

literal 766
zcmc(dze~eV5XUd2fg&jH87YDYDQKxq1{4b-_ydP-wqS9vgGh17QXQQAwOE{VaBvi*
zmu^z9t({y-&1ey<?*19x`_a%0;^>8Y_x;?x+`BviV9;aRjMgZ8M*!jgkRrFqSI9;F
zHyfX@Az|AvVmn~YWWZP`0&JWEY~BFm?*Vq}VD7&_%x%MP$p`D`4JMC!K|B7pt?Mmp
zUJAB7rxMXS6=!P+AtLU9V)J#61WPxwipRXCHO{BJ`l{m53#=t97a!znv~vfmr|AaP
zRGIT7#0FyJy3Z*hL{GQp-0TRhX8UzZ)+>%?mK0^goaX4Q;x<h|7I8a@t8#9Z`A~@1
zIx{#+`h7(7bA0+s7#-k=_?cTQZjqG{+al%<xj`*i0llsi@&x*V=JS=7GQ@hVV0w`-
td#$W2=*99o&LFePcYQf3%L?7WGUv;WVIDdObG#I0%L#Kp!H@7y;s@Y5ipBr{

diff --git a/Services/Website/Resources/Static/icon-192.png b/Services/Website/Resources/Static/icon-192.png
new file mode 100644
index 0000000000000000000000000000000000000000..d94836cf9e212425d1bb2405f6329e32220a3a0e
GIT binary patch
literal 4501
zcmaJ_c{J2-)c?*5!;mc|dsN6Wmh4*yh3s3#KE=pV$eOYYS;`WbF?NNJB}RxT!-N*g
z;FsOcP%?-zj4evu`Mv+Y?;p>-=iGD8z4y7#J@@(C`^e75jEh5r0{{Rn3v*KkCMW-Q
z*r817Fn5cM$zY-8uHj6M`roq|WIO@@d}bD=mz?g-{w%$pBaSZokU-2y4z)C2I!W}c
z?pEWMKS_S*k@Bn=%$bw{w-+>SZm9M2l&{awbCWF#vw2!5`Su6FsL*Ztl^siO7#|-W
z?<Jx+e4m%axcax1vE-RVQ+A@w?Al>^;6;u8p%Qw@Mp@yC%kCfSfP~t@e&<+7_fZ@@
zgV&h-O!EIr_DrYeXOq!jm8%M8ubi;&doikIYicPBv4Y}385mNV?u}_jIgO_xhcX<x
zoodYp*0U%@JC^Feygq{T4rTWakR1Q@8sa8|@6l_p7Q`%|t&eb4eppx(PjM3k{4DKC
z3}8Z>4WJ77U2r$cav-gbAh|<oX*hT(-__1LIAPSvb`gRAJ_N$w=SU+8i+#SGSIzb*
zgqcF@fL0K;wdjU9pFoW*dtA#uB8K*M!G(#m07;Q&njlZ|S2x!SrgesXT^ez19MXt<
z&_9xG;z$m$Cip3$%noPto;cu_cO*j=Kq>G}JS!!ayP=<0UK61FEe|nxp_#x?o%<t<
zhz8qdz41^`470FP^0+~nZ(q#!L9FPokS*N;o>+nx^ih;9_uKL4JL~ae<QMBS$%2;?
zr-(N$&%{dYP#(vFCDWgtL^j@G#{{)4o^^4GrK<)p;&<8cmEvI3MHR1lr7)9NMmPpU
zsIQ^kMV3XgCv{KNWq6Ew2I{J6zSg*V%n|F@$KXl>I@}eM84Sj6@t}>w0nUnt_T)?C
zJrM|sEtGK0+t<cUQ`yaj$Aenc6M&5Wx+#EsJ|S3m^0naObS}>a!98JJCV+muIIru|
zKRZDuF#D76n;V>&kohR~B%fB!vx93R=^_xxIvnLPvN4h!b3Cr}(2D))vT4w=oAX`v
z!CPqnlJiFumA953M^b7BR7eVX#o1&=k_m4~B~yA5E-Zey%oXG-7~_H>&Yb~*ryf6a
zs%>o_iqz~rlHDs}ruiNDF*96ImCJ9>I-FDTk+~A()UPKzNaD6lYzlBOl}9KKiwPe3
znUKJeo1B(}p=fqYO{?13m-!1L?%R{rqEiAj)+`@D>p@&#jhT}HrAG%br4UJuSh^)L
zIFud3{qwQEY{*gQq(OPed{Z=#EWI6sIIqn@79|V)%=H(7FL?M{yGQRfdfnpgWxO)s
z9U4=5l*)(a=nk|4O!LCN8WLKW&pOg-S#hR8epp{+hoTuYo$9ZH4<HXS1J7`iPfz8=
zaU9>un$_NoP?yN2#i!MfUE16$_zsRMCtq+)L?XL>@B-NZ?WUgJUFUQa<L#}_0GbUQ
zlbLKX09}{mQhk*5cot#FGnlI=>1v8H%5{+!FdS`sbg%3vM&>2J9vjYs$BKg`S*`@F
zB&$(>zI-`ZQX60vI<aFy_|t!eeRy;Oc5~6dV6s52&bR9kjUx^C)f{E3&3`zrFj-I=
zD2&h6jpe^9F>R|S8(97MD<w*$dHuq7pJx5lO@R*NTUigU_@-fbKpq{=h36Cpf4Tm%
zB9yrQc0fdx|K<IA{Xa+;Qeu_{l&tj3^{rfBK+N4Y8aJXit}g2%v~=}ZyK1NcZ99LC
z?I%IJJk(x>TpF+ny%J#d9`ndCdsHjrrUc;Ut{(>t`Z6V+^u_6CozPInSj$ULiwjdY
zn8yv;?4EVLfa-a5P^*Db+EK@!OPptBmS4qQPvKB{W0W^KWY``srN)mT5IlNJe-%{t
z(Men<XTw(5bBC{KNTn!t%z}UPdn2W;x!YO!3M4puC6jdz^w+}&*a4>nrM(Y^rH`FY
z>6!_&&R5GTKIR@2L&az58ox#C?J(}wYIyt=&|3P;jW*X`(EP7CDGz?F8`WxZ>!mrk
zr*6IR_Wtf4AVcpP<1+k_p==TPd95sLu*SRq606m2M*OCXg)huCWnt%>@5&O7KFFf@
z`hP6#8ePaw<h`6(_p4fQhhlTP!s$U&pVrSs{&plcu)$Jc(8}!(ky+Y$JuZB`zq6Jr
z4_fY==dfKXH3WT=_(EbA$iQqZJ(|jxzqD0pC91Gn|7suAz7U}T<4nA5q|VMt?(vB1
zd2IN3dhlDdi>M-(ByEPL1O8BKN0k5wm9{(L*4w^*UU;sLrVE_(1C&AbrL89lo)+uz
zH05{pnk?uyX65(f9?;epnQ~GdES)^2T%%a>oPL#QX?aLgKl{}f49rN7x9ZtP%ve9<
zB04;HwK&@M;gibrkb89wry=@mrgG~8C9xNSbyasL66nWYmHwSlKP_e4L$t_WcWPr1
zGV^-q9?ynuvXl|NAUA@1#y_3+YU}ufhmjX-FlGB2u|sue^J>guz`m4NDy6p)w=0JF
zq^B@QQ7reqdudttl-!7NokN)#rd?I#m_qI=kJ$1}a;UhT!!XV4QRVQ5+;i0Y%SJZj
zqAfdeF1{O69nW!)MigVs3yMzcS~@oYW@_WG0Y$aNs4uFMIaV<Suw>zaW9~0ND(8B-
z+CEoYc!m|;{pZ8%?(=fC6EjCUt#D*A|AFlz&B0KjP0Su!Fk1!A8DxX%;EyW!X1vgl
zv-Qel?rinvJAJ+<A6wqTRoC6e^k)iqxz4@uuDTVBg{h70)#2DsAc7A18y!d|uRfWr
zh`l~{#x>Q-`MRCz`CLM@>QhPQmrxt~8cn^LpsLKm^o_c!F>Z;1YAVOQ<THU+lF{g!
z+o1B0zuwT>1+TCDF^-I+#iD!$J}j_CfPIz@4fN~<PQ5><J>kBBtMSlIOy26BIda<7
zRI#<8r)@Y4p8sZzy|b>CB)5@vwTF+4W!`w7tWLa7zWB$zI+fY^ggYALMs&!jCmhO@
zP|8F%3eh1~(5Xt_2Xh0;Hlqph&cUv$4v)K^^O?di#Bf#>w$3B|@pnp#!&$pxjGz)u
z1L3*^nacI_Z?sumenoU<QTT35(smnJS&Y*zGUv7#bPC=rRijxzp#F}~cQ9Yhrcv$l
z7*?PSNCj?JRmE|`>d{07<$8I@Y0-Df3!lvfwqeionD%~u%A2ve-yM()B|im9ibmfA
zaT3gJhN2dIVxAkYE<U*?l~*R1`#raI)ft5sE4WY|QYK7{(;+2Df3-k~Zi*4w-Ys`?
z7D(;WP`I&&jqG_G-Dk_qZ;WP<9m&Jc5^4x`n}Pl7q1{t&B+(#eQ~Z$DXK>>8sm+Me
zp#?~Z)D%tO=-|=7vy_(ROwc6#L+6>z^alrYR&Lz4uqYezkLRo!*3CO!N}TJ4Hi#r|
zMJJIOWk1sBO~)V6@%;70$(GQqf7X7+{~d8dHJ0EV!3(iw%Uaidrc@HdbRPy&NMyCQ
za;1N{wVjj(_xZo@6&{<!9NYA8YV6F%o}8{*Pd9l{m9A@1V2a*$KY0pb&vlQj!)fE}
zF^hC~S?00U>}f4HnGui{IN}^OHENy^ob$cjNvR|oEw<^E1tJ)4h=_nT-&lE9<r1GH
z-xn(bt1S`4T3(TelD+%VA=aOlbDH#6$nCUOV*C;ScINlBxd<Uk?4U{@5%IAP+mGI(
z_P<R^hHF5Lnz}$sINJL{X2Ex!ucTkgeiB;R>-eQU%-x0#9$dOVK0HAab|l0O(>9Ce
z@Fq#Q?MNBAZAuerhHZLHrP|+6M=9apcw6;u_aO|%1F~0iFl#U2^UyfT8P$60yBXhh
zX5(ox&0VSV^wJwKJ{&0ny^$za__qg<222B)dD~&e$h~;{N10X~5@Nx|IGc$h&aBWd
zFFvgjZcQ$K@})D2m}hGwZ!Gb&Ep{`3`E@LWd2_FR_ct&wOdIZGbIEfvaJx8q?xv4-
z^e!T}G?fNU1K4R@9?uO^=*yMx@_>xvH7rh88M4RvLp&vysG~&((R!qj+!433!!rLX
zEbm_?A5z^WsWV|GU>_k(U_M@;Cb7yvb=zd26Z=52qm(88iMh)_qVTH<|Gg2FkMnRG
zsS!R^w1xZtzD?dU7#@iLeY<^iJi?bdDavt94{rGndNjqO;Pzp7{1s>&%TGUUm^E4A
z@WP<#7bNC|_RWS;bPn}y&C<$>=|^Gjw82Nhe7{nph3A?*-88K3y^{=fz0H<R7Q%GM
zJe}a({IzNxIo2Su8>w^Q++vrOT#=uT$Gp_nb7ZPU(K3vja{|;Yoe`bCR_&^>2GY3z
zNeUax6ySMsQGkakdHwVzbmQEEQ!*qg5^I3O3b(GGRa0P*bH-~3mi7tPEK%s79J0X`
z;jB>*HW5cw#}G(uayu0M?|CMaZj?^nR`lU3vBLPnaPJ4<NBMPw#TNWCZ-T@(59$P$
z<^`auR7a|M{S~T=S+zM6zn|HmEaL`>eK4<aS57Fh%3wV<U8$?5*6RPR6G+X7D2o;K
zLv`xTN{d{cRt=<^twI0}4ksiU)H-OkYy6T^86gJXC-imHNINTQS8!S`@SCU2d#WtL
zr^hEaadlof3n4@IF;lcT^}#hLQwu;|8)5kATc;-1l0A)Z<#@<Pd(U0@!kePJEDG!6
z>g!x6+}sRmaSVT_%&X}`vonn{B15BCwQ?fCR?m4B_jAcwrMvN$yj+8W?*td2cVRlM
zTM0+U&D_OZZFQYG?}(k>8?_Q!gn+y~JaM-K!;c&4*3qK83d}bVHT<)<(nzB)+n{C7
zKjaMI8vS;NBUF#I#Vd=<90tBHgA6Pbn>AYGq;9?6(9P2_gJk3~{A6ZX5D|qb*S1J0
zk+QIm3_1dJAn|dbR<cGjX=xLwj&zP4V}dwgDKVHnhpF%yj0}mEH&jtG>E2B85s5gB
z4;M>l3i(u<Rebb2Zl58uofxgA{`c{csehay_Xpb!H%=D#!tW>HV~BdQrE%zmPvNSf
z3g~b?7#8D>ku@Qmi0ynwH{b5bjcG}hM8a#FI<zRWFsnTGb*ort0<WO?>86NQb*zdY
zvh)FC+2FYm6M=*(-mH3aRP8!!-O`|h_gT**+5UU1-|$P))j6hxf0Z)&Cj_+OdjT<5
zR-o}O^p5V%zfyV4pDslYG)Kyu-X0r)DrKh`<!m-DCHwfjIkz71jEP6N<F?m;4A$()
z+JH$vRE3AT*)8cBI>RqkBh32FtSO>WRVhR!-!sfOc5$pra(}`2qMT4D_M1qoO`~<F
z()MoK^*!{6UVUBX0Xr}Hg&{aaOp9-Nbj0yX2C{3lgIjBWxNDivHRBReY%owv_w|_n
z!LoPuW2YB`dtprK=xXhz4+1M*?DulQ>EMtA94|NBpY8KDw9p2A$uaHak>#{=Dg~D!
zE%*}8i%rpdiGuroG`fg8*JE0k)0tE(6q(n25CYv3uZwg3z2+`*tcR!THBxTqOh0+n
ztGC_Ds21PIDP}CYeep<De;pDKnNamBLl4i7k;PXJ-ZVvO=3n!)ITqT~XFB_x_HV~%
z$BKQ4*DRo7dtI2T0dm$lf28PnCsD)XTLOR(d93xc?hwEC!5iB=x7Oiz`&FafZ%DUe
zOv_iP+pf7vcLm>;-OGzx?}d?j<wL6XgYBs5mSeQ-cZK8@xxxh2&<cD>6G&9u)4-b!
z*-mtEp0~>CH#$$SX6p1JQ6S#&x7OwOsP<Oye&CzfE+IAq%cO46F$h(J4>uZO_4*uf
z5ZkOg3cV%re5)PE7@rOp{lSW0nV)3JFThv(MD*6ol)+{}{UzGGtKcYqrVVW{GPfk~
zNBCW;wxT1o05sRmoQEr=2U06BRZ_b@c(ttuKacJ|pvAF}HQb7B>A+Tjy(x$14h6ri
zP5ef-<1c5bR|B3>0jmhbM?$p$t4HMhR)HIR73szQ=ZZo|I|0-|_mF)u6nmbzTLCOC
L+n6>Qqmupy;%#;E

literal 0
HcmV?d00001

diff --git a/Services/Website/Resources/Static/icon-512.png b/Services/Website/Resources/Static/icon-512.png
new file mode 100644
index 0000000000000000000000000000000000000000..6412cb0e8bcc61ba7dc75c05103fa6ed9fc1f30b
GIT binary patch
literal 13856
zcmcJ$g;$i__Xqj_0wP06cM6iyC8Z3~Aux1|AR*lYQiCYc2uMpx4k;-;NH-!4(t;w5
z#E|#l{r>KMaPO?enptO`z4zJm+4~I7MCfQK6Wyb`2LJ$(stQyW0I<Q2*uY&p@a>=P
z#5wpz;HF~i2>@8&NAOR2TKNkAh>fd4pXmF}ZI3;<hxGyoTd8y-yGm%qF?!hGM%CTN
zzwMmaiRF~~(b~Q$Bb}UPRBsP=5#;~>`8DP-uT^yHBkYL{T=%u|WN5$lib-Hdphy97
z?6y#5^0FCvcz>ih{T@hh88_hqvimbJo8GW=*Hcv4c%904Z4-wv7i|+hAdgyXpKbJ?
zD(rj+Su^B)b0(nG#?t+X=8lBB2bsAy;y&39D&up=zkEqauOa&mVwWI*EZ2pxtH0n%
zK9_}<SdD^TC60wrEh}HMPhIb8uv=h==U%S`N5h$AYc15}o)K<dx!5wd+fzddGO}6a
zya6u{Q*D<olY4p6o(X1@;R06x74oR5I6S;hPG@5KnMc%)*xv%>bz7t+i;q2yFOk^~
z8zm@|(`e-vNUKl&vn@+1TMt>lD)h1;Ba0`f9{>7UurW~G<@=&Zxi0G|5H5FdX9)Yf
zm-{VstSrTqtKs*IS;@2Ahhx}pt}pKChx}-20ktuyxl|^YdcA5L)J7_?;1%PFA|t6t
z$;fDH9!=J~Pc-FiRGM}u$XIv560)CXA~c_-V`F2p*7g14;t`d}vtW^sftRiT`9itO
z<fbqf9v&X8vvR`O*e!5%dD-F-y}&@qZcph8Vfg+OWK*2_)b7U9c%|y{#q?duULvoZ
zJXY8|0*)nFR0oAZ!#EmcHC(>ydHXBdF(YZ*>CtR%N~ICu;gE-uJI)?aO!H17mQ5-y
zRN+s4ShIq538@5OG(0Xc7V@UkT}JyD@q@60HsrRxd<YL$$&QrrPguxnS5vy9x1Nlg
z3BCS;kQnhvnq=$^W)0z>c>{mw${N-@-57!Q_I{40^Q&6PyFBdo)Of85*eMEd2U#*F
zlCAgreC`(u!b|cg$_prCgmt5GH2)%TetG9$(^_E9j<!XF0NmddSl+($Ud<P=IcZ#M
zS@0jN8N~$Iwgq>X^Zp&`AM&g}F3T^>zrvJa1A@`QGl4>>drrKjG35H*2^@PWlkeZ1
zWBy_TV?E1A8=;vgnju6keV8vfTqglhw$=Ic=u904*uUv&Ip_vSUx-E}HZ`74K2^;!
zLa0iIzJCV*A1FNi`S6a+%OO6=sPhMYd9tlnFLGNke{q1<;{!@p%H8lb(_gc~b%;t1
z?XQk$0HC1F^M*gNBS2#Qa44^h7A0+&z_lQ)N}h%dlH8}i(p0nI9sLw&z(vg&jz3e)
zaw`%c0FYU_8?(*Ug3J+-aBZRkPISWqzi(Ici2(4MTWDsf2QFvzOI#aPq;mLnp6?G!
zAr>%3-XazJ6mqhl5(GR{^vOhVs+h3%lkbkE-UanMe3MBLin-emG@0~+t90ugs3uOB
z3{<02Pj^ETicvAFt&S^oh~?03`J8qSP%z|87vbuL{{>I*&PC6k1k}?U*$)6-bu$hD
zqIgHo9R|0$#m!;VAi>{aJWB%~$Z_n3FU52O{BtnNLtQ;+<ph=M7vcb8Nd}_M4v=~w
zkjtrYuGttge^}!#ki$#qcTz$#q}<$Lu=E8b4FlIXRez-32Nb5cL$3tE?T;ENA)xIw
z2{J1Ja5Vrhw^4Gz?}BH5rwW}a|JuWe+EN28Ara&TkQMhs0|oGogi0sRiczs2)*}!c
zKd^z{bV4)c))=guyC;Elr&VA`2GgiO^JY%`ul|dFZ`E-3FA);mNhMH8R-$M~2^KJ6
zLAyOpGt}F}HnR!yM&?h0zRw(*004(a_1o>%f_n;as8&-Bzi)w2x4TW^Pe)@rTJ$J$
z-D^==iR%QXsQjx`CP2Zt+dzD*p9HXRF)VSY+}Ydn|CZVN4-`{+_e3AE!N}WCM<S5c
zT!gAf2AM21NPwJVgZlHhxQ><|L>oRRRBZfughU26HZY-;HV+d@MYL_()}88sCWqWE
zMoQEvL+YjRj_%CW7S76R!l=~`-<tBjlKF85D2|c*&?<p<^wPnGx_Aps*FxaN_TMti
z_BqWE`4(0kq7?K7eHtgAz|ZG8GRuo+N*(H_R(}4sjUDD42GU{@PHa#B&`&?KGeI--
zgSR;#TmsAD!#V+iSPvIav4F&6SP5!ZZGw6C233&+u5;b4&v_cQ{N)##85Bw_GWMxP
z#ipziG{AIwys&@-O4E}FnjyXNp&e6)z2~4EnuUbGhccRKQ)@x(uZDx~L{9W33&2R+
zQ(a3H1Qa~#8K-ER^dKADhP8CTWhh0CR#q^r5NX07EwaVk0<t0Yo2d@b3?8>q$Ob^J
zcfk=|aEtemEy4Auk&mF}C*u^HM8JpWj_w-bh>peZjuxsqzG8=j{FK`OCcMG{IM~Cs
zS80YECmbwM2dE}3Fb{(TodM*_E;vaK+@fe;%r_ggp$b+S+bcYBeBk%j4y-{d!AkSS
ztC~4~GjO}5pf`Yw<qb8b3iTtJKLg7=5LTxE67*UKz>57!<Kzd~sN-vp*PYB2^Ce$y
zNR<H;xZ-Yvgi@#L*j~y%_rDS7CwC$E0SZr@aWEqb^^2L8mV~FF<Un&>TJ!rgSOEA?
zqoWyw%383}Q)#d*AJu;=Nu!Vy5Zo}Rr{n5^FXAe>I*`DwLP2NDr#%JGsl19OlQcuk
zxmM_n(k+C;J}26XlME2Fy+w*4XXl0h5GhW)>rV4Qjz@wq08)tjs7=pGa4*jys7=Z)
z5_PQx8sSlR%VSkV4`zPhz=zCoRD=2)8yE&7&ijDiR^-Nzs?f|RNJM#DXxE)ugJHFN
z!Gi^Su7I3;0o7NPyThkeQ0E^(E#3*7!f62VIb~?zBfO&uKG%TfFxU8hgdh*|3t^DQ
zR_RA!54^GmzF1K1HZ2JYGzU-6E}RMSkcVcHhx$nvg1`t9y9H5OReYgbkU)0iWDMCb
zHy^yVfUR-J-l85GCj}t5n&o2KP8I457U$pvCVhj|zZAs{63Gg0i30{}+TfvM=z?=l
zX$kdehi@N8s^S9C#WdSl78pRMep}gLPYXPlp>PR+B&(_RKAX3$Di=yURWZ$Sv3Xyz
z#Q+i=AMEsZVFS;gL(Wei8?E~B^Vy{ik@-Ym4$F1@M}VBzLpEfm5*_w#!F|cb3JYik
z3m_8|WTmutMg+@z2*x-u|CNRS0B`u%aY!@dU)!!X$&_%5ZQ0fy;Qk@=HLI#5*-NbD
z;9Ga29KdXB&i;c7Y*(kww}1?d)i!p;sOO;)Sg|kPfD9aAJz}5&pV@MUJr__+R2m#W
zYaJEPF`J(7F#}GXkUdEw*d}Q7MOyxWhA;px`j~ql7khJ)WL}0UNwA0q5h;k17O2v*
z8f@!XS+a16D`|BF_cuqV;sM)Ll+!a^G}{kiZ!)Bx!MMQV_`}9c)9e8>aYXsHDDia$
z@8R|q>*5_6um%wV<V3&>t58D$!<E`2mkV1cj1Yv>pTkfbAndqn)%c<dUg@@93ig8+
zuw(VZu8iTAAjSXUCXwNS^&)Go*)W02EUF(5xKtCGab`GYoo^9l2+Bc?+(JvF1UNJ+
zn*7+#rV4Ex$z^U578TH+Y)cToHBOe30T?rgpT{s@UO3DuI_%AZfw_(#zz1q!Z@0M^
zFe|3C#K9>jty_Dm^8-^o0Ca}T&jI47j(WFcL~;A`$vdi!w@8t$iVw7?LSob<w;vn1
zI5L|FBeY@Ww`fGn$q4Loez75OUqG}7y9VgMJV6HMq>n;70Me4@@OqZvICJ;0!`>4x
z5Gg_jw~Hnx4~WmT8eVzJT{xr8$w9)qe0L35KtX6Gk>Q_tu}wB?@;bo+Y$gb7JrY3H
zrD_tv*Bda+6Z*60#06{@2%JO`;PP-OMQWpY5#AT8Gg$&!Ca#kH?H`Up++pEKc!z;!
zAEK3QCJ&5)uK`#t#!ldkqZq^j&n`rBHbytba54$xN&W&351%8)jJ{zlT}8sVO1AET
z$1&w#>;W5P-0Vq$Ipl;5Kj6+ljVr44Js3BBI608h>*U`byC!SZY9eaa27^)GX25ME
za(cVqH{Vv68V6)9qEW;j{xyMBzx0wG$WbnP#Z--e)Q5D+=KU-<ak=$4OdK0{4gKzL
zDTnXBZYm|{nEYP@ZLk=BSr1Ya$hI#Swx1U#5fwW;QXK`m+Xam&7GPdsCTZPHvn@t^
zQe5i*Hl>PNSvcZ2K$BUTUG|DjoE6TjKTHhFng#j<V%x_+PE<EsenThDLaEBNxHbDW
zjo*U75uogROdQ*>xU3WB@JRlP@01*>$p~cf5WfR7>62|AG5r2s*+-vkFc|`ZEnL79
z8~BMixw&HaE%b-@e+|@e=05OSI20$j8*VB!Vm&_P@gg`IH3D|Y2CZ>uJuc9s0*Pr~
z7mPEvsTu?)&1EIfxkX?2fiWd3mpJ#--s-Yjm^0@E6N&0}JCux0+4DnhTT*!s0ZQ89
ze=t`q28`iG8q}wTF2uX&_{ZHE@Sz+FneKTzKfbYEh!>Yx`Xr(RO93hV;lm(>*EFzw
zn0438rm9BYyYFNZA-fW5<qzcaSXDVnbusddCYQ9%gV793+W~hUZd?)w&3H1b#@7Ez
zQwkK(_bvqER+n({G788Ei+neGA%!ORIFAj}O!$`oQb?+m03Aipn{LR*mSo!{V2*vg
zZJdZ1HlR2yPs&plQlEwMNu_aEZ&C)dID<peIs?dgHn5<zxnHP9Tm5%paqSi(2gR`z
zV!A&399q#t9hX*ok~4-8g4Of07hKmYv!9!wabj1ND33HaafdOQ+~OO&6v$z6y}4n<
zm*@vaQxT5i2Mcmel)!|-Y&EmHQ=-%DWSU6;BKcR!Mn=+5=Z%>{<1~pj^hXe;&75qg
z-Ru)xr1b6qH10w(KN)6g>79-l2lKII?dK0uaIU!S$9M_325{ib55#M>_Gk|A#uyRS
zG@4DN&zy9!2+hb|va3L$&9gYazFo@+IL63)eYu;ZRHX!YL`Jsr)HF(_`L&<th=tii
zI?v&Dr_hW#L<A(j{|+u_P45?~Hz|$#UDkT$Wzqh21m_Ep2`E(bsU@aedAuee!2kJp
zV*;m}H~HnSdbZID+piJf_7ZJ}%v^uQEe~4$ttE^ki)IaGqzca%3(eq#Wrm0Q9P-}0
zN(g$`kI3oe$Yg!RkRrj#i*Gy3<Kh1{my2y{CvxnoJn@jUS?6OdUDkd?wf}>_@WG4^
z&hqqhq2{C5q+|z4H-eTJ%ZINLIhJB}6aFz(xIP7&JY#6<H(^q;V~s~WV`s=P3D~%<
zs@xm?L@$PE2{Id(z37hQ8VV>h;8*+4?+FGfhtD0-@+~*9xt1fkYfd6^-N^}`LMK`+
zF|Pg`TAhzg$9WS1K7#X8Nq$g;oAk|ts(2e#wykuFaK9yPx<wAvX+z@UnLyIMuiqG{
zLK(?JWrxQ}$tIh@3tacNSrM_8Ak{dPL*kRB{09ldzwRT(A`3NR8u@KP!o!=cd2fDj
zl&7pm)V{jF4+;I+!?;@EZewpo6Y6Z02GVzVZz2-F2|MDXI$tT_WQ`5cxBRW`wx9A*
zl0BbG>ew}#+>+Pte5^4po6v%HWd%wJZ0uvKlFq)WpK-WE;<B@$t_-i4Kh$a^OqWqV
zFz0zCY}n{|^I%_k@EP=@#-pwenPn?6DH9)Sl@g}E*3HY`)mRn2dE~!&&TbgEw9-qB
z?n=FQprg2*xm2d9p@RHq#<I+UT`T&o(8Dxo05#XM^|&FhMt8~U?WRO?t**&Yp;Cl?
z|Eu(m3HP7sZS|<;5Pd9krg)#OKHa=2;b<M*VYb?gXeBp}%;R|3VmGoIyLl)xe#Cqh
zz=ZMlIjv1QaKI!}bPmdSp-|?YhwT(+(qq3_{|3EDJrOY>OqnQsQA(17a_G&zbj3XZ
zVwk)cW|q0a=daaRAO$pq0W>h!{6?G8S1)RX5fTgoK3(84vHX(-TV1|D8CWN;+(#7Z
zXg86Zq^#*pTI1a_y0PDi4LE<xJTqpDxy{q9{4z+2P+OOom-I<>QE6%PNcWuYn{qe{
zwz>1@{@_$&ND@US0kZ*YQc4EX>&Atd0T@KC<$pDVn3j3bt9%JSM80SzDMxMbmA`ZS
zC4+f{(`LVIcX{XF*x+^6tTDfNnw9Syz7ec$xnDjkzNeGV%C-XUdKA6sLFdcxbxL>i
zhBqXhqO+Ey2DR1l=`xsF^5u-F&pqEU-BA%^v4un{-_G|YFz=1T;7CKutfTp>3?jc5
z+4xgNzr_VD%rRLMoi%dHC{&Fc27lTASxc2EvLLxJCR&bWWWb?dSnf9pCI5oIMOuzw
zmxcKhaHTtV%7i6uvi3s-l_Z~J<vWOP2@?wt+3XJ%62#V^KYZG@PIB#i*SapGgJN(#
z@C;U`ojG7tybc<MpC!KfE|5ZU>ClJN*rxlwB|))+eAeaPFP8*|?(|jD;nW`YX{zfP
zHDr^gifD+XA*eb0gPUh3o4kveM~ZTaXaYrxK7!>=s(QjchtN_z$fy)4YVHTu%{{`j
zw5X6^F;F_g*Rg6JvI`!^5mljpj$EBdCQsMEAIm%IYqrZa>=u38IoN!)#XqmqmOp&X
zMYVbyp3Yw#?Utf<sA}<5I#-$~I*W1gP=RiT^3-R_>=rYwSSh9>Ojfn`N6M$ar7+xw
z?Fb_@C-CH-$yMO^fWFYeVMnt?%{Euw5znWImEu9oVUinSdXrM(<BriU!1GQcoB3Wc
z>o5!a{9r}nX{KMNnCY~#9xT2u1xnuoc=@cEg~Wy3EFxFP-amsq9x^}PLJzN7Q|<?{
zTb!-8(@OqeJ7JB%Bi#DZBGm1+@csGZ50~<P$5dL^?L-WM>+b^SjqGsW9c(SfaEGk}
zB@Wb|E=LdNuWAmP75WeR<7V|}TO?tf<izo)`m1$I-k(sp3hXS<Q$MjkIUnTr^M(k1
zv`Y2(sPDa49@dMPHn4=s1>w%Pb`ko~oXPTXi6l7RbJXM8anI4O!_m5q3W;Ps<lZJk
zizRD%)YRxUiAJp~G4Q}L)&B}<)VhJCH)GpHc;N>xQA$jHB{P)A7p4}u^0u=8RU;O)
zQrgVpD8RwofbAdc%NhsJm!}S;*OqvhM!u-TDZI_V%^RPakF1YgV!PCu3EOQ4vG8dN
z1<bSRO&VxlmzbPC#C*MbMh*I{5}-EXOY@`y3oh_M4vPQNC9~to`ppyg!hbo0O=ZNB
zX1F!E-%rsQgs%n5kTi~aQT)A+F`o!61jfW1t<0ZTdt{1jSU_|ABUf)S`%9L?3j4Y>
z?fwH$x-;5_N_B4JM#ig?))>N0oQ0y2#8?t-3$DKVgw2C~s?JfARA$g5(Y;@YQ@qum
z9Z-f(Ondlr7f0@eU%oZXyr_=W<i6~CoykP`VPkBWm!Lx^+}?G^$Fi4}86`}rWiUb~
zudA3k4YxWC%@yPZ&_3*PrLL#hFJ9$;F6rHW%pHb9obNFDx}`hurWKtL*7Bher`^do
z-;rji)&XWfxP*8J^B?&L>wMqeYX!fPD!%^i(iL8y6klOIZI_&#X?0c>S~4dhH}|bS
zSZcqP?9sL&IxQL6l>VBpTw932Lk8A7_4(LnQ6<O)=LF2*Yv4?CkX2T(m1;4=YG&mF
z$|sY%G)W#RM}^tBHg3f6t?d4gwbqSqz_0%0QVAbcXUcb@XJG6uhxvME#-WR_8P_+Z
z;6sq_1GgD>*iKsFO)oMf<~G2=aN2xV6(O^1tC>GzD4+C#vUiC$*l>2Yg%8w+O3Q&%
zPtIe%t4T^se(NNza40f5_aNlD@eEOp_I=R~`D90s@A^vA$n9_<)k<>X43#AwSL=J&
z&O{@!`cCGalh>6}P*>MJ`cWZG52Mv&{e>>oATx{n-;hqwVcyG%0&RVxRn7J1dHVdp
z!%qx$`Vw!X&`b0O--0N=q6?_gFiB|lUgJ7zt?SZ|O)ww1u6){62%`-L8}ex^e2QV4
z3n@LycuU$ryEw#jV07_Ze7-B0ysV`XC^76bz&G_C33%!Ba#`lkovLa!ocbgK-E8g=
zZ`^wSt|E6Bcdu!kGuKTi(hhV)Q3x44o=`v-Ki}xw7Zqm6;4x{y-#W9}f0Kx&zl|;y
zqG^WBbI8}s&p7gzGjWrHi+p=!^#;S?ml+bw&_FPLg<FZzM#M9loz?%<(^`eJ9oLN|
zaNQYBEr)T%8*$53np24U)vO1(V0=B9?Rgl-TlqlVF~kt!$GU_U^izrImB{1L0$x3c
z_Tw{@d^KG?Sge)+1WOOpe?tiQ+Qn9MnuJz~d@%<UbKNYML1bRs23B$&m+B8t?eLYW
zdq0eIOzz)1^HY+RxXS?2KG0<(K>M%NNH3bT$)r71AsI)~+H9?B|C`mhf^|C_w;?dd
ze()G|-tpZ3x101l@n7gXHkwliO2)c@-zqTL`WEShRbp_hAGyM>n45Kp0R+L6^6PRv
zjq+mszb--)c5=`kEbG<>O1ud<ZO&&iS2HmF(q)J}N6vL)^5@689l^daSh>m}N9H>5
zOgT*IfAt{vL=ir@quO2LV(WIKGcH|(QUs93R5saX2J~i`R=y)S_9WSt;6IUs*WY~t
z<W_Yf|2^coQ8S5LA?#6lyns_ex63Xc6+#Az4aO7jVpTdvmYH04Qgo6je$KR)4O?Q7
zH^d&L0b2kTB|NwE;ka`Ciko@li-~3XqO@+or*gY^C%5hJ-oozv$ba0%{0k0lwK##X
zdNqBnr=tU0A%o@$@p6Sso!PYXJ5cTGSB~jNy=W%I#cD3(MTk;Gwn{eGyL)Erxn3V`
z>f4Wa<Y2WBx7f~jV(9kOE3(2rzzjZRTcwJM&qde@$@G-W9+11wuT|b;j)PsrOqL8Q
z$AaiDB*v!-U;FxjdioLVB5l)p_I2QU5-htWU$#SQU9o_XK6|dmU}w*fLWmPAiVEUs
z9Q&Ou;Y~Gqu^kfYLcG~OXF5@-2P=6d5AC;Kslp+tyPapj)ORaBg|~#BU%iM4`7YoV
zt#<^CrD4M3Jl~$b+Vl7Y&7Z~GXh%o+gj#3d4Tx^WncQ77mAx(veIK%f_z8Vk$P6qv
znAOsk^&UP;uW3?vc#2hdYIJD{RJhNARLdLF1S?6W+YMlyX${kKw+A6|@K<jTXx$V|
zs4WM*z)u^a+9;XVhrG$6o36IBV-U%?cPsKBBz%W*NF1A-sejJ<xen#O<Qc})VIORt
zSTbs$V=B_ZYoU=Vejx3oZ1Q#b1|LrB=yM~kkT1k>H`Zue0g&Fci~r3dH1DUaY#4#o
zu-?%=`Ej!}-(@12v<m%zJRW=VX1s_f(&sbz7cZh=%n$4*JB5~v3%CpGZz5D)=tAOX
z$alth(WJwTL0LF0)V^z?-8b}Tn~IchioyfIC|$@!OoUH~_V_1U=kx6IJ8o5)E7`XV
zWm+9->wn$eA8t?m*zb^hO4N>U%s!FU4Prl(c!7Lu#!r?;uFLn+6<V87ZrCZE?#Vo6
z|CtLZw0vhQRWTd8!tD$6<w$YwzU4D$^W`+wP4b4B*~6ZiQ%ONN<=`l|$iCvquB=K$
z_0ZZG!s9(D3#q`<4?~|CxI)UX*4eN<ly!V?^1fm}^?Sh%8?aR$!1hv~*J#fqcrvZS
zlW*p_qC1Fw6NPLj%LzBbWxdnUKji1103o=K&4K<f*kW34%;Bb0xarX}`sX?j6?CI_
zB<Hu7@?+0)#K@bMj8=&ENaWOQ%IQ02-b-nvnyF1%r50tt^0O0QKx93)%;3#KM(dtS
zB$rDBEqVWs!X%c(f_~ZY6E(69St%HYJ-nsMmJojUS<jhCO*UU&)bhciJ5pQqbw~=J
z9YBS%HjxYEAY1&gUS?cAtXPsLqtNo5?C88si`&X;pK>{SG84-2{AayivN%yeY_+$N
z+)RdV1Gd~df)Gu#$1>cTlT7tfP2;0iKXkUX?T~~K2%%-Y^l7B*WD+#r1Rq&2C;G8T
zP3UWcuO3$R>ZgJV4z>u>8n-E^on|&DapW*>G+Q#vcMvOk{8AxP6?%WuX;;IUN=>%#
z(!p^x5NDrzm=I0l%|)hq4!FgL6BY>Q2`2k8-wB93!n$4kShHaaZqM9sU)2OGa0Apl
z>zWe7IXFMbTc?W?6vX~$uO4fXKiI_!P^)>$s0O`HPUVqepQy7XLrv}~u&nnf?bbba
z?S^;eSU#R>?TW8z;)AknytzTA{vzYH8&(Gi(xYJ`jzhky-dJ)4ekz%2&}U`{Rz!<9
zegT<oHGdK5o(Z~0^a`zi8?NUS@G_9_#6#?01P>G?_21%1x^kV+L!yMD2nm9jJ7*s^
zT>cAfD`tv&B)xo&=HoL}?F@o&#3Rsqa&SX$elpsU-WzIrJsmopcguub&G+}YM;f<G
z*o1ZQkq_o5K8C5WBB&3DaRMSeLz|MrAsMHlQuO~E!2Nuc#~Y{fY4(~5x5AFmlHQNV
zXsINY7z&3KUiDF!%4xJP<H&VODg9K3hCSd*=dGoENR;kMz88QllAJE~kLauVn%AgI
zA2OcvhjWnv&I?MpKbB9-$);FsyHXZ0k}l_bN3FAvA3=J+1X}1>+>{y)QPuuFG{u=C
z>hoqWd>ZeJf~!&hWLPc3#EJt2UlL8#TGoK<Rhf$0Rau~H3@=C2SKPa<Vf$I_ceFI9
zd3ft3oA5*4P5fuWmd~RR-3wA(&A6b^1zWb@`bhd{DTa5z@<?{o9CAisSJIRg4pFlo
zW^}lW)YTgME2|03xCgF_2pThLLV2oX<UK#t*oM-z=UwvW4l}B?6oJ~!aw<64DBZ;+
zRW&W2FDB$+gb&)V&M1l$%|Vv?CO;|)D<97PLUdiQfQdnbzT+)UM*D#`RUWm%JK!^0
zjgqw1&Wphp$Cm5He2~rv-`4S+tPRW*yK*>-tPcG4bXR8eC(#+jrnI*N*=%kCk$`TE
z;m1BR?UqKQw)^X2cNQ{Q`|F!$Vy~4VhAac{KSzi&?sJbm-*RKS-@i%wE7G={t~C$J
z#h3ayVjB01q8Bw7p^~5Vbdb#9kX!Zp!djW1QgBr5gH+`fN3fRo3{%MCRVq?15MpQP
zn{^4p!^c^LyHAfoejSKhY3e2^ha<$7^|B1SrOEv8?L1FQI;Q_Qdy*h1O-=j=v*q12
z>^0kD!V24;^NcUmz|VuA8FyMhXKV_C46|Bxi`!dev-x<IiB81juY$b}R;(jdA~&u^
z(p|2~9kQ!ZFGLS^al!O9^?pn?8_Ro#`MGDMYLoiA<h5c2O!L1AnuYv!;}|_r#{Z?R
z0i4-ehRpBp<&C$)E=;R~&reR?GbOjB^a-;g>Xk)ouu10&q_&@2c`O&3>-gF))CQ&s
zK4L}FG+(HVn7VutJUGX}mrfo&b?4u$`y-^Y!dn{Cic1W+9ykUuxkvB~a12C{x<7F%
zy{@0sG`dSgy4MSO-2&IgV3V9|z}n7XYm$D?8oq~f4Ut^FgSR~QCNWd2^q)k9Lo(TI
z=F8ZX97Wt6NpGGUOJv;RmA82Tw?+<zXd;)AgWzO>OsmHmrbTb3F5|8jC)F{sM9>Uu
zr(64RyyfEYru|}Q_sV9A!?INBKlWZEZ`#FL!}-yB0CQpyvXiHgrTDmPZW`+m>tg5a
zp@3(lIFX`Nx~6|i95z%r?)pcTGv^3XW6|^2&t)Jl6=LS=ei3_2$yA7`i2vde=*qx9
z`?x9Ttq_m5aj)^6!v?$j;_1+vKZ!Imi)cng`vnr9F(hmI?NsgGH}Je!nvEh&mbovW
zH>psd8bP~ZVX;FphCN<9JH0d!<l>9P^(;bBBDansQM*u!a!o63EG@1%dpIMQ^psmj
zHX;X`T<>5z&2~D>z8+7irM~2119_GGos6^5kSmtO$bhPbnvP79A`W7pqahqY2qszR
zB!Lp$hnfu$hgBHk-s5||;vt;ZGH%3OM_GjlL>nJ({OfGl(*<rz_v5CT_tSVh3KP#7
zy0faoKAoP6`x^Lyw5v%QX=x)HSz~iCW=(S@9$-2D15wIPCsQZC<Ba&(V@C@e9PNOX
zN-3+BNBtj>i7XbFRTCo!)t}AmcvTDm=|L8DK;#b+4VW^;E0z~Rr*dL@xg2+!2^-hm
z%Pyt_=vhLxAqNB0RNi+P(k__0n(4sW+ngX%qEqQluPpK75?^ef-cO_uJt+$5WVL8;
zUhJhD8m(>XRI|J^WRxNTcmLc9XCvw|KJpjajjWO5TOau>TvW8}=#~-U1K*Anxa)Gk
z)J1RdH@Be3-j>{1riyHzTZ>sx)%<xr)?3W0=EsiWrS68Jn^%K}Utboi1#-9jJ0=xm
zTs;O`w%e3UsW)?gn)ugPUj&xiFDb)Jkn7{U4KuMFtfSZc>4Sk;&mr4=;RkJ^8+9QT
zOtps@dI%m%(us2tY2G#ECzxr-L=VwcG#e3`awr(}qL+&=oy%~<(QlNc=VB2E2s>1V
zZvmCz*TprqnOnJsUDJ?q+Tw^~w2`-Ry!2)ncgYK7TSv@I5HG`C2HpbxS+uR}zG`?w
z9w~!P^@ap0YCt#03ffWunds`@ie>XI(-*}rHCFC<Ah?+F&I|Cr-?>R!xASJ1bFvTF
znBu!M3_c;C`<|j?ulL4M|8tOOWZ~xkq3Ul3ZSz=`c7DW?<g4D)CUG89UMLHn)Zqi~
zE@Rqa9DLCd^~i~mLv{6u;-#V2cAlGhX(ZUCSeDcg!G2><E3b{=iVApgvCFDn^~M@B
z<L*D39AaWv3Ps82K|2BXj6yv{sO1CU#gr>AtX=~_rD_Xr3Mt|<#nqpQA;&lA(giAv
z_crnEid9J*TK4WP)1s%nS1p-DV`+ZA+rY^j{#o?;wP~cSbAYqE65iCckhfa=c?)pH
z93!_l?VMpJRP~)~EifjP3u)Z7k0I}UJGGuEW?GB6k^M!@L$)&(UFKiYRG^aSJ|*)r
zN3${b!&+cFR?AbVN}Lp&&*5ZLL*GZz1)Q&g)l2N#)M`0%Byb#qN<aoi<2tm4^Ta`0
zmAw{Cm+unq+&}gj3P~i5`3`@xl%vZ8)^era2VePtZziSIkrVN{LT4$@z;YfAK7EN-
z|JW^29D{XqUl4ya$;mCg##ZrjyN<){m}b9e1J9JeN}Lo^+Im~FF%?F)$D2x6JoF09
z<GdR>z>lV|`da^IIOe*pU-!G2N-Z~f3Q~4}*-B^gMk560jB6^M_goCfBLu4m6dqT>
z=+8e?<DC`V1M}Q@Oz1~O_^A%w)TynvR{Xi|WpG)~Mg0-eva0hcd%^>>K$n|yNB>AV
zjL7${@0WnPY;)5hRTcC|f~_nz+D#|H%8`tn>fMtmMVgt1@QR*`XEHz02VK918??BM
zj}pT!XmiFq7{15$_cdkZ?s6x%KX7D1Z637U&R}>`kcFaQ=`ZTmhJe1?6F2Kl2JCx1
z_nk%et?;IfO}w?^A*N~BjmnvA#RU}gY2+nCjp(SkVsce#HwdMNb7SZyu{eo7)@Aoq
z@0W0A!@p|^Y_wE!%j86Ii-^zSf4Zvgr1r5SWzT?UDuKrBxIWv{+@FmuJ9xg8$3_dg
zmQ-aFn@CZc3P>3EggR*Js-{XE7EGEm(e@VqU4Ep9?uKTh$CGFndq0nd9A<Ia4R4*>
z=QkG6?WrpT;k87OjT?*lH@?BVx?%!68pvFY@un`gy>;UuJi%v$9X%J<SiVm)yx9DR
zQVB&Lxa;uG!eeVTCZ%QWIEA<84@}Y;UwmpRQR$J)xX|qh{u_(}3yL%5^g;Uj5QF;$
z>2|i#8UA^@Jy_0z+|bAT?0<vPz}+XrfI2<AW$!1tbuOR0-!_MlMm-4xB=P}A%Zd=`
zrrL9&+o|Sd4slSa3r_;8Bh^Uy@3KFGtG?Ma9jbJDrG8JBB^@|wH@pl5M<@GPm$kc^
zMR4k>aA(xbVI1tAhBMQ;584j>32A0r&_r|jiGi)I_jaqc*UB23nTWAuojF<N3TR6r
zv`b1OUv2_!nwhbunb>6$oS7<F_#=hSRv+En*pPNy>^m{V3VlRcF2-Kx-rR&zc_!(Y
zHQaY|e6tt%)D78l;gDqsT*T`ZU^-UF#4<A}JP>5AO3w-vd<^U;RU6%|qhHb5M+Sy6
z>|KCyeA|1W>+(yYXt#FfP0lFX;_vWYgUI)`jChl@@?D+;j~A>6)w$k_rx}mENY?@b
z!360~MEm#A7!GBwl^LgWq+n;N*47B?K3XzFP^wCS_XBU?MMRwVA80kD(Vb}a&ja%G
zQjWXBGpx(=(2Uf0#a$D4t#p}+8s;*>dLU(M{8X6Yhe+Q+n>Q#r0w=aI&ctq_p72eE
zum|v)^H~^ib8pFDWWGLljR@%Jy{MSx%rufl_D`f`VfdA$9i>Iw@7fPCLTh=2brlIG
zZIpBeD5EteeJ#O4wb7dLwX`xO`J~P0Z`<)tHFua_>xPx(Yqb4)+x%qd|27*R*{h}h
zyehzy^Fy3kz!p1Pi7XKf*X{W9x6Dsy*t!zxh;3k(Ur4N5M5&s#81R?EZg`4LqERzf
z40Esd!WKKuF;R=-Kjg9({6BO|8COIXR-7dN3_tlCJu#KERnPXv|1$VVOvb#&?d{^A
zE!~dRP35y?7(X)<M8@$`3Kj(M_mM%BK-pp!-h?(BbV7Q}>FmO4ICUme3OK6+y*W<8
zhu!nn5(jvT>seb<$ZPW+xku(q0#|>w<rEA{QHfkk+jSZ<-LXAscvO$eJnm~btcR^N
z-u@P`HI!kVDJD_)n+;xhDoVDK8$B`4083U;`^elnos;%ccg1(90&V3y9ua%GlN*ft
z*r2*YX(XMfMDkA8jsD4T^u&TW>S6rHyHOjFJmOU;>f))2HnCVuwW?eRDM&)tRg$Ok
zkBm&QcI^&5WF_fNYV?E!*v%;)Bw$zA@2bxFE*Y^@f(YOtKbAMZe2&{er#*BTYyVl~
zpU7;lz9ySk{r@gYZK&u|Z^85sMu<$IrgXd$_96Nq?0R34{u6lRhJD6CC&RjF{qL8v
zv)B2yqEzyGUPs#cMD|>40F@4(wKxVtI`t3OxrVgoTlGb6U{Q(+MtzyewWGGbi4v`0
zN^D~5Wf-k{Jr^gqyW^ahGc%J`a66cP9`zjw0}QE~?DrG=a}nJPuF}^~2Y<jQzR%b4
z%dbxT4Qn*vZO(h5-@|_O6GoMbn03e)bmO2cSA%t}jh}6K#`7rWKQkC1(YU`B_-lzv
zY|-#&;of!$Ph}Q}!e?XYCl2PMeC@^I_Jkt;{QhvlVpWJF9px-PAGDp~@c!q+<GiFf
zp1QiMtukZtckXCE=wmU(<JaLl&+_q}I_}cs+Wx!95+{dPwYWx!Z$S?M(&B2z${PC<
z58R_4Z%MG??mIJ7v9gO@h{2*%lK4kQ88*vibwH#EMatWQ$(a!%BWRM8Sz+ju0zOIX
zXrZ~4=REr6&js1eNc6<6HHspBZb<0j#ri9|VgK9HUlK@~QD#~c<VnrUE|5no;5^)r
z)2vk&(eM1B|9}lfVe-S`-9cL*@^PIim-M2<^T|&U2t19uQ5|e{nm2txOfz1j{3*F6
z*Kc^B`H^4~A<11Sa~DT&CSi)f`WiG@W`=dA$@pelFeNhf4>rUJ$OZ6`3447%F+@S)
zc?c@g>-R{nwbu<|P7Bx?u=Mo1XD6LAPTi*#WUb_JYSYLgPBI~_d9SN^6!X<w1=Q_Z
z_Uv=?ZhHY`YUx&a5#gK0#*uW1up2of9P7KSU2)r}AuL=!q-LY%UdABKuM}LNDj~4V
zh>~DQ!CbDmhe?PL;=Z=2?~ykD4NCbvt_EV^97F$IG<N_Zn<JLq3#LghWqd80<<fPR
z41zqjwB`lwp63=ej|H%N56X-;SpuRBL8juOF^{ghai`7`&oWh-Labq5Vmc{3HzggX
zhz|ZDQ%H9XA(NN1DD3!`n>X#%U<!y4+G&=#wd@sv4QKE^oEql1X8imvvD?(b<KH+)
zF$C$(2gu}A9SVrQ^G^J1N3i!|1nW8vtPUBHA%mo?H_N2pl)=~T$g-jOb1Qn{#vzbF
zg@ZNIucoxd_Qy#K``O+tWZ{Xct_4PHY@&lux-T;R4><7;D3-nQu1NQ3`{Pag;_rNY
zx*y*l8f_@Lm=f87H#B*JQTb>`rID?F{i>oGM`52oFA#g5R`p4#K*A7sIR!lkW5O#e
z6}Dk1cq27!e6$L@M+)R=j*PXh*qAuS-vOHvBRHf%mdQY5c}X}%9IXdaD;W43<hr;L
zp=$W0AjzHtTaNJi<44eEMuz@_F27P@b<(0h^+r#ZaZoC>_rSY%bWMkh-Ei`6cZDNY
z=pc?9J0{P-B>(&bZ+DC{^SAF3M^YNZ&`41Ev18LB_-Hoe(4+8^AhaDv`}ccM`qS@`
zo3{majP~OZqCF_d%4=M4evfS1JQ6{yWIn_BEBudq*23gP{Q3@r55xqcAcE~m;l#J{
zyLBr!Bv`UaA{q7)w>m!>7;qSa7veI|@h!w=#L>EGs^i}<B86aMLrk3=){=ae!#Rsy
z_bErIc$oa_lmBvwC8_d&bFz(v#v~CjCAs%%HS-o<{$c)R)}q+@XK}wW_^M`{gy%CG
z<sZnEJea2X#9$%jY?&uZaK;C%?4~M-l@0M(_I6%X)FP04QozBDpj;M7*mG=zqBa4z
zP?a(LdCoYNh5<$e?-TY}^h<t06Ln5qb9|fztgE>NM5;Hs7bcLvY8_$~mUY5d`hdJ7
z<}>&m<8N?aPDS01kCq0E5<(QOVJ1BBbJDOST<|g6iJgc0I7sbR(sfX_KT>yPu+H#?
z_0YLII3*&Vkx}E)RAuod@m^w4o*}z<414sIzfz>d$@+@+gV2;Fbn#xa_(NDzKwIn&
zoKN|`lJO2*-~`Kh3HY@fY_HRF_(9wqyRRN9O>o8ze&t$@ZmwmxT^BnP7F1T}son`v
zh{^u<XX$ge1*d+@0!ghstx|o><1ylYSZ#QX>gp^Bj3UTbNUMfD`G@I@UZ~GQd@rDF
z;13SxpV3EoDFiWIS$K=31@}v4xW&$@#*~lks4?v)yUAju0P)(ss~}}<u}B((E&Wcn
ztDs<C<gfr|hbvs%fy^L<k4lM3!%93N^-k2XU<ph3qh2227xPCl{!*jf9ap%!<fBrj
zOQ~bEhs`GCv9D#SoTDbo9X`|fusZU*4|Vp-{={)*WPT(Gx8g$iPoA28ZT(X0BFHJK
z%4Dd{grhOpxb;eGh(}xsojRs<)V&84^c<Z0>yY|nx0Jd^iu0dekE4|xjHr24$Gh}g
zpGa@$!r@7)pj?ryAm_i%y}&9vEd!Fm7DA8b<$~8jx!IF~PZkYQCJFp^1CGn+3O_V&
zy*+3a>_{Cm@z!`(Rmo@QihA*;MVFn1e2$NPGI9XEB(485Z67&9EA~bxx4mZ9frf!b
zeKM4>ZL7IlE>)gzazNht=@RNODg@`x(>e>H`99COj!Tm=7X$6fMf}fht*;wm*35fh
zcmVsk96Tz6MPdRMSo3foT*8;pB?qE^6l^JpIVDt1l2KxzeakO5eP>{k0QxKA;`#;h
zy#p2!<JM$S9t2}%z{f^nJQ`mcn?J_|hEm=+s1p5u_;aeEIC(;RF+mSQ`#ZN%Rh6`$
J6;I)B{vU_9G$H^1

literal 0
HcmV?d00001

diff --git a/Services/Website/Resources/Static/icon.png b/Services/Website/Resources/Static/icon.png
deleted file mode 100644
index 8a42581d4a2a2a28bee1888835d21ffe4d6378d0..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 4029
zcma)9c{CJU+-8i7DZ7xZ8I2`GWQk%1lRYM~MW$%%yP>koG_P!lF_<icv1Q8=Le@&i
z&e#>+$k;;moo~MP{oen-d(OT0oZo$ZzjM$1-E*GjiAI^|v4I7_3=9lx2Kq=d`u^#E
zCkQ}aCz}pY3=AC44Uk%QpD?bZhX)E73`U%~7cQl85yvVXk(g;IUxeEq-gAn`O#OGr
z&lO(^T_yYT*6U?-xaqF>yQNy04owaZTcEWi85lr72<I~d1Ar04tH}TaaDosJhW{eK
z{{jSte<5@%!#@bZKPTl6Y=Dq>tIo@UX7J#rUIBw~lJs={CYso;p)qnluna#RzIviF
z@XZ9aXw3jLGsYiRA9QXSBQ0g8nvapf3GwJckKb+73+ey{f{A?pDZc1rRRp8J`eE{{
z12JxDMe;-X+2{~b8vxQ@V~^p|pRo&j-hK3?0HH28U;1{w2ngwys?NrTti=FA`$T!T
zWQv0~2?Ezt()hh=Kb*P7^9=EYtP-u>vPa~wP}kMQgxcDviA`8}&)>U$C)P<Av=ypq
zGc>UNAT?UbMk-poy=~^hjqHKnI3X=cZp-P;XD9*pla$REW99w&It*Gp-~k}4%869y
z&75l9QBIC77(y%a7F0CpRI&mOI)cS|2G^(9c}R(dLg1mseUuF!Fip+R_aKwl4%%uj
zlX2n}oG-heo>Vvj?eAXyA{Zm*=ok=ZaL!#;5M1SRAVx>y)(5UJAJiEcBVWyKd1<I{
z=~oO_2AqNkH0oA!W`Q#+tngO5SXNzV?;j(5uZPh7bL%5~F;aTZVFJt_>#y?aD-LnG
zMC`33$8jx0dMU7WPc|M#u(wXi0@GOU?K}P^?X3|lR7|v=Vg^wZDpj2x*3|TGKydpR
zU&=<7K9K64`B2||j*v}!6l4rM7?yl-rb=#F2`gn$il9VYQWGV$TuoDx$aZ)<j-u?F
z=R;9jU70=139WHax!3P0YUqv%9uku<I+Unn`0KM<{NB>EpYE|T5oqmIZ63g_SCfJl
zigFx_JCR8xHRqU%GC!Uph;`N2Vafm<Xl-O?HRh>e<A^>Ciuy_~JBx;+d|yA`?-``$
zhxc*=UqF&=VcN!=!6Mvdc`vdMB}S@H6mb6}R5=v^$0bKcrSg|eD>sgOqy1k2yyl%&
zUe>(103E_Fj1uq#@8g4s41<|rHi>NOHhSwSA7`dOQP{oc`Xw0Pc*N+%8U68yES-U;
zZD2x$?}_*Qlbf#CvoPL?P#r>%tuqvbd{Uvle~>rZ)hFUM?dw5rky$kpLCpTdLll3^
zXZr$pIZO43yL03_r_{_`U&f3_di1vvm2=Dq5u%(@TMZvOn#L}zr;nyajZs%_#BoTb
z{)KobkGI6J!cuc{b+j>#?I?=FV`jjuhNE%wA1jIRvPo>r3A$G~rM`w>C!7g58si{?
zLQ8)ZXH9z;0)LdYVFei{_T?E!?Y#W{_?@Q?CH@sWk+`(*B>21SVO;MNlO-4sPAqHs
zqy^eyDN`i1?}%)k<>Cj?FX!;lSi5Ohfw!PKR1^^YQsn-LFe0R<_2FS$%ELqUkH_)w
z3xM!w@1`%GS+_XWq>V_Z?`qzA;z{m-5L9hvCet0g_B=k0x`a{VGG#ftNCb50q?<5t
z33^P3jw0V1Yb^JnB^W$+Iv<9Zer(Qsr5}&WRqX3w0VTzegy62fX72hEiI(=sa26q=
z)wefEn@1-cNoK+T!UpR>VX$V%IZ*T9T{ne`3EmK=1ULUlS=CxZ3jZ6J2X(B__#H}u
zR%riaMEc0t8(8%S(rt8m2$$>%ydzm(N4`JVyEXDAgp`_p2h!NOPYAuf^)Y<t=5S^1
z!!8qL_3U1kM|H&}D)2nO;@t1%_isW)yDWc5#F9H79V|O^kLiCntSG&`cG=^jF@8f`
zbLf+fDsF5!J|cB?uBg63JX=_#&}q~VmcJ#CiCqZZ0ib(1oA<Nt`53fRC%SDT*$1u1
z4dtrHJg=!Y`zJM-lV56uY+7JssAI09E8bCjQ;sq=p3>h_+mH@7`kD{Hn!h2huDs=X
zG~T&{anJTiR^{<mwj3G4WIOVOu82=JMRGQ;XBUasS5sG-1pYRvHOhC$16QWi6~A1L
zIqF-RorT}|CUt8+>xs*_pZ^Bw5JQaHvkMSh`%)x#y2KN~lGxhZQ066kuiDyDczU=)
z&fBobH^_VT$}MzY+-cvejN{j`=Bom;LC^dg61vtWGqz?bUbO0<dVTYH>IUbMfUiov
zhNP$Hm~$v4zeNX~gU3bVpP1hFP!##}?w8}veUZnmEhf$_RwyTh&?jk`lS)iod{%nN
zCDwMY1g2L=AyvH$;l_|j)f4ZjHa``o@d{p7hmQ_{n8C-vuwZ0&mb`0^NU32<ML?65
zpd~@pHgz>E-B>SILeRoh9rqKOJZQ{fy^efaIdh8pI0Ccek}X1~4_dfdSAXl^`xW&0
zRLQiIbI$6*qCn{BZ;QMRp;mu3iCD9aa7zZ)4Drx)Q5(XR-wyg>Pj|((eyp6WbVgF$
z=f4MUa-G+&y!!%YktS=44wUQ180A0xVH0AVf?cT3u_f>9t`$|XiE4P}Ev?YOBu<cp
zEBq7{t9ew(efg>K&q@s$TeB3c?&tYER|*Y-)x?(ci?lb^UT`!w*o<%7=&3B4=_t_f
z)U}wHZp`VGeJN}EitL8{%XAY#(Z8E_{F}+bnAB$YR`Gsj@|E#tT`IzpYT1_L9eCzT
z+iJ^DdaFItX#@mUk>O!+%@FPACreI`7sOT6VT)x$MROOPuQ|SVL*7@#L{NrI|LXLF
z1ED|(BYOfO9CjOjWdPk!xbW<W>(usP75SZf1!e$<py<i`9AgbQtCTy0cDJu3p*I&}
zoH6DqW=aa23wmCWI+WeOlru2D@Q1}cwD9HD?R1`%<Qp=QK_l#hnLronpjoOR3s%>u
zS5<CG$|Q}Zwm1X?Vc&N^>lD(B2ID&qstc|OmUOAcxZh}V%`mU4=KyXLhdlw!tV<6*
z!{({uC}VTS)PvsluA)2QJxqiYg9I5Uw?1unxjts~B<DT5K~?EZogDHN_~1=WmqO&v
zPNb2q9W@I|R{-rVRT~2HtD2T^uV^;AA72Xq4}4TZYKlhrQqO$j^=Y}BnmqvNaZGGR
zP^Lo^UTT~>&sILmy54e?>c9C*p0nT$JI4FWg+m7gHWD^F3*qM$hS1!6qWsQ6%huv8
zqayPU6s0#dn9h1fzuMO#EGT8y+m#?RTDO%#2U-UL=jlH^$pRN5HoiS)w;sB@IGf#2
z#ZEZ7$jC=^nM*y>UE+BGJk;cO7O>w|W5-s5@b*+-(<jT&imhd1Z^mCN7yT?eu{YOl
z*bG=+g)8w&HIGFinyTz6<;|V(;9BhjplMDJMo9y>K_K=ae?I+rj7d-MqL-{cMpB8K
z3%N%-Mg;hNFnbRM_p3Ua(Nb2<NkARO51}93R%5!2h*1|J&##Bvp>hVjc`*CKg3fhd
zK0taD|LFDphqeZ<m8`yRnXWNwdfH22U){EPZ%ZW83A$syFjz|&)<Bhr&EUGz(Jv2Y
z_vq{;hb3VpmVY{YFbhNQBw(*cNj`vYKI<wZy?rqJmUr5^1KWQ;YA(D1mnV%8iU9Ov
zPJ|<P{64H~GTLK9f@97T*Gd&9jsk0R@yD-Di|6l!yCVLP8mm)G4iSjNKP#h0M<D#E
z#jyN)`>HlgbJLoj&Oj{xOlIwJB_cCJP2V8-W^Qg`xFT@lrNhDZn$Tbf)ck~d=i9dg
z%e8`DpHvS-%kx_fo<6%YroouuIX2L*)NSzLht1l4SnMnf$z^)`tYwIZ#5+B#RZXuT
z7$zh^N0=V#BToN#l4CAT$OpSz8(Vt6vNu(|{=wXs>Bqg6mR7g6aKzMJV`8k`F_B}q
zSSYfdE6_?(0C>48wb@fBuYT>b;nG&DIkk0_ey>j<5hmC3OGww&bQiLQ{bc%@kGV7d
z&|pHlZxX!hYS{@l|7@t=4p}RiuUaH5H7Nx<OR7v%ufzCdA0HSq<vwT$Ilt-i9!$U;
zXqpa@^{mR5x$r`oJJ71hBbUr#{F|+**~8rc!wF@6sZs0a2wj-xK^akE|E^sl+KK#5
z`FKsz%Jb^x!mTxV%{1f|{t%_c$3~*kyUrIVuMN56g&kYIesUu;?6^WJ1s19MKIuoW
zv0|xVpEXICn1!gARdLhgAT(`8M4HZ6Wfr8lm!sMJJU#^u`wy(B+BpeAY@9YNx=ZL1
zb-l!TuINWYbg6O$+N9<Hw~JO;kxY&mBu+i_Cm^qjN`L(^e(knFpLa$CqTR=BYT;-*
zvTVaot(-Jgcj_lA`lGfekDIN~D?@=--wU2{9;gmp1bW^D(R?VCx9B7%mhq0I=VG%H
zEIuTZ%22Ze6;GG$)uQC=g<0({aN(^cat<-4kyRbSfcrv97ks}LAS~S)U7uBG<mTqF
z0|6R|X~9DW;vHFjX~*O8Eby{NW&TGY92ys!a65Eu7&E$xpg4;KgA%o`Rv%v!g0KX%
z_h`)Ti^`W=%+39-!NFhb#SVy_pBIfQ%UUE~??3h{8eo-bbtudMKf)h~4l+olD)JYM
z*%A=5EUKrw?T)$*H!Po3?rm#npn6B1dicJ11i7XlC>D!nV|KG|U?jA82`&_Bmv6FB
zr8HvTl(3*bmo#xpQz>&EWjeIWt|BIi%!CZ5Du?ArFJBd}4D`+lMfAvSGk;B^DcCeW
z*N6s~OA`TMK}MnLeuvWm(3I0d%w|{+rBQ6JZ)(pNqE=|*R>1#wcU1^{7w&%nAmUKp
z*0RsNE$jO0#B8SvDk$sL^!@PUxKDVZWFVd{&U@r7ue3u!x%(Ub@0{0{kNwJ3m&~t@
zhK$v$xyvmjVJGQ7zl4#X`&tTEjUJ)DPuAre+obOLcP{GUp1WRf6<&SO00boVGwx{}
z$C6~jZvWsSU$33wN`3ih6q%X8-Y?!AYXag}(!?_Mdxv(fwVLIDfr4SO4?DuE;Vc18
zV4;LrlF2rm%SWoA{ny?n6h=44=3@RL8=AWe2#QR08P}QUKu(pZEZZQ?u3B>J{Q;MX
zh#gLS_au{=AR5bd6qga)JjV=w9`KY}fWNy~Ka0YWymJO{=Yn>mfg2I&fpZ=h9EvF5
zt9qEEYa-1=kf6Hwy8c<PzBuF@g={KtcHx@{1t~$p3bTzXU;L(suS?C9bGrCF8zNl2
q1`HDY&;HU)@4uGz|LuPNJ{xA}F1aHn=0LaQ3<kGMkfquW{`w#5IHleI

diff --git a/Services/Website/Resources/Static/icon.svg b/Services/Website/Resources/Static/icon.svg
index f232922..68e7d38 100644
--- a/Services/Website/Resources/Static/icon.svg
+++ b/Services/Website/Resources/Static/icon.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" viewBox="0 0 192 192"><path fill="#e08524" d="M75.3 73.4H18.4l45.3 34.3L48.3 163l46.1-32.3 48.2 34.6-16.9-58.3 44.9-33.6H115l-20.5-55-19.2 55z"/><path d="m96.7 18.8 18.2 8.2 16.5 44.3h-15.1L96.7 18.8zm-47 146 18.7 9.9 42.6-29.9-16.5-11.4-44.8 31.4zm79.1-56.8 17.4 9.4 18.6 60.1-19.7-11.3-16.3-58.2z"/><path d="m173.1 74.3 17.8 9.2-44.7 34-17.4-9.4 44.3-33.8z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" viewBox="0 0 192 192"><style>.accent{fill:#000}@media (prefers-color-scheme:dark){.accent{fill:#f3ecf5}}</style><path fill="#e08524" d="M75.3 73.4H18.4l45.3 34.3L48.3 163l46.1-32.3 48.2 34.6-16.9-58.3 44.9-33.6H115l-20.5-55-19.2 55z"/><path class="accent" d="m96.7 18.8 18.2 8.2 16.5 44.3h-15.1L96.7 18.8zm-47 146 18.7 9.9 42.6-29.9-16.5-11.4-44.8 31.4zm79.1-56.8 17.4 9.4 18.6 60.1-19.7-11.3-16.3-58.2z"/><path class="accent" d="m173.1 74.3 17.8 9.2-44.7 34-17.4-9.4 44.3-33.8z"/></svg>
diff --git a/Services/Website/Resources/Static/site.webmanifest b/Services/Website/Resources/Static/site.webmanifest
index 222ae16..e5e517f 100644
--- a/Services/Website/Resources/Static/site.webmanifest
+++ b/Services/Website/Resources/Static/site.webmanifest
@@ -2,9 +2,13 @@
   "short_name": "",
   "name": "",
   "icons": [{
-    "src": "icon.png",
+    "src": "icon-192.png",
     "type": "image/png",
     "sizes": "192x192"
+  }, {
+    "src": "icon-512.png",
+    "type": "image/png",
+    "sizes": "512x512"
   }],
   "start_url": "/?utm_source=homescreen",
   "background_color": "#fafafa",
diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
index aed99f7..69afb22 100644
--- a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
@@ -10,8 +10,12 @@ enum StaticFile: CaseIterable, Sendable {
     case error
     /// The `favicon.ico` icon.
     case favicon
-    /// The `icon.png` and `icon.svg` icons.
+    /// The `icon.svg` icon.
     case icon
+    /// The `icon-192.png` icon for the web manifest.
+    case icon192
+    /// The `icon-512.png` icon for the web manifest.
+    case icon512
     /// The `css/index.css` stylesheet and `js/index.js` script for the landing page.
     case index
     /// The `robots.txt` crawler directives.
@@ -57,12 +61,14 @@ extension StaticFile {
     /// The file extensions the file is available with.
     var fileExtensions: [Extension] {
         switch self {
-        case .appleTouchIcon: [.png]
+        case .appleTouchIcon,
+             .icon192,
+             .icon512: [.png]
         case .error,
              .index,
              .shared: [.css, .js]
         case .favicon: [.ico]
-        case .icon: [.png, .svg]
+        case .icon: [.svg]
         case .robots: [.txt]
         case .site: [.webmanifest]
         case .sitemap: [.xml]
@@ -76,6 +82,8 @@ extension StaticFile {
         case .error: "error"
         case .favicon: "favicon"
         case .icon: "icon"
+        case .icon192: "icon-192"
+        case .icon512: "icon-512"
         case .index: "index"
         case .robots: "robots"
         case .shared: "shared"
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index 7f8bf19..6a9b6e2 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -74,6 +74,14 @@ struct IndexPage: HTMLDocument, Sendable {
             .rel("manifest"),
             .href(StaticFile.site.urlPath(for: .webmanifest))
         )
+        meta(
+            .name("theme-color"),
+            .content("#0c0710"),
+            .custom(
+                name: "media",
+                value: "(prefers-color-scheme: dark)"
+            )
+        )
         meta(
             .name("theme-color"),
             .content("#fafafa")
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index 4cb579f..24bde11 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -114,7 +114,7 @@ struct StaticFileTests {
 
     @Test
     func `all cases`() {
-        #expect(File.allCases.count == 9)
+        #expect(File.allCases.count == 11)
     }
 
 }
@@ -159,7 +159,9 @@ private extension StaticFileTests {
         [.png],
         [.css, .js],
         [.ico],
-        [.png, .svg],
+        [.svg],
+        [.png],
+        [.png],
         [.css, .js],
         [.txt],
         [.css, .js],
@@ -171,6 +173,8 @@ private extension StaticFileTests {
         "error",
         "favicon",
         "icon",
+        "icon-192",
+        "icon-512",
         "index",
         "robots",
         "shared",
@@ -181,7 +185,9 @@ private extension StaticFileTests {
         ["apple-touch-icon.png"],
         ["css/error.css", "js/error.js"],
         ["favicon.ico"],
-        ["icon.png", "icon.svg"],
+        ["icon.svg"],
+        ["icon-192.png"],
+        ["icon-512.png"],
         ["css/index.css", "js/index.js"],
         ["robots.txt"],
         ["css/shared.css", "js/shared.js"],
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index a754d77..fc308d2 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -23,6 +23,7 @@ struct IndexPageTests {
         #expect(html.contains("/icon.svg"))
         #expect(html.contains("/apple-touch-icon.png"))
         #expect(html.contains("/site.webmanifest"))
+        #expect(html.contains(#"media="(prefers-color-scheme: dark)""#))
         #expect(html.contains("Hello world!"))
         #expect(html.contains("/js/shared.js"))
         #expect(html.contains("/js/index.js"))
-- 
2.54.0


From d0058dc636fa2656e45f4eebc52e4d9b52215846 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 19 Jul 2026 08:56:35 +0000
Subject: [PATCH 024/117] Shared HTML template for the Website service (#22)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR contains the work done to define a `Page` protocol that extracts the HTML scaffolding that `IndexPage` and `ErrorPage` pages duplicated, so every page of the website declares only what makes it unique — its content, title, and assets — while the document structure lives in one place. Also cleans up imports across the workspace.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/22
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../Cases/Public/Methods/ProbeTests.swift     |   1 -
 .../RouterMethods+RouteCollectionsTests.swift |   1 +
 Services/Website/Sources/App/App.swift        |   1 -
 .../Sources/App/Extensions/App+Build.swift    |   1 +
 .../Library/Internal/Pages/ErrorPage.swift    |  40 +++----
 .../Library/Internal/Pages/IndexPage.swift    |  77 +++----------
 .../Library/Internal/Protocols/Page.swift     | 107 ++++++++++++++++++
 .../Public/Controllers/RootController.swift   |   4 +-
 Services/Website/Tests/App/AppTests.swift     |   1 -
 .../Enumerations/StaticFileTests.swift        |   1 -
 10 files changed, 139 insertions(+), 95 deletions(-)
 create mode 100644 Services/Website/Sources/Library/Internal/Protocols/Page.swift

diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
index 92ff75e..4458f0e 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
@@ -1,7 +1,6 @@
 import FluentKit
 import HummingbirdFluent
 import Logging
-import NIOCore
 import Testing
 
 @testable import Persistence
diff --git a/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift b/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
index 1808834..2f6edc5 100644
--- a/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
+++ b/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
@@ -1,5 +1,6 @@
 import Hummingbird
 import HummingbirdTesting
+import NIOCore
 import Testing
 
 @testable import Web
diff --git a/Services/Website/Sources/App/App.swift b/Services/Website/Sources/App/App.swift
index ee99ab9..679beff 100644
--- a/Services/Website/Sources/App/App.swift
+++ b/Services/Website/Sources/App/App.swift
@@ -1,6 +1,5 @@
 import Configuration
 import Hummingbird
-import Logging
 
 /// The entry point of the website executable.
 ///
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 2bb0d52..1096740 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -3,6 +3,7 @@ import Hummingbird
 import HummingbirdCompression
 import Logging
 import Persistence
+import Web
 import WebsiteLibrary
 
 /// Builds the website application.
diff --git a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
index 79a1f53..3f332fb 100644
--- a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
@@ -3,12 +3,12 @@ import Foundation
 import Localization
 
 /// The HTML page rendered for a not-found response, with its text localized to a given locale.
-struct ErrorPage: HTMLDocument, Sendable {
+struct ErrorPage {
 
     // MARK: Properties
 
     /// The locale the page content is localized to.
-    private let locale: Locale
+    let locale: Locale
 
     /// Resolves the page's text from the bundled String Catalog for the page's ``locale``.
     private let localize: Localize
@@ -23,45 +23,31 @@ struct ErrorPage: HTMLDocument, Sendable {
         self.locale = locale
         self.localize = .init(bundle: .module)
     }
+}
 
-    // MARK: Document
+// MARK: Page
 
-    /// The page's content: a localized heading and explanatory message, followed by the error and shared scripts.
-    var body: some HTML {
+extension ErrorPage: Page {
+
+    // MARK: Properties
+
+    var content: some HTML {
         h1 {
             localize("error.heading", locale: locale)
         }
         p {
             localize("error.message", locale: locale)
         }
-        script(.src(StaticFile.error.urlPath(for: .js))) {}
-        script(.src(StaticFile.shared.urlPath(for: .js))) {}
     }
 
-    /// The metadata and stylesheet links placed in the document head.
-    var head: some HTML {
-        meta(.charset(.utf8))
-        meta(
-            .name(.viewport),
-            .content("width=device-width, initial-scale=1")
-        )
-        link(
-            .rel(.stylesheet),
-            .href(StaticFile.shared.urlPath(for: .css))
-        )
-        link(
-            .rel(.stylesheet),
-            .href(StaticFile.error.urlPath(for: .css))
-        )
+    var scripts: [StaticFile] {
+        [.error, .shared]
     }
 
-    /// The document language, derived from the page's locale and falling back to the default language.
-    var lang: String {
-        locale.language.languageCode?.identifier
-            ?? LanguageList(bundle: .module).default
+    var stylesheets: [StaticFile] {
+        [.shared, .error]
     }
 
-    /// The localized document title.
     var title: String {
         localize("error.title", locale: locale)
     }
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index 6a9b6e2..aabef0b 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -3,12 +3,12 @@ import Foundation
 import Localization
 
 /// The website's landing page, with its text localized to a given locale.
-struct IndexPage: HTMLDocument, Sendable {
+struct IndexPage {
 
     // MARK: Properties
 
     /// The locale the page content is localized to.
-    private let locale: Locale
+    let locale: Locale
 
     /// Resolves the page's text from the bundled String Catalog for the page's ``locale``.
     private let localize: Localize
@@ -24,77 +24,28 @@ struct IndexPage: HTMLDocument, Sendable {
         self.localize = .init(bundle: .module)
     }
 
-    // MARK: Document
+}
 
-    /// The page's content: a localized greeting followed by the shared and index scripts.
-    var body: some HTML {
+// MARK: - Page
+
+extension IndexPage: Page {
+
+    // MARK: Properties
+
+    var content: some HTML {
         p {
             localize("index.greeting", locale: locale)
         }
-        script(.src(StaticFile.index.urlPath(for: .js))) {}
-        script(.src(StaticFile.shared.urlPath(for: .js))) {}
     }
 
-    /// The metadata, stylesheet, icon, and manifest links placed in the document head.
-    var head: some HTML {
-        meta(.charset(.utf8))
-        meta(
-            .name(.viewport),
-            .content("width=device-width, initial-scale=1")
-        )
-        link(
-            .rel(.stylesheet),
-            .href(StaticFile.shared.urlPath(for: .css))
-        )
-        link(
-            .rel(.stylesheet),
-            .href(StaticFile.index.urlPath(for: .css))
-        )
-        link(
-            .rel(.icon),
-            .href(StaticFile.favicon.urlPath(for: .ico)),
-            .custom(
-                name: "sizes",
-                value: "any"
-            )
-        )
-        link(
-            .rel(.icon),
-            .href(StaticFile.icon.urlPath(for: .svg)),
-            .custom(
-                name: "type",
-                value: "image/svg+xml"
-            )
-        )
-        link(
-            .rel("apple-touch-icon"),
-            .href(StaticFile.appleTouchIcon.urlPath(for: .png))
-        )
-        link(
-            .rel("manifest"),
-            .href(StaticFile.site.urlPath(for: .webmanifest))
-        )
-        meta(
-            .name("theme-color"),
-            .content("#0c0710"),
-            .custom(
-                name: "media",
-                value: "(prefers-color-scheme: dark)"
-            )
-        )
-        meta(
-            .name("theme-color"),
-            .content("#fafafa")
-        )
+    var scripts: [StaticFile] {
+        [.index, .shared]
     }
 
-    /// The document language, derived from the page's locale and falling back to the default language.
-    var lang: String {
-        locale.language.languageCode?.identifier
-            ?? LanguageList(bundle: .module).default
+    var stylesheets: [StaticFile] {
+        [.shared, .index]
     }
 
-    /// The localized document title.
     var title: String {
         localize("index.title", locale: locale)
     }
diff --git a/Services/Website/Sources/Library/Internal/Protocols/Page.swift b/Services/Website/Sources/Library/Internal/Protocols/Page.swift
new file mode 100644
index 0000000..e05eb45
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Protocols/Page.swift
@@ -0,0 +1,107 @@
+import Elementary
+import Foundation
+import Localization
+
+/// A page of the website: an HTML document with the shared scaffolding assembled around the page's content.
+///
+/// A conforming page supplies its locale, its localized title, the stylesheets and scripts it needs, and its content; the protocol assembles the rest of the
+/// document around them: the metadata, stylesheet, icon, and manifest links in the head, the content followed by the script tags in the body, and the
+/// document language derived from the locale.
+protocol Page: HTMLDocument, Sendable {
+
+    // MARK: Associated types
+
+    /// The type of the page's markup.
+    associatedtype Content: HTML
+
+    // MARK: Properties
+
+    /// The page's markup, rendered before the ``scripts``.
+    @HTMLBuilder
+    var content: Content { get }
+
+    /// The locale the page content is localized to.
+    var locale: Locale { get }
+
+    /// The scripts loaded at the end of the document body, in order.
+    var scripts: [StaticFile] { get }
+
+    /// The stylesheets linked in the document head, in order.
+    var stylesheets: [StaticFile] { get }
+
+}
+
+// MARK: - Implementations
+
+extension Page {
+
+    // MARK: Computed
+
+    /// The page ``content`` followed by its ``scripts``.
+    @HTMLBuilder
+    var body: some HTML {
+        content
+        for file in scripts {
+            script(.src(file.urlPath(for: .js))) {}
+        }
+    }
+
+    /// The metadata, ``stylesheets``, icon, and manifest links placed in the document head.
+    @HTMLBuilder
+    var head: some HTML {
+        meta(.charset(.utf8))
+        meta(
+            .name(.viewport),
+            .content("width=device-width, initial-scale=1")
+        )
+        for file in stylesheets {
+            link(
+                .rel(.stylesheet),
+                .href(file.urlPath(for: .css))
+            )
+        }
+        link(
+            .rel(.icon),
+            .href(StaticFile.favicon.urlPath(for: .ico)),
+            .custom(
+                name: "sizes",
+                value: "any"
+            )
+        )
+        link(
+            .rel(.icon),
+            .href(StaticFile.icon.urlPath(for: .svg)),
+            .custom(
+                name: "type",
+                value: "image/svg+xml"
+            )
+        )
+        link(
+            .rel("apple-touch-icon"),
+            .href(StaticFile.appleTouchIcon.urlPath(for: .png))
+        )
+        link(
+            .rel("manifest"),
+            .href(StaticFile.site.urlPath(for: .webmanifest))
+        )
+        meta(
+            .name("theme-color"),
+            .content("#fafafa")
+        )
+        meta(
+            .name("theme-color"),
+            .content("#0c0710"),
+            .custom(
+                name: "media",
+                value: "(prefers-color-scheme: dark)"
+            )
+        )
+    }
+
+    /// The document language, derived from the page's locale and falling back to the default language.
+    var lang: String {
+        locale.language.languageCode?.identifier
+            ?? LanguageList(bundle: .module).default
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index de32221..7a0dff0 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -25,7 +25,9 @@ public struct RootController<Context: LocalizedRequestContext> {
 
     /// Creates a root controller.
     public init() {
-        self.responses = .init { IndexPage(locale: $0) }
+        self.responses = .init {
+            IndexPage(locale: $0)
+        }
     }
 
 }
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index e665763..23fe521 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -2,7 +2,6 @@ import Configuration
 import Foundation
 import Hummingbird
 import HummingbirdTesting
-import Logging
 import NIOCore
 import Testing
 
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index 24bde11..2ca9b20 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -1,4 +1,3 @@
-import Foundation
 import Testing
 
 @testable import WebsiteLibrary
-- 
2.54.0


From 242cb92bc55e5d20dff2ef911239e835213cac7f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 19 Jul 2026 18:23:46 +0000
Subject: [PATCH 025/117] Few small fixes for the Website service (#23)

This PR contains the work done to address small fixes.

To provide further details:

* HTML template
  * Removed the duplicate charset <meta> tag from the Page protocol's head property.

* Router
  * Enabled auto-generated HEAD endpoints so every GET route gets a HEAD sibling. Uptime monitors and crawlers probing with HEAD now receive the page's status and headers instead of a 404.

* Docker
  * Pinned the asset optimizer versionsvia build args so minified output is reproducible for a given Dockerfile commit.
  * Narrowed the build context copied into the release stage, only package manifests and Swift sources are copied. Static assets come from the separate assets stage after the binary is built.
  * svgo now minifies all SVGs recursively rather than just icon.svg, and the staging step creates Resources/Static explicitly instead of conditionally moving the unminified sources.
  * Added curl to the runtime image (needed for the container healthcheck) and .claude to .dockerignore.

* Docker-compose
  * Added a `healthcheck` to the website service hitting GET /health (liveness only), so Compose reports process health without coupling container health to database reachability.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/23
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .dockerignore                                 |  3 +-
 Services/Website/Dockerfile                   | 31 +++++++++++++------
 Services/Website/README.md                    |  6 +++-
 .../Sources/App/Extensions/App+Build.swift    |  7 ++++-
 .../Library/Internal/Protocols/Page.swift     |  4 ++-
 Services/Website/Tests/App/AppTests.swift     | 16 ++++++++++
 Services/Website/docker-compose.yml           |  6 ++++
 7 files changed, 59 insertions(+), 14 deletions(-)

diff --git a/.dockerignore b/.dockerignore
index a60105d..b84d7f9 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -13,9 +13,10 @@
 # Xcode project (not used by the Linux build)
 *.xcodeproj
 
-# OS / editor cruft
+# OS / editor / tooling cruft
 **/.DS_Store
 .vscode
+.claude
 
 # Local environment overrides and secrets (Compose still reads these from the
 # host at runtime; ignoring them here only keeps them out of the image build).
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index 6f3f1d4..98ac38a 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -3,9 +3,15 @@
 # ================================
 FROM node:22-alpine AS assets
 
-# Install the minifiers in their own layer, so they are cached across asset changes
-RUN apk add --no-cache oxipng \
-    && npm install --global esbuild svgo
+ARG ESBUILD_VERSION=0.28.1
+ARG OXIPNG_VERSION=9.1.5
+ARG SVGO_VERSION=4.0.2
+
+# Install the minifiers in their own layer, so they are cached across asset changes.
+# The oxipng pin is fuzzy (=~) so Alpine package revision bumps (-r0, -r1, ...) do
+# not break the build when the base image advances.
+RUN apk add --no-cache "oxipng=~${OXIPNG_VERSION}" \
+    && npm install --global "esbuild@${ESBUILD_VERSION}" "svgo@${SVGO_VERSION}"
 
 # Copy the static files and minify the JS/CSS/SVG sources and losslessly recompress
 # the PNG images in place, keeping their names so the URL paths derived from the
@@ -15,7 +21,7 @@ COPY ./Services/Website/Resources/Static .
 RUN esbuild --minify --allow-overwrite --outdir=css css/*.css \
     && esbuild --minify --allow-overwrite --outdir=js js/*.js \
     && oxipng --opt max --strip safe *.png \
-    && svgo icon.svg
+    && svgo --recursive --folder .
 
 # Export stage: `docker build --target assets-export --output <dir>` writes the
 # minified static files to <dir> for local inspection.
@@ -47,8 +53,13 @@ COPY ./Packages/Web/Package.swift ./Packages/Web/
 COPY ./Services/Website/Package.swift ./Services/Website/Package.resolved ./Services/Website/
 RUN swift package --package-path ./Services/Website resolve
 
-# Copy entire repo into container
-COPY . .
+# Copy only the Swift inputs needed for a release build. Static assets are built
+# in the assets stage and copied into staging after the binary is produced.
+COPY ./Packages/Localization/Sources ./Packages/Localization/Sources
+COPY ./Packages/Persistence/Sources ./Packages/Persistence/Sources
+COPY ./Packages/Web/Sources ./Packages/Web/Sources
+COPY ./Services/Website/Sources ./Services/Website/Sources
+COPY ./Services/Website/Tests ./Services/Website/Tests
 
 # Build the application, with optimizations, with static linking, and using jemalloc
 RUN swift build --package-path ./Services/Website -c release \
@@ -68,10 +79,9 @@ RUN cp "/usr/libexec/swift/linux/swift-backtrace-static" ./
 # Copy resources bundled by SPM to staging area
 RUN find -L "$(swift build --package-path /build/Services/Website -c release --show-bin-path)/" -regex '.*\.resources$' -exec cp -Ra {} ./ \;
 
-# Copy the static files directory (served by FileMiddleware) if it exists
-RUN [ -d /build/Services/Website/Resources ] && mv /build/Services/Website/Resources ./Resources || true
-
-# Overwrite the static files with the minified copies from the assets stage
+# Create the static files directory (served by FileMiddleware) and fill it with
+# the minified copies from the assets stage
+RUN mkdir -p ./Resources/Static
 COPY --from=assets /static ./Resources/Static
 
 # Ensure that by default, neither the directory nor any of its contents are writable.
@@ -89,6 +99,7 @@ RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
     && apt-get -q install -y \
       libjemalloc2 \
       ca-certificates \
+      curl \
       tzdata \
 # If your app or its dependencies import FoundationNetworking, also install `libcurl4`.
       # libcurl4 \
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 7e410c7..ccaa62c 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -166,6 +166,8 @@ DATABASE_DRIVER=mysql make site-mount   # run the site against MariaDB
 ### Health checks
 `GET /health` is a liveness check (process is up, no dependency check). `GET /health/ready` is a readiness check that runs `SELECT 1` against the database and returns `200` when reachable or `503` otherwise — so an orchestrator restarts on liveness failure but only withholds traffic on readiness failure.
 
+`docker-compose.yml` configures the `website` container healthcheck against `GET /health`, so Compose reports process liveness without coupling container health to database reachability.
+
 ## Testing
 ```sh
 make pkg-test
@@ -201,13 +203,15 @@ docker compose -f docker-compose.yml up -d
 ```
 
 ### Static assets
-The image build optimizes the files under `Resources/Static` in its `assets` stage, in place:
+The image build optimizes the files under `Resources/Static` in its `assets` stage, in place, with pinned optimizer versions so asset output is reproducible for a given Dockerfile commit:
 - CSS and JS are minified with [esbuild](https://esbuild.github.io).
 - PNG images are losslessly recompressed with [oxipng](https://github.com/oxipng/oxipng) — the output is pixel-identical, only encoded smaller.
 - The SVG icon is minified with [svgo](https://github.com/svg/svgo).
 
 Files keep their names and paths, so the URLs derived from the `StaticFile` enumeration are unaffected. The sources in the repository stay readable and unminified: a direct `swift run` serves them as-is, while any image build — including the local `make site-mount` one, which builds the same Dockerfile — serves the optimized copies.
 
+The Dockerfile copies only package manifests and Swift source inputs into the release build stage. Static assets are copied from the separate `assets` stage after the binary is built, so editing a CSS/JS/image file does not invalidate the release binary build cache.
+
 Preview the optimized output locally — requires only Docker and writes to the git-ignored `.build/minified`:
 ```sh
 make ast-minify
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 1096740..45814b8 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -140,7 +140,12 @@ private func router(
     logLevel: Logger.Level,
     probe: Probe
 ) -> Router<AppRequestContext> {
-    let router = Router(context: AppRequestContext.self)
+    // HEAD siblings are generated for every GET route, so uptime monitors and crawlers probing
+    // with HEAD requests get the page's status and headers instead of a 404.
+    let router = Router(
+        context: AppRequestContext.self,
+        options: .autoGenerateHeadEndpoints
+    )
 
     router.addMiddleware {
         LogRequestsMiddleware(logLevel)
diff --git a/Services/Website/Sources/Library/Internal/Protocols/Page.swift b/Services/Website/Sources/Library/Internal/Protocols/Page.swift
index e05eb45..e8bc515 100644
--- a/Services/Website/Sources/Library/Internal/Protocols/Page.swift
+++ b/Services/Website/Sources/Library/Internal/Protocols/Page.swift
@@ -47,9 +47,11 @@ extension Page {
     }
 
     /// The metadata, ``stylesheets``, icon, and manifest links placed in the document head.
+    ///
+    /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already
+    /// emits `<meta charset="UTF-8">` before this markup, and HTML5 allows only one.
     @HTMLBuilder
     var head: some HTML {
-        meta(.charset(.utf8))
         meta(
             .name(.viewport),
             .content("width=device-width, initial-scale=1")
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 23fe521..1b45edb 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -48,6 +48,22 @@ struct AppTests {
         }
     }
 
+    @Test
+    func `landing page to answer a head request`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .head
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
+                #expect(response.body.readableBytes == 0)
+            }
+        }
+    }
+
     @Test
     func `health check to be served at the health path`() async throws {
         try await app(
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index 81c40d5..0aa0ffb 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -31,3 +31,9 @@ services:
       DATABASE_USERNAME: ${DATABASE_USERNAME:-loud-ams}
       DATABASE_PASSWORD: ${DATABASE_PASSWORD:-}
       DATABASE_TLS: ${DATABASE_TLS:-require}
+    healthcheck:
+      test: ["CMD", "curl", "--fail", "--silent", "--show-error", "http://127.0.0.1:8080/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
-- 
2.54.0


From a8682753474556b802268aafbed2349491972072 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Wed, 22 Jul 2026 21:26:55 +0000
Subject: [PATCH 026/117] Renamed the Web package as Infrastructure (#24)

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/24
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../xcschemes/Infrastructure.xcscheme}           | 12 ++++++------
 Packages/{Web => Infrastructure}/Package.swift   | 12 ++++++------
 .../Public/Builders/RouteCollectionBuilder.swift |  0
 .../RouterMethods+RouteCollections.swift         |  0
 .../Public/Protocols/RouterController.swift      |  0
 .../RouterMethods+RouteCollectionsTests.swift    |  2 +-
 .../Tests/Utils/Controllers/StubController.swift |  2 +-
 Services/Website/Dockerfile                      |  4 ++--
 Services/Website/Package.swift                   |  6 +++---
 Services/Website/README.md                       |  2 +-
 .../Sources/App/Extensions/App+Build.swift       |  2 +-
 .../Public/Controllers/HealthController.swift    |  2 +-
 .../Public/Controllers/RootController.swift      |  2 +-
 Services/Website/Tests/App/AppTests.swift        | 16 ----------------
 Services/Website/Tests/Website.xctestplan        |  6 +++---
 15 files changed, 26 insertions(+), 42 deletions(-)
 rename Packages/{Web/.swiftpm/xcode/xcshareddata/xcschemes/Web.xcscheme => Infrastructure/.swiftpm/xcode/xcshareddata/xcschemes/Infrastructure.xcscheme} (88%)
 rename Packages/{Web => Infrastructure}/Package.swift (79%)
 rename Packages/{Web => Infrastructure}/Sources/Public/Builders/RouteCollectionBuilder.swift (100%)
 rename Packages/{Web => Infrastructure}/Sources/Public/Extensions/RouterMethods+RouteCollections.swift (100%)
 rename Packages/{Web => Infrastructure}/Sources/Public/Protocols/RouterController.swift (100%)
 rename Packages/{Web => Infrastructure}/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift (99%)
 rename Packages/{Web => Infrastructure}/Tests/Utils/Controllers/StubController.swift (96%)

diff --git a/Packages/Web/.swiftpm/xcode/xcshareddata/xcschemes/Web.xcscheme b/Packages/Infrastructure/.swiftpm/xcode/xcshareddata/xcschemes/Infrastructure.xcscheme
similarity index 88%
rename from Packages/Web/.swiftpm/xcode/xcshareddata/xcschemes/Web.xcscheme
rename to Packages/Infrastructure/.swiftpm/xcode/xcshareddata/xcschemes/Infrastructure.xcscheme
index 5212084..56914ab 100644
--- a/Packages/Web/.swiftpm/xcode/xcshareddata/xcschemes/Web.xcscheme
+++ b/Packages/Infrastructure/.swiftpm/xcode/xcshareddata/xcschemes/Infrastructure.xcscheme
@@ -15,8 +15,8 @@
             buildForAnalyzing = "YES">
             <BuildableReference
                BuildableIdentifier = "primary"
-               BlueprintIdentifier = "Web"
-               BuildableName = "Web"
+               BlueprintIdentifier = "Infrastructure"
+               BuildableName = "Infrastructure"
                ReferencedContainer = "container:">
             </BuildableReference>
          </BuildActionEntry>
@@ -33,8 +33,8 @@
             skipped = "NO">
             <BuildableReference
                BuildableIdentifier = "primary"
-               BlueprintIdentifier = "WebTests"
-               BuildableName = "WebTests"
+               BlueprintIdentifier = "InfrastructureTests"
+               BuildableName = "InfrastructureTests"
                ReferencedContainer = "container:">
             </BuildableReference>
          </TestableReference>
@@ -61,8 +61,8 @@
       <MacroExpansion>
          <BuildableReference
             BuildableIdentifier = "primary"
-            BlueprintIdentifier = "Web"
-            BuildableName = "Web"
+            BlueprintIdentifier = "Infrastructure"
+            BuildableName = "Infrastructure"
             ReferencedContainer = "container:">
          </BuildableReference>
       </MacroExpansion>
diff --git a/Packages/Web/Package.swift b/Packages/Infrastructure/Package.swift
similarity index 79%
rename from Packages/Web/Package.swift
rename to Packages/Infrastructure/Package.swift
index c0c94e8..2f9227a 100644
--- a/Packages/Web/Package.swift
+++ b/Packages/Infrastructure/Package.swift
@@ -3,15 +3,15 @@
 import PackageDescription
 
 let package = Package(
-    name: "Web",
+    name: "Infrastructure",
     platforms: [
         .macOS(.v15),
     ],
     products: [
         .library(
-            name: "Web",
+            name: "Infrastructure",
             targets: [
-                "Web"
+                "Infrastructure"
             ]
         ),
     ],
@@ -23,7 +23,7 @@ let package = Package(
     ],
     targets: [
         .target(
-            name: "Web",
+            name: "Infrastructure",
             dependencies: [
                 .product(
                     name: "Hummingbird",
@@ -33,9 +33,9 @@ let package = Package(
             path: "Sources"
         ),
         .testTarget(
-            name: "WebTests",
+            name: "InfrastructureTests",
             dependencies: [
-                .byName(name: "Web"),
+                .byName(name: "Infrastructure"),
                 .product(
                     name: "HummingbirdTesting",
                     package: "hummingbird"
diff --git a/Packages/Web/Sources/Public/Builders/RouteCollectionBuilder.swift b/Packages/Infrastructure/Sources/Public/Builders/RouteCollectionBuilder.swift
similarity index 100%
rename from Packages/Web/Sources/Public/Builders/RouteCollectionBuilder.swift
rename to Packages/Infrastructure/Sources/Public/Builders/RouteCollectionBuilder.swift
diff --git a/Packages/Web/Sources/Public/Extensions/RouterMethods+RouteCollections.swift b/Packages/Infrastructure/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
similarity index 100%
rename from Packages/Web/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
rename to Packages/Infrastructure/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
diff --git a/Packages/Web/Sources/Public/Protocols/RouterController.swift b/Packages/Infrastructure/Sources/Public/Protocols/RouterController.swift
similarity index 100%
rename from Packages/Web/Sources/Public/Protocols/RouterController.swift
rename to Packages/Infrastructure/Sources/Public/Protocols/RouterController.swift
diff --git a/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
similarity index 99%
rename from Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
rename to Packages/Infrastructure/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
index 2f6edc5..0bae410 100644
--- a/Packages/Web/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
@@ -3,7 +3,7 @@ import HummingbirdTesting
 import NIOCore
 import Testing
 
-@testable import Web
+@testable import Infrastructure
 
 @Suite("addController method")
 struct RouterMethodsTests {
diff --git a/Packages/Web/Tests/Utils/Controllers/StubController.swift b/Packages/Infrastructure/Tests/Utils/Controllers/StubController.swift
similarity index 96%
rename from Packages/Web/Tests/Utils/Controllers/StubController.swift
rename to Packages/Infrastructure/Tests/Utils/Controllers/StubController.swift
index 75b7586..48e2e24 100644
--- a/Packages/Web/Tests/Utils/Controllers/StubController.swift
+++ b/Packages/Infrastructure/Tests/Utils/Controllers/StubController.swift
@@ -1,5 +1,5 @@
 import Hummingbird
-import Web
+import Infrastructure
 
 /// A controller serving its path back as plain text, used to observe route registration.
 struct StubController {
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index 98ac38a..f0fef04 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -49,7 +49,7 @@ WORKDIR /build
 # a relative path, so its manifest must be present for resolution to succeed.
 COPY ./Packages/Localization/Package.swift ./Packages/Localization/
 COPY ./Packages/Persistence/Package.swift ./Packages/Persistence/
-COPY ./Packages/Web/Package.swift ./Packages/Web/
+COPY ./Packages/Infrastructure/Package.swift ./Packages/Infrastructure/
 COPY ./Services/Website/Package.swift ./Services/Website/Package.resolved ./Services/Website/
 RUN swift package --package-path ./Services/Website resolve
 
@@ -57,7 +57,7 @@ RUN swift package --package-path ./Services/Website resolve
 # in the assets stage and copied into staging after the binary is produced.
 COPY ./Packages/Localization/Sources ./Packages/Localization/Sources
 COPY ./Packages/Persistence/Sources ./Packages/Persistence/Sources
-COPY ./Packages/Web/Sources ./Packages/Web/Sources
+COPY ./Packages/Infrastructure/Sources ./Packages/Infrastructure/Sources
 COPY ./Services/Website/Sources ./Services/Website/Sources
 COPY ./Services/Website/Tests ./Services/Website/Tests
 
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 39c5aad..72dd107 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -27,7 +27,7 @@ let package = Package(
             path: "../../Packages/Persistence"
         ),
         .package(
-            path: "../../Packages/Web"
+            path: "../../Packages/Infrastructure"
         ),
         .package(
             url: "https://github.com/elementary-swift/elementary.git",
@@ -80,7 +80,7 @@ let package = Package(
             dependencies: [
                 .byName(name: "Localization"),
                 .byName(name: "Persistence"),
-                .byName(name: "Web"),
+                .byName(name: "Infrastructure"),
                 .product(
                     name: "Configuration",
                     package: "swift-configuration"
@@ -120,7 +120,7 @@ let package = Package(
             name: "WebsiteLibraryTests",
             dependencies: [
                 .byName(name: "Persistence"),
-                .byName(name: "Web"),
+                .byName(name: "Infrastructure"),
                 .byName(name: "WebsiteLibrary"),
                 .product(
                     name: "Elementary",
diff --git a/Services/Website/README.md b/Services/Website/README.md
index ccaa62c..8178dfc 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -26,7 +26,7 @@ Two SwiftPM targets:
 
 The `Website` executable depends on three local packages:
 - `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteLibrary`).
-- `Web` (`Packages/Web`) — the `RouterController` protocol the controllers conform to and the `addController` result-builder extension that registers their routes on the router declaratively.
+- `Infrastructure` (`Packages/Infrastructure`) — the `RouterController` protocol the controllers conform to and the `addController` result-builder extension that registers their routes on the router declaratively.
 - `Persistence` (`Packages/Persistence`) — the Fluent-based data layer: the `Driver` selector, the `Service` factory that builds the `Fluent` service, the `PrepareDB` registrar that declares the migrations, and the `Probe` consulted by the readiness check; the models, migrations, and repositories stay internal to the package. It has no dependency on `swift-configuration`; the executable maps the `database.*` keys onto the driver.
 
 The persistence backend runs as a `Fluent` service inside the application's ServiceLifecycle group, so it starts and stops alongside the HTTP server (which owns its connection-pool shutdown on graceful termination).
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 45814b8..e7bd7bc 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -3,7 +3,7 @@ import Hummingbird
 import HummingbirdCompression
 import Logging
 import Persistence
-import Web
+import Infrastructure
 import WebsiteLibrary
 
 /// Builds the website application.
diff --git a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
index 55f732e..4597e27 100644
--- a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
@@ -1,7 +1,7 @@
 import Hummingbird
 import NIOCore
 import Persistence
-import Web
+import Infrastructure
 
 /// Serves the website's health-check routes.
 ///
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index 7a0dff0..f4995ed 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -1,5 +1,5 @@
 import Hummingbird
-import Web
+import Infrastructure
 
 /// Serves the website's root routes.
 ///
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 1b45edb..23fe521 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -48,22 +48,6 @@ struct AppTests {
         }
     }
 
-    @Test
-    func `landing page to answer a head request`() async throws {
-        try await app(
-            staticFilesPath: staticFilesPath
-        ).test(.router) { client in
-            try await client.execute(
-                uri: "/",
-                method: .head
-            ) { response in
-                #expect(response.status == .ok)
-                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
-                #expect(response.body.readableBytes == 0)
-            }
-        }
-    }
-
     @Test
     func `health check to be served at the health path`() async throws {
         try await app(
diff --git a/Services/Website/Tests/Website.xctestplan b/Services/Website/Tests/Website.xctestplan
index 0a36976..b82c471 100644
--- a/Services/Website/Tests/Website.xctestplan
+++ b/Services/Website/Tests/Website.xctestplan
@@ -48,9 +48,9 @@
     },
     {
       "target" : {
-        "containerPath" : "container:..\/..\/Packages\/Web",
-        "identifier" : "WebTests",
-        "name" : "WebTests"
+        "containerPath" : "container:..\/..\/Packages\/Infrastructure",
+        "identifier" : "InfrastructureTests",
+        "name" : "InfrastructureTests"
       }
     }
   ],
-- 
2.54.0


From cdded06ba3e7bb2c88dce2a8b2871acb1e6c60f8 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 23 Jul 2026 01:04:37 +0000
Subject: [PATCH 027/117] Renamed the Web package as Infrastructure (#25)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR contains the work done to rename the _Web_ package as _Infrastructure_, to provide a clear naming and purpose to this particular package within the project.

To provide further details about the work:

* Infrastructure
  * Asset fingerprinting: an FNV-1a token derived from the static files directory, appended as ?v= to asset URLs so deploys bust caches; pre-rendered pages also revalidate via weak ETags.
  * New middlewares: fixed-window RateLimitMiddleware (per-client budgets keyed by trusted X-Forwarded-For or remote address) and VaryMiddleware (Accept-Encoding on every response); SecurityHeadersMiddleware now also stamps error responses.
  * Auto-generated HEAD endpoints, cache max-age configuration, and Docker build/Compose refinements.
  * Protocols and scaffolding: Asset/AssetExtension, the Page protocol (viewport, stylesheets, scripts, versioned URLs), and LocalizedRequestContext.
  * Rate limiter's counter store swapped from an actor to a Mutex (no executor hop per request) with amortized batch eviction instead of O(n²) scans under client floods.
  * FingerprintAssets reports unreadable files to a logger instead of silently producing a token that never busts their cache.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/25
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Packages/Infrastructure/Package.swift         |  23 +-
 Packages/Infrastructure/README.md             |  34 ++
 .../Sources/Internal/Types/FNV1aHash.swift    |  47 +++
 .../Public/Enumerations/AssetExtension.swift  |  53 ++++
 .../Extensions/HTTPFieldName+Constants.swift  |   4 +-
 .../Public/Extensions/Int+Constants.swift     |   9 +
 .../Public/Extensions/String+Constants.swift  |  23 ++
 .../Public/Methods/FingerprintAssets.swift    |  85 +++++
 .../Middlewares/LocalizationMiddleware.swift  |  10 +-
 .../Middlewares/NotFoundMiddleware.swift      |  33 +-
 .../Middlewares/RateLimitMiddleware.swift     | 291 ++++++++++++++++++
 .../SecurityHeadersMiddleware.swift           |  21 +-
 .../Public/Middlewares/VaryMiddleware.swift   |  71 +++++
 .../Sources/Public/Protocols/Asset.swift      |  81 +++++
 .../Protocols/LocalizedRequestContext.swift   |  15 +
 .../Sources/Public/Protocols/Page.swift       |  87 ++++++
 .../Public/Responses/CachedHTMLResponse.swift | 114 +++++++
 .../LocalizedHTMLCollectionResponse.swift     |  31 +-
 .../Cases/Internal/Types/FNV1aHashTests.swift |  76 +++++
 .../Enumerations/AssetExtensionTests.swift    |  71 +++++
 .../Methods/FingerprintAssetsTests.swift      | 171 ++++++++++
 .../LocalizationMiddlewareTests.swift         |  69 +++++
 .../Middlewares/NotFoundMiddlewareTests.swift | 191 ++++++++++++
 .../RateLimitMiddlewareTests.swift            | 170 ++++++++++
 .../SecurityHeadersMiddlewareTests.swift      |  42 ++-
 .../Middlewares/VaryMiddlewareTests.swift     | 131 ++++++++
 .../Cases/Public/Protocols/AssetTests.swift   |  79 +++++
 .../Cases/Public/Protocols/PageTests.swift    |  62 ++++
 .../Tests/Catalogs/Localizable.xcstrings      |  23 ++
 .../Tests/Utils/Assets/StubAsset.swift        |  11 +
 .../Utils/Contexts/StubRequestContext.swift   |  26 ++
 .../Utils/Extensions/Tag+Constants.swift      |   8 +
 .../Tests/Utils/Pages/StubPage.swift          |  66 ++++
 Services/Website/Dockerfile                   |   2 +-
 Services/Website/Package.swift                |   1 +
 Services/Website/README.md                    |  12 +-
 .../Sources/App/Extensions/App+Build.swift    |  27 +-
 .../Extensions/ConfigReader+Properties.swift  |  37 ++-
 .../Internal/Enumerations/StaticFile.swift    | 105 +------
 .../Internal/Extensions/Page+Defaults.swift   |  70 +++++
 .../Library/Internal/Pages/ErrorPage.swift    |  21 +-
 .../Library/Internal/Pages/IndexPage.swift    |  21 +-
 .../Library/Internal/Protocols/Page.swift     | 109 -------
 .../Responses/CachedHTMLResponse.swift        |  72 -----
 ...text.swift => WebsiteRequestContext.swift} |  26 +-
 .../Public/Controllers/RootController.swift   |  19 +-
 .../AbsoluteConfigKey+Constants.swift         |  13 +-
 .../Extensions/ConfigKey+Constants.swift      |  13 +-
 .../Public/Extensions/Int+Constants.swift     |   4 +-
 .../LocalizationMiddleware+Defaults.swift     |  13 +
 .../NotFoundMiddleware+Defaults.swift         |  21 ++
 .../Public/Extensions/String+Constants.swift  |  21 --
 Services/Website/Tests/App/AppTests.swift     | 179 ++++++++++-
 .../Enumerations/StaticFileTests.swift        | 124 +-------
 .../Cases/Internal/Pages/IndexPageTests.swift |  14 +
 .../Controllers/RootControllerTests.swift     | 114 +++++++
 .../LocalizationMiddlewareTests.swift         |   2 +
 .../Middlewares/NotFoundMiddlewareTests.swift |  95 +++++-
 58 files changed, 2844 insertions(+), 519 deletions(-)
 create mode 100644 Packages/Infrastructure/README.md
 create mode 100644 Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
 rename {Services/Website/Sources/Library => Packages/Infrastructure/Sources}/Public/Extensions/HTTPFieldName+Constants.swift (72%)
 create mode 100644 Packages/Infrastructure/Sources/Public/Extensions/Int+Constants.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift
 rename {Services/Website/Sources/Library => Packages/Infrastructure/Sources}/Public/Middlewares/LocalizationMiddleware.swift (87%)
 rename {Services/Website/Sources/Library => Packages/Infrastructure/Sources}/Public/Middlewares/NotFoundMiddleware.swift (62%)
 create mode 100644 Packages/Infrastructure/Sources/Public/Middlewares/RateLimitMiddleware.swift
 rename {Services/Website/Sources/Library => Packages/Infrastructure/Sources}/Public/Middlewares/SecurityHeadersMiddleware.swift (88%)
 create mode 100644 Packages/Infrastructure/Sources/Public/Middlewares/VaryMiddleware.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Protocols/Page.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Responses/CachedHTMLResponse.swift
 rename {Services/Website/Sources/Library/Internal => Packages/Infrastructure/Sources/Public}/Responses/LocalizedHTMLCollectionResponse.swift (70%)
 create mode 100644 Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift
 rename {Services/Website/Tests/Library => Packages/Infrastructure/Tests}/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift (71%)
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
 create mode 100644 Packages/Infrastructure/Tests/Catalogs/Localizable.xcstrings
 create mode 100644 Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift
 create mode 100644 Packages/Infrastructure/Tests/Utils/Contexts/StubRequestContext.swift
 create mode 100644 Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
 create mode 100644 Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
 create mode 100644 Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
 delete mode 100644 Services/Website/Sources/Library/Internal/Protocols/Page.swift
 delete mode 100644 Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
 rename Services/Website/Sources/Library/Public/Contexts/{LocalizedRequestContext.swift => WebsiteRequestContext.swift} (57%)
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/LocalizationMiddleware+Defaults.swift
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift

diff --git a/Packages/Infrastructure/Package.swift b/Packages/Infrastructure/Package.swift
index 2f9227a..e399fba 100644
--- a/Packages/Infrastructure/Package.swift
+++ b/Packages/Infrastructure/Package.swift
@@ -16,6 +16,13 @@ let package = Package(
         ),
     ],
     dependencies: [
+        .package(
+            path: "../Localization"
+        ),
+        .package(
+            url: "https://github.com/elementary-swift/elementary.git",
+            from: "0.6.0"
+        ),
         .package(
             url: "https://github.com/hummingbird-project/hummingbird.git",
             from: "2.25.0"
@@ -25,6 +32,11 @@ let package = Package(
         .target(
             name: "Infrastructure",
             dependencies: [
+                .byName(name: "Localization"),
+                .product(
+                    name: "Elementary",
+                    package: "elementary"
+                ),
                 .product(
                     name: "Hummingbird",
                     package: "hummingbird"
@@ -36,12 +48,21 @@ let package = Package(
             name: "InfrastructureTests",
             dependencies: [
                 .byName(name: "Infrastructure"),
+                .product(
+                    name: "Elementary",
+                    package: "elementary"
+                ),
                 .product(
                     name: "HummingbirdTesting",
                     package: "hummingbird"
                 ),
             ],
-            path: "Tests"
+            path: "Tests",
+            resources: [
+                // Copied verbatim rather than processed: the String Catalog is read as raw JSON at
+                // runtime so it resolves identically on Darwin and Linux (which cannot compile it).
+                .copy("Catalogs/Localizable.xcstrings")
+            ]
         ),
     ]
 )
diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
new file mode 100644
index 0000000..7913a19
--- /dev/null
+++ b/Packages/Infrastructure/README.md
@@ -0,0 +1,34 @@
+# Infrastructure
+The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) toolkit the **Loud** services build on: declarative routing, hardened HTTP middlewares, pre-rendered localized HTML responses, and the page and asset scaffolding.
+
+## Overview
+The package provides, grouped by role:
+
+| Role | Types |
+| --- | --- |
+| Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
+| Middlewares | `SecurityHeadersMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
+| Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
+| Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
+| Contexts | `LocalizedRequestContext` |
+
+## Design rules
+The package holds only what every service can reuse; anything a service owns is injected, never referenced:
+
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors.
+- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern to follow.
+- **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
+
+## Layout
+Sources are split by visibility, then by kind, one type per file:
+
+```
+Sources/Public/<Kind>/     public API (Protocols, Middlewares, Responses, …)
+Sources/Internal/<Kind>/   implementation details (e.g. FNV1aHash)
+Tests/Cases/…              mirrors the source layout
+Tests/Utils/…              stubs and test-only extensions
+```
+
+## Requirements
+- Swift 6.3 toolchain (`swift-tools-version:6.3`).
+- macOS 15, matching the sibling `Localization` and `Persistence` packages (the services deploy to Linux containers; the packages carry no UI platforms).
diff --git a/Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift b/Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift
new file mode 100644
index 0000000..c33baab
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift
@@ -0,0 +1,47 @@
+import Foundation
+
+/// Hashes bytes with the FNV-1a 64-bit algorithm.
+///
+/// The hash is stable across processes and platforms, which `Hasher` deliberately is not, so it
+/// suits values that must agree between instances and survive restarts: the asset version token
+/// (``FingerprintAssets``) and the entity tags of the pre-rendered pages (`CachedHTMLResponse`).
+/// It is not cryptographic — a collision only risks serving a stale cached asset, not security.
+struct FNV1aHash {
+
+    // MARK: Properties
+
+    /// The running hash value.
+    private var hash: UInt64
+
+    // MARK: Initializers
+
+    /// Creates a hasher at the FNV-1a offset basis.
+    init() {
+        self.hash = 0xcbf2_9ce4_8422_2325
+    }
+
+    // MARK: Computed
+
+    /// The hash of everything combined so far, as a fixed-width, 16-character hexadecimal token.
+    ///
+    /// Reading it does not consume the running hash: more bytes can be combined afterwards.
+    var digest: String {
+        String(
+            format: "%016llx",
+            hash
+        )
+    }
+
+    // MARK: Functions
+
+    /// Folds the given bytes into the hash.
+    /// - Parameter bytes: the bytes to fold in.
+    mutating func combine(
+        _ bytes: some Sequence<UInt8>
+    ) {
+        for byte in bytes {
+            hash = (hash ^ UInt64(byte)) &* 0x100_0000_01b3
+        }
+    }
+
+}
diff --git a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
new file mode 100644
index 0000000..8729209
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
@@ -0,0 +1,53 @@
+/// A file extension used by an ``Asset``.
+///
+/// Each case's raw value is the extension itself (e.g. `"css"`), which an asset appends to its
+/// file name when resolving paths.
+public enum AssetExtension: String, Sendable {
+    /// A Cascading Style Sheets file.
+    case css
+    /// A JavaScript file.
+    case js
+    /// A Portable Network Graphics image.
+    case png
+    /// A Windows icon image.
+    case ico
+    /// A Scalable Vector Graphics image.
+    case svg
+    /// A plain text file.
+    case txt
+    /// A web application manifest file.
+    case webmanifest
+    /// An Extensible Markup Language file.
+    case xml
+}
+
+// MARK: - Extensions
+
+public extension AssetExtension {
+
+    // MARK: Computed
+
+    /// The file's content type.
+    var contentType: String {
+        switch self {
+        case .css: "text/css"
+        case .js: "text/javascript"
+        case .png: "image/png"
+        case .ico: "image/vnd.microsoft.icon"
+        case .svg: "image/svg+xml"
+        case .txt: "text/plain"
+        case .webmanifest: "application/manifest+json"
+        case .xml: "application/xml"
+        }
+    }
+
+    /// The sub-directory within the static root that holds files with this extension, if any.
+    var subdirectory: String? {
+        switch self {
+        case .css: "css"
+        case .js: "js"
+        default: nil
+        }
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift b/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
similarity index 72%
rename from Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift
rename to Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
index 4ebf3bb..9f89f0a 100644
--- a/Services/Website/Sources/Library/Public/Extensions/HTTPFieldName+Constants.swift
+++ b/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
@@ -1,10 +1,12 @@
 import HTTPTypes
 
-extension HTTPField.Name {
+public extension HTTPField.Name {
     /// The `Permissions-Policy` field name (not provided as a standard `HTTPField.Name`).
     static let permissionsPolicy = Self("Permissions-Policy")!
     /// The `Referrer-Policy` field name (not provided as a standard `HTTPField.Name`).
     static let referrerPolicy = Self("Referrer-Policy")!
     /// The `X-Frame-Options` field name (not provided as a standard `HTTPField.Name`).
     static let frameOptions = Self("X-Frame-Options")!
+    /// The `X-Forwarded-For` field name (not provided as a standard `HTTPField.Name`).
+    static let xForwardedFor = Self("X-Forwarded-For")!
 }
diff --git a/Packages/Infrastructure/Sources/Public/Extensions/Int+Constants.swift b/Packages/Infrastructure/Sources/Public/Extensions/Int+Constants.swift
new file mode 100644
index 0000000..b08ed06
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Extensions/Int+Constants.swift
@@ -0,0 +1,9 @@
+extension Int {
+    /// A namespace for the rate limit's default configuration values.
+    public enum RateLimit {
+        /// The default number of requests admitted per client per window.
+        public static let limit = 5
+        /// The default window length, in seconds (1 minute).
+        public static let window = 60
+    }
+}
diff --git a/Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift b/Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift
new file mode 100644
index 0000000..d01536e
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift
@@ -0,0 +1,23 @@
+extension String {
+    /// A namespace for the security headers' default configuration values.
+    ///
+    /// `Strict-Transport-Security` is intentionally absent: it is only safe over HTTPS and is
+    /// "sticky" in browsers, so it stays off unless explicitly configured in production.
+    public enum Security {
+        /// The default `Content-Security-Policy`.
+        ///
+        /// Restricts every resource to the site's own origin (`default-src 'self'`), blocks plugins
+        /// (`object-src 'none'`), pins the document base URL (`base-uri 'self'`), and forbids framing
+        /// (`frame-ancestors 'none'`). No inline-style exception is included, so pages must link
+        /// external stylesheets.
+        public static let contentSecurityPolicy = "default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
+        /// The default `X-Content-Type-Options` (disables MIME sniffing).
+        public static let contentTypeOptions = "nosniff"
+        /// The default `X-Frame-Options` (forbids framing the page).
+        public static let frameOptions = "DENY"
+        /// The default `Referrer-Policy`.
+        public static let referrerPolicy = "strict-origin-when-cross-origin"
+        /// The default `Permissions-Policy` (denies access to powerful browser features a static site does not use).
+        public static let permissionsPolicy = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
+    }
+}
diff --git a/Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift b/Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift
new file mode 100644
index 0000000..3a55d87
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift
@@ -0,0 +1,85 @@
+import Foundation
+import Logging
+
+/// Derives a version token from the contents of the static files directory.
+///
+/// The token folds every file under the directory — its relative path and its bytes, in a stable order — into one FNV-1a digest, so it changes whenever any
+/// asset changes and agrees across the instances of a deployment. The pages append it to their asset URLs (`?v=<token>`), which lets the assets be
+/// served with a long-lived, immutable cache policy: a deploy that changes an asset changes the URLs pointing at it, so no client ever revalidates or holds a
+/// stale copy.
+public struct FingerprintAssets: Sendable {
+
+    // MARK: Properties
+
+    /// The logger unreadable files are reported to, or `nil` to skip them silently.
+    private let logger: Logger?
+
+    // MARK: Initializers
+
+    /// Creates an asset fingerprinting method.
+    /// - Parameter logger: the logger unreadable files are reported to, or `nil` (the default) to skip them silently.
+    public init(
+        logger: Logger? = nil
+    ) {
+        self.logger = logger
+    }
+
+    // MARK: Functions
+
+    /// Fingerprints the static files under the given directory.
+    ///
+    /// A file that cannot be read is reported to the ``logger`` and left out of the token, so its
+    /// later changes would not bust caches — a warning there usually points at a permissions
+    /// problem in the deployment.
+    /// - Parameter path: the directory the static files are served from.
+    /// - Returns: the version token, or `nil` when the directory holds no readable files (asset URLs are then left unversioned).
+    public func callAsFunction(
+        _ path: String
+    ) -> String? {
+        let manager = FileManager.default
+
+        guard let enumerated = manager.enumerator(atPath: path) else {
+            return nil
+        }
+
+        // The path-based enumerator yields paths relative to the directory, so the token depends
+        // only on the directory's contents — never on where the directory itself lives (the
+        // URL-based enumerator standardizes symlinked bases, e.g. `/var/…` to `/private/var/…`,
+        // which would leak the absolute path into the hash).
+        var files: [String] = []
+
+        while let relativePath = enumerated.nextObject() as? String {
+            if enumerated.fileAttributes?[.type] as? FileAttributeType == .typeRegular {
+                files.append(relativePath)
+            }
+        }
+
+        var hash = FNV1aHash()
+        var hashed = false
+
+        for relativePath in files.sorted() {
+            guard let contents = manager.contents(
+                atPath: "\(path)/\(relativePath)"
+            ) else {
+                logger?.warning(
+                    "Static file could not be read while fingerprinting; the version token will not reflect it.",
+                    metadata: ["path": "\(relativePath)"]
+                )
+
+                continue
+            }
+
+            hash.combine(Array(relativePath.utf8))
+            hash.combine(contents)
+
+            hashed = true
+        }
+
+        guard hashed else {
+            return nil
+        }
+
+        return hash.digest
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
similarity index 87%
rename from Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift
rename to Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
index db18270..c743aa8 100644
--- a/Services/Website/Sources/Library/Public/Middlewares/LocalizationMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
@@ -1,3 +1,4 @@
+import Foundation
 import HTTPTypes
 import Hummingbird
 import Localization
@@ -19,9 +20,12 @@ public struct LocalizationMiddleware<Context: LocalizedRequestContext> {
 
     // MARK: Initializers
 
-    /// Creates a localization middleware that negotiates against the module's String Catalog languages.
-    public init() {
-        self.negotiate = .init(bundle: .module)
+    /// Creates a localization middleware that negotiates against the given bundle's String Catalog languages.
+    /// - Parameter bundle: the bundle whose String Catalog names the supported languages.
+    public init(
+        bundle: Bundle
+    ) {
+        self.negotiate = .init(bundle: bundle)
     }
 
 }
diff --git a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift
similarity index 62%
rename from Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
rename to Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift
index 6d053aa..b5f51e6 100644
--- a/Services/Website/Sources/Library/Public/Middlewares/NotFoundMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift
@@ -1,11 +1,12 @@
+import Elementary
+import Foundation
 import Hummingbird
 
 /// Serves a custom error page for requests that match neither a route nor a static file.
 ///
-/// Placed ahead of `FileMiddleware` in the middleware chain, it catches the `.notFound` error
-/// that bubbles up when no file exists for the requested path and responds with the rendered
-/// ``ErrorPage`` and a `404 Not Found` status. The page is served in the language stored on the
-/// context by ``LocalizationMiddleware``, falling back to the default language.
+/// Placed ahead of `FileMiddleware` in the middleware chain, it catches the `.notFound` error that bubbles up when no file exists for the requested
+/// path and responds with the rendered error page and a `404 Not Found` status. The page is served in the language stored on the context by
+/// ``LocalizationMiddleware``, falling back to the default language.
 public struct NotFoundMiddleware<Context: LocalizedRequestContext> {
 
     // MARK: Properties
@@ -16,12 +17,18 @@ public struct NotFoundMiddleware<Context: LocalizedRequestContext> {
     // MARK: Initializers
 
     /// Creates a not-found middleware.
-    public init() {
+    /// - Parameters:
+    ///   - bundle: the bundle whose String Catalog names the languages the page is rendered for.
+    ///   - document: builds the error page to render for a given locale.
+    public init<Document: HTMLDocument>(
+        bundle: Bundle,
+        document: (Locale) -> Document
+    ) {
         self.responses = .init(
-            status: .notFound
-        ) {
-            ErrorPage(locale: $0)
-        }
+            bundle: bundle,
+            status: .notFound,
+            document: document
+        )
     }
 
 }
@@ -32,15 +39,14 @@ extension NotFoundMiddleware: RouterMiddleware {
 
     // MARK: Functions
 
-    /// Passes the request down the chain, rendering the error page if it results in a not-found
-    /// response.
+    /// Passes the request down the chain, rendering the error page if it results in a not-found response.
     ///
     /// Any error other than `.notFound` is rethrown unchanged.
     /// - Parameters:
     ///   - request: the incoming request.
     ///   - context: the context the request is resolved against.
     ///   - next: the next responder in the middleware chain.
-    /// - Returns: the downstream response, or the rendered ``ErrorPage`` with a `404 Not Found` status.
+    /// - Returns: the downstream response, or the rendered error page with a `404 Not Found` status.
     /// - Throws: any non-not-found error thrown downstream.
     public func handle(
         _ request: Request,
@@ -59,7 +65,8 @@ extension NotFoundMiddleware: RouterMiddleware {
             }
 
             return responses.response(
-                for: context.language
+                for: context.language,
+                request: request
             )
         }
     }
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/RateLimitMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/RateLimitMiddleware.swift
new file mode 100644
index 0000000..d1a0f19
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/RateLimitMiddleware.swift
@@ -0,0 +1,291 @@
+import Foundation
+import HTTPTypes
+import Hummingbird
+import NIOCore
+import Synchronization
+
+/// Rejects a client's requests with `429 Too Many Requests` once they exceed a fixed-window rate limit.
+///
+/// Added to the routes that must not be hammered — the subscription endpoint, an unauthenticated database write — it admits up to the configured limit of
+/// requests per client per window, and answers the excess with `429 Too Many Requests` and a `Retry-After` header naming the seconds until the
+/// window resets.
+///
+/// A client is keyed by the first `X-Forwarded-For` entry when the ``Configuration`` trusts it, by the connection's remote address otherwise, and by
+/// one shared bucket when neither names the client. The counters live in memory with a bounded capacity, so a flood of distinct clients cannot grow the
+/// store without bound — and each instance of a multi-instance deployment enforces its own budget.
+public struct RateLimitMiddleware<Context: RequestContext>: Sendable {
+
+    // MARK: Properties
+
+    /// The fixed-window request counters, keyed by client.
+    private let buckets: Buckets
+
+    /// The limits the middleware enforces.
+    private let configuration: Configuration
+
+    // MARK: Initializers
+
+    /// Creates a rate-limit middleware.
+    /// - Parameter configuration: the limits the middleware enforces. Defaults to a budget suited to a form endpoint: a handful of requests per
+    ///   client per minute.
+    public init(
+        configuration: Configuration = .init()
+    ) {
+        self.buckets = .init(
+            limit: configuration.limit,
+            window: configuration.window
+        )
+        self.configuration = configuration
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension RateLimitMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Passes the request down the chain while the client stays within its budget, and answers it with `429 Too Many Requests` and a `Retry-After`
+    /// header once it does not.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response, or the `429` rejection.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        let admission = buckets.admit(
+            client(
+                for: request,
+                context: context
+            )
+        )
+
+        switch admission {
+        case .admitted:
+            return try await next(
+                request,
+                context
+            )
+        case .limited(let retryAfter):
+            var response = Response(status: .tooManyRequests)
+
+            response.headers[.retryAfter] = String(max(1, retryAfter.components.seconds))
+
+            return response
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension RateLimitMiddleware {
+
+    // MARK: Methods
+
+    /// The key identifying the requesting client: the first `X-Forwarded-For` entry when trusted, the connection's remote address otherwise, and one
+    /// bucket shared by every unidentifiable client when neither is known.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    /// - Returns: the client key the request is counted under.
+    func client(
+        for request: Request,
+        context: Context
+    ) -> String {
+        if
+            configuration.trustForwardedFor,
+            let forwarded = request.headers[.xForwardedFor]?
+                .split(separator: ",")
+                .first?
+                .trimmingCharacters(in: .whitespaces),
+            !forwarded.isEmpty
+        {
+            return forwarded
+        }
+
+        if let address = (context as? any RemoteAddressRequestContext)?.remoteAddress {
+            return address.ipAddress
+                ?? address.description
+        }
+
+        return .unidentified
+    }
+
+}
+
+// MARK: - Buckets
+
+private extension RateLimitMiddleware {
+
+    /// The outcome of asking the ``Buckets`` store to admit a request.
+    enum Admission {
+        /// The request is within the client's budget.
+        case admitted
+        /// The client exhausted its budget; the payload is the time until its window resets.
+        case limited(retryAfter: Duration)
+    }
+
+    /// The fixed-window request counters, keyed by client.
+    ///
+    /// The counters sit behind a mutex rather than an actor: an admission is a handful of dictionary operations, so the lock is held only briefly and the
+    /// calling task never suspends — requests skip the executor hop an actor would add on every pass through the middleware.
+    final class Buckets: Sendable {
+
+        // MARK: Properties
+
+        /// The maximum number of clients tracked at once, bounding the store's memory.
+        private let capacity: Int
+
+        /// The per-client counters: the start of the client's current window and its request count.
+        private let counters: Mutex<[String: (start: ContinuousClock.Instant, count: Int)]>
+
+        /// The number of requests admitted per client per ``window``.
+        private let limit: Int
+
+        /// The length of the fixed window the ``limit`` applies to.
+        private let window: Duration
+
+        // MARK: Initializers
+
+        /// Creates a counter store.
+        /// - Parameters:
+        ///   - limit: the number of requests admitted per client per window.
+        ///   - window: the length of the fixed window the limit applies to.
+        ///   - capacity: the maximum number of clients tracked at once.
+        init(
+            limit: Int,
+            window: Duration,
+            capacity: Int = 10_000
+        ) {
+            self.capacity = capacity
+            self.counters = .init([:])
+            self.limit = limit
+            self.window = window
+        }
+
+        // MARK: Functions
+
+        /// Counts a request against the client's current window and admits it while the count stays within the limit.
+        /// - Parameter client: the key the request is counted under.
+        /// - Returns: the admission outcome.
+        func admit(
+            _ client: String
+        ) -> Admission {
+            let now = ContinuousClock.now
+
+            return counters.withLock { counters in
+                if let counter = counters[client], now < counter.start.advanced(by: window) {
+                    guard counter.count < limit else {
+                        return .limited(retryAfter: now.duration(to: counter.start.advanced(by: window)))
+                    }
+
+                    counters[client] = (counter.start, counter.count + 1)
+
+                    return .admitted
+                }
+
+                makeRoom(
+                    in: &counters,
+                    at: now
+                )
+
+                counters[client] = (now, 1)
+
+                return .admitted
+            }
+        }
+
+        // MARK: Methods
+
+        /// Keeps the store within its capacity before a new client is tracked: expired windows are dropped first, and when the store remains full, the
+        /// oldest live windows are evicted in one batch — a tenth of the capacity — so the sort that finds them runs once per batch of admissions
+        /// instead of once per request while a flood of distinct clients keeps the store full.
+        /// - Parameters:
+        ///   - counters: the counters the room is made in.
+        ///   - now: the instant the expiry is evaluated against.
+        private func makeRoom(
+            in counters: inout [String: (start: ContinuousClock.Instant, count: Int)],
+            at now: ContinuousClock.Instant
+        ) {
+            guard counters.count >= capacity else {
+                return
+            }
+
+            counters = counters.filter {
+                now < $0.value.start.advanced(by: window)
+            }
+
+            let headroom = max(1, capacity / 10)
+            let excess = counters.count - (capacity - headroom)
+
+            guard excess > 0 else {
+                return
+            }
+
+            let oldest = counters
+                .sorted { $0.value.start < $1.value.start }
+                .prefix(excess)
+
+            for counter in oldest {
+                counters.removeValue(forKey: counter.key)
+            }
+        }
+
+    }
+
+}
+
+// MARK: - Configuration
+
+extension RateLimitMiddleware {
+    /// The limits a ``RateLimitMiddleware`` enforces.
+    public struct Configuration: Sendable {
+
+        // MARK: Properties
+
+        /// The number of requests admitted per client per ``window``.
+        public let limit: Int
+
+        /// Whether a client is keyed by the first `X-Forwarded-For` entry.
+        ///
+        /// Enable it only behind a reverse proxy that sets the header — there, the connection's own address would name the proxy for every visitor,
+        /// sharing one budget across all of them. On a directly reachable server the header is client-supplied, so trusting it lets a client forge fresh keys
+        /// at will.
+        public let trustForwardedFor: Bool
+
+        /// The length of the fixed window the ``limit`` applies to.
+        public let window: Duration
+
+        // MARK: Initializers
+
+        /// Creates a rate-limit configuration.
+        /// - Parameters:
+        ///   - limit: the number of requests admitted per client per window.
+        ///   - window: the length of the fixed window the limit applies to.
+        ///   - trustForwardedFor: whether a client is keyed by the first `X-Forwarded-For` entry.
+        public init(
+            limit: Int = .RateLimit.limit,
+            window: Duration = .seconds(Int.RateLimit.window),
+            trustForwardedFor: Bool = false
+        ) {
+            self.limit = limit
+            self.trustForwardedFor = trustForwardedFor
+            self.window = window
+        }
+
+    }
+}
+
+// MARK: - String+Constants
+
+private extension String {
+    /// The bucket shared by every client the middleware cannot identify.
+    static let unidentified = "unidentified"
+}
diff --git a/Services/Website/Sources/Library/Public/Middlewares/SecurityHeadersMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/SecurityHeadersMiddleware.swift
similarity index 88%
rename from Services/Website/Sources/Library/Public/Middlewares/SecurityHeadersMiddleware.swift
rename to Packages/Infrastructure/Sources/Public/Middlewares/SecurityHeadersMiddleware.swift
index 4bd48e9..ffa531f 100644
--- a/Services/Website/Sources/Library/Public/Middlewares/SecurityHeadersMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/SecurityHeadersMiddleware.swift
@@ -4,7 +4,7 @@ import Hummingbird
 /// Stamps a set of security-related HTTP headers onto every response.
 ///
 /// Placed at (or near) the top of the middleware chain, it adds the configured headers to whatever
-/// response bubbles back up — the rendered landing page, the ``ErrorPage`` produced by
+/// response bubbles back up — the rendered pages, the error page produced by
 /// ``NotFoundMiddleware``, and every static file served by `FileMiddleware` — so the browser applies
 /// the strict, hardened interpretation of the content instead of its lenient legacy defaults.
 ///
@@ -40,6 +40,9 @@ extension SecurityHeadersMiddleware: RouterMiddleware {
     /// Passes the request down the chain and stamps the configured security headers onto the
     /// response on the way back up.
     ///
+    /// Errors that can render themselves (`HTTPResponseError`, like the `HTTPError`s thrown by the
+    /// controllers) are converted to their response here rather than left to the router: the router
+    /// converts them above the middleware chain, where the response would escape these headers.
     /// Existing values for the same header names are replaced so downstream middleware cannot leave
     /// a weaker policy in place.
     /// - Parameters:
@@ -47,13 +50,25 @@ extension SecurityHeadersMiddleware: RouterMiddleware {
     ///   - context: the context the request is resolved against.
     ///   - next: the next responder in the middleware chain.
     /// - Returns: the downstream response with the security headers applied.
-    /// - Throws: any error thrown downstream.
+    /// - Throws: any downstream error that does not render as an HTTP response.
     public func handle(
         _ request: Request,
         context: Context,
         next: (Request, Context) async throws -> Response
     ) async throws -> Response {
-        var response = try await next(request, context)
+        var response: Response
+
+        do {
+            response = try await next(
+                request,
+                context
+            )
+        } catch let error as any HTTPResponseError {
+            response = try error.response(
+                from: request,
+                context: context
+            )
+        }
 
         for field in fields {
             response.headers[field.name] = field.value
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/VaryMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/VaryMiddleware.swift
new file mode 100644
index 0000000..a500a1b
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/VaryMiddleware.swift
@@ -0,0 +1,71 @@
+import Foundation
+import HTTPTypes
+import Hummingbird
+
+/// Appends header names to the `Vary` header of every response passing through.
+///
+/// Placed just above the response-compression middleware, it marks each response as varying on `Accept-Encoding`: the static files and pre-rendered
+/// pages are served with `Cache-Control: public`, so without the signal a shared cache could store a compressed body and hand it to a client that
+/// never advertised support for the encoding.
+///
+/// Names already present on a response's `Vary` header — such as the `Accept-Language` the localized pages carry — are kept, and duplicates are not
+/// added.
+public struct VaryMiddleware<Context: RequestContext>: Sendable {
+
+    // MARK: Properties
+
+    /// The header names appended to every response's `Vary` header.
+    private let names: [String]
+
+    // MARK: Initializers
+
+    /// Creates a vary middleware.
+    /// - Parameter fields: the header names appended to every response's `Vary` header. Defaults to `Accept-Encoding`, the request header
+    ///   the response-compression middleware acts on.
+    public init(
+        fields: [HTTPField.Name] = [.acceptEncoding]
+    ) {
+        self.names = fields.map(\.rawName)
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension VaryMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Passes the request down the chain and appends the configured names to the response's `Vary` header on the way back up.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the downstream response with the `Vary` names applied.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        var response = try await next(
+            request,
+            context
+        )
+
+        var vary = response.headers[.vary]?
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespaces) } ?? []
+
+        for name in names where !vary.contains(where: {
+            $0.caseInsensitiveCompare(name) == .orderedSame
+        }) {
+            vary.append(name)
+        }
+
+        response.headers[.vary] = vary.joined(separator: ", ")
+
+        return response
+    }
+
+}
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift b/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
new file mode 100644
index 0000000..6624516
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
@@ -0,0 +1,81 @@
+/// An asset shipped with a website: a file stored under the static files root and served by
+/// Hummingbird's `FileMiddleware` middleware.
+///
+/// A conforming asset supplies its file name and the extensions it is available with, each
+/// resolving to its own file; the protocol derives the paths from them: the file's path within
+/// the static files root and the URL path it is served at, optionally versioned to bust caches.
+public protocol Asset: Sendable {
+
+    // MARK: Properties
+
+    /// The file extensions the asset is available with.
+    var fileExtensions: [AssetExtension] { get }
+
+    /// The asset's file name, without extension.
+    var fileName: String { get }
+
+}
+
+// MARK: - Implementations
+
+public extension Asset {
+
+    // MARK: Methods
+
+    /// Resolves the asset's path against the given base directory.
+    ///
+    /// - Parameters:
+    ///   - basePath: the directory the static files are served from.
+    ///   - fileExtension: the extension of the file to resolve.
+    /// - Returns: the path to the file, relative to the `basePath` path.
+    func path(
+        relativeTo basePath: String,
+        for fileExtension: AssetExtension
+    ) -> String {
+        let relativePath = relativePath(for: fileExtension)
+
+        guard !basePath.isEmpty else {
+            return relativePath
+        }
+
+        return "\(basePath)/\(relativePath)"
+    }
+
+    /// Resolves the asset's path relative to the static files root (e.g. `"css/shared.css"`).
+    ///
+    /// This also matches the URL path the file is served at by `FileMiddleware`.
+    ///
+    /// - Parameter fileExtension: the extension of the file to resolve.
+    /// - Returns: the path to the file, relative to the static files root.
+    func relativePath(
+        for fileExtension: AssetExtension
+    ) -> String {
+        let file = "\(fileName).\(fileExtension.rawValue)"
+
+        return fileExtension.subdirectory
+            .map { "\($0)/\(file)" } ?? file
+    }
+
+    /// Resolves the absolute URL path the asset is served at (e.g. `"/css/shared.css"`).
+    ///
+    /// A version token appends as a `v` query parameter (e.g. `"/css/shared.css?v=abc123"`):
+    /// `FileMiddleware` ignores the query when resolving the file, while caches key on the full
+    /// URL, so a deploy that changes the assets busts every cached copy at once.
+    /// - Parameters:
+    ///   - fileExtension: the extension of the file to resolve.
+    ///   - version: the version token to append, or `nil` to leave the URL unversioned.
+    /// - Returns: the path to use in `href` and `src` attributes.
+    func urlPath(
+        for fileExtension: AssetExtension,
+        version: String? = nil
+    ) -> String {
+        let path = "/\(relativePath(for: fileExtension))"
+
+        guard let version, !version.isEmpty else {
+            return path
+        }
+
+        return "\(path)?v=\(version)"
+    }
+
+}
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift b/Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift
new file mode 100644
index 0000000..86fec3e
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift
@@ -0,0 +1,15 @@
+import Hummingbird
+
+/// A request context that carries the language negotiated for the request.
+///
+/// ``LocalizationMiddleware`` resolves the visitor's preferred language from the `Accept-Language`
+/// header and stores it here, so downstream controllers and middleware can serve the matching
+/// localization without re-reading the header.
+public protocol LocalizedRequestContext: RequestContext {
+
+    // MARK: Properties
+
+    /// The language identifier negotiated for the request.
+    var language: String { get set }
+
+}
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
new file mode 100644
index 0000000..1ab393e
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
@@ -0,0 +1,87 @@
+import Elementary
+import Foundation
+
+/// A page of a website: an HTML document with the shared scaffolding assembled around the page's content.
+///
+/// A conforming page supplies its locale, its title, the stylesheets and scripts it needs, its head metadata, and its content; the protocol assembles the
+/// rest of the document around them: the viewport declaration and stylesheet links followed by the metadata in the head, and the content followed by
+/// the script tags in the body.
+public protocol Page: HTMLDocument, Sendable {
+
+    // MARK: Associated types
+
+    /// The type of the page's markup.
+    associatedtype Content: HTML
+
+    /// The type of the page's head metadata markup.
+    associatedtype Metadata: HTML
+
+    // MARK: Properties
+
+    /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
+    var assetVersion: String? { get }
+
+    /// The page's markup, rendered before the ``scripts``.
+    @HTMLBuilder
+    var content: Content { get }
+
+    /// The locale the page content is localized to.
+    var locale: Locale { get }
+
+    /// The markup placed in the document head after the ``stylesheets``: icon and manifest
+    /// links, extra meta tags, and the like.
+    @HTMLBuilder
+    var metadata: Metadata { get }
+
+    /// The scripts loaded at the end of the document body, in order.
+    var scripts: [any Asset] { get }
+
+    /// The stylesheets linked in the document head, in order.
+    var stylesheets: [any Asset] { get }
+
+}
+
+// MARK: - Implementations
+
+public extension Page {
+
+    // MARK: Computed
+
+    /// The page ``content`` followed by its ``scripts``.
+    @HTMLBuilder
+    var body: some HTML {
+        content
+
+        for file in scripts {
+            script(.src(file.urlPath(
+                for: .js,
+                version: assetVersion
+            ))) {}
+        }
+    }
+
+    /// The viewport declaration and ``stylesheets`` links followed by the ``metadata``, placed in the document head.
+    ///
+    /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already
+    /// emits `<meta charset="UTF-8">` before this markup, and HTML5 allows only one.
+    @HTMLBuilder
+    var head: some HTML {
+        meta(
+            .name(.viewport),
+            .content("width=device-width, initial-scale=1")
+        )
+
+        metadata
+
+        for file in stylesheets {
+            link(
+                .rel(.stylesheet),
+                .href(file.urlPath(
+                    for: .css,
+                    version: assetVersion
+                ))
+            )
+        }
+    }
+
+}
diff --git a/Packages/Infrastructure/Sources/Public/Responses/CachedHTMLResponse.swift b/Packages/Infrastructure/Sources/Public/Responses/CachedHTMLResponse.swift
new file mode 100644
index 0000000..331defb
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Responses/CachedHTMLResponse.swift
@@ -0,0 +1,114 @@
+import Elementary
+import HTTPTypes
+import Hummingbird
+import NIOCore
+
+/// A pre-rendered HTTP response for a fully static HTML page.
+///
+/// The document is rendered to bytes once, at initialization, and every ``response(for:)`` reuses those bytes — along with a fixed status and
+/// precomputed headers — instead of re-rendering. This suits pages whose markup never changes between requests, such as the landing page and the
+/// not-found page, avoiding a per-request Elementary render on hot paths.
+///
+/// A successful page also revalidates cheaply: its headers carry a weak entity tag derived from the rendered bytes and a `Cache-Control` that asks
+/// clients to revalidate (`no-cache`), so a repeat visit costs a `304 Not Modified` instead of a full transfer — and a deploy that changes the page
+/// changes the tag, propagating immediately.
+///
+/// ``LocalizedHTMLCollectionResponse`` builds on this type, caching one instance per supported language.
+///
+/// The body is written as an unsized stream (no `Content-Length`), mirroring `HTMLResponse`, so the response-compression middleware downstream
+/// treats it exactly as it would a freshly rendered page.
+public struct CachedHTMLResponse: Sendable {
+
+    // MARK: Properties
+
+    /// The page rendered to bytes once.
+    private let buffer: ByteBuffer
+
+    /// The weak entity tag of the rendered bytes, present on successful pages only.
+    private let eTag: String?
+
+    /// The headers applied to every response, precomputed once.
+    private let headers: HTTPFields
+
+    /// The status applied to every response.
+    private let status: HTTPResponse.Status
+
+    // MARK: Initializers
+
+    /// Renders the given document to bytes once.
+    ///
+    /// A `200 OK` page gets the revalidation headers (`ETag` and `Cache-Control`); an error page does not, since a `304 Not Modified` only
+    /// ever stands in for a success.
+    /// - Parameters:
+    ///   - status: the status applied to every response. Defaults to `.ok`.
+    ///   - additionalHeaders: extra headers merged onto every response, alongside the content type.
+    ///     Used to carry per-language signals such as `Content-Language` and `Vary`.
+    ///   - document: the static HTML document to render and cache.
+    public init(
+        status: HTTPResponse.Status = .ok,
+        additionalHeaders: HTTPFields = [:],
+        document: some HTMLDocument
+    ) {
+        let buffer = ByteBuffer(string: document.render())
+        var headers: HTTPFields = [
+            .contentType: "text/html; charset=utf-8"
+        ]
+        var eTag: String?
+
+        if status == .ok {
+            var hash = FNV1aHash()
+
+            hash.combine(buffer.readableBytesView)
+
+            eTag = "W/\"\(hash.digest)\""
+
+            headers[.eTag] = eTag
+            headers[.cacheControl] = "public, no-cache"
+        }
+
+        for field in additionalHeaders {
+            headers[field.name] = field.value
+        }
+
+        self.buffer = buffer
+        self.eTag = eTag
+        self.headers = headers
+        self.status = status
+    }
+
+    // MARK: Methods
+
+    /// Builds a response from the cached, pre-rendered bytes.
+    ///
+    /// A conditional request whose `If-None-Match` names the page's entity tag is answered with a
+    /// bodyless `304 Not Modified`. Otherwise the full page is served, mirroring the
+    /// `text/html; charset=utf-8` content type `HTMLResponse` produces and leaving the
+    /// `Content-Length` unset so small pages remain eligible for compression.
+    /// - Parameter request: the request the response answers.
+    /// - Returns: the response carrying the cached HTML body, or its `304` revalidation.
+    public func response(
+        for request: Request
+    ) -> Response {
+        if
+            let eTag,
+            request.method == .get || request.method == .head,
+            let match = request.headers[.ifNoneMatch],
+            match == "*" || match.contains(eTag)
+        {
+            return Response(
+                status: .notModified,
+                headers: headers
+            )
+        }
+
+        return Response(
+            status: status,
+            headers: headers,
+            body: .init { [buffer] writer in
+                try await writer.write(buffer)
+                try await writer.finish(nil)
+            }
+        )
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Internal/Responses/LocalizedHTMLCollectionResponse.swift b/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
similarity index 70%
rename from Services/Website/Sources/Library/Internal/Responses/LocalizedHTMLCollectionResponse.swift
rename to Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
index e6772d1..b8c1161 100644
--- a/Services/Website/Sources/Library/Internal/Responses/LocalizedHTMLCollectionResponse.swift
+++ b/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
@@ -10,11 +10,11 @@ import Localization
 /// reports and caches the bytes, mirroring ``CachedHTMLResponse``'s render-once model but keyed by
 /// language. Each cached response carries a `Content-Language` header and `Vary: Accept-Language`, so
 /// shared caches key on the negotiated language instead of serving one language to everyone.
-struct LocalizedHTMLCollectionResponse: Sendable {
+public struct LocalizedHTMLCollectionResponse: Sendable {
 
     // MARK: Properties
 
-    /// The supported languages and default language, derived from the module's String Catalog.
+    /// The supported languages and default language, derived from the bundle's String Catalog.
     private let list: LanguageList
 
     /// The pre-rendered responses, keyed by language identifier.
@@ -24,13 +24,15 @@ struct LocalizedHTMLCollectionResponse: Sendable {
 
     /// Renders the document once per supported language.
     /// - Parameters:
+    ///   - bundle: the bundle whose String Catalog names the languages the document is rendered for.
     ///   - status: the status applied to every response. Defaults to `.ok`.
     ///   - document: builds the document to render for a given locale.
-    init<Document: HTMLDocument>(
+    public init<Document: HTMLDocument>(
+        bundle: Bundle,
         status: HTTPResponse.Status = .ok,
         document: (Locale) -> Document
     ) {
-        self.list = .init(bundle: .module)
+        self.list = .init(bundle: bundle)
         self.responses = list.all
             .reduce(into: [:]) { responses, language in
                 responses[language] = CachedHTMLResponse(
@@ -39,7 +41,9 @@ struct LocalizedHTMLCollectionResponse: Sendable {
                         .contentLanguage: language,
                         .vary: "Accept-Language",
                     ],
-                    document: document(.init(identifier: language))
+                    document: document(.init(
+                        identifier: language
+                    ))
                 )
             }
     }
@@ -47,19 +51,26 @@ struct LocalizedHTMLCollectionResponse: Sendable {
     // MARK: Methods
 
     /// Builds the response for the given language, falling back to the default language.
-    /// - Parameter language: the negotiated language identifier.
+    /// - Parameters:
+    ///   - language: the negotiated language identifier.
+    ///   - request: the request the response answers, consulted for conditional revalidation.
     /// - Returns: the cached response for the language, the default language's response when the
     ///   language is unavailable, or a `500 Internal Server Error` if neither is cached.
-    func response(
-        for language: String
+    public func response(
+        for language: String,
+        request: Request
     ) -> Response {
         guard
             let response = responses[language] ?? responses[list.default]
         else {
-            return .init(status: .internalServerError)
+            return .init(
+                status: .internalServerError
+            )
         }
 
-        return response.response()
+        return response.response(
+            for: request
+        )
     }
 
 }
diff --git a/Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift b/Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift
new file mode 100644
index 0000000..e876252
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift
@@ -0,0 +1,76 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite("FNV1aHash type")
+struct FNV1aHashTests {
+
+    // MARK: Functional tests
+
+    @Test(arguments: [
+        ("", "cbf29ce484222325"),
+        ("a", "af63dc4c8601ec8c"),
+        ("b", "af63df4c8601f1a5"),
+        ("foobar", "85944171f73967e8"),
+    ])
+    func `matches the published FNV-1a 64-bit test vectors`(
+        input: String,
+        digest: String
+    ) {
+        var hash = FNV1aHash()
+
+        hash.combine(input.utf8)
+
+        #expect(hash.digest == digest)
+    }
+
+    @Test
+    func `pads the digest to sixteen characters`() {
+        var hash = FNV1aHash()
+
+        // "aa" hashes to 0x089c4307b54596b7, whose leading zero the digest must keep.
+        hash.combine("aa".utf8)
+
+        #expect(hash.digest == "089c4307b54596b7")
+        #expect(hash.digest.count == 16)
+    }
+
+    @Test
+    func `hashes incrementally combined bytes as one stream`() {
+        var combined = FNV1aHash()
+        var whole = FNV1aHash()
+
+        combined.combine("foo".utf8)
+        combined.combine("bar".utf8)
+        whole.combine("foobar".utf8)
+
+        #expect(combined.digest == whole.digest)
+    }
+
+    @Test
+    func `distinguishes the order of the combined bytes`() {
+        var forward = FNV1aHash()
+        var backward = FNV1aHash()
+
+        forward.combine("ab".utf8)
+        backward.combine("ba".utf8)
+
+        #expect(forward.digest != backward.digest)
+    }
+
+    @Test
+    func `digests without consuming the running hash`() {
+        var hash = FNV1aHash()
+
+        hash.combine("foo".utf8)
+
+        let first = hash.digest
+
+        #expect(hash.digest == first)
+
+        hash.combine("bar".utf8)
+
+        #expect(hash.digest != first)
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
new file mode 100644
index 0000000..98730b5
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
@@ -0,0 +1,71 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite("AssetExtension enumeration")
+struct AssetExtensionTests {
+
+    // MARK: Computed tests
+
+    @Test(arguments: zip(
+        Self.extensions,
+        Self.contentTypes
+    ))
+    func `content type`(
+        for fileExtension: AssetExtension,
+        expects contentType: String
+    ) {
+        #expect(fileExtension.contentType == contentType)
+    }
+
+    @Test(arguments: zip(
+        Self.extensions,
+        Self.subdirectories
+    ))
+    func `subdirectory`(
+        for fileExtension: AssetExtension,
+        expects subdirectory: String?
+    ) {
+        #expect(fileExtension.subdirectory == subdirectory)
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension AssetExtensionTests {
+
+    // MARK: Constants
+
+    static let extensions: [AssetExtension] = [
+        .css,
+        .js,
+        .png,
+        .ico,
+        .svg,
+        .txt,
+        .webmanifest,
+        .xml
+    ]
+    static let contentTypes: [String] = [
+        "text/css",
+        "text/javascript",
+        "image/png",
+        "image/vnd.microsoft.icon",
+        "image/svg+xml",
+        "text/plain",
+        "application/manifest+json",
+        "application/xml"
+    ]
+    static let subdirectories: [String?] = [
+        "css",
+        "js",
+        nil,
+        nil,
+        nil,
+        nil,
+        nil,
+        nil
+    ]
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift
new file mode 100644
index 0000000..5c073e8
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift
@@ -0,0 +1,171 @@
+import Foundation
+import Testing
+
+@testable import Infrastructure
+
+@Suite("FingerprintAssets method")
+struct FingerprintAssetsTests {
+
+    // MARK: Properties
+
+    private let fingerprint = FingerprintAssets()
+
+    // MARK: Functional tests
+
+    @Test
+    func `fingerprints the files under a directory`() throws {
+        let directory = try makeDirectory(files: [
+            "css/site.css": "body { margin: 0; }",
+            "robots.txt": "User-agent: *"
+        ])
+
+        defer {
+            removeDirectory(directory)
+        }
+
+        let token = try #require(fingerprint(directory.path))
+
+        #expect(token.count == 16)
+        #expect(token.allSatisfy { $0.isHexDigit })
+    }
+
+    @Test
+    func `agrees across directories with identical contents`() throws {
+        let files = [
+            "css/site.css": "body { margin: 0; }",
+            "js/site.js": "console.log(1);"
+        ]
+        let first = try makeDirectory(files: files)
+        let second = try makeDirectory(files: files)
+
+        defer {
+            removeDirectory(first)
+            removeDirectory(second)
+        }
+
+        #expect(fingerprint(first.path) == fingerprint(second.path))
+    }
+
+    @Test
+    func `changes the token when a file's contents change`() throws {
+        let directory = try makeDirectory(files: [
+            "css/site.css": "body { margin: 0; }"
+        ])
+
+        defer {
+            removeDirectory(directory)
+        }
+
+        let before = fingerprint(directory.path)
+
+        try "body { margin: 1px; }".write(
+            to: directory.appendingPathComponent("css/site.css"),
+            atomically: true,
+            encoding: .utf8
+        )
+
+        #expect(fingerprint(directory.path) != before)
+    }
+
+    @Test
+    func `changes the token when a file is renamed`() throws {
+        let contents = "body { margin: 0; }"
+        let first = try makeDirectory(files: ["css/site.css": contents])
+        let second = try makeDirectory(files: ["css/main.css": contents])
+
+        defer {
+            removeDirectory(first)
+            removeDirectory(second)
+        }
+
+        #expect(fingerprint(first.path) != fingerprint(second.path))
+    }
+
+    @Test
+    func `changes the token when a file is added`() throws {
+        let directory = try makeDirectory(files: [
+            "css/site.css": "body { margin: 0; }"
+        ])
+
+        defer {
+            removeDirectory(directory)
+        }
+
+        let before = fingerprint(directory.path)
+
+        try "console.log(1);".write(
+            to: directory.appendingPathComponent("site.js"),
+            atomically: true,
+            encoding: .utf8
+        )
+
+        #expect(fingerprint(directory.path) != before)
+    }
+
+    @Test
+    func `returns nil for a directory without files`() throws {
+        let directory = try makeDirectory(files: [:])
+
+        defer {
+            removeDirectory(directory)
+        }
+
+        #expect(fingerprint(directory.path) == nil)
+    }
+
+    @Test
+    func `returns nil for a missing directory`() {
+        let missing = FileManager.default.temporaryDirectory
+            .appendingPathComponent("FingerprintAssetsTests-missing-\(UUID().uuidString)")
+
+        #expect(fingerprint(missing.path) == nil)
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension FingerprintAssetsTests {
+
+    // MARK: Methods
+
+    /// Creates a unique temporary directory holding the given files, keyed by relative path.
+    /// - Parameter files: the files to create, keyed by their path relative to the directory.
+    /// - Returns: the URL of the created directory.
+    func makeDirectory(
+        files: [String: String]
+    ) throws -> URL {
+        let directory = FileManager.default.temporaryDirectory
+            .appendingPathComponent("FingerprintAssetsTests-\(UUID().uuidString)")
+
+        try FileManager.default.createDirectory(
+            at: directory,
+            withIntermediateDirectories: true
+        )
+
+        for (relativePath, contents) in files {
+            let file = directory.appendingPathComponent(relativePath)
+
+            try FileManager.default.createDirectory(
+                at: file.deletingLastPathComponent(),
+                withIntermediateDirectories: true
+            )
+            try contents.write(
+                to: file,
+                atomically: true,
+                encoding: .utf8
+            )
+        }
+
+        return directory
+    }
+
+    /// Removes a temporary directory created by ``makeDirectory(files:)``.
+    /// - Parameter directory: the URL of the directory to remove.
+    func removeDirectory(
+        _ directory: URL
+    ) {
+        try? FileManager.default.removeItem(at: directory)
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
new file mode 100644
index 0000000..c18276e
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
@@ -0,0 +1,69 @@
+import Foundation
+import HTTPTypes
+import Hummingbird
+import HummingbirdTesting
+import NIOCore
+import Testing
+
+@testable import Infrastructure
+
+@Suite("LocalizationMiddleware middleware", .tags(.middleware))
+struct LocalizationMiddlewareTests {
+
+    // MARK: Constants
+
+    private let app: Application = .init(router: {
+        let router = Router(context: StubRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware(bundle: .module)
+        }
+
+        router.get("language") { _, context in
+            context.language
+        }
+
+        return router
+    }())
+
+    // MARK: Functional tests
+
+    @Test
+    func `negotiates a supported language from the header`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language",
+                method: .get,
+                headers: [.acceptLanguage: "de-DE,de;q=0.9"]
+            ) { response in
+                #expect(String(buffer: response.body) == "de")
+            }
+        }
+    }
+
+    @Test
+    func `falls back to the default without a header`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language",
+                method: .get
+            ) { response in
+                #expect(String(buffer: response.body) == "en")
+            }
+        }
+    }
+
+    @Test
+    func `falls back to the default for an unsupported language`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language",
+                method: .get,
+                headers: [.acceptLanguage: "fr-FR,fr;q=0.9"]
+            ) { response in
+                #expect(String(buffer: response.body) == "en")
+            }
+        }
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
new file mode 100644
index 0000000..895d90c
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
@@ -0,0 +1,191 @@
+import Foundation
+import Hummingbird
+import HummingbirdTesting
+import NIOCore
+import Testing
+
+@testable import Infrastructure
+
+@Suite("NotFoundMiddleware middleware", .tags(.middleware))
+struct NotFoundMiddlewareTests {
+
+    // MARK: Constants
+
+    private let app: Application = .init(router: {
+        let router = Router(context: StubRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware(bundle: .module)
+            NotFoundMiddleware(bundle: .module) {
+                StubPage(locale: $0)
+            }
+        }
+
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        router.get("boom") { _, _ -> String in
+            throw HTTPError(.badRequest)
+        }
+
+        return router
+    }())
+
+    // MARK: Functional tests
+
+    @Test
+    func `renders the error page for an unmatched request`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .notFound)
+                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
+                #expect(response.headers[.contentLanguage] == "en")
+                #expect(response.headers[.vary] == "Accept-Language")
+                #expect(body.contains("Stub content"))
+            }
+        }
+    }
+
+    @Test
+    func `renders the error page in the negotiated language`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get,
+                headers: [.acceptLanguage: "de-DE,de;q=0.9"]
+            ) { response in
+                #expect(response.status == .notFound)
+                #expect(response.headers[.contentLanguage] == "de")
+            }
+        }
+    }
+
+    @Test
+    func `passes a matched response through untouched`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.body == ByteBuffer(string: "Hello!"))
+            }
+        }
+    }
+
+    @Test
+    func `rethrows a non-not-found error unchanged`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/boom",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .badRequest)
+                #expect(!body.contains("Stub content"))
+            }
+        }
+    }
+
+    @Test
+    func `renders versioned asset URLs when given a version`() async throws {
+        try await app(
+            assetVersion: "0123456789abcdef"
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains("/css/stub.css?v=0123456789abcdef"))
+                #expect(body.contains("/js/stub.js?v=0123456789abcdef"))
+            }
+        }
+    }
+
+    @Test
+    func `renders unversioned asset URLs by default`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains(#"href="/css/stub.css""#))
+                #expect(!body.contains("?v="))
+            }
+        }
+    }
+
+    @Test
+    func `serves the error page without revalidation headers`() async throws {
+        // A `304 Not Modified` only ever stands in for a success, so the error page must not
+        // invite revalidation with an entity tag or a cache policy.
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                #expect(response.status == .notFound)
+                #expect(response.headers[.eTag] == nil)
+                #expect(response.headers[.cacheControl] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `serves the full error page to a conditional request`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get,
+                headers: [.ifNoneMatch: "*"]
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .notFound)
+                #expect(body.contains("Stub content"))
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension NotFoundMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose not-found middleware appends the given version token to the
+    /// error page's asset URLs.
+    /// - Parameter assetVersion: the version token appended to the page's asset URLs.
+    /// - Returns: the configured application.
+    func app(
+        assetVersion: String?
+    ) -> some ApplicationProtocol {
+        let router = Router(context: StubRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware(bundle: .module)
+            NotFoundMiddleware(bundle: .module) {
+                StubPage(
+                    locale: $0,
+                    assetVersion: assetVersion
+                )
+            }
+        }
+
+        return Application(router: router)
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift
new file mode 100644
index 0000000..5c6bd32
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift
@@ -0,0 +1,170 @@
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import Infrastructure
+
+@Suite("RateLimitMiddleware middleware", .tags(.middleware))
+struct RateLimitMiddlewareTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `admits requests within the limit`() async throws {
+        try await app(
+            configuration: .init(limit: 3)
+        ).test(.router) { client in
+            for _ in 1 ... 3 {
+                try await client.execute(
+                    uri: "/hello",
+                    method: .get
+                ) { response in
+                    #expect(response.status == .ok)
+                }
+            }
+        }
+    }
+
+    @Test
+    func `rejects a request over the limit with a retry-after header`() async throws {
+        try await app(
+            configuration: .init(limit: 2)
+        ).test(.router) { client in
+            for _ in 1 ... 2 {
+                try await client.execute(
+                    uri: "/hello",
+                    method: .get
+                ) { response in
+                    #expect(response.status == .ok)
+                }
+            }
+
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .tooManyRequests)
+
+                let retryAfter = try #require(response.headers[.retryAfter])
+
+                #expect(try #require(Int(retryAfter)) >= 1)
+            }
+        }
+    }
+
+    @Test
+    func `admits requests again once the window resets`() async throws {
+        try await app(
+            configuration: .init(
+                limit: 1,
+                window: .milliseconds(50)
+            )
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+            }
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .tooManyRequests)
+            }
+
+            try await Task.sleep(for: .milliseconds(100))
+
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+            }
+        }
+    }
+
+    @Test
+    func `separates clients by their forwarded address when trusted`() async throws {
+        try await app(
+            configuration: .init(
+                limit: 1,
+                trustForwardedFor: true
+            )
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.7"]
+            ) { response in
+                #expect(response.status == .ok)
+            }
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.8"]
+            ) { response in
+                #expect(response.status == .ok)
+            }
+            // The first entry names the client; the appended proxy hop must not change its key.
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.7, 10.0.0.1"]
+            ) { response in
+                #expect(response.status == .tooManyRequests)
+            }
+        }
+    }
+
+    @Test
+    func `ignores the forwarded address when not trusted`() async throws {
+        try await app(
+            configuration: .init(limit: 1)
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.7"]
+            ) { response in
+                #expect(response.status == .ok)
+            }
+            // Without trust (and without a connection address in router-only testing), every client
+            // shares one bucket, so a rotated header must not mint a fresh budget.
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedFor: "203.0.113.8"]
+            ) { response in
+                #expect(response.status == .tooManyRequests)
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension RateLimitMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose router applies the rate-limit middleware ahead of a single
+    /// `/hello` route returning a plain body.
+    func app(
+        configuration: RateLimitMiddleware<BasicRequestContext>.Configuration
+    ) -> some ApplicationProtocol {
+        let router = Router()
+
+        router.addMiddleware {
+            RateLimitMiddleware(configuration: configuration)
+        }
+
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        return Application(router: router)
+    }
+
+}
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
similarity index 71%
rename from Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
rename to Packages/Infrastructure/Tests/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
index e987adc..78db8c0 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
@@ -2,7 +2,7 @@ import Hummingbird
 import HummingbirdTesting
 import Testing
 
-@testable import WebsiteLibrary
+@testable import Infrastructure
 
 @Suite("SecurityHeadersMiddleware middleware", .tags(.middleware))
 struct SecurityHeadersMiddlewareTests {
@@ -17,11 +17,11 @@ struct SecurityHeadersMiddlewareTests {
                 method: .get
             ) { response in
                 #expect(response.status == .ok)
-                #expect(response.headers[.contentSecurityPolicy] == String.Security.contentSecurityPolicy)
-                #expect(response.headers[.xContentTypeOptions] == String.Security.contentTypeOptions)
-                #expect(response.headers[.frameOptions] == String.Security.frameOptions)
-                #expect(response.headers[.referrerPolicy] == String.Security.referrerPolicy)
-                #expect(response.headers[.permissionsPolicy] == String.Security.permissionsPolicy)
+                #expect(response.headers[.contentSecurityPolicy] == .Security.contentSecurityPolicy)
+                #expect(response.headers[.xContentTypeOptions] == .Security.contentTypeOptions)
+                #expect(response.headers[.frameOptions] == .Security.frameOptions)
+                #expect(response.headers[.referrerPolicy] == .Security.referrerPolicy)
+                #expect(response.headers[.permissionsPolicy] == .Security.permissionsPolicy)
             }
         }
     }
@@ -91,7 +91,24 @@ struct SecurityHeadersMiddlewareTests {
                 uri: "/weak",
                 method: .get
             ) { response in
-                #expect(response.headers[.xContentTypeOptions] == String.Security.contentTypeOptions)
+                #expect(response.headers[.xContentTypeOptions] == .Security.contentTypeOptions)
+            }
+        }
+    }
+
+    @Test
+    func `applies the security headers to an error response`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/throws",
+                method: .get
+            ) { response in
+                #expect(response.status == .badRequest)
+                #expect(response.headers[.contentSecurityPolicy] == .Security.contentSecurityPolicy)
+                #expect(response.headers[.xContentTypeOptions] == .Security.contentTypeOptions)
+                #expect(response.headers[.frameOptions] == .Security.frameOptions)
+                #expect(response.headers[.referrerPolicy] == .Security.referrerPolicy)
+                #expect(response.headers[.permissionsPolicy] == .Security.permissionsPolicy)
             }
         }
     }
@@ -104,9 +121,10 @@ private extension SecurityHeadersMiddlewareTests {
 
     // MARK: Methods
 
-    /// Builds an application whose router applies the security-headers middleware ahead of two
-    /// routes: `/hello` returns a plain body, and `/weak` returns a response that already carries a
-    /// deliberately weak `X-Content-Type-Options` value for the middleware to override.
+    /// Builds an application whose router applies the security-headers middleware ahead of three
+    /// routes: `/hello` returns a plain body, `/weak` returns a response that already carries a
+    /// deliberately weak `X-Content-Type-Options` value for the middleware to override, and
+    /// `/throws` fails with an `HTTPError` the way the controllers do on invalid input.
     func app(
         configuration: SecurityHeadersMiddleware<BasicRequestContext>.Configuration = .init()
     ) -> some ApplicationProtocol {
@@ -128,6 +146,10 @@ private extension SecurityHeadersMiddlewareTests {
             return response
         }
 
+        router.get("throws") { _, _ -> Response in
+            throw HTTPError(.badRequest)
+        }
+
         return Application(router: router)
     }
 
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift
new file mode 100644
index 0000000..afa7dad
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift
@@ -0,0 +1,131 @@
+import HTTPTypes
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import Infrastructure
+
+@Suite("VaryMiddleware middleware", .tags(.middleware))
+struct VaryMiddlewareTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `adds the default field to a response without a vary header`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/plain",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.vary] == "Accept-Encoding")
+            }
+        }
+    }
+
+    @Test
+    func `appends to an existing vary header`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/localized",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "Accept-Language, Accept-Encoding")
+            }
+        }
+    }
+
+    @Test
+    func `does not duplicate a name already present`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/encoded",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "Accept-Encoding")
+            }
+        }
+    }
+
+    @Test
+    func `matches an existing name regardless of its casing`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/lowercased",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "accept-encoding")
+            }
+        }
+    }
+
+    @Test
+    func `normalizes the whitespace of an existing list`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/spaced",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "Accept-Language, User-Agent, Accept-Encoding")
+            }
+        }
+    }
+
+    @Test
+    func `appends every configured field`() async throws {
+        try await app(
+            fields: [.acceptEncoding, .acceptLanguage]
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/plain",
+                method: .get
+            ) { response in
+                #expect(response.headers[.vary] == "Accept-Encoding, Accept-Language")
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension VaryMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose router applies the vary middleware ahead of routes whose
+    /// responses carry different `Vary` starting points: `/plain` none, `/localized` an
+    /// `Accept-Language`, `/encoded` an `Accept-Encoding` already, `/lowercased` a lowercase
+    /// `accept-encoding`, and `/spaced` a list with irregular whitespace.
+    func app(
+        fields: [HTTPField.Name] = [.acceptEncoding]
+    ) -> some ApplicationProtocol {
+        let router = Router()
+
+        router.addMiddleware {
+            VaryMiddleware(fields: fields)
+        }
+
+        router.get("plain") { _, _ in
+            "Hello!"
+        }
+
+        for (path, vary) in [
+            ("localized", "Accept-Language"),
+            ("encoded", "Accept-Encoding"),
+            ("lowercased", "accept-encoding"),
+            ("spaced", "Accept-Language ,  User-Agent"),
+        ] {
+            router.get(RouterPath(path)) { _, _ -> Response in
+                var response = Response(status: .ok)
+
+                response.headers[.vary] = vary
+
+                return response
+            }
+        }
+
+        return Application(router: router)
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
new file mode 100644
index 0000000..ea9c778
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
@@ -0,0 +1,79 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite("Asset protocol")
+struct AssetTests {
+
+    // MARK: Properties
+
+    private let image = StubAsset(
+        fileExtensions: [.png],
+        fileName: "icon"
+    )
+    private let shared = StubAsset(
+        fileExtensions: [.css, .js],
+        fileName: "shared"
+    )
+
+    // MARK: Method tests
+
+    @Test
+    func `relative path nests the file inside its extension's sub-directory`() {
+        #expect(shared.relativePath(for: .css) == "css/shared.css")
+        #expect(shared.relativePath(for: .js) == "js/shared.js")
+    }
+
+    @Test
+    func `relative path keeps the file at the root without a sub-directory`() {
+        #expect(image.relativePath(for: .png) == "icon.png")
+    }
+
+    @Test
+    func `url path prefixes the relative path with a slash`() {
+        #expect(shared.urlPath(for: .css) == "/css/shared.css")
+        #expect(image.urlPath(for: .png) == "/icon.png")
+    }
+
+    @Test
+    func `url path appends a version token as a query parameter`() {
+        #expect(shared.urlPath(
+            for: .css,
+            version: "0123456789abcdef"
+        ) == "/css/shared.css?v=0123456789abcdef")
+    }
+
+    @Test(arguments: [nil, ""] as [String?])
+    func `url path without a version`(
+        version: String?
+    ) {
+        #expect(shared.urlPath(
+            for: .css,
+            version: version
+        ) == "/css/shared.css")
+    }
+
+    @Test(arguments: [
+        "",
+        ".",
+        "Resources/Static"
+    ])
+    func `path relative to`(
+        _ basePath: String
+    ) {
+        for fileExtension in shared.fileExtensions {
+            let pathRelativeToBasePath = shared.path(
+                relativeTo: basePath,
+                for: fileExtension
+            )
+            let relativePath = shared.relativePath(for: fileExtension)
+
+            if basePath.isEmpty {
+                #expect(pathRelativeToBasePath == relativePath)
+            } else {
+                #expect(pathRelativeToBasePath == "\(basePath)/\(relativePath)")
+            }
+        }
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
new file mode 100644
index 0000000..a09a533
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
@@ -0,0 +1,62 @@
+import Elementary
+import Foundation
+import Testing
+
+@testable import Infrastructure
+
+@Suite("Page protocol", .tags(.page))
+struct PageTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `assembles the document around the page's parts`() {
+        let html = StubPage().render()
+
+        #expect(html.contains("<title>Stub Page</title>"))
+        #expect(html.contains(#"lang="en""#))
+        #expect(html.contains(#"name="viewport""#))
+        #expect(html.contains(#"<meta name="stub" content="marker">"#))
+        #expect(html.contains(#"<link rel="stylesheet" href="/css/stub.css">"#))
+        #expect(html.contains(#"<script src="/js/stub.js"></script>"#))
+        #expect(html.contains("Stub content"))
+    }
+
+    @Test
+    func `places the metadata between the viewport and the stylesheets`() throws {
+        let html = StubPage().render()
+
+        let viewport = try #require(html.range(of: #"name="viewport""#))
+        let metadata = try #require(html.range(of: #"name="stub""#))
+        let stylesheet = try #require(html.range(of: "/css/stub.css"))
+
+        #expect(viewport.lowerBound < metadata.lowerBound)
+        #expect(metadata.lowerBound < stylesheet.lowerBound)
+    }
+
+    @Test
+    func `renders the scripts after the content`() throws {
+        let html = StubPage().render()
+
+        let content = try #require(html.range(of: "Stub content"))
+        let script = try #require(html.range(of: "/js/stub.js"))
+
+        #expect(content.lowerBound < script.lowerBound)
+    }
+
+    @Test
+    func `appends the version token to the asset URLs`() {
+        let html = StubPage(assetVersion: "0123456789abcdef").render()
+
+        #expect(html.contains("/css/stub.css?v=0123456789abcdef"))
+        #expect(html.contains("/js/stub.js?v=0123456789abcdef"))
+    }
+
+    @Test
+    func `derives the document language from the locale`() {
+        let html = StubPage(locale: .init(identifier: "de-DE")).render()
+
+        #expect(html.contains(#"lang="de""#))
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Catalogs/Localizable.xcstrings b/Packages/Infrastructure/Tests/Catalogs/Localizable.xcstrings
new file mode 100644
index 0000000..897a3e0
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Catalogs/Localizable.xcstrings
@@ -0,0 +1,23 @@
+{
+  "sourceLanguage" : "en",
+  "strings" : {
+    "test.greeting" : {
+      "comment" : "Fixture string used by the Infrastructure test suite.",
+      "localizations" : {
+        "de" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hallo"
+          }
+        },
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Hello"
+          }
+        }
+      }
+    }
+  },
+  "version" : "1.0"
+}
diff --git a/Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift b/Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift
new file mode 100644
index 0000000..c508008
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift
@@ -0,0 +1,11 @@
+import Infrastructure
+
+/// An ``Asset`` with a fixed file name and set of extensions.
+struct StubAsset: Asset {
+
+    // MARK: Properties
+
+    let fileExtensions: [AssetExtension]
+    let fileName: String
+
+}
diff --git a/Packages/Infrastructure/Tests/Utils/Contexts/StubRequestContext.swift b/Packages/Infrastructure/Tests/Utils/Contexts/StubRequestContext.swift
new file mode 100644
index 0000000..aa28122
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Utils/Contexts/StubRequestContext.swift
@@ -0,0 +1,26 @@
+import Hummingbird
+import Infrastructure
+
+/// A ``LocalizedRequestContext`` carrying the core storage and the negotiated language only.
+struct StubRequestContext: LocalizedRequestContext {
+
+    // MARK: Properties
+
+    /// The core request context storage Hummingbird requires.
+    var coreContext: CoreRequestContextStorage
+
+    /// The language identifier negotiated for the request.
+    var language: String
+
+    // MARK: Initializers
+
+    /// Creates a request context for the given source.
+    /// - Parameter source: the source the context is initialized from.
+    init(
+        source: Source
+    ) {
+        self.coreContext = .init(source: source)
+        self.language = ""
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift b/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
new file mode 100644
index 0000000..e83de46
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
@@ -0,0 +1,8 @@
+import Testing
+
+extension Tag {
+    /// Tests exercising a middleware of the Infrastructure package.
+    @Tag static var middleware: Tag
+    /// Tests exercising the page scaffolding of the Infrastructure package.
+    @Tag static var page: Tag
+}
diff --git a/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift b/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
new file mode 100644
index 0000000..eae187d
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
@@ -0,0 +1,66 @@
+import Elementary
+import Foundation
+import Infrastructure
+
+/// A ``Page`` with fixed content, metadata, and stub assets.
+struct StubPage: Page {
+
+    // MARK: Properties
+
+    /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
+    let assetVersion: String?
+
+    /// The locale the page content is localized to.
+    let locale: Locale
+
+    // MARK: Initializers
+
+    /// Creates a stub page.
+    /// - Parameters:
+    ///   - locale: the locale the page content is localized to. Defaults to `en`.
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
+    ///     default) to leave them unversioned.
+    init(
+        locale: Locale = .init(identifier: "en"),
+        assetVersion: String? = nil
+    ) {
+        self.assetVersion = assetVersion
+        self.locale = locale
+    }
+
+    // MARK: Computed
+
+    var content: some HTML {
+        p { "Stub content" }
+    }
+
+    var lang: String {
+        locale.language.languageCode?.identifier ?? "en"
+    }
+
+    var metadata: some HTML {
+        meta(
+            .name("stub"),
+            .content("marker")
+        )
+    }
+
+    var scripts: [any Asset] {
+        [StubAsset(
+            fileExtensions: [.css, .js],
+            fileName: "stub"
+        )]
+    }
+
+    var stylesheets: [any Asset] {
+        [StubAsset(
+            fileExtensions: [.css, .js],
+            fileName: "stub"
+        )]
+    }
+
+    var title: String {
+        "Stub Page"
+    }
+
+}
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index f0fef04..2570487 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -55,9 +55,9 @@ RUN swift package --package-path ./Services/Website resolve
 
 # Copy only the Swift inputs needed for a release build. Static assets are built
 # in the assets stage and copied into staging after the binary is produced.
+COPY ./Packages/Infrastructure/Sources ./Packages/Infrastructure/Sources
 COPY ./Packages/Localization/Sources ./Packages/Localization/Sources
 COPY ./Packages/Persistence/Sources ./Packages/Persistence/Sources
-COPY ./Packages/Infrastructure/Sources ./Packages/Infrastructure/Sources
 COPY ./Services/Website/Sources ./Services/Website/Sources
 COPY ./Services/Website/Tests ./Services/Website/Tests
 
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 72dd107..0163147 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -108,6 +108,7 @@ let package = Package(
         .testTarget(
             name: "WebsiteTests",
             dependencies: [
+                .byName(name: "Infrastructure"),
                 .byName(name: "Website"),
                 .product(
                     name: "HummingbirdTesting",
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 8178dfc..9eef3ae 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -26,7 +26,7 @@ Two SwiftPM targets:
 
 The `Website` executable depends on three local packages:
 - `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteLibrary`).
-- `Infrastructure` (`Packages/Infrastructure`) — the `RouterController` protocol the controllers conform to and the `addController` result-builder extension that registers their routes on the router declaratively.
+- `Infrastructure` (`Packages/Infrastructure`) — the shared Hummingbird toolkit: the `RouterController` protocol and `addController` result-builder extension for declarative routing, the security/vary/rate-limit/localization/not-found middlewares, the `Page` and `Asset` scaffolding, the pre-rendered localized HTML responses, and the `FingerprintAssets` version-token derivation. The service supplies its specifics (String Catalog bundle, pages, icon metadata) through the `*+Defaults` extensions in `WebsiteLibrary`.
 - `Persistence` (`Packages/Persistence`) — the Fluent-based data layer: the `Driver` selector, the `Service` factory that builds the `Fluent` service, the `PrepareDB` registrar that declares the migrations, and the `Probe` consulted by the readiness check; the models, migrations, and repositories stay internal to the package. It has no dependency on `swift-configuration`; the executable maps the `database.*` keys onto the driver.
 
 The persistence backend runs as a `Fluent` service inside the application's ServiceLifecycle group, so it starts and stops alongside the HTTP server (which owns its connection-pool shutdown on graceful termination).
@@ -65,7 +65,8 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 ### Static file caching
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `cache.maxAge.text` | `CACHE_MAX_AGE_TEXT` | `3600` (1 hour) | `max-age` for text assets (CSS, JS, plain text); also marked `must-revalidate`. |
+| `cache.maxAge.asset` | `CACHE_MAX_AGE_ASSET` | `31536000` (1 year) | `max-age` for fingerprinted assets (CSS, JS) and fonts; also marked `immutable`. The pages reference CSS/JS through content-versioned URLs (`?v=<token>`), so a deploy busts them by changing the URL. |
+| `cache.maxAge.text` | `CACHE_MAX_AGE_TEXT` | `3600` (1 hour) | `max-age` for unversioned text assets (e.g. `robots.txt`); also marked `must-revalidate`. |
 | `cache.maxAge.image` | `CACHE_MAX_AGE_IMAGE` | `604800` (1 week) | `max-age` for images (ICO, PNG, SVG). |
 | `cache.maxAge.default` | `CACHE_MAX_AGE_DEFAULT` | `86400` (1 day) | `max-age` for everything else (e.g. the web manifest). |
 
@@ -106,6 +107,13 @@ See [Persistence](#persistence-1) below for the workflow.
 | --- | --- | --- | --- |
 | `path.staticFiles` | `PATH_STATIC_FILES` | `Resources/Static` | Directory, relative to the working directory, that static files are served from. |
 
+### Rate limiting
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `rateLimit.limit` | `RATELIMIT_LIMIT` | `5` | Requests admitted per client per window on the subscribe endpoint; the excess is answered with `429 Too Many Requests` and a `Retry-After` header. |
+| `rateLimit.window` | `RATELIMIT_WINDOW` | `60` | Window length, in seconds, the limit applies to. |
+| `rateLimit.trustForwardedFor` | `RATELIMIT_TRUST_FORWARDED_FOR` | `false` | Key clients by the first `X-Forwarded-For` entry instead of the connection's address. Enable only behind a reverse proxy that sets the header — otherwise clients can forge it; leave it off when the server is directly reachable. |
+
 ### Security headers
 | Config key | Environment variable | Default |
 | --- | --- | --- |
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index e7bd7bc..d4f66ed 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -26,6 +26,8 @@ func application(
         logger: logger
     )
     let fluent = persistence()
+
+    let fingerprintAssets = FingerprintAssets(logger: logger)
     let prepareDB = PrepareDB()
 
     await prepareDB(for: fluent)
@@ -33,8 +35,10 @@ func application(
     var app = Application(
         router: router(
             staticFilesPath: reader.staticFilesPath,
+            assetVersion: fingerprintAssets(reader.staticFilesPath),
             cacheControl: reader.cacheControl,
             compressionMinResponseSize: reader.compressionMinResponseSize,
+            rateLimit: reader.rateLimit,
             securityHeaders: reader.securityHeaders,
             logLevel: reader.logLevel,
             probe: Probe(fluent: fluent)
@@ -117,25 +121,31 @@ private func logger(
 /// Builds the application's router.
 ///
 /// Registers the request-logging middleware, the security-headers middleware that stamps the given `securityHeaders` onto every response, the
-/// response-compression middleware that compresses responses larger than `minimumResponseSizeToCompress` when the client advertises support,
-/// the localization middleware that negotiates the request's language from its `Accept-Language` header, the not-found middleware that serves the
-/// error page, and the static file middleware that serves the contents of `staticFilesPath` (tagging responses with the given `cacheControl`
-/// directives), then adds the `RootController` routes that render the landing page and the `HealthController` routes that serve the health check.
+/// vary middleware that marks every response as varying on `Accept-Encoding`, the response-compression middleware that compresses responses
+/// larger than `minimumResponseSizeToCompress` when the client advertises support, the localization middleware that negotiates the request's
+/// language from its `Accept-Language` header, the not-found middleware that serves the error page, and the static file middleware that serves the
+/// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then adds the `RootController` routes that
+/// render the landing page, the `SubscriptionController` routes that register newsletter subscriptions, and the `HealthController` routes
+/// that serve the health check.
 ///
 /// The security-headers middleware sits just inside request logging so it covers every response that reaches a client — the landing page, the compressed
 /// responses, the rendered error page, and the served static files.
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
+///   - assetVersion: the version token the pages append to their asset URLs, or `nil` to leave them unversioned.
 ///   - cacheControl: the cache-control directives applied to the served static files.
 ///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
+///   - rateLimit: the rate limit applied to the subscription endpoint.
 ///   - securityHeaders: the security headers applied to every response.
 ///   - logLevel: the level the request-logging middleware logs at.
 ///   - probe: the probe consulted by the `HealthController` readiness route.
 /// - Returns: the configured router.
 private func router(
     staticFilesPath: String,
+    assetVersion: String?,
     cacheControl: CacheControl,
     compressionMinResponseSize: Int,
+    rateLimit: RateLimitMiddleware<AppRequestContext>.Configuration,
     securityHeaders: SecurityHeadersMiddleware<AppRequestContext>.Configuration,
     logLevel: Logger.Level,
     probe: Probe
@@ -152,11 +162,14 @@ private func router(
         SecurityHeadersMiddleware(
             configuration: securityHeaders
         )
+        VaryMiddleware()
         ResponseCompressionMiddleware(
             minimumResponseSizeToCompress: compressionMinResponseSize
         )
         LocalizationMiddleware()
-        NotFoundMiddleware()
+        NotFoundMiddleware(
+            assetVersion: assetVersion
+        )
         FileMiddleware(
             staticFilesPath,
             cacheControl: cacheControl
@@ -164,7 +177,9 @@ private func router(
     }
 
     router.addController {
-        RootController<AppRequestContext>()
+        RootController<AppRequestContext>(
+            assetVersion: assetVersion
+        )
         HealthController<AppRequestContext>(
             probe: probe
         )
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index 2f9fdc2..9acbbe5 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -1,5 +1,6 @@
 import Configuration
 import Hummingbird
+import Infrastructure
 import Logging
 import Persistence
 import WebsiteLibrary
@@ -15,9 +16,16 @@ package extension ConfigReader {
 
     /// The `Cache-Control` policy applied to static files, grouped by media type.
     ///
-    /// The max-ages are read from the `cache.maxAge.text`, `cache.maxAge.image`, and `cache.maxAge.default` keys. Text files (CSS,
-    /// JavaScript, plain text) additionally require revalidation once stale; images and everything else are served public with their max-age alone.
+    /// The max-ages are read from the `cache.maxAge.asset`, `cache.maxAge.text`, `cache.maxAge.image`, and
+    /// `cache.maxAge.default` keys. Stylesheets and scripts are referenced through fingerprinted URLs (see `FingerprintAssets`) and
+    /// fonts are immutable subset files, so all three are served long-lived and `immutable` — a deploy busts them by changing the URL, never by
+    /// revalidation. The remaining text files (e.g. `robots.txt`) keep their unversioned URLs and require revalidation once stale; images and
+    /// everything else are served public with their max-age alone. The groups match in order, so the specific types precede the `text` category.
     var cacheControl: CacheControl {
+        let maxAgeAsset = int(
+            forKey: .Cache.maxAgeAsset,
+            default: .Cache.maxAgeAsset
+        )
         let maxAgeDefault = int(
             forKey: .Cache.maxAgeDefault,
             default: .Cache.maxAgeDefault
@@ -32,6 +40,9 @@ package extension ConfigReader {
         )
 
         return .init([
+            (.textCss, [.public, .maxAge(maxAgeAsset), .immutable]),
+            (.textJavascript, [.public, .maxAge(maxAgeAsset), .immutable]),
+            (.font, [.public, .maxAge(maxAgeAsset), .immutable]),
             (.text, [.public, .maxAge(maxAgeText), .mustRevalidate]),
             (.image, [.public, .maxAge(maxAgeImage)]),
             (.init(type: .any), [.public, .maxAge(maxAgeDefault)]),
@@ -110,6 +121,28 @@ package extension ConfigReader {
         )
     }
 
+    /// The rate limit applied to the subscription endpoint, built from the `rateLimit.*` keys.
+    ///
+    /// `rateLimit.limit` requests are admitted per client per `rateLimit.window` seconds. When
+    /// `rateLimit.trustForwardedFor` is set, clients are keyed by the first `X-Forwarded-For` entry —
+    /// enable it only behind a reverse proxy that sets the header, since clients can forge it otherwise.
+    var rateLimit: RateLimitMiddleware<AppRequestContext>.Configuration {
+        .init(
+            limit: int(
+                forKey: .RateLimit.limit,
+                default: .RateLimit.limit
+            ),
+            window: .seconds(int(
+                forKey: .RateLimit.window,
+                default: .RateLimit.window
+            )),
+            trustForwardedFor: bool(
+                forKey: .RateLimit.trustForwardedFor,
+                default: false
+            )
+        )
+    }
+
     /// The security headers middleware configuration, built from the `security.*` keys.
     ///
     /// Every header value has a default except `Strict-Transport-Security`, which is only sent when `security.strictTransportSecurity`
diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
index 69afb22..d953601 100644
--- a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
@@ -1,9 +1,11 @@
+import Infrastructure
+
 /// A static file shipped with the website service.
 ///
 /// Each case identifies a file name stored under the static files root (the `Resources/Static`
 /// directory) and served by Hummingbird's `FileMiddleware` middleware. A name can be available
 /// with more than one extension (see ``fileExtensions``), each resolving to its own file.
-enum StaticFile: CaseIterable, Sendable {
+enum StaticFile: Asset, CaseIterable {
     /// The `apple-touch-icon.png` icon.
     case appleTouchIcon
     /// The `css/error.css` stylesheet and `js/error.js` script for the not-found page.
@@ -28,30 +30,6 @@ enum StaticFile: CaseIterable, Sendable {
     case sitemap
 }
 
-// MARK: - Enumerations
-
-extension StaticFile {
-    /// A file extension used by a ``StaticFile``.
-    enum Extension: String, Sendable {
-        /// A Cascading Style Sheets file.
-        case css
-        /// A JavaScript file.
-        case js
-        /// A Portable Network Graphics image.
-        case png
-        /// A Windows icon image.
-        case ico
-        /// A Scalable Vector Graphics image.
-        case svg
-        /// A plain text file.
-        case txt
-        /// A web application manifest file.
-        case webmanifest
-        /// An Extensible Markup Language file.
-        case xml
-    }
-}
-
 // MARK: - Extensions
 
 extension StaticFile {
@@ -59,7 +37,7 @@ extension StaticFile {
     // MARK: Computed
     
     /// The file extensions the file is available with.
-    var fileExtensions: [Extension] {
+    var fileExtensions: [AssetExtension] {
         switch self {
         case .appleTouchIcon,
              .icon192,
@@ -92,79 +70,4 @@ extension StaticFile {
         }
     }
 
-    // MARK: Methods
-
-    /// Resolves the file's path against the given base directory.
-    ///
-    /// - Parameters:
-    ///   - basePath: the directory the static files are served from.
-    ///   - fileExtension: the extension of the file to resolve.
-    /// - Returns: the path to the file, relative to the `basePath` path.
-    func path(
-        relativeTo basePath: String,
-        for fileExtension: Extension
-    ) -> String {
-        let relativePath = relativePath(for: fileExtension)
-
-        guard !basePath.isEmpty else {
-            return relativePath
-        }
-
-        return "\(basePath)/\(relativePath)"
-    }
-    
-    /// Resolves the file's path relative to the static files root (e.g. `"css/shared.css"`).
-    ///
-    /// This also matches the URL path the file is served at by `FileMiddleware`.
-    ///
-    /// - Parameter fileExtension: the extension of the file to resolve.
-    /// - Returns: the path to the file, relative to the static files root.
-    func relativePath(
-        for fileExtension: Extension
-    ) -> String {
-        let file = "\(fileName).\(fileExtension.rawValue)"
-
-        return fileExtension.subdirectory
-            .map { "\($0)/\(file)" } ?? file
-    }
-
-    /// Resolves the absolute URL path the file is served at (e.g. `"/css/shared.css"`).
-    ///
-    /// - Parameter fileExtension: the extension of the file to resolve.
-    /// - Returns: the path to use in `href` and `src` attributes.
-    func urlPath(
-        for fileExtension: Extension
-    ) -> String {
-        "/\(relativePath(for: fileExtension))"
-    }
-
-}
-
-extension StaticFile.Extension {
-    
-    // MARK: Computed
-
-    /// The file's content type.
-    var contentType: String {
-        switch self {
-        case .css: "text/css"
-        case .js: "text/javascript"
-        case .png: "image/png"
-        case .ico: "image/vnd.microsoft.icon"
-        case .svg: "image/svg+xml"
-        case .txt: "text/plain"
-        case .webmanifest: "application/manifest+json"
-        case .xml: "application/xml"
-        }
-    }
-
-    /// The sub-directory within the static root that holds files with this extension, if any.
-    var subdirectory: String? {
-        switch self {
-        case .css: "css"
-        case .js: "js"
-        default: nil
-        }
-    }
-
 }
diff --git a/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift b/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
new file mode 100644
index 0000000..71eefba
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
@@ -0,0 +1,70 @@
+import Elementary
+import Foundation
+import Infrastructure
+import Localization
+
+/// The site-wide defaults shared by every page of the website.
+extension Page {
+
+    // MARK: Computed
+
+    /// The document language, derived from the page's locale and falling back to the default language.
+    var lang: String {
+        locale.language.languageCode?.identifier
+            ?? LanguageList(bundle: .module).default
+    }
+
+    /// The icon, manifest, and theme colour metadata shared by every page of the website.
+    @HTMLBuilder
+    var metadata: some HTML {
+        link(
+            .rel(.icon),
+            .href(StaticFile.favicon.urlPath(
+                for: .ico,
+                version: assetVersion
+            )),
+            .custom(
+                name: "sizes",
+                value: "any"
+            )
+        )
+        link(
+            .rel(.icon),
+            .href(StaticFile.icon.urlPath(
+                for: .svg,
+                version: assetVersion
+            )),
+            .custom(
+                name: "type",
+                value: "image/svg+xml"
+            )
+        )
+        link(
+            .rel("apple-touch-icon"),
+            .href(StaticFile.appleTouchIcon.urlPath(
+                for: .png,
+                version: assetVersion
+            ))
+        )
+        link(
+            .rel("manifest"),
+            .href(StaticFile.site.urlPath(
+                for: .webmanifest,
+                version: assetVersion
+            ))
+        )
+        meta(
+            .name("theme-color"),
+            .content("#fafafa")
+        )
+        meta(
+            .name("theme-color"),
+            .content("#0c0710"),
+            .custom(
+                name: "media",
+                value: "(prefers-color-scheme: dark)"
+            )
+        )
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
index 3f332fb..2b19f7b 100644
--- a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
@@ -1,5 +1,6 @@
 import Elementary
 import Foundation
+import Infrastructure
 import Localization
 
 /// The HTML page rendered for a not-found response, with its text localized to a given locale.
@@ -7,6 +8,9 @@ struct ErrorPage {
 
     // MARK: Properties
 
+    /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
+    let assetVersion: String?
+
     /// The locale the page content is localized to.
     let locale: Locale
 
@@ -16,10 +20,15 @@ struct ErrorPage {
     // MARK: Initializers
 
     /// Creates a not-found page localized to the given locale.
-    /// - Parameter locale: the locale the page content is localized to.
+    /// - Parameters:
+    ///   - locale: the locale the page content is localized to.
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
+    ///     default) to leave them unversioned.
     init(
-        locale: Locale
+        locale: Locale,
+        assetVersion: String? = nil
     ) {
+        self.assetVersion = assetVersion
         self.locale = locale
         self.localize = .init(bundle: .module)
     }
@@ -40,12 +49,12 @@ extension ErrorPage: Page {
         }
     }
 
-    var scripts: [StaticFile] {
-        [.error, .shared]
+    var scripts: [any Asset] {
+        [StaticFile.error, StaticFile.shared]
     }
 
-    var stylesheets: [StaticFile] {
-        [.shared, .error]
+    var stylesheets: [any Asset] {
+        [StaticFile.shared, StaticFile.error]
     }
 
     var title: String {
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index aabef0b..bcb0475 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -1,5 +1,6 @@
 import Elementary
 import Foundation
+import Infrastructure
 import Localization
 
 /// The website's landing page, with its text localized to a given locale.
@@ -7,6 +8,9 @@ struct IndexPage {
 
     // MARK: Properties
 
+    /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
+    let assetVersion: String?
+
     /// The locale the page content is localized to.
     let locale: Locale
 
@@ -16,10 +20,15 @@ struct IndexPage {
     // MARK: Initializers
 
     /// Creates a landing page localized to the given locale.
-    /// - Parameter locale: the locale the page content is localized to.
+    /// - Parameters:
+    ///   - locale: the locale the page content is localized to.
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
+    ///     default) to leave them unversioned.
     init(
-        locale: Locale
+        locale: Locale,
+        assetVersion: String? = nil
     ) {
+        self.assetVersion = assetVersion
         self.locale = locale
         self.localize = .init(bundle: .module)
     }
@@ -38,12 +47,12 @@ extension IndexPage: Page {
         }
     }
 
-    var scripts: [StaticFile] {
-        [.index, .shared]
+    var scripts: [any Asset] {
+        [StaticFile.index, StaticFile.shared]
     }
 
-    var stylesheets: [StaticFile] {
-        [.shared, .index]
+    var stylesheets: [any Asset] {
+        [StaticFile.shared, StaticFile.index]
     }
 
     var title: String {
diff --git a/Services/Website/Sources/Library/Internal/Protocols/Page.swift b/Services/Website/Sources/Library/Internal/Protocols/Page.swift
deleted file mode 100644
index e8bc515..0000000
--- a/Services/Website/Sources/Library/Internal/Protocols/Page.swift
+++ /dev/null
@@ -1,109 +0,0 @@
-import Elementary
-import Foundation
-import Localization
-
-/// A page of the website: an HTML document with the shared scaffolding assembled around the page's content.
-///
-/// A conforming page supplies its locale, its localized title, the stylesheets and scripts it needs, and its content; the protocol assembles the rest of the
-/// document around them: the metadata, stylesheet, icon, and manifest links in the head, the content followed by the script tags in the body, and the
-/// document language derived from the locale.
-protocol Page: HTMLDocument, Sendable {
-
-    // MARK: Associated types
-
-    /// The type of the page's markup.
-    associatedtype Content: HTML
-
-    // MARK: Properties
-
-    /// The page's markup, rendered before the ``scripts``.
-    @HTMLBuilder
-    var content: Content { get }
-
-    /// The locale the page content is localized to.
-    var locale: Locale { get }
-
-    /// The scripts loaded at the end of the document body, in order.
-    var scripts: [StaticFile] { get }
-
-    /// The stylesheets linked in the document head, in order.
-    var stylesheets: [StaticFile] { get }
-
-}
-
-// MARK: - Implementations
-
-extension Page {
-
-    // MARK: Computed
-
-    /// The page ``content`` followed by its ``scripts``.
-    @HTMLBuilder
-    var body: some HTML {
-        content
-        for file in scripts {
-            script(.src(file.urlPath(for: .js))) {}
-        }
-    }
-
-    /// The metadata, ``stylesheets``, icon, and manifest links placed in the document head.
-    ///
-    /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already
-    /// emits `<meta charset="UTF-8">` before this markup, and HTML5 allows only one.
-    @HTMLBuilder
-    var head: some HTML {
-        meta(
-            .name(.viewport),
-            .content("width=device-width, initial-scale=1")
-        )
-        for file in stylesheets {
-            link(
-                .rel(.stylesheet),
-                .href(file.urlPath(for: .css))
-            )
-        }
-        link(
-            .rel(.icon),
-            .href(StaticFile.favicon.urlPath(for: .ico)),
-            .custom(
-                name: "sizes",
-                value: "any"
-            )
-        )
-        link(
-            .rel(.icon),
-            .href(StaticFile.icon.urlPath(for: .svg)),
-            .custom(
-                name: "type",
-                value: "image/svg+xml"
-            )
-        )
-        link(
-            .rel("apple-touch-icon"),
-            .href(StaticFile.appleTouchIcon.urlPath(for: .png))
-        )
-        link(
-            .rel("manifest"),
-            .href(StaticFile.site.urlPath(for: .webmanifest))
-        )
-        meta(
-            .name("theme-color"),
-            .content("#fafafa")
-        )
-        meta(
-            .name("theme-color"),
-            .content("#0c0710"),
-            .custom(
-                name: "media",
-                value: "(prefers-color-scheme: dark)"
-            )
-        )
-    }
-
-    /// The document language, derived from the page's locale and falling back to the default language.
-    var lang: String {
-        locale.language.languageCode?.identifier
-            ?? LanguageList(bundle: .module).default
-    }
-
-}
diff --git a/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift b/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
deleted file mode 100644
index f9da28a..0000000
--- a/Services/Website/Sources/Library/Internal/Responses/CachedHTMLResponse.swift
+++ /dev/null
@@ -1,72 +0,0 @@
-import Elementary
-import HTTPTypes
-import Hummingbird
-import NIOCore
-
-/// A pre-rendered HTTP response for a fully static HTML page.
-///
-/// The document is rendered to bytes once, at initialization, and every ``response()`` reuses those
-/// bytes — along with a fixed status and precomputed headers — instead of re-rendering. This suits
-/// pages whose markup never changes between requests, such as the landing page and the not-found
-/// page, avoiding a per-request Elementary render on hot paths.
-///
-/// ``LocalizedHTMLCollectionResponse`` builds on this type, caching one instance per supported language.
-///
-/// The body is written as an unsized stream (no `Content-Length`), mirroring `HTMLResponse`, so the
-/// response-compression middleware downstream treats it exactly as it would a freshly rendered page.
-struct CachedHTMLResponse: Sendable {
-
-    // MARK: Properties
-
-    /// The page rendered to bytes once.
-    private let buffer: ByteBuffer
-    /// The headers applied to every response, precomputed once.
-    private let headers: HTTPFields
-    /// The status applied to every response.
-    private let status: HTTPResponse.Status
-
-    // MARK: Initializers
-
-    /// Renders the given document to bytes once.
-    /// - Parameters:
-    ///   - status: the status applied to every response. Defaults to `.ok`.
-    ///   - additionalHeaders: extra headers merged onto every response, alongside the content type.
-    ///     Used to carry per-language signals such as `Content-Language` and `Vary`.
-    ///   - document: the static HTML document to render and cache.
-    init(
-        status: HTTPResponse.Status = .ok,
-        additionalHeaders: HTTPFields = [:],
-        document: some HTMLDocument
-    ) {
-        var headers: HTTPFields = [
-            .contentType: "text/html; charset=utf-8"
-        ]
-
-        for field in additionalHeaders {
-            headers[field.name] = field.value
-        }
-
-        self.status = status
-        self.headers = headers
-        self.buffer = .init(string: document.render())
-    }
-
-    // MARK: Methods
-
-    /// Builds a response from the cached, pre-rendered bytes.
-    ///
-    /// Mirrors the `text/html; charset=utf-8` content type `HTMLResponse` produces, and leaves the
-    /// `Content-Length` unset so small pages remain eligible for compression.
-    /// - Returns: the response carrying the cached HTML body.
-    func response() -> Response {
-        Response(
-            status: status,
-            headers: headers,
-            body: .init { [buffer] writer in
-                try await writer.write(buffer)
-                try await writer.finish(nil)
-            }
-        )
-    }
-
-}
diff --git a/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift b/Services/Website/Sources/Library/Public/Contexts/WebsiteRequestContext.swift
similarity index 57%
rename from Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift
rename to Services/Website/Sources/Library/Public/Contexts/WebsiteRequestContext.swift
index 0172f98..36e98d2 100644
--- a/Services/Website/Sources/Library/Public/Contexts/LocalizedRequestContext.swift
+++ b/Services/Website/Sources/Library/Public/Contexts/WebsiteRequestContext.swift
@@ -1,26 +1,13 @@
 import Hummingbird
-
-/// A request context that carries the language negotiated for the request.
-///
-/// ``LocalizationMiddleware`` resolves the visitor's preferred language from the `Accept-Language`
-/// header and stores it here, so downstream controllers and middleware can serve the matching
-/// localization without re-reading the header.
-public protocol LocalizedRequestContext: RequestContext {
-
-    // MARK: Properties
-
-    /// The language identifier negotiated for the request.
-    var language: String { get set }
-
-}
-
-// MARK: - Context
+import Infrastructure
+import NIOCore
 
 /// The website's request context.
 ///
 /// Extends the core request storage with the negotiated language, defaulting to the default
-/// supported language until ``LocalizationMiddleware`` resolves it from the request.
-public struct WebsiteRequestContext: LocalizedRequestContext {
+/// supported language until ``LocalizationMiddleware`` resolves it from the request, and with
+/// the connected client's address, so ``RateLimitMiddleware`` can key its budgets per client.
+public struct WebsiteRequestContext: LocalizedRequestContext, RemoteAddressRequestContext {
 
     // MARK: Properties
 
@@ -28,6 +15,8 @@ public struct WebsiteRequestContext: LocalizedRequestContext {
     public var coreContext: CoreRequestContextStorage
     /// The language identifier negotiated for the request.
     public var language: String
+    /// The address of the connected client, captured from the source channel.
+    public let remoteAddress: SocketAddress?
 
     // MARK: Initializers
 
@@ -38,6 +27,7 @@ public struct WebsiteRequestContext: LocalizedRequestContext {
     ) {
         self.coreContext = .init(source: source)
         self.language = .empty
+        self.remoteAddress = source.channel.remoteAddress
     }
 
 }
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index f4995ed..fef2cb9 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -1,3 +1,4 @@
+import Foundation
 import Hummingbird
 import Infrastructure
 
@@ -24,9 +25,16 @@ public struct RootController<Context: LocalizedRequestContext> {
     // MARK: Initializers
 
     /// Creates a root controller.
-    public init() {
-        self.responses = .init {
-            IndexPage(locale: $0)
+    /// - Parameter assetVersion: the version token appended to the page's asset URLs, or `nil`
+    ///   (the default) to leave them unversioned.
+    public init(
+        assetVersion: String? = nil
+    ) {
+        self.responses = .init(bundle: .module) {
+            IndexPage(
+                locale: $0,
+                assetVersion: assetVersion
+            )
         }
     }
 
@@ -70,7 +78,10 @@ private extension RootController {
         request: Request,
         context: Context
     ) -> Response {
-        responses.response(for: context.language)
+        responses.response(
+            for: context.language,
+            request: request
+        )
     }
 
 }
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index 9e3ac7d..9e4a82e 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -3,7 +3,9 @@ import Configuration
 extension AbsoluteConfigKey {
     /// A namespace for the static files cache configuration keys, as absolute keys.
     public enum Cache {
-        /// The absolute configuration key for the max-age, in seconds, applied to text-based static files.
+        /// The absolute configuration key for the max-age, in seconds, applied to fingerprinted assets and fonts.
+        public static let maxAgeAsset: AbsoluteConfigKey = .init(.Cache.maxAgeAsset)
+        /// The absolute configuration key for the max-age, in seconds, applied to unversioned text-based static files.
         public static let maxAgeText: AbsoluteConfigKey = .init(.Cache.maxAgeText)
         /// The absolute configuration key for the max-age, in seconds, applied to image static files.
         public static let maxAgeImage: AbsoluteConfigKey = .init(.Cache.maxAgeImage)
@@ -50,6 +52,15 @@ extension AbsoluteConfigKey {
         /// The absolute configuration key for the minimum log level.
         public static let level: AbsoluteConfigKey = .init(.Log.level)
     }
+    /// A namespace for the rate limit configuration keys, as absolute keys.
+    public enum RateLimit {
+        /// The absolute configuration key for the number of requests admitted per client per window.
+        public static let limit: AbsoluteConfigKey = .init(.RateLimit.limit)
+        /// The absolute configuration key for the window length, in seconds.
+        public static let window: AbsoluteConfigKey = .init(.RateLimit.window)
+        /// The absolute configuration key for keying clients by the first `X-Forwarded-For` entry.
+        public static let trustForwardedFor: AbsoluteConfigKey = .init(.RateLimit.trustForwardedFor)
+    }
     /// A namespace for the path configuration keys, as absolute keys.
     public enum Path {
         /// The absolute configuration key for the directory the static files are served from.
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index cef6a42..289641c 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -3,7 +3,9 @@ import Configuration
 extension ConfigKey {
     /// A namespace for the static files cache configuration keys.
     public enum Cache {
-        /// The configuration key for the max-age, in seconds, applied to text-based static files (CSS, JavaScript, plain text).
+        /// The configuration key for the max-age, in seconds, applied to fingerprinted assets (CSS, JavaScript) and fonts.
+        public static let maxAgeAsset: ConfigKey = "cache.maxAge.asset"
+        /// The configuration key for the max-age, in seconds, applied to unversioned text-based static files (e.g. plain text).
         public static let maxAgeText: ConfigKey = "cache.maxAge.text"
         /// The configuration key for the max-age, in seconds, applied to image static files (ICO, PNG, SVG).
         public static let maxAgeImage: ConfigKey = "cache.maxAge.image"
@@ -50,6 +52,15 @@ extension ConfigKey {
         /// The configuration key for the minimum log level.
         public static let level: ConfigKey = "log.level"
     }
+    /// A namespace for the rate limit configuration keys.
+    public enum RateLimit {
+        /// The configuration key for the number of requests admitted per client per window.
+        public static let limit: ConfigKey = "rateLimit.limit"
+        /// The configuration key for the window length, in seconds.
+        public static let window: ConfigKey = "rateLimit.window"
+        /// The configuration key for keying clients by the first `X-Forwarded-For` entry (enable only behind a trusted proxy).
+        public static let trustForwardedFor: ConfigKey = "rateLimit.trustForwardedFor"
+    }
     /// A namespace for the path configuration keys.
     public enum Path {
         /// The configuration key for the directory the static files are served from.
diff --git a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
index 201068a..f1adf3f 100644
--- a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
@@ -1,7 +1,9 @@
 extension Int {
     /// A namespace for the cache's default configuration values.
     public enum Cache {
-        /// The default max-age, in seconds, applied to text-based static files (1 hour).
+        /// The default max-age, in seconds, applied to fingerprinted assets and fonts (1 year).
+        public static let maxAgeAsset = 31_536_000
+        /// The default max-age, in seconds, applied to unversioned text-based static files (1 hour).
         public static let maxAgeText = 3_600
         /// The default max-age, in seconds, applied to image static files (1 week).
         public static let maxAgeImage = 604_800
diff --git a/Services/Website/Sources/Library/Public/Extensions/LocalizationMiddleware+Defaults.swift b/Services/Website/Sources/Library/Public/Extensions/LocalizationMiddleware+Defaults.swift
new file mode 100644
index 0000000..009dc7b
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/LocalizationMiddleware+Defaults.swift
@@ -0,0 +1,13 @@
+import Foundation
+import Infrastructure
+
+public extension LocalizationMiddleware {
+
+    // MARK: Initializers
+
+    /// Creates a localization middleware that negotiates against the module's String Catalog languages.
+    init() {
+        self.init(bundle: .module)
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift b/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
new file mode 100644
index 0000000..545dd1f
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
@@ -0,0 +1,21 @@
+import Foundation
+import Infrastructure
+
+public extension NotFoundMiddleware {
+
+    // MARK: Initializers
+
+    /// Creates a not-found middleware that renders the website's error page, localized to the module's String Catalog languages.
+    /// - Parameter assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
+    init(
+        assetVersion: String? = nil
+    ) {
+        self.init(bundle: .module) {
+            ErrorPage(
+                locale: $0,
+                assetVersion: assetVersion
+            )
+        }
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 23fa620..a70db40 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -23,27 +23,6 @@ extension String {
         /// The directory, relative to the working directory, that the website's static files are served from.
         public static let staticResources = "Resources/Static"
     }
-    /// A namespace for the security headers' default configuration values.
-    ///
-    /// `Strict-Transport-Security` is intentionally absent: it is only safe over HTTPS and is
-    /// "sticky" in browsers, so it stays off unless explicitly configured in production.
-    public enum Security {
-        /// The default `Content-Security-Policy`.
-        ///
-        /// Restricts every resource to the site's own origin (`default-src 'self'`), blocks plugins
-        /// (`object-src 'none'`), pins the document base URL (`base-uri 'self'`), and forbids framing
-        /// (`frame-ancestors 'none'`). Both pages link external stylesheets, so no inline-style
-        /// exception is required.
-        public static let contentSecurityPolicy = "default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
-        /// The default `X-Content-Type-Options` (disables MIME sniffing).
-        public static let contentTypeOptions = "nosniff"
-        /// The default `X-Frame-Options` (forbids framing the page).
-        public static let frameOptions = "DENY"
-        /// The default `Referrer-Policy`.
-        public static let referrerPolicy = "strict-origin-when-cross-origin"
-        /// The default `Permissions-Policy` (denies access to powerful browser features the site does not use).
-        public static let permissionsPolicy = "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()"
-    }
     /// A namespace for the server string constants.
     public enum Server {
         /// The website server's name.
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 23fe521..70fce3c 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -2,6 +2,7 @@ import Configuration
 import Foundation
 import Hummingbird
 import HummingbirdTesting
+import Infrastructure
 import NIOCore
 import Testing
 
@@ -12,11 +13,11 @@ import Testing
 struct AppTests {
 
     // MARK: Constants
-    
-    private let textExtensions: [StaticFile.Extension] = [
+
+    // Stylesheets and scripts are referenced through fingerprinted URLs, so they are served immutable.
+    private let immutableExtensions: [AssetExtension] = [
         .css,
-        .js,
-        .txt
+        .js
     ]
 
     // Absolute path to the package's "Resources/Static" folder, derived from this
@@ -48,6 +49,22 @@ struct AppTests {
         }
     }
 
+    @Test
+    func `landing page to answer a head request`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .head
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
+                #expect(response.body.readableBytes == 0)
+            }
+        }
+    }
+
     @Test
     func `health check to be served at the health path`() async throws {
         try await app(
@@ -106,7 +123,9 @@ struct AppTests {
                     #expect(cacheControl.contains("public") == true)
                     #expect(cacheControl.contains("max-age=") == true)
 
-                    if textExtensions.contains(fileExtension) {
+                    if immutableExtensions.contains(fileExtension) {
+                        #expect(cacheControl.contains("immutable") == true)
+                    } else if fileExtension == .txt {
                         #expect(cacheControl.contains("must-revalidate") == true)
                     }
                 }
@@ -114,6 +133,81 @@ struct AppTests {
         }
     }
 
+    @Test
+    func `versioned asset URL to be served`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/css/shared.css?v=0123456789abcdef",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.contentType] == "text/css")
+            }
+        }
+    }
+
+    @Test
+    func `landing page to reference fingerprinted assets`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains("/css/shared.css?v="))
+                #expect(body.contains("/js/shared.js?v="))
+            }
+        }
+    }
+
+    @Test
+    func `landing page to revalidate with an entity tag`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            let eTag = try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                #expect(response.headers[.cacheControl] == "public, no-cache")
+
+                return try #require(response.headers[.eTag])
+            }
+
+            try await client.execute(
+                uri: "/",
+                method: .get,
+                headers: [.ifNoneMatch: eTag]
+            ) { response in
+                #expect(response.status == .notModified)
+                #expect(response.body.readableBytes == 0)
+                #expect(response.headers[.eTag] == eTag)
+            }
+        }
+    }
+
+    @Test
+    func `responses to vary on language and encoding`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                let vary = try #require(response.headers[.vary])
+
+                #expect(vary.contains("Accept-Language"))
+                #expect(vary.contains("Accept-Encoding"))
+            }
+        }
+    }
+
     @Test
     func `response to be compressed when the client supports it`() async throws {
         try await app(
@@ -163,6 +257,81 @@ struct AppTests {
         }
     }
 
+    @Test
+    func `error page to reference fingerprinted assets`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains("/css/error.css?v="))
+                #expect(body.contains("/js/shared.js?v="))
+            }
+        }
+    }
+
+    @Test
+    func `error page to be served without revalidation headers`() async throws {
+        // A `304 Not Modified` only ever stands in for a success, so the error page must not
+        // invite revalidation with an entity tag or a cache policy.
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                #expect(response.status == .notFound)
+                #expect(response.headers[.eTag] == nil)
+                #expect(response.headers[.cacheControl] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `error page to vary on language and encoding`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let vary = try #require(response.headers[.vary])
+
+                #expect(vary.contains("Accept-Language"))
+                #expect(vary.contains("Accept-Encoding"))
+            }
+        }
+    }
+
+    @Test
+    func `landing page to revalidate a conditional head request`() async throws {
+        try await app(
+            staticFilesPath: staticFilesPath
+        ).test(.router) { client in
+            let eTag = try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                try #require(response.headers[.eTag])
+            }
+
+            try await client.execute(
+                uri: "/",
+                method: .head,
+                headers: [.ifNoneMatch: eTag]
+            ) { response in
+                #expect(response.status == .notModified)
+                #expect(response.body.readableBytes == 0)
+            }
+        }
+    }
+
     @Test
     func `security headers to be applied to the landing page`() async throws {
         try await app(
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index 2ca9b20..449238c 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -1,3 +1,4 @@
+import Infrastructure
 import Testing
 
 @testable import WebsiteLibrary
@@ -8,7 +9,6 @@ struct StaticFileTests {
     // MARK: Type aliases
 
     typealias File = StaticFile
-    typealias FileExtension = StaticFile.Extension
 
     // MARK: Computed tests
 
@@ -18,7 +18,7 @@ struct StaticFileTests {
     ))
     func `file extensions`(
         for file: File,
-        expects extensions: [FileExtension]
+        expects extensions: [AssetExtension]
     ) {
         #expect(file.fileExtensions == extensions)
     }
@@ -34,81 +34,6 @@ struct StaticFileTests {
         #expect(file.fileName == fileName)
     }
 
-    @Test(arguments: zip(
-        Self.extensions,
-        Self.contentTypes
-    ))
-    func `content type`(
-        for fileExtension: FileExtension,
-        expects contentType: String
-    ) {
-        #expect(fileExtension.contentType == contentType)
-    }
-
-    @Test(arguments: zip(
-        Self.extensions,
-        Self.subdirectories
-    ))
-    func `subdirectory`(
-        for fileExtension: FileExtension,
-        expects subdirectory: String?
-    ) {
-        #expect(fileExtension.subdirectory == subdirectory)
-    }
-
-    // MARK: Method tests
-
-    @Test(arguments: zip(
-        File.allCases,
-        Self.relativePaths
-    ))
-    func `relative path for`(
-        for file: File,
-        expects relativePaths: [String]
-    ) {
-        for (fileExtension, relativePath) in zip(file.fileExtensions, relativePaths) {
-            #expect(file.relativePath(for: fileExtension) == relativePath)
-        }
-    }
-
-    @Test(arguments: zip(
-        File.allCases,
-        Self.relativePaths
-    ))
-    func `url path for`(
-        for file: File,
-        expects relativePaths: [String]
-    ) {
-        for (fileExtension, relativePath) in zip(file.fileExtensions, relativePaths) {
-            #expect(file.urlPath(for: fileExtension) == "/\(relativePath)")
-        }
-    }
-
-    @Test(arguments: [
-        "",
-        ".",
-        "Resources/Static"
-    ])
-    func `path relative to`(
-        _ basePath: String
-    ) {
-        for file in File.allCases {
-            for fileExtension in file.fileExtensions {
-                let pathRelativeToBasePath = file.path(
-                    relativeTo: basePath,
-                    for: fileExtension
-                )
-                let relativePath = file.relativePath(for: fileExtension)
-
-                if basePath.isEmpty {
-                    #expect(pathRelativeToBasePath == relativePath)
-                } else {
-                    #expect(pathRelativeToBasePath == "\(basePath)/\(relativePath)")
-                }
-            }
-        }
-    }
-
     // MARK: CaseIterable tests
 
     @Test
@@ -124,37 +49,7 @@ private extension StaticFileTests {
 
     // MARK: Constants
 
-    static let extensions: [FileExtension] = [
-        .css,
-        .js,
-        .png,
-        .ico,
-        .svg,
-        .txt,
-        .webmanifest,
-        .xml
-    ]
-    static let contentTypes: [String] = [
-        "text/css",
-        "text/javascript",
-        "image/png",
-        "image/vnd.microsoft.icon",
-        "image/svg+xml",
-        "text/plain",
-        "application/manifest+json",
-        "application/xml"
-    ]
-    static let subdirectories: [String?] = [
-        "css",
-        "js",
-        nil,
-        nil,
-        nil,
-        nil,
-        nil,
-        nil
-    ]
-    static let fileExtensions: [[FileExtension]] = [
+    static let fileExtensions: [[AssetExtension]] = [
         [.png],
         [.css, .js],
         [.ico],
@@ -180,18 +75,5 @@ private extension StaticFileTests {
         "site",
         "sitemap"
     ]
-    static let relativePaths: [[String]] = [
-        ["apple-touch-icon.png"],
-        ["css/error.css", "js/error.js"],
-        ["favicon.ico"],
-        ["icon.svg"],
-        ["icon-192.png"],
-        ["icon-512.png"],
-        ["css/index.css", "js/index.js"],
-        ["robots.txt"],
-        ["css/shared.css", "js/shared.js"],
-        ["site.webmanifest"],
-        ["sitemap.xml"]
-    ]
 
 }
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index fc308d2..a98bb33 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -29,4 +29,18 @@ struct IndexPageTests {
         #expect(html.contains("/js/index.js"))
     }
 
+    @Test
+    func `renders versioned asset URLs when given a version`() {
+        let html = IndexPage(
+            locale: .init(identifier: "en"),
+            assetVersion: "0123456789abcdef"
+        ).render()
+
+        #expect(html.contains("/css/shared.css?v=0123456789abcdef"))
+        #expect(html.contains("/css/index.css?v=0123456789abcdef"))
+        #expect(html.contains("/js/shared.js?v=0123456789abcdef"))
+        #expect(html.contains("/js/index.js?v=0123456789abcdef"))
+        #expect(html.contains("/favicon.ico?v=0123456789abcdef"))
+    }
+
 }
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
index 54c3a4f..b705b7a 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
@@ -1,5 +1,6 @@
 import Hummingbird
 import HummingbirdTesting
+import Infrastructure
 import NIOCore
 import Testing
 
@@ -42,4 +43,117 @@ struct RootControllerTests {
         }
     }
 
+    @Test
+    func `serves the landing page with revalidation headers`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                let eTag = try #require(response.headers[.eTag])
+
+                #expect(eTag.hasPrefix(#"W/""#))
+                #expect(response.headers[.cacheControl] == "public, no-cache")
+            }
+        }
+    }
+
+    @Test
+    func `revalidates a matching conditional request with a 304`() async throws {
+        try await app.test(.router) { client in
+            let eTag = try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                try #require(response.headers[.eTag])
+            }
+
+            try await client.execute(
+                uri: "/",
+                method: .get,
+                headers: [.ifNoneMatch: eTag]
+            ) { response in
+                #expect(response.status == .notModified)
+                #expect(response.headers[.eTag] == eTag)
+                #expect(response.body.readableBytes == 0)
+            }
+        }
+    }
+
+    @Test
+    func `serves the full page to a non-matching conditional request`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get,
+                headers: [.ifNoneMatch: #"W/"0123456789abcdef""#]
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .ok)
+                #expect(body.contains("Hello world!"))
+            }
+        }
+    }
+
+    @Test
+    func `renders versioned asset URLs when given a version`() async throws {
+        try await app(
+            assetVersion: "0123456789abcdef"
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains("/css/index.css?v=0123456789abcdef"))
+                #expect(body.contains("/js/index.js?v=0123456789abcdef"))
+            }
+        }
+    }
+
+    @Test
+    func `renders unversioned asset URLs by default`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains(#"href="/css/index.css""#))
+                #expect(!body.contains("?v="))
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension RootControllerTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose root controller appends the given version token to the landing
+    /// page's asset URLs.
+    /// - Parameter assetVersion: the version token appended to the page's asset URLs.
+    /// - Returns: the configured application.
+    func app(
+        assetVersion: String?
+    ) -> some ApplicationProtocol {
+        let router = Router(context: WebsiteRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware()
+        }
+
+        router.addRoutes(RootController<WebsiteRequestContext>(
+            assetVersion: assetVersion
+        ).routes)
+
+        return Application(router: router)
+    }
+
 }
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
index 9b71671..60c8871 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
@@ -4,6 +4,8 @@ import HummingbirdTesting
 import NIOCore
 import Testing
 
+import Infrastructure
+
 @testable import WebsiteLibrary
 
 @Suite("LocalizationMiddleware middleware", .tags(.middleware))
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
index 3cffe32..22f1f9b 100644
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
@@ -3,6 +3,8 @@ import HummingbirdTesting
 import NIOCore
 import Testing
 
+import Infrastructure
+
 @testable import WebsiteLibrary
 
 @Suite("NotFoundMiddleware middleware", .tags(.middleware))
@@ -70,11 +72,102 @@ struct NotFoundMiddlewareTests {
                 method: .get
             ) { response in
                 let body = String(buffer: response.body)
-                
+
                 #expect(response.status == .badRequest)
                 #expect(!body.contains("Page Not Found"))
             }
         }
     }
 
+    @Test
+    func `renders versioned asset URLs when given a version`() async throws {
+        try await app(
+            assetVersion: "0123456789abcdef"
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains("/css/error.css?v=0123456789abcdef"))
+                #expect(body.contains("/js/shared.js?v=0123456789abcdef"))
+            }
+        }
+    }
+
+    @Test
+    func `renders unversioned asset URLs by default`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains(#"href="/css/error.css""#))
+                #expect(!body.contains("?v="))
+            }
+        }
+    }
+
+    @Test
+    func `serves the error page without revalidation headers`() async throws {
+        // A `304 Not Modified` only ever stands in for a success, so the error page must not
+        // invite revalidation with an entity tag or a cache policy.
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get
+            ) { response in
+                #expect(response.status == .notFound)
+                #expect(response.headers[.eTag] == nil)
+                #expect(response.headers[.cacheControl] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `serves the full error page to a conditional request`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/this-path-does-not-exist",
+                method: .get,
+                headers: [.ifNoneMatch: "*"]
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(response.status == .notFound)
+                #expect(body.contains("Page Not Found"))
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension NotFoundMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose not-found middleware appends the given version token to the
+    /// error page's asset URLs.
+    /// - Parameter assetVersion: the version token appended to the page's asset URLs.
+    /// - Returns: the configured application.
+    func app(
+        assetVersion: String?
+    ) -> some ApplicationProtocol {
+        let router = Router(context: WebsiteRequestContext.self)
+
+        router.addMiddleware {
+            LocalizationMiddleware()
+            NotFoundMiddleware(
+                assetVersion: assetVersion
+            )
+        }
+
+        return Application(router: router)
+    }
+
 }
-- 
2.54.0


From 088713532836fe053cb44431ce86af5036ce133c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 28 Jul 2026 23:37:33 +0000
Subject: [PATCH 028/117] Fixes for the Localization package (#26)

This PR contains the work done to

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/26
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../Internal/Protocols/CatalogResolving.swift |   6 +-
 .../Internal/Types/LanguageRange.swift        |  18 +++
 .../Internal/Types/StringCatalog.swift        | 120 ++++++++++++++--
 .../Public/Enumerations/CatalogState.swift    |  17 +++
 .../Sources/Public/Methods/Localize.swift     |  12 +-
 .../Sources/Public/Methods/Negotiate.swift    | 131 +++++++++++++-----
 .../Sources/Public/Types/LanguageList.swift   |  41 +++---
 .../Cases/Public/Methods/LocalizeTests.swift  |  86 ++++++++++++
 .../Cases/Public/Methods/NegotiateTests.swift |  53 ++++++-
 .../Public/Types/LanguageListTests.swift      |  55 ++++++--
 .../Tests/Catalogs/Localizable.xcstrings      |   6 +
 .../Tests/Utils/Resolvers/StubCatalog.swift   |  23 +++
 Services/Website/Package.swift                |   1 +
 .../Sources/App/Extensions/App+Build.swift    |  14 +-
 .../Internal/Extensions/Page+Defaults.swift   |   2 +-
 .../Extensions/LanguageList+Defaults.swift    |  13 ++
 16 files changed, 518 insertions(+), 80 deletions(-)
 create mode 100644 Packages/Localization/Sources/Internal/Types/LanguageRange.swift
 create mode 100644 Packages/Localization/Sources/Public/Enumerations/CatalogState.swift
 create mode 100644 Packages/Localization/Tests/Utils/Resolvers/StubCatalog.swift
 create mode 100644 Services/Website/Sources/Library/Public/Extensions/LanguageList+Defaults.swift

diff --git a/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift b/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
index bb003fd..a0e4dcf 100644
--- a/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
+++ b/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
@@ -16,9 +16,13 @@ protocol CatalogResolving: Sendable {
 
     // MARK: Properties
 
-    /// The source (development) language, used as the final fallback when a locale has no localization.
+    /// The source (development) language, used as the final fallback when a locale has no localization
+    /// and as the default language a ``LanguageList`` serves.
     var sourceLanguage: String { get }
 
+    /// The outcome of reading the backing catalog, for consumers to surface at startup.
+    var state: CatalogState { get }
+
     /// Every language the backend can resolve strings for, including the source language.
     var languages: Set<String> { get }
 
diff --git a/Packages/Localization/Sources/Internal/Types/LanguageRange.swift b/Packages/Localization/Sources/Internal/Types/LanguageRange.swift
new file mode 100644
index 0000000..1afaa6b
--- /dev/null
+++ b/Packages/Localization/Sources/Internal/Types/LanguageRange.swift
@@ -0,0 +1,18 @@
+/// A single language range parsed from an `Accept-Language` header entry.
+///
+/// A range pairs the language tag a client asked for with the `q` weight expressing how much the
+/// client prefers it, as RFC 9110 defines them. ``Negotiate`` parses each comma-separated header
+/// entry into one of these, then orders the ranges by descending weight so the most preferred tag
+/// is matched first.
+struct LanguageRange {
+
+    // MARK: Properties
+
+    /// The language tag the client asked for, such as `de` or `de-AT`, or the `*` wildcard.
+    let tag: String
+
+    /// The tag's `q` weight, from 0 ("not acceptable") to 1 (most preferred, the default when
+    /// an entry names no weight).
+    let quality: Double
+
+}
diff --git a/Packages/Localization/Sources/Internal/Types/StringCatalog.swift b/Packages/Localization/Sources/Internal/Types/StringCatalog.swift
index 477c33c..5eb7bd0 100644
--- a/Packages/Localization/Sources/Internal/Types/StringCatalog.swift
+++ b/Packages/Localization/Sources/Internal/Types/StringCatalog.swift
@@ -1,4 +1,5 @@
 import Foundation
+import Synchronization
 
 /// A decoded `.xcstrings` String Catalog, read directly from a bundle's resources.
 ///
@@ -18,6 +19,9 @@ struct StringCatalog: Sendable {
     /// The resolved entries, keyed by catalog key then by language code.
     let entries: [String: [String: String]]
 
+    /// The outcome of reading the catalog from its bundle.
+    let state: CatalogState
+
     // MARK: Computed
 
     /// Every language the catalog provides a localization for, including the source language.
@@ -46,8 +50,9 @@ struct StringCatalog: Sendable {
             forResource: table,
             withExtension: .Extension.stringCatalog
         ) else {
-            self.sourceLanguage = "en"
+            self.sourceLanguage = .Default.sourceLanguage
             self.entries = [:]
+            self.state = .missing
             return
         }
 
@@ -65,9 +70,59 @@ struct StringCatalog: Sendable {
                     (entry.localizations ?? [:])
                         .compactMapValues { $0.stringUnit?.value }
                 }
+            self.state = .loaded
         } catch {
-            self.sourceLanguage = "en"
+            self.sourceLanguage = .Default.sourceLanguage
             self.entries = [:]
+            self.state = .undecodable
+        }
+    }
+
+}
+
+// MARK: - Cache
+
+extension StringCatalog {
+
+    /// A cache key identifying a catalog by its bundle location and table name.
+    private struct Key: Hashable, Sendable {
+        let bundle: URL
+        let table: String
+    }
+
+    /// The decoded catalogs, keyed by bundle and table.
+    private static let cache = Mutex<[Key: StringCatalog]>([:])
+
+    /// Returns the catalog for the given bundle and table, decoding it on first access.
+    ///
+    /// Catalogs are immutable at runtime, so every ``Localize``, ``Negotiate``, and ``LanguageList``
+    /// bound to the same bundle shares one decoded catalog instead of re-reading its JSON.
+    /// - Parameters:
+    ///   - bundle: the bundle whose resources contain the String Catalog.
+    ///   - table: the name of the String Catalog resource, without the `.xcstrings` extension.
+    /// - Returns: the decoded catalog, from the cache when it has been read before.
+    static func cached(
+        bundle: Bundle,
+        table: String = "Localizable"
+    ) -> StringCatalog {
+        let key = Key(
+            bundle: bundle.bundleURL,
+            table: table
+        )
+
+        return cache.withLock { cache in
+            if let catalog = cache[key] {
+                return catalog
+            }
+
+            let catalog = StringCatalog(
+                bundle: bundle,
+                table: table
+            )
+
+            cache[key] = catalog
+
+            return catalog
         }
     }
 
@@ -77,6 +132,9 @@ struct StringCatalog: Sendable {
 
 extension StringCatalog: CatalogResolving {
 
+    /// Resolves a key by the most specific language tag first: the locale's full tag (`pt-BR`), then its
+    /// primary language code (`pt`), then the source language, then the key itself. Tags are matched
+    /// case-insensitively, so a regional catalog entry resolves for the locale ``Negotiate`` picked it for.
     func string(
         for key: String,
         in locale: Locale
@@ -85,15 +143,46 @@ extension StringCatalog: CatalogResolving {
             return key
         }
 
-        let language = locale
-            .language
-            .languageCode?
-            .identifier
-            ?? sourceLanguage
+        for tag in locale.catalogTags {
+            if let match = byLanguage.first(
+                where: { $0.key.lowercased() == tag }
+            ) {
+                return match.value
+            }
+        }
 
-        return byLanguage[language]
-            ?? byLanguage[sourceLanguage]
-            ?? key
+        return byLanguage[sourceLanguage] ?? key
+    }
+
+}
+
+// MARK: - Locale+Extensions
+
+private extension Locale {
+
+    /// The language tags to resolve a catalog entry against, most specific first.
+    ///
+    /// The locale's full identifier comes first, as a hyphenated, lowercased tag (`pt_BR` becomes
+    /// `pt-br`), followed by its primary language code when the two differ.
+    var catalogTags: [String] {
+        var tags: [String] = []
+        let identifier = identifier
+            .replacingOccurrences(
+                of: String.Separator.underscore,
+                with: String.Separator.dash
+            )
+            .lowercased()
+
+        if !identifier.isEmpty {
+            tags.append(identifier)
+        }
+
+        if let code = language.languageCode?.identifier.lowercased(),
+           code != identifier {
+            tags.append(code)
+        }
+
+        return tags
     }
 
 }
@@ -127,7 +216,18 @@ private extension StringCatalog {
 // MARK: - String+Constants
 
 private extension String {
+    /// The source language assumed when a catalog is missing or cannot be decoded, matching the
+    /// package's default localization.
+    enum Default {
+        static let sourceLanguage = "en"
+    }
+
     enum Extension {
         static let stringCatalog = "xcstrings"
     }
+
+    enum Separator {
+        static let dash = "-"
+        static let underscore = "_"
+    }
 }
diff --git a/Packages/Localization/Sources/Public/Enumerations/CatalogState.swift b/Packages/Localization/Sources/Public/Enumerations/CatalogState.swift
new file mode 100644
index 0000000..2e35e1b
--- /dev/null
+++ b/Packages/Localization/Sources/Public/Enumerations/CatalogState.swift
@@ -0,0 +1,17 @@
+/// The outcome of reading a String Catalog from its bundle.
+///
+/// The package degrades gracefully when a catalog cannot be read — lookups return their keys and the
+/// language list falls back to the default language — so nothing fails at the call site. This state is
+/// the signal a server checks once at startup to warn before visitors ever see raw localization keys.
+public enum CatalogState: Equatable, Sendable {
+
+    /// The catalog was found and decoded; its entries are resolvable.
+    case loaded
+
+    /// No catalog resource exists in the bundle; every lookup returns its key.
+    case missing
+
+    /// The catalog resource exists but is not valid `.xcstrings` JSON; every lookup returns its key.
+    case undecodable
+
+}
diff --git a/Packages/Localization/Sources/Public/Methods/Localize.swift b/Packages/Localization/Sources/Public/Methods/Localize.swift
index e2c18a6..b088d27 100644
--- a/Packages/Localization/Sources/Public/Methods/Localize.swift
+++ b/Packages/Localization/Sources/Public/Methods/Localize.swift
@@ -12,6 +12,16 @@ public struct Localize: Sendable {
     /// The backend that resolves keys against the catalog.
     private let resolver: any CatalogResolving
 
+    // MARK: Computed
+
+    /// The outcome of reading the bundle's String Catalog.
+    ///
+    /// Resolution degrades to returning raw keys rather than failing, so check this once at startup
+    /// and warn when it is not ``CatalogState/loaded``.
+    public var catalogState: CatalogState {
+        resolver.state
+    }
+
     // MARK: Initializers
 
     /// Creates a localizer backed by the String Catalog in the given bundle.
@@ -22,7 +32,7 @@ public struct Localize: Sendable {
         bundle: Bundle,
         table: String = "Localizable"
     ) {
-        self.init(resolver: StringCatalog(
+        self.init(resolver: StringCatalog.cached(
             bundle: bundle,
             table: table
         ))
diff --git a/Packages/Localization/Sources/Public/Methods/Negotiate.swift b/Packages/Localization/Sources/Public/Methods/Negotiate.swift
index 878b649..e0604be 100644
--- a/Packages/Localization/Sources/Public/Methods/Negotiate.swift
+++ b/Packages/Localization/Sources/Public/Methods/Negotiate.swift
@@ -4,7 +4,8 @@ import Foundation
 ///
 /// Bound to a bundle's catalog languages via ``LanguageList``, an instance is invoked like a
 /// function — through ``callAsFunction(acceptLanguage:)`` — to resolve a header value to a
-/// supported language identifier, falling back to the default language.
+/// supported language identifier, honouring the header's `q` weights as RFC 9110 prescribes and
+/// falling back to the default language.
 public struct Negotiate: Sendable {
 
     // MARK: Properties
@@ -27,10 +28,12 @@ public struct Negotiate: Sendable {
     /// Picks the best supported language for the given `Accept-Language` header value.
     ///
     /// Invoked by calling the instance directly, for example `negotiate(acceptLanguage: header)`.
-    /// The header is split into its language tags (dropping any `q` weights), then each tag is matched
-    /// against the supported languages in order of preference — first by an exact match, then by its
-    /// primary language subtag, so `de-AT` resolves to a supported `de`. When the header is absent or
-    /// matches nothing, the default language is returned.
+    /// The header is parsed into its language ranges, which are ordered by descending `q` weight as
+    /// RFC 9110 prescribes: an entry without a weight counts as 1, entries weighted 0 are
+    /// "not acceptable" and dropped, and equal weights keep the header order. Each tag is then matched
+    /// against the supported languages in turn — first by an exact match, then by its primary language
+    /// subtag, so `de-AT` resolves to a supported `de` — while the `*` wildcard accepts the default
+    /// language. When the header is absent or matches nothing, the default language is returned.
     /// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
     /// - Returns: the identifier of the supported language to serve.
     public func callAsFunction(
@@ -40,16 +43,20 @@ public struct Negotiate: Sendable {
             return list.default
         }
 
-        let tags = tags(from: language)
+        let ranges = ranges(from: language)
 
-        guard !tags.isEmpty else {
+        guard !ranges.isEmpty else {
             return list.default
         }
 
         let supported = list.all
 
-        for tag in tags {
-            if let match = match(tag: tag, in: supported) {
+        for range in ranges {
+            if range.tag == .wildcard {
+                return list.default
+            }
+
+            if let match = match(range.tag, in: supported) {
                 return match
             }
         }
@@ -65,27 +72,69 @@ private extension Negotiate {
 
     // MARK: Methods
 
-    /// Extracts the ordered language tags from an `Accept-Language` header value.
+    /// Parses an `Accept-Language` header value into its ``LanguageRange`` list, ordered by preference.
     ///
-    /// Each comma-separated entry is reduced to its language tag by dropping the `;q=` weight, and
-    /// blank entries are removed. The original order is kept, which mirrors descending preference
-    /// closely enough for `preferredLocalizations(from:forPreferences:)` to resolve correctly.
+    /// Each comma-separated entry yields its language tag and `q` weight. The ranges are sorted by
+    /// descending weight, entries weighted 0 are dropped as "not acceptable", and equally weighted
+    /// entries keep the header order.
     /// - Parameter acceptLanguage: the raw `Accept-Language` header value.
-    /// - Returns: the ordered, weight-stripped language tags.
-    func tags(
+    /// - Returns: the language ranges, most preferred first.
+    func ranges(
         from acceptLanguage: String
-    ) -> [String] {
+    ) -> [LanguageRange] {
         acceptLanguage
             .split(separator: .Separator.comma)
-            .map { entry in
-                entry
-                    .split(separator: .Separator.semicolon)
-                    .first
-                    .map(String.init)?
-                    .trimmingCharacters(in: .whitespaces)
-                ?? .empty
+            .compactMap(range(from:))
+            .filter { $0.quality > 0 }
+            .enumerated()
+            .sorted { lhs, rhs in
+                lhs.element.quality == rhs.element.quality
+                    ? lhs.offset < rhs.offset
+                    : lhs.element.quality > rhs.element.quality
             }
-            .filter { !$0.isEmpty }
+            .map(\.element)
+    }
+
+    /// Parses a single `Accept-Language` header entry into its ``LanguageRange``.
+    ///
+    /// The entry's language tag precedes the first `;`; a `q` parameter after it sets the weight.
+    /// A missing or malformed weight counts as 1, the highest preference, matching a tag sent
+    /// without one.
+    /// - Parameter entry: a single comma-separated header entry.
+    /// - Returns: the entry's language range, or `nil` when it has no language tag.
+    func range(
+        from entry: Substring
+    ) -> LanguageRange? {
+        let parts = entry.split(separator: .Separator.semicolon)
+        let tag = parts.first
+            .map(String.init)?
+            .trimmingCharacters(in: .whitespaces)
+            ?? .empty
+
+        guard !tag.isEmpty else {
+            return nil
+        }
+
+        let quality = parts
+            .dropFirst()
+            .compactMap { parameter -> Double? in
+                let parameter = parameter
+                    .trimmingCharacters(in: .whitespaces)
+                    .lowercased()
+
+                guard parameter.hasPrefix(.Prefix.quality) else {
+                    return nil
+                }
+
+                return Double(parameter.dropFirst(String.Prefix.quality.count))
+            }
+            .first
+            ?? 1
+
+        return .init(
+            tag: tag,
+            quality: quality
+        )
     }
 
     /// Finds the supported language that best matches a single `Accept-Language` tag.
@@ -97,7 +146,7 @@ private extension Negotiate {
     ///   - supported: the supported language identifiers.
     /// - Returns: the matching supported language, or `nil` when the tag matches none.
     func match(
-        tag: String,
+        _ tag: String,
         in supported: [String]
     ) -> String? {
         let tag = tag.lowercased()
@@ -117,10 +166,32 @@ private extension Negotiate {
 
 }
 
+// MARK: - Character+Extensions
+
+private extension Character {
+    
+    // MARK: Constants
+    
+    enum Separator {
+        static let comma: Character = ","
+        static let dash: Character = "-"
+        static let semicolon: Character = ";"
+    }
+}
+
+
 // MARK: - String+Extensions
 
 private extension String {
+    
+    // MARK: Constants
+
     static let empty: String = ""
+    static let wildcard: String = "*"
+    
+    enum Prefix {
+        static let quality = "q="
+    }
 
     /// The primary language subtag, i.e. everything before the first `-` (`de-AT` becomes `de`).
     var primarySubtag: String {
@@ -130,13 +201,3 @@ private extension String {
         ?? self
     }
 }
-
-// MARK: - Constants
-
-private extension Character {
-    enum Separator {
-        static let comma: Character = ","
-        static let dash: Character = "-"
-        static let semicolon: Character = ";"
-    }
-}
diff --git a/Packages/Localization/Sources/Public/Types/LanguageList.swift b/Packages/Localization/Sources/Public/Types/LanguageList.swift
index eff831a..42a0e84 100644
--- a/Packages/Localization/Sources/Public/Types/LanguageList.swift
+++ b/Packages/Localization/Sources/Public/Types/LanguageList.swift
@@ -8,46 +8,47 @@ public struct LanguageList: Sendable {
 
     // MARK: Properties
 
-    /// The language served when none of the supported languages match a request.
-    ///
-    /// Should match the catalog bundle's development localization.
-    public let `default`: String
-
     /// The backend that reports the available languages.
     private let resolver: any CatalogResolving
 
     // MARK: Initializers
 
     /// Creates a language list backed by the given bundle.
-    /// - Parameters:
-    ///   - bundle: the bundle whose String Catalog defines the available languages.
-    ///   - default: the language served when none of the supported languages match. Defaults to `"en"`.
+    /// - Parameter bundle: the bundle whose String Catalog defines the available languages.
     public init(
-        bundle: Bundle,
-        `default`: String = "en"
+        bundle: Bundle
     ) {
-        self.init(
-            resolver: StringCatalog(bundle: bundle),
-            default: `default`
-        )
+        self.init(resolver: StringCatalog.cached(bundle: bundle))
     }
 
     /// Creates a language list backed by the given resolver.
     ///
     /// The seam for tests and alternative backends; the public API derives languages from a bundled catalog.
-    /// - Parameters:
-    ///   - resolver: the backend that reports the available languages.
-    ///   - default: the language served when none of the supported languages match.
+    /// - Parameter resolver: the backend that reports the available languages.
     init(
-        resolver: any CatalogResolving,
-        `default`: String = "en"
+        resolver: any CatalogResolving
     ) {
         self.resolver = resolver
-        self.`default` = `default`
     }
 
     // MARK: Computed
 
+    /// The outcome of reading the bundle's String Catalog.
+    ///
+    /// The list degrades to the default language rather than failing, so check this once at startup
+    /// and warn when it is not ``CatalogState/loaded``.
+    public var catalogState: CatalogState {
+        resolver.state
+    }
+
+    /// The language served when none of the supported languages match a request.
+    ///
+    /// Always the catalog's source (development) language, so the default cannot drift from the
+    /// bundle the list is bound to.
+    public var `default`: String {
+        resolver.sourceLanguage
+    }
+
     /// Every language the bundle's String Catalog provides a localization for.
     ///
     /// The `Base` internationalization is excluded, as it is a development placeholder rather than a real language.
diff --git a/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift b/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift
index 502d226..f071950 100644
--- a/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift
+++ b/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift
@@ -32,6 +32,36 @@ struct LocalizeTests {
         #expect(text == "Hallo")
     }
 
+    @Test
+    func `resolves a key in a regional locale`() {
+        let text = localize(
+            "test.greeting",
+            locale: Locale(identifier: "pt-BR"),
+        )
+
+        #expect(text == "Olá")
+    }
+
+    @Test
+    func `falls back to the primary language for an unmatched regional locale`() {
+        let text = localize(
+            "test.greeting",
+            locale: Locale(identifier: "de-AT"),
+        )
+
+        #expect(text == "Hallo")
+    }
+
+    @Test
+    func `falls back to the source language for an unsupported locale`() {
+        let text = localize(
+            "test.greeting",
+            locale: Locale(identifier: "fr"),
+        )
+
+        #expect(text == "Hello")
+    }
+
     @Test
     func `falls back to the key for an unknown entry`() {
         let text = localize(
@@ -42,4 +72,60 @@ struct LocalizeTests {
         #expect(text == "unknown.key")
     }
 
+    @Test
+    func `falls back to the key for a missing catalog`() {
+        let localize = Localize(bundle: .main)
+
+        let text = localize(
+            "test.greeting",
+            locale: Locale(identifier: "en")
+        )
+
+        #expect(text == "test.greeting")
+    }
+
+    // MARK: Properties tests
+
+    @Test
+    func `reports a loaded catalog`() {
+        #expect(localize.catalogState == .loaded)
+    }
+
+    @Test
+    func `reports a missing catalog`() {
+        let localize = Localize(bundle: .main)
+
+        #expect(localize.catalogState == .missing)
+    }
+
+    // A malformed catalog cannot ship as a test resource — Xcode generates string symbols for every
+    // bundled `.xcstrings` and fails the build on invalid JSON — so one is staged in a temporary
+    // directory bundle instead.
+    @Test
+    func `reports an undecodable catalog`() throws {
+        let directory = URL(fileURLWithPath: NSTemporaryDirectory())
+            .appendingPathComponent(
+                "UndecodableCatalog-\(UUID().uuidString)",
+                isDirectory: true
+            )
+
+        try FileManager.default.createDirectory(
+            at: directory,
+            withIntermediateDirectories: true
+        )
+
+        defer {
+            try? FileManager.default.removeItem(at: directory)
+        }
+
+        try Data("not a catalog".utf8).write(
+            to: directory.appendingPathComponent("Localizable.xcstrings")
+        )
+
+        let bundle = try #require(Bundle(url: directory))
+        let localize = Localize(bundle: bundle)
+
+        #expect(localize.catalogState == .undecodable)
+    }
+
 }
diff --git a/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift b/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
index 4ab3160..5bd2680 100644
--- a/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
+++ b/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
@@ -26,6 +26,20 @@ struct NegotiateTests {
         #expect(language == "de")
     }
 
+    @Test
+    func `matches a regional catalog language exactly`() {
+        let language = negotiate(acceptLanguage: "pt-BR")
+
+        #expect(language == "pt-BR")
+    }
+
+    @Test
+    func `matches a regional catalog language by its primary subtag`() {
+        let language = negotiate(acceptLanguage: "pt")
+
+        #expect(language == "pt-BR")
+    }
+
     @Test
     func `respects the header order of preference`() {
         let language = negotiate(acceptLanguage: "de, en")
@@ -34,12 +48,47 @@ struct NegotiateTests {
     }
 
     @Test
-    func `strips quality weights from the language tags`() {
-        let language = negotiate(acceptLanguage: "de;q=0.5, en;q=0.9")
+    func `orders the language tags by descending quality weight`() {
+        let language = negotiate(acceptLanguage: "en;q=0.5, de;q=0.9")
 
         #expect(language == "de")
     }
 
+    @Test
+    func `treats a tag without a weight as the highest preference`() {
+        let language = negotiate(acceptLanguage: "en;q=0.9, de")
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `treats a tag with a malformed weight as the highest preference`() {
+        let language = negotiate(acceptLanguage: "en;q=0.9, de;q=broken")
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `drops language tags weighted as not acceptable`() {
+        let language = negotiate(acceptLanguage: "de;q=0, en;q=0.8")
+
+        #expect(language == "en")
+    }
+
+    @Test
+    func `falls back to the default when every tag is weighted as not acceptable`() {
+        let language = negotiate(acceptLanguage: "de;q=0, fr;q=0")
+
+        #expect(language == "en")
+    }
+
+    @Test
+    func `serves the default language for a wildcard`() {
+        let language = negotiate(acceptLanguage: "fr;q=0.9, *;q=0.5")
+
+        #expect(language == "en")
+    }
+
     @Test
     func `trims whitespace around the language tags`() {
         let language = negotiate(acceptLanguage: " de , en ")
diff --git a/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift b/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift
index 4e144e2..ea4eaa7 100644
--- a/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift
+++ b/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift
@@ -20,16 +20,39 @@ struct LanguageListTests {
         }
 
         @Test
-        func `uses the provided default language`() {
+        func `follows the catalog's source language`() {
             let list = LanguageList(
-                bundle: .module,
-                default: "de"
+                resolver: StubCatalog(
+                    sourceLanguage: "de",
+                    languages: ["de", "en"]
+                )
             )
 
             #expect(list.default == "de")
         }
     }
 
+    @Suite("catalogState")
+    struct CatalogState {
+        @Test
+        func `reports a loaded catalog`() {
+            let list = LanguageList(
+                bundle: .module
+            )
+
+            #expect(list.catalogState == .loaded)
+        }
+
+        @Test
+        func `reports a missing catalog`() {
+            let list = LanguageList(
+                bundle: .main
+            )
+
+            #expect(list.catalogState == .missing)
+        }
+    }
+
     @Suite("all")
     struct All {
         @Test
@@ -45,20 +68,34 @@ struct LanguageListTests {
         @Test
         func `excludes the base localization`() {
             let list = LanguageList(
-                bundle: .module
+                resolver: StubCatalog(
+                    sourceLanguage: "en",
+                    languages: ["Base", "de", "en"]
+                )
             )
 
-            #expect(!list.all.contains("Base"))
+            #expect(list.all == ["de", "en"])
         }
 
         @Test
-        func `lists each language only once`() {
+        func `sorts the languages`() {
             let list = LanguageList(
-                bundle: .module
+                resolver: StubCatalog(
+                    sourceLanguage: "en",
+                    languages: ["fr", "en", "de"]
+                )
             )
-            let all = list.all
 
-            #expect(all.count == Set(all).count)
+            #expect(list.all == ["de", "en", "fr"])
+        }
+
+        @Test
+        func `degrades to the default language for a missing catalog`() {
+            let list = LanguageList(
+                bundle: .main
+            )
+
+            #expect(list.all == ["en"])
         }
     }
 
diff --git a/Packages/Localization/Tests/Catalogs/Localizable.xcstrings b/Packages/Localization/Tests/Catalogs/Localizable.xcstrings
index 509d868..7135307 100644
--- a/Packages/Localization/Tests/Catalogs/Localizable.xcstrings
+++ b/Packages/Localization/Tests/Catalogs/Localizable.xcstrings
@@ -15,6 +15,12 @@
             "state" : "translated",
             "value" : "Hello"
           }
+        },
+        "pt-BR" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Olá"
+          }
         }
       }
     }
diff --git a/Packages/Localization/Tests/Utils/Resolvers/StubCatalog.swift b/Packages/Localization/Tests/Utils/Resolvers/StubCatalog.swift
new file mode 100644
index 0000000..1bd3ead
--- /dev/null
+++ b/Packages/Localization/Tests/Utils/Resolvers/StubCatalog.swift
@@ -0,0 +1,23 @@
+import Foundation
+
+@testable import Localization
+
+/// A ``CatalogResolving`` backend with fixed languages, for exercising types apart from a bundled catalog.
+struct StubCatalog: CatalogResolving {
+
+    // MARK: Properties
+
+    let sourceLanguage: String
+    let languages: Set<String>
+    var state: CatalogState = .loaded
+
+    // MARK: Methods
+
+    func string(
+        for key: String,
+        in locale: Locale
+    ) -> String {
+        key
+    }
+
+}
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 0163147..71e1f67 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -58,6 +58,7 @@ let package = Package(
         .executableTarget(
             name: "Website",
             dependencies: [
+                .byName(name: "Localization"),
                 .byName(name: "Persistence"),
                 .byName(name: "WebsiteLibrary"),
                 .product(
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index d4f66ed..254319f 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -1,6 +1,7 @@
 import Configuration
 import Hummingbird
 import HummingbirdCompression
+import Localization
 import Logging
 import Persistence
 import Infrastructure
@@ -9,7 +10,8 @@ import WebsiteLibrary
 /// Builds the website application.
 ///
 /// Reads the log level, server name, static files location, minimum response size to compress, and security headers from the configuration, then assembles
-/// the router, server configuration, and logger. It also builds the persistence driver, registers its migrations, and attaches the `Fluent` service so it starts
+/// the router, server configuration, and logger. It warns when the localization catalog cannot be read, since pages would serve raw localization keys.
+/// It also builds the persistence driver, registers its migrations, and attaches the `Fluent` service so it starts
 /// and stops alongside the HTTP server; the ephemeral in-memory backend is migrated on startup, while a MySQL/MariaDB backend is migrated out of
 /// band (so a shared database is never migrated on boot).
 /// - Parameter reader: the configuration reader the values are read from.
@@ -17,10 +19,20 @@ import WebsiteLibrary
 func application(
     reader: ConfigReader
 ) async -> some ApplicationProtocol {
+    let languages = LanguageList()
     let logger = logger(
         serverName: reader.serverName,
         logLevel: reader.logLevel
     )
+
+    // A broken catalog degrades to serving raw localization keys rather than failing, so it is
+    // only ever visible to visitors — surface it here instead.
+    if languages.catalogState != .loaded {
+        let isCatalogMissing = languages.catalogState == .missing
+        
+        logger.warning("String Catalog is \(isCatalogMissing ? "missing" : "undecodable"); pages will serve raw localization keys")
+    }
+
     let persistence = Service(
         driver: reader.driver,
         logger: logger
diff --git a/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift b/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
index 71eefba..f852a71 100644
--- a/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
+++ b/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
@@ -11,7 +11,7 @@ extension Page {
     /// The document language, derived from the page's locale and falling back to the default language.
     var lang: String {
         locale.language.languageCode?.identifier
-            ?? LanguageList(bundle: .module).default
+            ?? LanguageList().default
     }
 
     /// The icon, manifest, and theme colour metadata shared by every page of the website.
diff --git a/Services/Website/Sources/Library/Public/Extensions/LanguageList+Defaults.swift b/Services/Website/Sources/Library/Public/Extensions/LanguageList+Defaults.swift
new file mode 100644
index 0000000..49f9bdc
--- /dev/null
+++ b/Services/Website/Sources/Library/Public/Extensions/LanguageList+Defaults.swift
@@ -0,0 +1,13 @@
+import Foundation
+import Localization
+
+public extension LanguageList {
+
+    // MARK: Initializers
+
+    /// Creates a language list backed by the module's String Catalog.
+    init() {
+        self.init(bundle: .module)
+    }
+
+}
-- 
2.54.0


From ea00b94841b3dcd04e64c38eaf51ec7d3e2454ec Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 30 Jul 2026 06:33:57 +0000
Subject: [PATCH 029/117] Tweaks and fixes throughout the project (#27)

This PR contains the work done to do a little bit of housekeeping pass across all packages and the Website service.

To provide further details about the work:
* Refreshed the READMEs and source documentation to match the current code;
* Tagged every test case consistently across the Infrastructure, Localization, Persistence, and Website test targets;
* Removed Website middleware tests now covered by Infrastructure's own suite;
* Conformed the `PrepareDB` method to Sendable;
* Relaxes the production Compose DATABASE_TLS default from require to prefer;
* Added Persistence test verifying the prefer posture falls back to plaintext connections.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/27
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
Co-committed-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Packages/Infrastructure/README.md             |  28 ++-
 .../Sources/Internal/Types/FNV1aHash.swift    |   5 +-
 .../Builders/RouteCollectionBuilder.swift     |   4 +-
 .../Public/Enumerations/AssetExtension.swift  |   3 +-
 .../RouterMethods+RouteCollections.swift      |   6 +-
 .../Public/Extensions/String+Constants.swift  |  11 +-
 .../Public/Methods/FingerprintAssets.swift    |  12 +-
 .../Middlewares/LocalizationMiddleware.swift  |   9 +-
 .../SecurityHeadersMiddleware.swift           |  39 ++--
 .../Sources/Public/Protocols/Asset.swift      |  13 +-
 .../Protocols/LocalizedRequestContext.swift   |   5 +-
 .../Sources/Public/Protocols/Page.swift       |   4 +-
 .../Public/Protocols/RouterController.swift   |   4 +-
 .../LocalizedHTMLCollectionResponse.swift     |  11 +-
 .../Cases/Internal/Types/FNV1aHashTests.swift |   5 +-
 .../Enumerations/AssetExtensionTests.swift    |   5 +-
 .../RouterMethods+RouteCollectionsTests.swift |   5 +-
 .../Methods/FingerprintAssetsTests.swift      |   5 +-
 .../LocalizationMiddlewareTests.swift         |   5 +-
 .../Middlewares/NotFoundMiddlewareTests.swift |   5 +-
 .../RateLimitMiddlewareTests.swift            |   5 +-
 .../SecurityHeadersMiddlewareTests.swift      |   5 +-
 .../Middlewares/VaryMiddlewareTests.swift     |   5 +-
 .../Cases/Public/Protocols/AssetTests.swift   |   5 +-
 .../Cases/Public/Protocols/PageTests.swift    |   5 +-
 .../Utils/Extensions/Tag+Constants.swift      |  10 +-
 Packages/Localization/README.md               |  44 +++++
 .../Internal/Protocols/CatalogResolving.swift |  17 +-
 .../Internal/Types/LanguageRange.swift        |   8 +-
 .../Internal/Types/StringCatalog.swift        |  13 +-
 .../Public/Enumerations/CatalogState.swift    |   9 +-
 .../Sources/Public/Methods/Localize.swift     |  12 +-
 .../Sources/Public/Methods/Negotiate.swift    |  29 ++-
 .../Sources/Public/Types/LanguageList.swift   |   6 +-
 .../Cases/Public/Methods/LocalizeTests.swift  |   5 +-
 .../Cases/Public/Methods/NegotiateTests.swift |   5 +-
 .../Public/Types/LanguageListTests.swift      |   5 +-
 .../Utils/Extensions/Tag+Constants.swift      |   8 +
 Packages/Persistence/Package.swift            |  22 ++-
 Packages/Persistence/README.md                |  60 ++++++
 .../Sources/Public/Enumerations/Driver.swift  |  11 +-
 .../Sources/Public/Enumerations/TLS.swift     |  23 ++-
 .../Sources/Public/Methods/PrepareDB.swift    |  12 +-
 .../Sources/Public/Methods/Probe.swift        |  13 +-
 .../Sources/Public/Methods/Service.swift      |  14 +-
 .../Sources/Public/Types/Configuration.swift  |   3 +-
 .../Cases/Public/Enumerations/TLSTests.swift  |  32 +++-
 .../Cases/Public/Methods/ProbeTests.swift     |   5 +-
 .../Cases/Public/Methods/ServiceTests.swift   |   5 +-
 .../Utils/Extensions/Tag+Constants.swift      |   8 +
 .../Utils/Fakes/PlaintextMySQLServer.swift    | 162 ++++++++++++++++
 Services/Website/Dockerfile                   |  25 ++-
 Services/Website/README.md                    |  22 ++-
 Services/Website/Sources/App/App.swift        |   6 +-
 .../Sources/App/Extensions/App+Build.swift    |  15 +-
 .../Extensions/ConfigReader+Properties.swift  |   6 +-
 .../Internal/Enumerations/StaticFile.swift    |   5 +-
 .../Library/Internal/Pages/IndexPage.swift    |   3 +-
 .../Contexts/WebsiteRequestContext.swift      |   5 +-
 .../Public/Controllers/HealthController.swift |  13 +-
 .../Public/Controllers/RootController.swift   |  12 +-
 .../Enumerations/StaticFileTests.swift        |   5 +-
 .../Cases/Internal/Pages/ErrorPageTests.swift |   5 +-
 .../Cases/Internal/Pages/IndexPageTests.swift |   5 +-
 .../Controllers/HealthControllerTests.swift   |   5 +-
 .../Controllers/RootControllerTests.swift     |   5 +-
 .../LocalizationMiddlewareTests.swift         |  57 ------
 .../Middlewares/NotFoundMiddlewareTests.swift | 173 ------------------
 .../Utils/Extensions/Tag+Constants.swift      |   4 +-
 Services/Website/docker-compose.override.yml  |  12 +-
 Services/Website/docker-compose.yml           |  12 +-
 71 files changed, 633 insertions(+), 512 deletions(-)
 create mode 100644 Packages/Localization/README.md
 create mode 100644 Packages/Localization/Tests/Utils/Extensions/Tag+Constants.swift
 create mode 100644 Packages/Persistence/README.md
 create mode 100644 Packages/Persistence/Tests/Utils/Extensions/Tag+Constants.swift
 create mode 100644 Packages/Persistence/Tests/Utils/Fakes/PlaintextMySQLServer.swift
 delete mode 100644 Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
 delete mode 100644 Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 7913a19..cade1d7 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -3,7 +3,6 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 
 ## Overview
 The package provides, grouped by role:
-
 | Role | Types |
 | --- | --- |
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
@@ -11,23 +10,36 @@ The package provides, grouped by role:
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
 | Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
 | Contexts | `LocalizedRequestContext` |
+| Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
 
 ## Design rules
 The package holds only what every service can reuse; anything a service owns is injected, never referenced:
-
 - **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors.
 - **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern to follow.
 - **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
 ## Layout
 Sources are split by visibility, then by kind, one type per file:
+```
+Sources/
+├── Public/                public API
+│   ├── Builders/          RouteCollectionBuilder
+│   ├── Enumerations/      AssetExtension
+│   ├── Extensions/        addController, plus the default header names and values
+│   ├── Methods/           FingerprintAssets
+│   ├── Middlewares/       the five HTTP middlewares
+│   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
+│   └── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
+└── Internal/
+    └── Types/             implementation details (FNV1aHash)
+Tests/
+├── Cases/                 the test suites, mirroring the Sources/ layout
+├── Catalogs/              the String Catalog fixture, copied verbatim so it loads on Linux
+└── Utils/                 stubs (StubAsset, StubPage, …) and the suite Tag constants
+```
 
-```
-Sources/Public/<Kind>/     public API (Protocols, Middlewares, Responses, …)
-Sources/Internal/<Kind>/   implementation details (e.g. FNV1aHash)
-Tests/Cases/…              mirrors the source layout
-Tests/Utils/…              stubs and test-only extensions
-```
+## Testing
+Every suite carries a tag naming the kind of API it exercises — `.asset`, `.extension`, `.middleware`, `.protocol`, or `.type`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
diff --git a/Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift b/Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift
index c33baab..4165586 100644
--- a/Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift
+++ b/Packages/Infrastructure/Sources/Internal/Types/FNV1aHash.swift
@@ -2,9 +2,8 @@ import Foundation
 
 /// Hashes bytes with the FNV-1a 64-bit algorithm.
 ///
-/// The hash is stable across processes and platforms, which `Hasher` deliberately is not, so it
-/// suits values that must agree between instances and survive restarts: the asset version token
-/// (``FingerprintAssets``) and the entity tags of the pre-rendered pages (`CachedHTMLResponse`).
+/// The hash is stable across processes and platforms, which `Hasher` deliberately is not, so it suits values that must agree between instances and survive
+/// restarts: the asset version token (``FingerprintAssets``) and the entity tags of the pre-rendered pages (`CachedHTMLResponse`).
 /// It is not cryptographic — a collision only risks serving a stale cached asset, not security.
 struct FNV1aHash {
 
diff --git a/Packages/Infrastructure/Sources/Public/Builders/RouteCollectionBuilder.swift b/Packages/Infrastructure/Sources/Public/Builders/RouteCollectionBuilder.swift
index 548bc46..a201c2e 100644
--- a/Packages/Infrastructure/Sources/Public/Builders/RouteCollectionBuilder.swift
+++ b/Packages/Infrastructure/Sources/Public/Builders/RouteCollectionBuilder.swift
@@ -2,8 +2,8 @@ import Hummingbird
 
 /// A result builder that collects the route collections of ``RouterController`` values into a stack.
 ///
-/// Mirrors the `MiddlewareFixedTypeBuilder` Hummingbird uses for `addMiddleware`, letting
-/// controllers be listed declaratively rather than having their routes added one statement at a time.
+/// Mirrors the `MiddlewareFixedTypeBuilder` Hummingbird uses for `addMiddleware`, letting controllers be listed declaratively rather than having
+/// their routes added one statement at a time.
 @resultBuilder
 public enum RouteCollectionBuilder<Context: RequestContext> {
 
diff --git a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
index 8729209..9d1ae00 100644
--- a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
+++ b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
@@ -1,7 +1,6 @@
 /// A file extension used by an ``Asset``.
 ///
-/// Each case's raw value is the extension itself (e.g. `"css"`), which an asset appends to its
-/// file name when resolving paths.
+/// Each case's raw value is the extension itself (e.g. `"css"`), which an asset appends to its file name when resolving paths.
 public enum AssetExtension: String, Sendable {
     /// A Cascading Style Sheets file.
     case css
diff --git a/Packages/Infrastructure/Sources/Public/Extensions/RouterMethods+RouteCollections.swift b/Packages/Infrastructure/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
index d753351..25c55f2 100644
--- a/Packages/Infrastructure/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
+++ b/Packages/Infrastructure/Sources/Public/Extensions/RouterMethods+RouteCollections.swift
@@ -4,8 +4,7 @@ public extension RouterMethods {
 
     // MARK: Methods
     
-    /// Adds the routes of ``RouterController`` values to the router using the
-    /// ``RouteCollectionBuilder`` result builder.
+    /// Adds the routes of ``RouterController`` values to the router using the ``RouteCollectionBuilder`` result builder.
     ///
     /// Mirrors `addMiddleware`, letting controllers be listed declaratively:
     ///
@@ -16,8 +15,7 @@ public extension RouterMethods {
     /// }
     /// ```
     ///
-    /// Each controller's route collection is added at the router's root, exactly as a
-    /// sequence of `addRoutes(_:)` calls would.
+    /// Each controller's route collection is added at the router's root, exactly as a sequence of `addRoutes(_:)` calls would.
     /// - Parameter build: the controller stack result builder.
     /// - Returns: the router, so calls can be chained.
     @discardableResult
diff --git a/Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift b/Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift
index d01536e..2791b1e 100644
--- a/Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift
+++ b/Packages/Infrastructure/Sources/Public/Extensions/String+Constants.swift
@@ -1,15 +1,14 @@
 extension String {
     /// A namespace for the security headers' default configuration values.
     ///
-    /// `Strict-Transport-Security` is intentionally absent: it is only safe over HTTPS and is
-    /// "sticky" in browsers, so it stays off unless explicitly configured in production.
+    /// `Strict-Transport-Security` is intentionally absent: it is only safe over HTTPS and is "sticky" in browsers, so it stays off unless explicitly
+    /// configured in production.
     public enum Security {
         /// The default `Content-Security-Policy`.
         ///
-        /// Restricts every resource to the site's own origin (`default-src 'self'`), blocks plugins
-        /// (`object-src 'none'`), pins the document base URL (`base-uri 'self'`), and forbids framing
-        /// (`frame-ancestors 'none'`). No inline-style exception is included, so pages must link
-        /// external stylesheets.
+        /// Restricts every resource to the site's own origin (`default-src 'self'`), blocks plugins (`object-src 'none'`), pins the document
+        /// base URL (`base-uri 'self'`), and forbids framing (`frame-ancestors 'none'`). No inline-style exception is included, so pages must
+        /// link external stylesheets.
         public static let contentSecurityPolicy = "default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'"
         /// The default `X-Content-Type-Options` (disables MIME sniffing).
         public static let contentTypeOptions = "nosniff"
diff --git a/Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift b/Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift
index 3a55d87..70a2097 100644
--- a/Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift
+++ b/Packages/Infrastructure/Sources/Public/Methods/FingerprintAssets.swift
@@ -28,9 +28,8 @@ public struct FingerprintAssets: Sendable {
 
     /// Fingerprints the static files under the given directory.
     ///
-    /// A file that cannot be read is reported to the ``logger`` and left out of the token, so its
-    /// later changes would not bust caches — a warning there usually points at a permissions
-    /// problem in the deployment.
+    /// A file that cannot be read is reported to the ``logger`` and left out of the token, so its later changes would not bust caches — a warning there
+    /// usually points at a permissions problem in the deployment.
     /// - Parameter path: the directory the static files are served from.
     /// - Returns: the version token, or `nil` when the directory holds no readable files (asset URLs are then left unversioned).
     public func callAsFunction(
@@ -42,10 +41,9 @@ public struct FingerprintAssets: Sendable {
             return nil
         }
 
-        // The path-based enumerator yields paths relative to the directory, so the token depends
-        // only on the directory's contents — never on where the directory itself lives (the
-        // URL-based enumerator standardizes symlinked bases, e.g. `/var/…` to `/private/var/…`,
-        // which would leak the absolute path into the hash).
+        // The path-based enumerator yields paths relative to the directory, so the token depends only on the
+        // directory's contents — never on where the directory itself lives (the URL-based enumerator standardizes
+        // symlinked bases, e.g. `/var/…` to `/private/var/…`, which would leak the absolute path into the hash).
         var files: [String] = []
 
         while let relativePath = enumerated.nextObject() as? String {
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
index c743aa8..964909c 100644
--- a/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
@@ -5,12 +5,11 @@ import Localization
 
 /// Resolves the visitor's preferred language and records it on the request context.
 ///
-/// Placed ahead of the localized responders in the middleware chain, it reads the request's
-/// `Accept-Language` header, negotiates the best supported match (falling back to the default
-/// language), and stores it on the context's ``LocalizedRequestContext/language``.
+/// Placed ahead of the localized responders in the middleware chain, it reads the request's `Accept-Language` header, negotiates the best supported
+/// match (falling back to the default language), and stores it on the context's ``LocalizedRequestContext/language``.
 ///
-/// The request is otherwise passed through untouched — the URL and routing are not affected — so
-/// each page is served at its existing path and varies its content by header.
+/// The request is otherwise passed through untouched — the URL and routing are not affected — so each page is served at its existing path and varies its
+/// content by header.
 public struct LocalizationMiddleware<Context: LocalizedRequestContext> {
 
     // MARK: Properties
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/SecurityHeadersMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/SecurityHeadersMiddleware.swift
index ffa531f..8658e8c 100644
--- a/Packages/Infrastructure/Sources/Public/Middlewares/SecurityHeadersMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/SecurityHeadersMiddleware.swift
@@ -3,13 +3,12 @@ import Hummingbird
 
 /// Stamps a set of security-related HTTP headers onto every response.
 ///
-/// Placed at (or near) the top of the middleware chain, it adds the configured headers to whatever
-/// response bubbles back up — the rendered pages, the error page produced by
-/// ``NotFoundMiddleware``, and every static file served by `FileMiddleware` — so the browser applies
-/// the strict, hardened interpretation of the content instead of its lenient legacy defaults.
+/// Placed at (or near) the top of the middleware chain, it adds the configured headers to whatever response bubbles back up — the rendered pages, the
+/// error page produced by ``NotFoundMiddleware``, and every static file served by `FileMiddleware` — so the browser applies the strict, hardened
+/// interpretation of the content instead of its lenient legacy defaults.
 ///
-/// The headers are precomputed once from the ``Configuration`` at initialization and reused for
-/// every request, so the per-request cost is a handful of header copies.
+/// The headers are precomputed once from the ``Configuration`` at initialization and reused for every request, so the per-request cost is a handful of
+/// header copies.
 public struct SecurityHeadersMiddleware<Context: RequestContext> {
 
     // MARK: Properties
@@ -20,9 +19,8 @@ public struct SecurityHeadersMiddleware<Context: RequestContext> {
     // MARK: Initializers
 
     /// Creates a security-headers middleware.
-    /// - Parameter configuration: the headers applied to every response. Defaults to a hardened
-    ///   baseline suitable for a static site, with `Strict-Transport-Security` left off (see
-    ///   ``Configuration``).
+    /// - Parameter configuration: the headers applied to every response. Defaults to a hardened baseline suitable for a static site, with
+    ///   `Strict-Transport-Security` left off (see ``Configuration``).
     public init(
         configuration: Configuration = .init()
     ) {
@@ -37,14 +35,11 @@ extension SecurityHeadersMiddleware: RouterMiddleware {
 
     // MARK: Functions
 
-    /// Passes the request down the chain and stamps the configured security headers onto the
-    /// response on the way back up.
+    /// Passes the request down the chain and stamps the configured security headers onto the response on the way back up.
     ///
-    /// Errors that can render themselves (`HTTPResponseError`, like the `HTTPError`s thrown by the
-    /// controllers) are converted to their response here rather than left to the router: the router
-    /// converts them above the middleware chain, where the response would escape these headers.
-    /// Existing values for the same header names are replaced so downstream middleware cannot leave
-    /// a weaker policy in place.
+    /// Errors that can render themselves (`HTTPResponseError`, like the `HTTPError`s thrown by the controllers) are converted to their response
+    /// here rather than left to the router: the router converts them above the middleware chain, where the response would escape these headers.
+    /// Existing values for the same header names are replaced so downstream middleware cannot leave a weaker policy in place.
     /// - Parameters:
     ///   - request: the incoming request.
     ///   - context: the context the request is resolved against.
@@ -106,10 +101,9 @@ private extension SecurityHeadersMiddleware.Configuration {
 extension SecurityHeadersMiddleware {
     /// The set of security headers a ``SecurityHeadersMiddleware`` applies.
     ///
-    /// Each property maps to a single response header. A `nil` value omits that header entirely,
-    /// which is how `Strict-Transport-Security` stays disabled by default: it is only safe to send
-    /// over HTTPS and is "sticky" in browsers, so it must stay off in plain-HTTP development and be
-    /// switched on (via configuration) only in TLS-terminated production.
+    /// Each property maps to a single response header. A `nil` value omits that header entirely, which is how `Strict-Transport-Security` stays
+    /// disabled by default: it is only safe to send over HTTPS and is "sticky" in browsers, so it must stay off in plain-HTTP development and be switched on
+    /// (via configuration) only in TLS-terminated production.
     public struct Configuration: Sendable {
         
         // MARK: Properties
@@ -131,9 +125,8 @@ extension SecurityHeadersMiddleware {
         
         /// Creates a security-headers configuration.
         ///
-        /// Every parameter defaults to the hardened baseline defined in `String.Security`, except
-        /// `strictTransportSecurity`, which defaults to `nil` (omitted). Pass `nil` for any header
-        /// to drop it from the response.
+        /// Every parameter defaults to the hardened baseline defined in `String.Security`, except `strictTransportSecurity`, which defaults
+        /// to `nil` (omitted). Pass `nil` for any header to drop it from the response.
         /// - Parameters:
         ///   - contentSecurityPolicy: the `Content-Security-Policy` value.
         ///   - contentTypeOptions: the `X-Content-Type-Options` value.
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift b/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
index 6624516..be5506d 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
@@ -1,9 +1,7 @@
-/// An asset shipped with a website: a file stored under the static files root and served by
-/// Hummingbird's `FileMiddleware` middleware.
+/// An asset shipped with a website: a file stored under the static files root and served by Hummingbird's `FileMiddleware` middleware.
 ///
-/// A conforming asset supplies its file name and the extensions it is available with, each
-/// resolving to its own file; the protocol derives the paths from them: the file's path within
-/// the static files root and the URL path it is served at, optionally versioned to bust caches.
+/// A conforming asset supplies its file name and the extensions it is available with, each resolving to its own file; the protocol derives the paths from them:
+/// the file's path within the static files root and the URL path it is served at, optionally versioned to bust caches.
 public protocol Asset: Sendable {
 
     // MARK: Properties
@@ -58,9 +56,8 @@ public extension Asset {
 
     /// Resolves the absolute URL path the asset is served at (e.g. `"/css/shared.css"`).
     ///
-    /// A version token appends as a `v` query parameter (e.g. `"/css/shared.css?v=abc123"`):
-    /// `FileMiddleware` ignores the query when resolving the file, while caches key on the full
-    /// URL, so a deploy that changes the assets busts every cached copy at once.
+    /// A version token appends as a `v` query parameter (e.g. `"/css/shared.css?v=abc123"`): `FileMiddleware` ignores the query when
+    /// resolving the file, while caches key on the full URL, so a deploy that changes the assets busts every cached copy at once.
     /// - Parameters:
     ///   - fileExtension: the extension of the file to resolve.
     ///   - version: the version token to append, or `nil` to leave the URL unversioned.
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift b/Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift
index 86fec3e..50dcb35 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/LocalizedRequestContext.swift
@@ -2,9 +2,8 @@ import Hummingbird
 
 /// A request context that carries the language negotiated for the request.
 ///
-/// ``LocalizationMiddleware`` resolves the visitor's preferred language from the `Accept-Language`
-/// header and stores it here, so downstream controllers and middleware can serve the matching
-/// localization without re-reading the header.
+/// ``LocalizationMiddleware`` resolves the visitor's preferred language from the `Accept-Language` header and stores it here, so downstream
+/// controllers and middleware can serve the matching localization without re-reading the header.
 public protocol LocalizedRequestContext: RequestContext {
 
     // MARK: Properties
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
index 1ab393e..7875f6b 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
@@ -62,8 +62,8 @@ public extension Page {
 
     /// The viewport declaration and ``stylesheets`` links followed by the ``metadata``, placed in the document head.
     ///
-    /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already
-    /// emits `<meta charset="UTF-8">` before this markup, and HTML5 allows only one.
+    /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already emits `<meta charset="UTF-8">` before this markup,
+    /// and HTML5 allows only one.
     @HTMLBuilder
     var head: some HTML {
         meta(
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/RouterController.swift b/Packages/Infrastructure/Sources/Public/Protocols/RouterController.swift
index 819ec82..ae1ca19 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/RouterController.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/RouterController.swift
@@ -2,8 +2,8 @@ import Hummingbird
 
 /// A type exposing its endpoints as a route collection ready to be added to a router.
 ///
-/// Conforming controllers group related endpoints behind a single ``routes`` property,
-/// so the application composes them declaratively with ``Hummingbird/RouterMethods/addController(_:)``:
+/// Conforming controllers group related endpoints behind a single ``routes`` property, so the application composes them declaratively with
+/// ``Hummingbird/RouterMethods/addController(_:)``:
 ///
 /// ```swift
 /// struct HealthController<Context: RequestContext>: RouterController {
diff --git a/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift b/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
index b8c1161..b497105 100644
--- a/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
+++ b/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
@@ -6,10 +6,9 @@ import Localization
 
 /// A per-language collection of pre-rendered HTML responses.
 ///
-/// At initialization it renders the document once for each language the bundle's ``LanguageList``
-/// reports and caches the bytes, mirroring ``CachedHTMLResponse``'s render-once model but keyed by
-/// language. Each cached response carries a `Content-Language` header and `Vary: Accept-Language`, so
-/// shared caches key on the negotiated language instead of serving one language to everyone.
+/// At initialization it renders the document once for each language the bundle's ``LanguageList`` reports and caches the bytes, mirroring
+/// ``CachedHTMLResponse``'s render-once model but keyed by language. Each cached response carries a `Content-Language` header and
+/// `Vary: Accept-Language`, so shared caches key on the negotiated language instead of serving one language to everyone.
 public struct LocalizedHTMLCollectionResponse: Sendable {
 
     // MARK: Properties
@@ -54,8 +53,8 @@ public struct LocalizedHTMLCollectionResponse: Sendable {
     /// - Parameters:
     ///   - language: the negotiated language identifier.
     ///   - request: the request the response answers, consulted for conditional revalidation.
-    /// - Returns: the cached response for the language, the default language's response when the
-    ///   language is unavailable, or a `500 Internal Server Error` if neither is cached.
+    /// - Returns: the cached response for the language, the default language's response when the language is unavailable, or a
+    ///   `500 Internal Server Error` if neither is cached.
     public func response(
         for language: String,
         request: Request
diff --git a/Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift b/Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift
index e876252..8931989 100644
--- a/Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Internal/Types/FNV1aHashTests.swift
@@ -2,7 +2,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("FNV1aHash type")
+@Suite(
+    "FNV1aHash type",
+    .tags(.type)
+)
 struct FNV1aHashTests {
 
     // MARK: Functional tests
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
index 98730b5..f49dbea 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
@@ -2,7 +2,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("AssetExtension enumeration")
+@Suite(
+    "AssetExtension enumeration",
+    .tags(.asset)
+)
 struct AssetExtensionTests {
 
     // MARK: Computed tests
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
index 0bae410..8deb485 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Extensions/RouterMethods+RouteCollectionsTests.swift
@@ -5,7 +5,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("addController method")
+@Suite(
+    "addController method",
+    .tags(.`extension`)
+)
 struct RouterMethodsTests {
 
     // MARK: Functional tests
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift
index 5c073e8..cb8d213 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Methods/FingerprintAssetsTests.swift
@@ -3,7 +3,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("FingerprintAssets method")
+@Suite(
+    "FingerprintAssets method",
+    .tags(.asset)
+)
 struct FingerprintAssetsTests {
 
     // MARK: Properties
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
index c18276e..f246f5c 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
@@ -7,7 +7,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("LocalizationMiddleware middleware", .tags(.middleware))
+@Suite(
+    "LocalizationMiddleware middleware",
+    .tags(.middleware)
+)
 struct LocalizationMiddlewareTests {
 
     // MARK: Constants
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
index 895d90c..ea26298 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
@@ -6,7 +6,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("NotFoundMiddleware middleware", .tags(.middleware))
+@Suite(
+    "NotFoundMiddleware middleware",
+    .tags(.middleware)
+)
 struct NotFoundMiddlewareTests {
 
     // MARK: Constants
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift
index 5c6bd32..75aa6c7 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/RateLimitMiddlewareTests.swift
@@ -4,7 +4,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("RateLimitMiddleware middleware", .tags(.middleware))
+@Suite(
+    "RateLimitMiddleware middleware",
+    .tags(.middleware)
+)
 struct RateLimitMiddlewareTests {
 
     // MARK: Functional tests
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
index 78db8c0..c15e01d 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/SecurityHeadersMiddlewareTests.swift
@@ -4,7 +4,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("SecurityHeadersMiddleware middleware", .tags(.middleware))
+@Suite(
+    "SecurityHeadersMiddleware middleware",
+    .tags(.middleware)
+)
 struct SecurityHeadersMiddlewareTests {
 
     // MARK: Functional tests
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift
index afa7dad..30389de 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/VaryMiddlewareTests.swift
@@ -5,7 +5,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("VaryMiddleware middleware", .tags(.middleware))
+@Suite(
+    "VaryMiddleware middleware",
+    .tags(.middleware)
+)
 struct VaryMiddlewareTests {
 
     // MARK: Functional tests
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
index ea9c778..08b392b 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
@@ -2,7 +2,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("Asset protocol")
+@Suite(
+    "Asset protocol",
+    .tags(.`protocol`)
+)
 struct AssetTests {
 
     // MARK: Properties
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
index a09a533..485d65e 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
@@ -4,7 +4,10 @@ import Testing
 
 @testable import Infrastructure
 
-@Suite("Page protocol", .tags(.page))
+@Suite(
+    "Page protocol",
+    .tags(.`protocol`)
+)
 struct PageTests {
 
     // MARK: Functional tests
diff --git a/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift b/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
index e83de46..9fec14b 100644
--- a/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
+++ b/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
@@ -1,8 +1,14 @@
 import Testing
 
 extension Tag {
+    /// Tests exercising the asset scaffolding of the Infrastructure package.
+    @Tag static var asset: Tag
+    /// Tests exercising an extension of the Infrastructure package.
+    @Tag static var `extension`: Tag
     /// Tests exercising a middleware of the Infrastructure package.
     @Tag static var middleware: Tag
-    /// Tests exercising the page scaffolding of the Infrastructure package.
-    @Tag static var page: Tag
+    /// Tests exercising a protocol scaffolding of the Infrastructure package.
+    @Tag static var `protocol`: Tag
+    /// Tests exercising an internal type of the Infrastructure package.
+    @Tag static var type: Tag
 }
diff --git a/Packages/Localization/README.md b/Packages/Localization/README.md
new file mode 100644
index 0000000..e0a1c40
--- /dev/null
+++ b/Packages/Localization/README.md
@@ -0,0 +1,44 @@
+# Localization
+The server-side localization toolkit the **Loud** services build on: locale-explicit String Catalog lookups, `Accept-Language` negotiation, and the catalog-derived language list — with no dependencies beyond Foundation.
+
+## Overview
+The package provides, grouped by role:
+| Role | Types |
+| --- | --- |
+| Lookup | `Localize`, a bundle-bound localizer that resolves a catalog key for an explicit locale |
+| Negotiation | `Negotiate`, which picks the best supported language from an `Accept-Language` header per RFC 9110 |
+| Languages | `LanguageList`, the supported and default languages a bundle's String Catalog defines |
+| Diagnostics | `CatalogState`, the outcome of reading the catalog (`loaded`, `missing`, or `undecodable`) |
+
+## Design rules
+- **The String Catalog is the single source of truth.** Supported languages, the default language, and every string come from the bundle's `Localizable.xcstrings`. Adding a language is a translation-only change — once a locale exists in the catalog, `LanguageList` and `Negotiate` pick it up with no code change.
+- **The locale is always explicit.** A server has no single "current" locale, so every lookup names the locale to resolve in; nothing reads process-wide locale state.
+- **Raw `.xcstrings` parsing, for Linux parity.** The catalog is decoded from its JSON rather than through Foundation's compiled-catalog APIs, which are unavailable or non-functional on Linux. Consumers must `.copy` the catalog resource verbatim (not `.process` it) so it ships as raw JSON on every platform. Only simple `stringUnit` values are decoded; plural and device variations are not represented.
+- **Resolution never fails.** A missing entry falls back to the source-language string, then to the key itself; a missing or undecodable catalog degrades the language list to the default. Check `catalogState` once at startup and warn when it is not `.loaded`, before visitors ever see raw keys.
+- **Method structs.** `Localize` and `Negotiate` hold their lifetime-fixed configuration (the bundle) in `init` and take only per-call inputs in `callAsFunction`.
+- **One decoded catalog per bundle.** Catalogs are immutable at runtime, so every `Localize`, `Negotiate`, and `LanguageList` bound to the same bundle and table shares one cached `StringCatalog`.
+
+## Layout
+Sources are split by visibility, then by kind, one type per file:
+```
+Sources/
+├── Public/
+│   ├── Enumerations/      CatalogState
+│   ├── Methods/           Localize, Negotiate
+│   └── Types/             LanguageList
+└── Internal/
+    ├── Protocols/         CatalogResolving, the seam between the public API and the catalog backend
+    └── Types/             StringCatalog (the cached .xcstrings decoder), LanguageRange
+Tests/
+├── Cases/                 the test suites, mirroring the Sources/ layout
+├── Catalogs/              the String Catalog fixture, copied verbatim so it loads on Linux
+└── Utils/                 the StubCatalog resolver and the suite Tag constants
+```
+
+## Testing
+Every suite carries a tag naming the kind of API it exercises — `.method` or `.type`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
+
+## Requirements
+- Swift 6.3 toolchain (`swift-tools-version:6.3`).
+- macOS 15, matching the sibling `Infrastructure` and `Persistence` packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- No package dependencies — Foundation and Synchronization only.
diff --git a/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift b/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
index a0e4dcf..9a30292 100644
--- a/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
+++ b/Packages/Localization/Sources/Internal/Protocols/CatalogResolving.swift
@@ -2,22 +2,19 @@ import Foundation
 
 /// A backend that resolves localized strings for an explicit locale and reports the languages it serves.
 ///
-/// This is the seam that decouples ``Localize`` and ``LanguageList`` from *how* localizations are stored
-/// and resolved. The shipping implementation, ``StringCatalog``, reads a raw `.xcstrings` catalog so it
-/// behaves identically on Darwin and Linux. A future backend — for example one built on
-/// `String(localized:)` for a native Apple app that needs plural and device variations — can conform
-/// without changing any caller.
+/// This is the seam that decouples ``Localize`` and ``LanguageList`` from *how* localizations are stored and resolved. The shipping implementation,
+/// ``StringCatalog``, reads a raw `.xcstrings` catalog so it behaves identically on Darwin and Linux. A future backend — for example one built on
+/// `String(localized:)` for a native Apple app that needs plural and device variations — can conform without changing any caller.
 ///
-/// Resolution never fails: an implementation returns the key itself when it has no localization for it,
-/// mirroring Foundation's `String(localized:)`. This is the contract both a dictionary lookup and the
-/// native API can honour, since the native API cannot distinguish a missing key from a translation that
+/// Resolution never fails: an implementation returns the key itself when it has no localization for it, mirroring Foundation's `String(localized:)`.
+/// This is the contract both a dictionary lookup and the native API can honour, since the native API cannot distinguish a missing key from a translation that
 /// happens to equal the key.
 protocol CatalogResolving: Sendable {
 
     // MARK: Properties
 
-    /// The source (development) language, used as the final fallback when a locale has no localization
-    /// and as the default language a ``LanguageList`` serves.
+    /// The source (development) language, used as the final fallback when a locale has no localization and as the default language a ``LanguageList``
+    /// serves.
     var sourceLanguage: String { get }
 
     /// The outcome of reading the backing catalog, for consumers to surface at startup.
diff --git a/Packages/Localization/Sources/Internal/Types/LanguageRange.swift b/Packages/Localization/Sources/Internal/Types/LanguageRange.swift
index 1afaa6b..b4c203d 100644
--- a/Packages/Localization/Sources/Internal/Types/LanguageRange.swift
+++ b/Packages/Localization/Sources/Internal/Types/LanguageRange.swift
@@ -1,8 +1,7 @@
 /// A single language range parsed from an `Accept-Language` header entry.
 ///
-/// A range pairs the language tag a client asked for with the `q` weight expressing how much the
-/// client prefers it, as RFC 9110 defines them. ``Negotiate`` parses each comma-separated header
-/// entry into one of these, then orders the ranges by descending weight so the most preferred tag
+/// A range pairs the language tag a client asked for with the `q` weight expressing how much the client prefers it, as RFC 9110 defines them.
+/// ``Negotiate`` parses each comma-separated header entry into one of these, then orders the ranges by descending weight so the most preferred tag
 /// is matched first.
 struct LanguageRange {
 
@@ -11,8 +10,7 @@ struct LanguageRange {
     /// The language tag the client asked for, such as `de` or `de-AT`, or the `*` wildcard.
     let tag: String
 
-    /// The tag's `q` weight, from 0 ("not acceptable") to 1 (most preferred, the default when
-    /// an entry names no weight).
+    /// The tag's `q` weight, from 0 ("not acceptable") to 1 (most preferred, the default when an entry names no weight).
     let quality: Double
 
 }
diff --git a/Packages/Localization/Sources/Internal/Types/StringCatalog.swift b/Packages/Localization/Sources/Internal/Types/StringCatalog.swift
index 5eb7bd0..de68dbc 100644
--- a/Packages/Localization/Sources/Internal/Types/StringCatalog.swift
+++ b/Packages/Localization/Sources/Internal/Types/StringCatalog.swift
@@ -95,8 +95,8 @@ extension StringCatalog {
 
     /// Returns the catalog for the given bundle and table, decoding it on first access.
     ///
-    /// Catalogs are immutable at runtime, so every ``Localize``, ``Negotiate``, and ``LanguageList``
-    /// bound to the same bundle shares one decoded catalog instead of re-reading its JSON.
+    /// Catalogs are immutable at runtime, so every ``Localize``, ``Negotiate``, and ``LanguageList`` bound to the same bundle shares one
+    /// decoded catalog instead of re-reading its JSON.
     /// - Parameters:
     ///   - bundle: the bundle whose resources contain the String Catalog.
     ///   - table: the name of the String Catalog resource, without the `.xcstrings` extension.
@@ -132,9 +132,8 @@ extension StringCatalog {
 
 extension StringCatalog: CatalogResolving {
 
-    /// Resolves a key by the most specific language tag first: the locale's full tag (`pt-BR`), then its
-    /// primary language code (`pt`), then the source language, then the key itself. Tags are matched
-    /// case-insensitively, so a regional catalog entry resolves for the locale ``Negotiate`` picked it for.
+    /// Resolves a key by the most specific language tag first: the locale's full tag (`pt-BR`), then its primary language code (`pt`), then the source
+    /// language, then the key itself. Tags are matched case-insensitively, so a regional catalog entry resolves for the locale ``Negotiate`` picked it for.
     func string(
         for key: String,
         in locale: Locale
@@ -162,8 +161,8 @@ private extension Locale {
 
     /// The language tags to resolve a catalog entry against, most specific first.
     ///
-    /// The locale's full identifier comes first, as a hyphenated, lowercased tag (`pt_BR` becomes
-    /// `pt-br`), followed by its primary language code when the two differ.
+    /// The locale's full identifier comes first, as a hyphenated, lowercased tag (`pt_BR` becomes `pt-br`), followed by its primary language code when
+    /// the two differ.
     var catalogTags: [String] {
         var tags: [String] = []
         let identifier = identifier
diff --git a/Packages/Localization/Sources/Public/Enumerations/CatalogState.swift b/Packages/Localization/Sources/Public/Enumerations/CatalogState.swift
index 2e35e1b..56d3ceb 100644
--- a/Packages/Localization/Sources/Public/Enumerations/CatalogState.swift
+++ b/Packages/Localization/Sources/Public/Enumerations/CatalogState.swift
@@ -1,17 +1,12 @@
 /// The outcome of reading a String Catalog from its bundle.
 ///
-/// The package degrades gracefully when a catalog cannot be read — lookups return their keys and the
-/// language list falls back to the default language — so nothing fails at the call site. This state is
-/// the signal a server checks once at startup to warn before visitors ever see raw localization keys.
+/// The package degrades gracefully when a catalog cannot be read — lookups return their keys and the language list falls back to the default language — so
+/// nothing fails at the call site. This state is the signal a server checks once at startup to warn before visitors ever see raw localization keys.
 public enum CatalogState: Equatable, Sendable {
-
     /// The catalog was found and decoded; its entries are resolvable.
     case loaded
-
     /// No catalog resource exists in the bundle; every lookup returns its key.
     case missing
-
     /// The catalog resource exists but is not valid `.xcstrings` JSON; every lookup returns its key.
     case undecodable
-
 }
diff --git a/Packages/Localization/Sources/Public/Methods/Localize.swift b/Packages/Localization/Sources/Public/Methods/Localize.swift
index b088d27..b45e264 100644
--- a/Packages/Localization/Sources/Public/Methods/Localize.swift
+++ b/Packages/Localization/Sources/Public/Methods/Localize.swift
@@ -2,9 +2,8 @@ import Foundation
 
 /// A reusable, bundle-bound localizer that resolves String Catalog entries for an explicit locale.
 ///
-/// A server has no single "current" locale, so each lookup must name the locale to use. An instance
-/// is bound to the bundle whose catalog holds the strings, then invoked like a function to resolve a
-/// key in a chosen locale.
+/// A server has no single "current" locale, so each lookup must name the locale to use. An instance is bound to the bundle whose catalog holds the strings,
+/// then invoked like a function to resolve a key in a chosen locale.
 public struct Localize: Sendable {
 
     // MARK: Properties
@@ -16,8 +15,7 @@ public struct Localize: Sendable {
 
     /// The outcome of reading the bundle's String Catalog.
     ///
-    /// Resolution degrades to returning raw keys rather than failing, so check this once at startup
-    /// and warn when it is not ``CatalogState/loaded``.
+    /// Resolution degrades to returning raw keys rather than failing, so check this once at startup and warn when it is not ``CatalogState/loaded``.
     public var catalogState: CatalogState {
         resolver.state
     }
@@ -56,8 +54,8 @@ public struct Localize: Sendable {
     /// - Parameters:
     ///   - key: the String Catalog key to look up.
     ///   - locale: the locale to resolve the key in.
-    /// - Returns: the localized string for the locale, the source-language string when the locale has no
-    ///   entry, or the key itself when the catalog has no entry for it.
+    /// - Returns: the localized string for the locale, the source-language string when the locale has no entry, or the key itself when the catalog has no
+    ///   entry for it.
     public func callAsFunction(
         _ key: String,
         locale: Locale
diff --git a/Packages/Localization/Sources/Public/Methods/Negotiate.swift b/Packages/Localization/Sources/Public/Methods/Negotiate.swift
index e0604be..ee41bed 100644
--- a/Packages/Localization/Sources/Public/Methods/Negotiate.swift
+++ b/Packages/Localization/Sources/Public/Methods/Negotiate.swift
@@ -2,10 +2,9 @@ import Foundation
 
 /// Negotiates the best supported language for a request from its `Accept-Language` header.
 ///
-/// Bound to a bundle's catalog languages via ``LanguageList``, an instance is invoked like a
-/// function — through ``callAsFunction(acceptLanguage:)`` — to resolve a header value to a
-/// supported language identifier, honouring the header's `q` weights as RFC 9110 prescribes and
-/// falling back to the default language.
+/// Bound to a bundle's catalog languages via ``LanguageList``, an instance is invoked like a function — through
+/// ``callAsFunction(acceptLanguage:)`` — to resolve a header value to a supported language identifier, honouring the header's `q` weights as
+/// RFC 9110 prescribes and falling back to the default language.
 public struct Negotiate: Sendable {
 
     // MARK: Properties
@@ -28,12 +27,10 @@ public struct Negotiate: Sendable {
     /// Picks the best supported language for the given `Accept-Language` header value.
     ///
     /// Invoked by calling the instance directly, for example `negotiate(acceptLanguage: header)`.
-    /// The header is parsed into its language ranges, which are ordered by descending `q` weight as
-    /// RFC 9110 prescribes: an entry without a weight counts as 1, entries weighted 0 are
-    /// "not acceptable" and dropped, and equal weights keep the header order. Each tag is then matched
-    /// against the supported languages in turn — first by an exact match, then by its primary language
-    /// subtag, so `de-AT` resolves to a supported `de` — while the `*` wildcard accepts the default
-    /// language. When the header is absent or matches nothing, the default language is returned.
+    /// The header is parsed into its language ranges, which are ordered by descending `q` weight as RFC 9110 prescribes: an entry without a weight
+    /// counts as 1, entries weighted 0 are "not acceptable" and dropped, and equal weights keep the header order. Each tag is then matched against the
+    /// supported languages in turn — first by an exact match, then by its primary language subtag, so `de-AT` resolves to a supported `de` — while the
+    /// `*` wildcard accepts the default language. When the header is absent or matches nothing, the default language is returned.
     /// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
     /// - Returns: the identifier of the supported language to serve.
     public func callAsFunction(
@@ -74,9 +71,8 @@ private extension Negotiate {
 
     /// Parses an `Accept-Language` header value into its ``LanguageRange`` list, ordered by preference.
     ///
-    /// Each comma-separated entry yields its language tag and `q` weight. The ranges are sorted by
-    /// descending weight, entries weighted 0 are dropped as "not acceptable", and equally weighted
-    /// entries keep the header order.
+    /// Each comma-separated entry yields its language tag and `q` weight. The ranges are sorted by descending weight, entries weighted 0 are dropped
+    /// as "not acceptable", and equally weighted entries keep the header order.
     /// - Parameter acceptLanguage: the raw `Accept-Language` header value.
     /// - Returns: the language ranges, most preferred first.
     func ranges(
@@ -98,8 +94,7 @@ private extension Negotiate {
     /// Parses a single `Accept-Language` header entry into its ``LanguageRange``.
     ///
     /// The entry's language tag precedes the first `;`; a `q` parameter after it sets the weight.
-    /// A missing or malformed weight counts as 1, the highest preference, matching a tag sent
-    /// without one.
+    /// A missing or malformed weight counts as 1, the highest preference, matching a tag sent without one.
     /// - Parameter entry: a single comma-separated header entry.
     /// - Returns: the entry's language range, or `nil` when it has no language tag.
     func range(
@@ -139,8 +134,8 @@ private extension Negotiate {
 
     /// Finds the supported language that best matches a single `Accept-Language` tag.
     ///
-    /// An exact, case-insensitive match wins; otherwise the tag's primary subtag is matched against the
-    /// supported languages' primary subtags, so a regional tag such as `de-AT` resolves to `de`.
+    /// An exact, case-insensitive match wins; otherwise the tag's primary subtag is matched against the supported languages' primary subtags, so a
+    /// regional tag such as `de-AT` resolves to `de`.
     /// - Parameters:
     ///   - tag: a single language tag from the header.
     ///   - supported: the supported language identifiers.
diff --git a/Packages/Localization/Sources/Public/Types/LanguageList.swift b/Packages/Localization/Sources/Public/Types/LanguageList.swift
index 42a0e84..d3b666c 100644
--- a/Packages/Localization/Sources/Public/Types/LanguageList.swift
+++ b/Packages/Localization/Sources/Public/Types/LanguageList.swift
@@ -35,16 +35,14 @@ public struct LanguageList: Sendable {
 
     /// The outcome of reading the bundle's String Catalog.
     ///
-    /// The list degrades to the default language rather than failing, so check this once at startup
-    /// and warn when it is not ``CatalogState/loaded``.
+    /// The list degrades to the default language rather than failing, so check this once at startup and warn when it is not ``CatalogState/loaded``.
     public var catalogState: CatalogState {
         resolver.state
     }
 
     /// The language served when none of the supported languages match a request.
     ///
-    /// Always the catalog's source (development) language, so the default cannot drift from the
-    /// bundle the list is bound to.
+    /// Always the catalog's source (development) language, so the default cannot drift from the bundle the list is bound to.
     public var `default`: String {
         resolver.sourceLanguage
     }
diff --git a/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift b/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift
index f071950..3ef1c67 100644
--- a/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift
+++ b/Packages/Localization/Tests/Cases/Public/Methods/LocalizeTests.swift
@@ -3,7 +3,10 @@ import Testing
 
 @testable import Localization
 
-@Suite("Localize method")
+@Suite(
+    "Localize method",
+    .tags(.method)
+)
 struct LocalizeTests {
     
     // MARK: Constants
diff --git a/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift b/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
index 5bd2680..f7cb0bc 100644
--- a/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
+++ b/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
@@ -3,7 +3,10 @@ import Testing
 
 @testable import Localization
 
-@Suite("Negotiate method")
+@Suite(
+    "Negotiate method",
+    .tags(.method)
+)
 struct NegotiateTests {
 
     // MARK: Constants
diff --git a/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift b/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift
index ea4eaa7..0c3829b 100644
--- a/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift
+++ b/Packages/Localization/Tests/Cases/Public/Types/LanguageListTests.swift
@@ -3,7 +3,10 @@ import Testing
 
 @testable import Localization
 
-@Suite("LanguageList type")
+@Suite(
+    "LanguageList type",
+    .tags(.type)
+)
 struct LanguageListTests {
 
     // MARK: Properties tests
diff --git a/Packages/Localization/Tests/Utils/Extensions/Tag+Constants.swift b/Packages/Localization/Tests/Utils/Extensions/Tag+Constants.swift
new file mode 100644
index 0000000..1c1e8cf
--- /dev/null
+++ b/Packages/Localization/Tests/Utils/Extensions/Tag+Constants.swift
@@ -0,0 +1,8 @@
+import Testing
+
+extension Tag {
+    /// Tests exercising a method of the Localization package.
+    @Tag static var method: Tag
+    /// Tests exercising a type of the Localization package.
+    @Tag static var type: Tag
+}
diff --git a/Packages/Persistence/Package.swift b/Packages/Persistence/Package.swift
index ca63107..5d83c1f 100644
--- a/Packages/Persistence/Package.swift
+++ b/Packages/Persistence/Package.swift
@@ -32,6 +32,14 @@ let package = Package(
             url: "https://github.com/vapor/sql-kit.git",
             from: "3.36.0"
         ),
+        .package(
+            url: "https://github.com/vapor/mysql-nio.git",
+            from: "1.7.0"
+        ),
+        .package(
+            url: "https://github.com/apple/swift-nio.git",
+            from: "2.65.0"
+        ),
     ],
     targets: [
         .target(
@@ -59,7 +67,19 @@ let package = Package(
         .testTarget(
             name: "PersistenceTests",
             dependencies: [
-                .byName(name: "Persistence")
+                .byName(name: "Persistence"),
+                .product(
+                    name: "MySQLNIO",
+                    package: "mysql-nio"
+                ),
+                .product(
+                    name: "NIOCore",
+                    package: "swift-nio"
+                ),
+                .product(
+                    name: "NIOPosix",
+                    package: "swift-nio"
+                ),
             ],
             path: "Tests"
         ),
diff --git a/Packages/Persistence/README.md b/Packages/Persistence/README.md
new file mode 100644
index 0000000..571fdac
--- /dev/null
+++ b/Packages/Persistence/README.md
@@ -0,0 +1,60 @@
+# Persistence
+The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based data layer the **Loud** services build on: runtime selection between a MySQL/MariaDB backend and an ephemeral in-memory SQLite one, single-place migration registration, and a database readiness probe.
+
+## Overview
+The package provides, grouped by role:
+| Role | Types |
+| --- | --- |
+| Backend selection | `Driver` (`mysql` or `inMemory`), `Configuration` (the MySQL/MariaDB connection parameters), `TLS` (the connection's TLS posture) |
+| Service | `Service`, which builds the `Fluent` service configured for the chosen driver |
+| Migrations | `PrepareDB`, the single registrar declaring every migration, in order |
+| Readiness | `Probe`, which reports whether the default database answers a `SELECT 1` |
+| Scaffolding (internal) | `ExampleRecord`, `CreateExampleRecord`, and `ExampleRepository` — the model → migration → repository pattern, to be replaced by the first real domain model |
+
+## Design rules
+- **The package reads no configuration.** The executable maps its `database.*` keys onto a `Driver` and hands it over; connection values arrive as plain data. See the Website service's `ConfigReader+Properties` for the mapping.
+- **One default database.** `Service` registers the selected backend as the *default* database, so repositories resolve it with a plain `fluent.db()` and stay agnostic of which driver is in use.
+- **Migrations are declared once, and append-only.** `PrepareDB` is the single place migrations are registered, in the order they must run; alter the schema by adding a new migration, never by editing one that has already run. Registering does not apply them — the in-memory backend is migrated on startup, while a shared MySQL/MariaDB database is migrated out of band (the executable's migrate-and-exit mode), so multiple booting instances never race.
+- **Models never cross a concurrency boundary.** FluentKit models are mutable reference types; repositories map them to `Sendable` value-type snapshots (e.g. `Example`) before returning, and the models themselves stay internal to the package.
+- **Readiness never throws.** `Probe` runs a `SELECT 1` — the cheapest statement both backends understand, independent of any schema — and maps every failure to `false`, so callers translate it straight into a readiness response.
+- **A single connection for the in-memory store.** The SQLite backend is capped at one connection per event loop so every query reaches the same in-memory database, rather than each pooled connection getting its own private one.
+- **Method structs.** `Service`, `PrepareDB`, and `Probe` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
+
+> **Note:** the `prefer` TLS posture is enforced by the driver itself: a supplied TLS configuration upgrades the connection only when the server advertises TLS, and continues in plaintext otherwise (pinned by a test against a fake server that offers no TLS). `require` currently maps to the same configuration and therefore behaves like `prefer` — the refusal when the server offers no TLS is not yet enforced.
+
+## Layout
+Sources are split by visibility, then by kind, one type per file:
+```
+Sources/
+├── Public/
+│   ├── Enumerations/      Driver, TLS
+│   ├── Methods/           Service, PrepareDB, Probe
+│   └── Types/             Configuration
+└── Internal/
+    ├── Migrations/        CreateExampleRecord
+    ├── Models/            ExampleRecord
+    └── Repositories/      ExampleRepository (returning the Example snapshot)
+Tests/
+├── Cases/                 the test suites, mirroring the Sources/ layout
+└── Utils/                 the NotSQL* fakes backing the probe's non-SQL-database case, the
+                           plaintext-only fake MySQL server, and the suite Tag constants
+```
+
+## Testing
+The suite runs against the in-memory backend by default, so `swift test` needs no database. The MySQL/MariaDB integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`, `MYSQL_TEST_NAME`, `MYSQL_TEST_USERNAME`, and `MYSQL_TEST_PASSWORD`); it reverts its migrations afterwards, so the shared database is left as it was found:
+```sh
+# in-memory only
+swift test                                
+# or
+# with the local MariaDB up (make db-mount):
+MYSQL_TEST_HOST=127.0.0.1 swift test
+```
+
+Outside the application's service group, a built `Fluent` service must be shut down explicitly — even on failure — or its connection pool asserts on `deinit`; the suites' `do`/`catch` pattern around `fluent.shutdown()` is the shape to follow.
+
+Every suite carries a tag naming the kind of API it exercises — `.enumeration` or `.method`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
+
+## Requirements
+- Swift 6.3 toolchain (`swift-tools-version:6.3`).
+- macOS 15, matching the sibling `Infrastructure` and `Localization` packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- Package dependencies: `hummingbird-fluent`, `fluent-mysql-driver`, `fluent-sqlite-driver`, and `sql-kit`; the test target additionally depends on `mysql-nio` and `swift-nio` for the TLS fallback test.
diff --git a/Packages/Persistence/Sources/Public/Enumerations/Driver.swift b/Packages/Persistence/Sources/Public/Enumerations/Driver.swift
index c52b9ef..60f053b 100644
--- a/Packages/Persistence/Sources/Public/Enumerations/Driver.swift
+++ b/Packages/Persistence/Sources/Public/Enumerations/Driver.swift
@@ -1,20 +1,17 @@
 /// The persistence backend the service runs against.
 ///
-/// The executable picks a driver at startup and hands it to ``Service``, which registers the
-/// matching database as the default one. Repositories resolve that default and stay agnostic
-/// of which backend is in use.
+/// The executable picks a driver at startup and hands it to ``Service``, which registers the matching database as the default one. Repositories resolve
+/// that default and stay agnostic of which backend is in use.
 public enum Driver: Sendable {
 
     /// A MySQL/MariaDB server, reached with the given connection parameters.
     ///
-    /// - Parameter configuration: the host, credentials, TLS posture, and pooling limits the
-    ///   connection is opened with.
+    /// - Parameter configuration: the host, credentials, TLS posture, and pooling limits the connection is opened with.
     case mysql(Configuration)
 
     /// An ephemeral, in-process SQLite database held entirely in memory.
     ///
-    /// Nothing is written to disk, and all data is lost when the service stops — intended for
-    /// local development and tests.
+    /// Nothing is written to disk, and all data is lost when the service stops — intended for local development and tests.
     case inMemory
 
 }
diff --git a/Packages/Persistence/Sources/Public/Enumerations/TLS.swift b/Packages/Persistence/Sources/Public/Enumerations/TLS.swift
index 1efaa16..be6f492 100644
--- a/Packages/Persistence/Sources/Public/Enumerations/TLS.swift
+++ b/Packages/Persistence/Sources/Public/Enumerations/TLS.swift
@@ -2,9 +2,8 @@ import NIOSSL
 
 /// The TLS posture used when connecting to the database.
 ///
-/// The executable derives a posture from its `database.tls` configuration and passes it along as
-/// part of ``Configuration``; the MySQL driver receives the resulting `TLSConfiguration` through
-/// ``tlsConfiguration``.
+/// The executable derives a posture from its `database.tls` configuration and passes it along as part of ``Configuration``; the MySQL driver
+/// receives the resulting `TLSConfiguration` through ``tlsConfiguration``.
 public enum TLS: Sendable {
 
     /// Connect without TLS, in plaintext.
@@ -14,6 +13,9 @@ public enum TLS: Sendable {
     case prefer
 
     /// Connect only over TLS, refusing the connection when the server offers none.
+    ///
+    /// - Important: the refusal is not yet enforced — until it is, `require` behaves like ``prefer`` and silently falls back to plaintext when the
+    ///   server offers no TLS.
     case require
 
 }
@@ -24,18 +26,15 @@ extension TLS {
 
     /// The NIO TLS configuration passed to the MySQL driver for this posture.
     ///
-    /// Returns `nil` for ``off`` (connect in plaintext) and the default client configuration for
-    /// ``prefer`` and ``require``.
+    /// Returns `nil` for ``off`` (connect in plaintext) and the default client configuration for ``prefer`` and ``require``.
     ///
-    /// - Note: `prefer` and `require` currently map to the same client configuration — both enable TLS.
-    ///   The distinction (fall back to plaintext vs. fail when the server offers no TLS) is not yet
-    ///   enforced here; tighten this mapping if that guarantee becomes required.
+    /// - Note: the driver gives a supplied configuration ``prefer`` semantics natively — it upgrades to TLS only when the server advertises support,
+    ///   and continues in plaintext otherwise — so `prefer` is fully enforced. `require` maps to the same configuration and therefore currently
+    ///   behaves like ``prefer``: the refusal when the server offers no TLS is not yet enforced.
     var tlsConfiguration: TLSConfiguration? {
         switch self {
-        case .off:
-            return nil
-        case .prefer, .require:
-            return .makeClientConfiguration()
+        case .off: nil
+        default: .makeClientConfiguration()
         }
     }
 
diff --git a/Packages/Persistence/Sources/Public/Methods/PrepareDB.swift b/Packages/Persistence/Sources/Public/Methods/PrepareDB.swift
index 43283b3..932216e 100644
--- a/Packages/Persistence/Sources/Public/Methods/PrepareDB.swift
+++ b/Packages/Persistence/Sources/Public/Methods/PrepareDB.swift
@@ -2,9 +2,9 @@ import HummingbirdFluent
 
 /// A registrar declaring every migration against a `Fluent` service.
 ///
-/// Built once around the application's `Fluent` service and called as a function — `await migrate()` —
-/// during startup, before the migrations are applied.
-public struct PrepareDB {
+/// Built once around the application's `Fluent` service and called as a function — `await migrate()` — during startup, before the migrations are
+/// applied.
+public struct PrepareDB: Sendable {
 
     // MARK: Initializers
 
@@ -15,9 +15,9 @@ public struct PrepareDB {
 
     /// Registers every migration against the `Fluent` service, in order.
     ///
-    /// This is the single place migrations are declared: add each new migration here, in the order it must
-    /// run (migrations are applied in registration order and are append-only). Registering does not apply
-    /// them — the caller runs `fluent.migrate()` (or the executable's migrate-and-exit mode) to do that.
+    /// This is the single place migrations are declared: add each new migration here, in the order it must run (migrations are applied in registration order
+    /// and are append-only). Registering does not apply them — the caller runs `fluent.migrate()` (or the executable's migrate-and-exit mode) to do
+    /// that.
     public func callAsFunction(
         for fluent: Fluent
     ) async {
diff --git a/Packages/Persistence/Sources/Public/Methods/Probe.swift b/Packages/Persistence/Sources/Public/Methods/Probe.swift
index cdbda36..8abbc8b 100644
--- a/Packages/Persistence/Sources/Public/Methods/Probe.swift
+++ b/Packages/Persistence/Sources/Public/Methods/Probe.swift
@@ -3,8 +3,8 @@ import SQLKit
 
 /// A readiness probe reporting whether the database behind a `Fluent` service is reachable.
 ///
-/// Built once around the application's `Fluent` service and called as a function whenever a fresh
-/// answer is needed — typically from a readiness endpoint: `let ready = await probe()`.
+/// Built once around the application's `Fluent` service and called as a function whenever a fresh answer is needed — typically from a readiness endpoint:
+/// `let ready = await probe()`.
 public struct Probe: Sendable {
 
     // MARK: Properties
@@ -26,11 +26,10 @@ public struct Probe: Sendable {
 
     /// Reports whether the database behind the `Fluent` service is reachable.
     ///
-    /// Runs a trivial `SELECT 1` against the default database — the cheapest statement both the MySQL/MariaDB
-    /// and SQLite backends understand — so a readiness check does not depend on any particular schema or model.
-    /// Any failure (connection refused, authentication error, pool exhausted) is reported as not reachable
-    /// rather than thrown, so callers can map it straight onto a readiness response. A default database that
-    /// is not an SQL database is likewise reported as not reachable.
+    /// Runs a trivial `SELECT 1` against the default database — the cheapest statement both the MySQL/MariaDB and SQLite backends understand — so
+    /// a readiness check does not depend on any particular schema or model. Any failure (connection refused, authentication error, pool exhausted) is
+    /// reported as not reachable rather than thrown, so callers can map it straight onto a readiness response. A default database that is not an SQL
+    /// database is likewise reported as not reachable.
     /// - Returns: `true` when the database answers the probe, `false` otherwise.
     public func callAsFunction() async -> Bool {
         guard let database = fluent.db() as? any SQLDatabase else {
diff --git a/Packages/Persistence/Sources/Public/Methods/Service.swift b/Packages/Persistence/Sources/Public/Methods/Service.swift
index 033adcf..a8953f2 100644
--- a/Packages/Persistence/Sources/Public/Methods/Service.swift
+++ b/Packages/Persistence/Sources/Public/Methods/Service.swift
@@ -5,8 +5,7 @@ import Logging
 
 /// A factory building the `Fluent` service the application persists through.
 ///
-/// Built once around the driver the executable picks at startup and called as a function to produce
-/// the configured service: `let fluent = service()`.
+/// Built once around the driver the executable picks at startup and called as a function to produce the configured service: `let fluent = service()`.
 public struct Service: Sendable {
 
     // MARK: Properties
@@ -35,10 +34,9 @@ public struct Service: Sendable {
 
     /// Builds a `Fluent` service configured for the driver.
     ///
-    /// The selected backend is registered as the *default* database, so repositories resolve it with a plain
-    /// `fluent.db()` and stay agnostic of which driver is in use. The returned service is not yet running; add
-    /// it to the application's service group (`app.addServices(_:)`) so it starts and shuts its connection pool
-    /// down alongside the server.
+    /// The selected backend is registered as the *default* database, so repositories resolve it with a plain `fluent.db()` and stay agnostic of which
+    /// driver is in use. The returned service is not yet running; add it to the application's service group (`app.addServices(_:)`) so it starts and shuts
+    /// its connection pool down alongside the server.
     /// - Returns: the configured `Fluent` service, ready to be added to the service group.
     public func callAsFunction() -> Fluent {
         let fluent = Fluent(
@@ -63,8 +61,8 @@ public struct Service: Sendable {
                 isDefault: true
             )
         case .inMemory:
-            // A single connection keeps every query pointed at the same in-memory store,
-            // rather than each pooled connection getting its own private database.
+            // A single connection keeps every query pointed at the same in-memory store, rather than each pooled
+            // connection getting its own private database.
             fluent.databases.use(
                 .sqlite(.memory, maxConnectionsPerEventLoop: 1),
                 as: .sqlite,
diff --git a/Packages/Persistence/Sources/Public/Types/Configuration.swift b/Packages/Persistence/Sources/Public/Types/Configuration.swift
index a60408e..8867228 100644
--- a/Packages/Persistence/Sources/Public/Types/Configuration.swift
+++ b/Packages/Persistence/Sources/Public/Types/Configuration.swift
@@ -1,7 +1,6 @@
 /// The connection parameters for the MySQL/MariaDB backend.
 ///
-/// The executable builds this from its `database.*` configuration; the package itself reads no
-/// configuration, so these values arrive as plain data.
+/// The executable builds this from its `database.*` configuration; the package itself reads no configuration, so these values arrive as plain data.
 public struct Configuration: Sendable {
 
     // MARK: Properties
diff --git a/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift b/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
index aa12a00..0cd7d4e 100644
--- a/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
@@ -1,9 +1,16 @@
+import Logging
+import MySQLNIO
+import NIOCore
+import NIOPosix
 import NIOSSL
 import Testing
 
 @testable import Persistence
 
-@Suite("TLS enumeration")
+@Suite(
+    "TLS enumeration",
+    .tags(.enumeration)
+)
 struct TLSTests {
 
     // MARK: Properties tests
@@ -25,4 +32,27 @@ struct TLSTests {
         #expect(configuration.bestEffortEquals(.makeClientConfiguration()))
     }
 
+    @Test
+    func `prefer falls back to plaintext when the server offers no TLS`() async throws {
+        // The fake server never advertises `CLIENT_SSL`, so this connection can only succeed by downgrading to
+        // plaintext — pinning the driver behavior the `prefer` posture relies on.
+        let server = try await PlaintextMySQLServer.start()
+        let tlsConfiguration = try #require(TLS.prefer.tlsConfiguration)
+        let connection = try await MySQLConnection.connect(
+            to: .init(ipAddress: "127.0.0.1", port: server.port),
+            username: "loud",
+            database: "loud",
+            tlsConfiguration: tlsConfiguration,
+            logger: Logger(label: "test"),
+            on: MultiThreadedEventLoopGroup.singleton.any()
+        ).get()
+
+        let isConnected = !connection.isClosed
+
+        try await connection.close().get()
+        try await server.stop()
+
+        #expect(isConnected)
+    }
+
 }
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
index 4458f0e..6f44afa 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
@@ -5,7 +5,10 @@ import Testing
 
 @testable import Persistence
 
-@Suite("Probe method")
+@Suite(
+    "Probe method",
+    .tags(.method)
+)
 struct ProbeTests {
 
     // MARK: Methods tests
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
index 0ef5fb1..b52dbf9 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
@@ -5,7 +5,10 @@ import Testing
 
 @testable import Persistence
 
-@Suite("Service method")
+@Suite(
+    "Service method",
+    .tags(.method)
+)
 struct ServiceTests {
 
     // MARK: Methods tests
diff --git a/Packages/Persistence/Tests/Utils/Extensions/Tag+Constants.swift b/Packages/Persistence/Tests/Utils/Extensions/Tag+Constants.swift
new file mode 100644
index 0000000..bec1ff6
--- /dev/null
+++ b/Packages/Persistence/Tests/Utils/Extensions/Tag+Constants.swift
@@ -0,0 +1,8 @@
+import Testing
+
+extension Tag {
+    /// Tests exercising an enumeration of the Persistence package.
+    @Tag static var enumeration: Tag
+    /// Tests exercising a method of the Persistence package.
+    @Tag static var method: Tag
+}
diff --git a/Packages/Persistence/Tests/Utils/Fakes/PlaintextMySQLServer.swift b/Packages/Persistence/Tests/Utils/Fakes/PlaintextMySQLServer.swift
new file mode 100644
index 0000000..27973c7
--- /dev/null
+++ b/Packages/Persistence/Tests/Utils/Fakes/PlaintextMySQLServer.swift
@@ -0,0 +1,162 @@
+import NIOCore
+import NIOPosix
+
+/// A fake MySQL server speaking just enough of the wire protocol to complete a plaintext handshake.
+///
+/// Its greeting advertises the `mysql_native_password` plugin but **not** the `CLIENT_SSL` capability, and
+/// it answers the client's handshake response with a bare OK packet — so a client asking for TLS can only
+/// end up connected in plaintext. This is what the `prefer` fallback test connects to, proving the driver
+/// downgrades to plaintext rather than refusing the connection.
+final class PlaintextMySQLServer {
+
+    // MARK: Properties
+
+    /// The port the server listens on, assigned by the system at bind time.
+    let port: Int
+
+    /// The listening channel the server accepts connections through.
+    private let channel: Channel
+
+    // MARK: Initializers
+
+    private init(
+        channel: Channel,
+        port: Int
+    ) {
+        self.channel = channel
+        self.port = port
+    }
+
+    // MARK: Functions
+
+    /// Starts a server on the loopback interface, on a system-assigned port.
+    /// - Returns: the running server, ready to be connected to at ``port``.
+    static func start() async throws -> PlaintextMySQLServer {
+        let channel = try await ServerBootstrap(group: MultiThreadedEventLoopGroup.singleton)
+            .childChannelInitializer { channel in
+                channel.eventLoop.makeCompletedFuture {
+                    try channel.pipeline.syncOperations.addHandler(Handler())
+                }
+            }
+            .bind(host: "127.0.0.1", port: 0)
+            .get()
+
+        guard let port = channel.localAddress?.port else {
+            throw ChannelError.unknownLocalAddress
+        }
+
+        return .init(
+            channel: channel,
+            port: port
+        )
+    }
+
+    /// Stops the server, closing its listening channel.
+    func stop() async throws {
+        try await channel.close().get()
+    }
+
+}
+
+// MARK: - Handlers
+
+private extension PlaintextMySQLServer {
+
+    /// Greets a freshly accepted connection, accepts whatever authentication response arrives,
+    /// and closes on anything after that (e.g. a `COM_QUIT`).
+    final class Handler: ChannelInboundHandler {
+
+        // MARK: Type aliases
+
+        typealias InboundIn = ByteBuffer
+        typealias OutboundOut = ByteBuffer
+
+        // MARK: Properties
+
+        /// Whether the client's handshake response has already been answered with an OK packet.
+        private var didAuthenticate = false
+
+        // MARK: Functions
+
+        func channelActive(context: ChannelHandlerContext) {
+            context.writeAndFlush(
+                wrapOutboundOut(Self.greeting(allocator: context.channel.allocator)),
+                promise: nil
+            )
+        }
+
+        func channelRead(
+            context: ChannelHandlerContext,
+            data: NIOAny
+        ) {
+            guard didAuthenticate else {
+                didAuthenticate = true
+
+                context.writeAndFlush(
+                    wrapOutboundOut(Self.ok(allocator: context.channel.allocator)),
+                    promise: nil
+                )
+
+                return
+            }
+
+            context.close(promise: nil)
+        }
+
+        // MARK: Helpers
+
+        /// The `HandshakeV10` greeting, framed and ready to send as the connection's first packet.
+        ///
+        /// The advertised capabilities are `CLIENT_LONG_PASSWORD`, `CLIENT_PROTOCOL_41`,
+        /// `CLIENT_SECURE_CONNECTION`, and `CLIENT_PLUGIN_AUTH` — deliberately **not** `CLIENT_SSL`,
+        /// so the client cannot upgrade the connection to TLS.
+        private static func greeting(allocator: ByteBufferAllocator) -> ByteBuffer {
+            var payload = allocator.buffer(capacity: 80)
+
+            payload.writeInteger(10, endianness: .little, as: UInt8.self)     // protocol version
+            payload.writeNullTerminatedString("8.0.0")                       // server version
+            payload.writeInteger(1, endianness: .little, as: UInt32.self)    // connection id
+            payload.writeBytes([1, 2, 3, 4, 5, 6, 7, 8])                     // auth plugin data, part 1
+            payload.writeInteger(0, endianness: .little, as: UInt8.self)     // filler
+            payload.writeInteger(0x8201, endianness: .little, as: UInt16.self) // capabilities, lower: LONG_PASSWORD | PROTOCOL_41 | SECURE_CONNECTION
+            payload.writeInteger(0x21, endianness: .little, as: UInt8.self)  // character set (utf8)
+            payload.writeInteger(0x0002, endianness: .little, as: UInt16.self) // status flags (autocommit)
+            payload.writeInteger(0x0008, endianness: .little, as: UInt16.self) // capabilities, upper: PLUGIN_AUTH
+            payload.writeInteger(21, endianness: .little, as: UInt8.self)    // auth plugin data length
+            payload.writeBytes([UInt8](repeating: 0, count: 10))             // reserved
+            payload.writeBytes([9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 0]) // auth plugin data, part 2
+            payload.writeNullTerminatedString("mysql_native_password")       // auth plugin name
+
+            return framed(payload, sequence: 0, allocator: allocator)
+        }
+
+        /// A bare OK packet, framed as the reply to the client's handshake response.
+        private static func ok(allocator: ByteBufferAllocator) -> ByteBuffer {
+            var payload = allocator.buffer(capacity: 8)
+
+            payload.writeBytes([0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00])  // OK, no rows, autocommit, no warnings
+
+            return framed(payload, sequence: 2, allocator: allocator)
+        }
+
+        /// Wraps a payload in the MySQL packet frame: a 3-byte little-endian length and a sequence byte.
+        private static func framed(
+            _ payload: ByteBuffer,
+            sequence: UInt8,
+            allocator: ByteBufferAllocator
+        ) -> ByteBuffer {
+            var packet = allocator.buffer(capacity: payload.readableBytes + 4)
+            var payload = payload
+
+            packet.writeInteger(UInt8(payload.readableBytes & 0xff))
+            packet.writeInteger(UInt8((payload.readableBytes >> 8) & 0xff))
+            packet.writeInteger(UInt8((payload.readableBytes >> 16) & 0xff))
+            packet.writeInteger(sequence)
+            packet.writeBuffer(&payload)
+
+            return packet
+        }
+
+    }
+
+}
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index 2570487..9693882 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -8,14 +8,13 @@ ARG OXIPNG_VERSION=9.1.5
 ARG SVGO_VERSION=4.0.2
 
 # Install the minifiers in their own layer, so they are cached across asset changes.
-# The oxipng pin is fuzzy (=~) so Alpine package revision bumps (-r0, -r1, ...) do
-# not break the build when the base image advances.
+# The oxipng pin is fuzzy (=~) so Alpine package revision bumps (-r0, -r1, ...) do not break the build when the base
+# image advances.
 RUN apk add --no-cache "oxipng=~${OXIPNG_VERSION}" \
     && npm install --global "esbuild@${ESBUILD_VERSION}" "svgo@${SVGO_VERSION}"
 
-# Copy the static files and minify the JS/CSS/SVG sources and losslessly recompress
-# the PNG images in place, keeping their names so the URL paths derived from the
-# StaticFile enumeration stay unchanged.
+# Copy the static files and minify the JS/CSS/SVG sources and losslessly recompress the PNG images in place, keeping
+# their names so the URL paths derived from the StaticFile enumeration stay unchanged.
 WORKDIR /static
 COPY ./Services/Website/Resources/Static .
 RUN esbuild --minify --allow-overwrite --outdir=css css/*.css \
@@ -23,8 +22,8 @@ RUN esbuild --minify --allow-overwrite --outdir=css css/*.css \
     && oxipng --opt max --strip safe *.png \
     && svgo --recursive --folder .
 
-# Export stage: `docker build --target assets-export --output <dir>` writes the
-# minified static files to <dir> for local inspection.
+# Export stage: `docker build --target assets-export --output <dir>` writes the minified static files to <dir> for
+# local inspection.
 FROM scratch AS assets-export
 COPY --from=assets /static /
 
@@ -44,17 +43,16 @@ RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
 WORKDIR /build
 
 # First just resolve dependencies.
-# This creates a cached layer that can be reused as long as the manifests do
-# not change. The Website package depends on the local Localization package via
-# a relative path, so its manifest must be present for resolution to succeed.
+# This creates a cached layer that can be reused as long as the manifests do not change. The Website package depends on
+# the local Localization package via a relative path, so its manifest must be present for resolution to succeed.
 COPY ./Packages/Localization/Package.swift ./Packages/Localization/
 COPY ./Packages/Persistence/Package.swift ./Packages/Persistence/
 COPY ./Packages/Infrastructure/Package.swift ./Packages/Infrastructure/
 COPY ./Services/Website/Package.swift ./Services/Website/Package.resolved ./Services/Website/
 RUN swift package --package-path ./Services/Website resolve
 
-# Copy only the Swift inputs needed for a release build. Static assets are built
-# in the assets stage and copied into staging after the binary is produced.
+# Copy only the Swift inputs needed for a release build. Static assets are built in the assets stage and copied into
+# staging after the binary is produced.
 COPY ./Packages/Infrastructure/Sources ./Packages/Infrastructure/Sources
 COPY ./Packages/Localization/Sources ./Packages/Localization/Sources
 COPY ./Packages/Persistence/Sources ./Packages/Persistence/Sources
@@ -79,8 +77,7 @@ RUN cp "/usr/libexec/swift/linux/swift-backtrace-static" ./
 # Copy resources bundled by SPM to staging area
 RUN find -L "$(swift build --package-path /build/Services/Website -c release --show-bin-path)/" -regex '.*\.resources$' -exec cp -Ra {} ./ \;
 
-# Create the static files directory (served by FileMiddleware) and fill it with
-# the minified copies from the assets stage
+# Create the static files directory (served by FileMiddleware) and fill it with the minified copies from the assets stage
 RUN mkdir -p ./Resources/Static
 COPY --from=assets /static ./Resources/Static
 
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 9eef3ae..ec2eaaa 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -34,13 +34,14 @@ The persistence backend runs as a `Fluent` service inside the application's Serv
 Requests pass through the middleware chain in this order (outermost first), then reach the routes:
 ```
 LogRequestsMiddleware
-  → SecurityHeadersMiddleware       (security headers on every response)
-    → ResponseCompressionMiddleware  (gzip/deflate above the size threshold)
-      → LocalizationMiddleware       (negotiates the request's language)
-        → NotFoundMiddleware         (renders the localized 404 page on .notFound)
-          → FileMiddleware           (serves Resources/Static)
-RootController                       (GET / → landing page)
-HealthController                     (GET /health → liveness, GET /health/ready → readiness)
+  → SecurityHeadersMiddleware        (security headers on every response)
+    → VaryMiddleware                 (marks every response as varying on Accept-Encoding)
+      → ResponseCompressionMiddleware (gzip/deflate above the size threshold)
+        → LocalizationMiddleware      (negotiates the request's language)
+          → NotFoundMiddleware        (renders the localized 404 page on .notFound)
+            → FileMiddleware          (serves Resources/Static)
+RootController                        (GET / → landing page)
+HealthController                      (GET /health → liveness, GET /health/ready → readiness)
 ```
 
 ## Configuration
@@ -108,6 +109,7 @@ See [Persistence](#persistence-1) below for the workflow.
 | `path.staticFiles` | `PATH_STATIC_FILES` | `Resources/Static` | Directory, relative to the working directory, that static files are served from. |
 
 ### Rate limiting
+These keys configure the `RateLimitMiddleware` budget for the upcoming newsletter subscription endpoint. They are read at startup, but the middleware is **not yet attached to any route** — the values have no effect until the subscription endpoint ships.
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
 | `rateLimit.limit` | `RATELIMIT_LIMIT` | `5` | Requests admitted per client per window on the subscribe endpoint; the excess is answered with `429 Too Many Requests` and a `Retry-After` header. |
@@ -182,7 +184,7 @@ make pkg-test
 # = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
 ```
 
-Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Website.xctestplan` covers the service's two targets — `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests) — plus the local packages' suites: `WebTests`, `PersistenceTests`, and `LocalizationTests`.
+Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Tests/Website.xctestplan` covers the service's two targets — `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests) — plus the local packages' suites: `InfrastructureTests`, `PersistenceTests`, and `LocalizationTests`.
 
 The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the MySQL integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
 ```sh
@@ -259,8 +261,8 @@ The Makefile and Compose files read these from a `.env` file (or the environment
 | `LOG_LEVEL` | Runtime log level (default `info`). |
 | `HTTP_SERVER_NAME` | Runtime server name (default `LoudWebsite`). |
 | `SECURITY_STRICT_TRANSPORT_SECURITY` | HSTS header value (default `max-age=31536000; includeSubDomains`). |
-| `DATABASE_DRIVER` | `inMemory` (default) or `mysql`. Set to `mysql` in production to use a managed database. |
+| `DATABASE_DRIVER` | `inMemory` or `mysql`. The production Compose file defaults it to `mysql`; the local override defaults back to the in-memory backend. |
 | `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` | MySQL/MariaDB connection (when `DATABASE_DRIVER=mysql`). Provide the password via a secret. |
-| `DATABASE_TLS` | TLS posture when connecting: `off`, `prefer`, or `require` (default `require` in production). |
+| `DATABASE_TLS` | TLS posture when connecting: `off`, `prefer`, or `require` (default `prefer` in production — set `require` when the database enforces TLS, so a stripped connection fails instead of silently downgrading to plaintext). |
 
 Run the migrations against the production database once before (or during) rollout: `docker compose -f docker-compose.yml run --rm website --database-migrate`.
diff --git a/Services/Website/Sources/App/App.swift b/Services/Website/Sources/App/App.swift
index 679beff..d75a38f 100644
--- a/Services/Website/Sources/App/App.swift
+++ b/Services/Website/Sources/App/App.swift
@@ -31,9 +31,9 @@ struct App {
             ]
         )
 
-        // Migrate-and-exit mode runs the registered migrations against the configured backend and returns,
-        // so a shared database is migrated by a single deliberate invocation (`--database-migrate`) rather
-        // than by every booting instance.
+        // Migrate-and-exit mode runs the registered migrations against the configured backend and returns, so a shared
+        // database is migrated by a single deliberate invocation (`--database-migrate`) rather than by every booting
+        // instance.
         guard !reader.migrate else {
             try await migration(
                 reader: reader
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 254319f..2164f29 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -25,8 +25,8 @@ func application(
         logLevel: reader.logLevel
     )
 
-    // A broken catalog degrades to serving raw localization keys rather than failing, so it is
-    // only ever visible to visitors — surface it here instead.
+    // A broken catalog degrades to serving raw localization keys rather than failing, so it is only ever visible to
+    // visitors — surface it here instead.
     if languages.catalogState != .loaded {
         let isCatalogMissing = languages.catalogState == .missing
         
@@ -63,8 +63,8 @@ func application(
 
     app.addServices(fluent)
 
-    // The in-memory backend is recreated on every launch, so it is migrated on startup. The MySQL/MariaDB
-    // backend is left untouched here: a shared database is migrated out of band to avoid multi-instance races.
+    // The in-memory backend is recreated on every launch, so it is migrated on startup. The MySQL/MariaDB backend is
+    // left untouched here: a shared database is migrated out of band to avoid multi-instance races.
     if case .inMemory = reader.driver {
         app.beforeServerStarts {
             try await fluent.migrate()
@@ -137,8 +137,7 @@ private func logger(
 /// larger than `minimumResponseSizeToCompress` when the client advertises support, the localization middleware that negotiates the request's
 /// language from its `Accept-Language` header, the not-found middleware that serves the error page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then adds the `RootController` routes that
-/// render the landing page, the `SubscriptionController` routes that register newsletter subscriptions, and the `HealthController` routes
-/// that serve the health check.
+/// render the landing page, and the `HealthController` routes that serve the health check.
 ///
 /// The security-headers middleware sits just inside request logging so it covers every response that reaches a client — the landing page, the compressed
 /// responses, the rendered error page, and the served static files.
@@ -162,8 +161,8 @@ private func router(
     logLevel: Logger.Level,
     probe: Probe
 ) -> Router<AppRequestContext> {
-    // HEAD siblings are generated for every GET route, so uptime monitors and crawlers probing
-    // with HEAD requests get the page's status and headers instead of a 404.
+    // HEAD siblings are generated for every GET route, so uptime monitors and crawlers probing with HEAD requests get
+    // the page's status and headers instead of a 404.
     let router = Router(
         context: AppRequestContext.self,
         options: .autoGenerateHeadEndpoints
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index 9acbbe5..c596d3f 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -123,9 +123,9 @@ package extension ConfigReader {
 
     /// The rate limit applied to the subscription endpoint, built from the `rateLimit.*` keys.
     ///
-    /// `rateLimit.limit` requests are admitted per client per `rateLimit.window` seconds. When
-    /// `rateLimit.trustForwardedFor` is set, clients are keyed by the first `X-Forwarded-For` entry —
-    /// enable it only behind a reverse proxy that sets the header, since clients can forge it otherwise.
+    /// `rateLimit.limit` requests are admitted per client per `rateLimit.window` seconds. When `rateLimit.trustForwardedFor` is set,
+    /// clients are keyed by the first `X-Forwarded-For` entry — enable it only behind a reverse proxy that sets the header, since clients can forge it
+    /// otherwise.
     var rateLimit: RateLimitMiddleware<AppRequestContext>.Configuration {
         .init(
             limit: int(
diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
index d953601..3196f8f 100644
--- a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
@@ -2,9 +2,8 @@ import Infrastructure
 
 /// A static file shipped with the website service.
 ///
-/// Each case identifies a file name stored under the static files root (the `Resources/Static`
-/// directory) and served by Hummingbird's `FileMiddleware` middleware. A name can be available
-/// with more than one extension (see ``fileExtensions``), each resolving to its own file.
+/// Each case identifies a file name stored under the static files root (the `Resources/Static` directory) and served by Hummingbird's
+/// `FileMiddleware` middleware. A name can be available with more than one extension (see ``fileExtensions``), each resolving to its own file.
 enum StaticFile: Asset, CaseIterable {
     /// The `apple-touch-icon.png` icon.
     case appleTouchIcon
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index bcb0475..843d85a 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -22,8 +22,7 @@ struct IndexPage {
     /// Creates a landing page localized to the given locale.
     /// - Parameters:
     ///   - locale: the locale the page content is localized to.
-    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
-    ///     default) to leave them unversioned.
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
     init(
         locale: Locale,
         assetVersion: String? = nil
diff --git a/Services/Website/Sources/Library/Public/Contexts/WebsiteRequestContext.swift b/Services/Website/Sources/Library/Public/Contexts/WebsiteRequestContext.swift
index 36e98d2..5c8f037 100644
--- a/Services/Website/Sources/Library/Public/Contexts/WebsiteRequestContext.swift
+++ b/Services/Website/Sources/Library/Public/Contexts/WebsiteRequestContext.swift
@@ -4,9 +4,8 @@ import NIOCore
 
 /// The website's request context.
 ///
-/// Extends the core request storage with the negotiated language, defaulting to the default
-/// supported language until ``LocalizationMiddleware`` resolves it from the request, and with
-/// the connected client's address, so ``RateLimitMiddleware`` can key its budgets per client.
+/// Extends the core request storage with the negotiated language, defaulting to the default supported language until ``LocalizationMiddleware``
+/// resolves it from the request, and with the connected client's address, so ``RateLimitMiddleware`` can key its budgets per client.
 public struct WebsiteRequestContext: LocalizedRequestContext, RemoteAddressRequestContext {
 
     // MARK: Properties
diff --git a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
index 4597e27..b6043a0 100644
--- a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
@@ -28,8 +28,7 @@ public struct HealthController<Context: RequestContext> {
     // MARK: Initializers
 
     /// Creates a health controller.
-    /// - Parameter probe: the probe consulted by the readiness route; when `nil`, only the liveness
-    ///   route is served.
+    /// - Parameter probe: the probe consulted by the readiness route; when `nil`, only the liveness route is served.
     public init(
         probe: Probe? = nil
     ) {
@@ -72,9 +71,8 @@ private extension HealthController {
 
     /// Handles a request for the liveness check.
     ///
-    /// Returns a constant JSON body built directly per request — the payload is a tiny literal with no
-    /// rendering step, so there is nothing to pre-render or cache. It reports only that the process is up,
-    /// with no dependency check, so an orchestrator restarts the process only when the process itself is
+    /// Returns a constant JSON body built directly per request — the payload is a tiny literal with no rendering step, so there is nothing to pre-render or
+    /// cache. It reports only that the process is up, with no dependency check, so an orchestrator restarts the process only when the process itself is
     /// unresponsive.
     /// - Parameters:
     ///   - request: the incoming request.
@@ -93,9 +91,8 @@ private extension HealthController {
 
     /// Handles a request for the readiness check.
     ///
-    /// Consults the `Probe` supplied at initialization and reports `200 OK` when the service's
-    /// database is reachable, or `503 Service Unavailable` otherwise, so a load balancer withholds
-    /// traffic from an instance that cannot yet serve it without restarting the process.
+    /// Consults the `Probe` supplied at initialization and reports `200 OK` when the service's database is reachable, or `503 Service Unavailable`
+    /// otherwise, so a load balancer withholds traffic from an instance that cannot yet serve it without restarting the process.
     /// - Parameters:
     ///   - request: the incoming request.
     ///   - context: the context the request is resolved against.
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index fef2cb9..b1a440f 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -4,8 +4,7 @@ import Infrastructure
 
 /// Serves the website's root routes.
 ///
-/// The controller exposes its routes through its `RouterController` conformance, so the
-/// application that composes it registers them declaratively:
+/// The controller exposes its routes through its `RouterController` conformance, so the application that composes it registers them declaratively:
 ///
 /// ```swift
 /// router.addController {
@@ -13,8 +12,7 @@ import Infrastructure
 /// }
 /// ```
 ///
-/// - Note: `Context` is the request context the routes are resolved against, and must match the
-///   context of the router the routes are added to.
+/// - Note: `Context` is the request context the routes are resolved against, and must match the context of the router the routes are added to.
 public struct RootController<Context: LocalizedRequestContext> {
 
     // MARK: Properties
@@ -25,8 +23,7 @@ public struct RootController<Context: LocalizedRequestContext> {
     // MARK: Initializers
 
     /// Creates a root controller.
-    /// - Parameter assetVersion: the version token appended to the page's asset URLs, or `nil`
-    ///   (the default) to leave them unversioned.
+    /// - Parameter assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
     public init(
         assetVersion: String? = nil
     ) {
@@ -67,8 +64,7 @@ private extension RootController {
 
     /// Handles a request for the landing page.
     ///
-    /// Renders the ``IndexPage`` in the language stored on the context by ``LocalizationMiddleware``,
-    /// falling back to the default language.
+    /// Renders the ``IndexPage`` in the language stored on the context by ``LocalizationMiddleware``, falling back to the default language.
     /// - Parameters:
     ///   - request: the incoming request.
     ///   - context: the context the request is resolved against.
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index 449238c..0c141e5 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -3,7 +3,10 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("StaticFile enumeration")
+@Suite(
+    "StaticFile enumeration",
+    .tags(.enumeration)
+)
 struct StaticFileTests {
 
     // MARK: Type aliases
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
index 3268b64..4a2771c 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
@@ -4,7 +4,10 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("ErrorPage page", .tags(.page))
+@Suite(
+    "ErrorPage page",
+    .tags(.page)
+)
 struct ErrorPageTests {
     
     // MARK: Functional tests
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index a98bb33..d06606a 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -4,7 +4,10 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("IndexPage page", .tags(.page))
+@Suite(
+    "IndexPage page",
+    .tags(.page)
+)
 struct IndexPageTests {
     
     // MARK: Functional tests
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
index 9d565bf..dcf3654 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -7,7 +7,10 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("HealthController controller", .tags(.controller))
+@Suite(
+    "HealthController controller",
+    .tags(.controller)
+)
 struct HealthControllerTests {
 
     // MARK: Functional tests
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
index b705b7a..a211e9b 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
@@ -6,7 +6,10 @@ import Testing
 
 @testable import WebsiteLibrary
 
-@Suite("RootController controller", .tags(.controller))
+@Suite(
+    "RootController controller",
+    .tags(.controller)
+)
 struct RootControllerTests {
     
     // MARK: Constants
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
deleted file mode 100644
index 60c8871..0000000
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
+++ /dev/null
@@ -1,57 +0,0 @@
-import HTTPTypes
-import Hummingbird
-import HummingbirdTesting
-import NIOCore
-import Testing
-
-import Infrastructure
-
-@testable import WebsiteLibrary
-
-@Suite("LocalizationMiddleware middleware", .tags(.middleware))
-struct LocalizationMiddlewareTests {
-
-    // MARK: Constants
-
-    private let app: Application = .init(router: {
-        let router = Router(context: WebsiteRequestContext.self)
-
-        router.addMiddleware {
-            LocalizationMiddleware()
-        }
-
-        router.get("language") { _, context in
-            context.language
-        }
-
-        return router
-    }())
-
-    // MARK: Functional tests
-
-    @Test
-    func `negotiates a supported language from the header`() async throws {
-        try await app.test(.router) { client in
-            try await client.execute(
-                uri: "/language",
-                method: .get,
-                headers: [.acceptLanguage: "en-US,en;q=0.9"]
-            ) { response in
-                #expect(String(buffer: response.body) == "en")
-            }
-        }
-    }
-
-    @Test
-    func `falls back to the default without a header`() async throws {
-        try await app.test(.router) { client in
-            try await client.execute(
-                uri: "/language",
-                method: .get
-            ) { response in
-                #expect(String(buffer: response.body) == "en")
-            }
-        }
-    }
-
-}
diff --git a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift b/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
deleted file mode 100644
index 22f1f9b..0000000
--- a/Services/Website/Tests/Library/Cases/Public/Middlewares/NotFoundMiddlewareTests.swift
+++ /dev/null
@@ -1,173 +0,0 @@
-import Hummingbird
-import HummingbirdTesting
-import NIOCore
-import Testing
-
-import Infrastructure
-
-@testable import WebsiteLibrary
-
-@Suite("NotFoundMiddleware middleware", .tags(.middleware))
-struct NotFoundMiddlewareTests {
-    
-    // MARK: Constants
-    
-    private let app: Application = .init(router: {
-        let router = Router(context: WebsiteRequestContext.self)
-        
-        router.addMiddleware {
-            LocalizationMiddleware()
-            NotFoundMiddleware()
-        }
-        
-        router.get("hello") { _, _ in
-            "Hello!"
-        }
-
-        router.get("boom") { _, _ -> String in
-            throw HTTPError(.badRequest)
-        }
-
-        return router
-    }())
-    
-    // MARK: Functional tests
-
-    @Test
-    func `renders the error page for an unmatched request`() async throws {
-        try await app.test(.router) { client in
-            try await client.execute(
-                uri: "/this-path-does-not-exist",
-                method: .get
-            ) { response in
-                let body = String(buffer: response.body)
-
-                #expect(response.status == .notFound)
-                #expect(response.headers[.contentType] == "text/html; charset=utf-8")
-                #expect(response.headers[.contentLanguage] == "en")
-                #expect(response.headers[.vary] == "Accept-Language")
-                #expect(body.contains("Page Not Found"))
-            }
-        }
-    }
-
-    @Test
-    func `passes a matched response through untouched`() async throws {
-        try await app.test(.router) { client in
-            try await client.execute(
-                uri: "/hello",
-                method: .get
-            ) { response in
-                #expect(response.status == .ok)
-                #expect(response.body == ByteBuffer(string: "Hello!"))
-            }
-        }
-    }
-
-    @Test
-    func `rethrows a non-not-found error unchanged`() async throws {
-        try await app.test(.router) { client in
-            try await client.execute(
-                uri: "/boom",
-                method: .get
-            ) { response in
-                let body = String(buffer: response.body)
-
-                #expect(response.status == .badRequest)
-                #expect(!body.contains("Page Not Found"))
-            }
-        }
-    }
-
-    @Test
-    func `renders versioned asset URLs when given a version`() async throws {
-        try await app(
-            assetVersion: "0123456789abcdef"
-        ).test(.router) { client in
-            try await client.execute(
-                uri: "/this-path-does-not-exist",
-                method: .get
-            ) { response in
-                let body = String(buffer: response.body)
-
-                #expect(body.contains("/css/error.css?v=0123456789abcdef"))
-                #expect(body.contains("/js/shared.js?v=0123456789abcdef"))
-            }
-        }
-    }
-
-    @Test
-    func `renders unversioned asset URLs by default`() async throws {
-        try await app.test(.router) { client in
-            try await client.execute(
-                uri: "/this-path-does-not-exist",
-                method: .get
-            ) { response in
-                let body = String(buffer: response.body)
-
-                #expect(body.contains(#"href="/css/error.css""#))
-                #expect(!body.contains("?v="))
-            }
-        }
-    }
-
-    @Test
-    func `serves the error page without revalidation headers`() async throws {
-        // A `304 Not Modified` only ever stands in for a success, so the error page must not
-        // invite revalidation with an entity tag or a cache policy.
-        try await app.test(.router) { client in
-            try await client.execute(
-                uri: "/this-path-does-not-exist",
-                method: .get
-            ) { response in
-                #expect(response.status == .notFound)
-                #expect(response.headers[.eTag] == nil)
-                #expect(response.headers[.cacheControl] == nil)
-            }
-        }
-    }
-
-    @Test
-    func `serves the full error page to a conditional request`() async throws {
-        try await app.test(.router) { client in
-            try await client.execute(
-                uri: "/this-path-does-not-exist",
-                method: .get,
-                headers: [.ifNoneMatch: "*"]
-            ) { response in
-                let body = String(buffer: response.body)
-
-                #expect(response.status == .notFound)
-                #expect(body.contains("Page Not Found"))
-            }
-        }
-    }
-
-}
-
-// MARK: - Helpers
-
-private extension NotFoundMiddlewareTests {
-
-    // MARK: Methods
-
-    /// Builds an application whose not-found middleware appends the given version token to the
-    /// error page's asset URLs.
-    /// - Parameter assetVersion: the version token appended to the page's asset URLs.
-    /// - Returns: the configured application.
-    func app(
-        assetVersion: String?
-    ) -> some ApplicationProtocol {
-        let router = Router(context: WebsiteRequestContext.self)
-
-        router.addMiddleware {
-            LocalizationMiddleware()
-            NotFoundMiddleware(
-                assetVersion: assetVersion
-            )
-        }
-
-        return Application(router: router)
-    }
-
-}
diff --git a/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift b/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
index 2dee5a2..63cb88f 100644
--- a/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
+++ b/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
@@ -3,8 +3,8 @@ import Testing
 extension Tag {
     /// Tests exercising a controller of the Website library.
     @Tag static var controller: Tag
-    /// Tests exercising a middleware of the Website library.
-    @Tag static var middleware: Tag
+    /// Tests exercising an enumeration of the Website library.
+    @Tag static var enumeration: Tag
     /// Tests exercising a page of the Website library.
     @Tag static var page: Tag
 }
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
index c297e23..4ca579d 100644
--- a/Services/Website/docker-compose.override.yml
+++ b/Services/Website/docker-compose.override.yml
@@ -1,12 +1,12 @@
 # Local development overrides.
-# Compose merges this file on top of docker-compose.yml automatically, so a
-# plain `docker compose up` builds from source instead of pulling a registry image:
+# Compose merges this file on top of docker-compose.yml automatically, so a plain `docker compose up` builds from
+# source instead of pulling a registry image:
 #
 #   docker compose up --build       # build locally and run
 #   docker compose up -d            # reuse the last local build
 #
-# It reuses the `image:` name from the base file, so the local build is tagged
-# the same way the production image would be.
+# It reuses the `image:` name from the base file, so the local build is tagged the same way the production image would
+# be.
 services:
   website:
     image: ${IMAGE_NAME}:${IMAGE_TAG:-latest}
@@ -20,8 +20,8 @@ services:
       DATABASE_HOST: ${DATABASE_HOST:-localhost}
       DATABASE_TLS: ${DATABASE_TLS:-off}
 
-  # Local development database, started only with the `database` profile so a plain
-  # `docker compose up` still runs the in-memory backend:
+  # Local development database, started only with the `database` profile so a plain `docker compose up` still runs the
+  # in-memory backend:
   #
   #   docker compose --profile database up mariadb
   mariadb:
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index 0aa0ffb..06c973c 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -6,9 +6,8 @@ name: loud-platform
 #   docker compose -f docker-compose.yml pull
 #   docker compose -f docker-compose.yml up -d
 #
-# The `-f docker-compose.yml` flag is important in production: it skips the
-# docker-compose.override.yml file, which Compose would otherwise merge in
-# automatically for local development.
+# The `-f docker-compose.yml` flag is important in production: it skips the docker-compose.override.yml file, which
+# Compose would otherwise merge in automatically for local development.
 services:
   website:
     image: ${HOST_CONTAINER}/${HOST_OWNER}/${IMAGE_NAME}:${IMAGE_TAG:-latest}
@@ -21,16 +20,15 @@ services:
       LOG_LEVEL: ${LOG_LEVEL:-info}
       HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-LoudWebsite}
       SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
-      # Persistence: in-memory by default; set DATABASE_DRIVER=mysql to run against a
-      # managed MySQL/MariaDB database. Provide the password via the environment or a
-      # secret — never commit it.
+      # Persistence: in-memory by default; set DATABASE_DRIVER=mysql to run against a managed MySQL/MariaDB database.
+      # Provide the password via the environment or a secret — never commit it.
       DATABASE_DRIVER: ${DATABASE_DRIVER:-mysql}
       DATABASE_HOST: ${DATABASE_HOST:-localhost}
       DATABASE_PORT: ${DATABASE_PORT:-3306}
       DATABASE_NAME: ${DATABASE_NAME:-loud-ams}
       DATABASE_USERNAME: ${DATABASE_USERNAME:-loud-ams}
       DATABASE_PASSWORD: ${DATABASE_PASSWORD:-}
-      DATABASE_TLS: ${DATABASE_TLS:-require}
+      DATABASE_TLS: ${DATABASE_TLS:-prefer}
     healthcheck:
       test: ["CMD", "curl", "--fail", "--silent", "--show-error", "http://127.0.0.1:8080/health"]
       interval: 30s
-- 
2.54.0


From efc933d5d0c3cbba056899645c5a796a1a569984 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 1 Aug 2026 10:57:29 +0000
Subject: [PATCH 030/117] Extra tags and Social Card integration in the
 Infrastructure package (#28)

This PR contains the work done to extends the `Page` protocol with the head tags that control search snippets and link previews: a meta description, a canonical URL, and a social card rendered as _Open Graph_ and _Twitter_ meta tags. All three are optional with nil defaults, so existing conformers compile and render unchanged.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/28
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../Sources/Public/Protocols/Page.swift       |  71 +++++++--
 .../Sources/Public/Types/SocialCard.swift     | 138 ++++++++++++++++++
 .../Types/SocialCard/SocialCardImage.swift    |  72 +++++++++
 .../Types/SocialCard/SocialCardTag.swift      |  55 +++++++
 .../Cases/Public/Protocols/PageTests.swift    |  50 +++++++
 .../Cases/Public/Types/SocialCardTests.swift  |  84 +++++++++++
 .../Utils/Extensions/Tag+Constants.swift      |   2 +-
 .../Tests/Utils/Pages/StubPage.swift          |  23 ++-
 8 files changed, 483 insertions(+), 12 deletions(-)
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift

diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
index 7875f6b..7ab842e 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
@@ -4,8 +4,8 @@ import Foundation
 /// A page of a website: an HTML document with the shared scaffolding assembled around the page's content.
 ///
 /// A conforming page supplies its locale, its title, the stylesheets and scripts it needs, its head metadata, and its content; the protocol assembles the
-/// rest of the document around them: the viewport declaration and stylesheet links followed by the metadata in the head, and the content followed by
-/// the script tags in the body.
+/// rest of the document around them: the viewport declaration, the summary, canonical, and social card tags, and the metadata followed by the
+/// stylesheet links in the head, and the content followed by the script tags in the body.
 public protocol Page: HTMLDocument, Sendable {
 
     // MARK: Associated types
@@ -21,6 +21,9 @@ public protocol Page: HTMLDocument, Sendable {
     /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
     var assetVersion: String? { get }
 
+    /// The canonical URL the page is served at, rendered as a `link rel="canonical"` tag in the document head, or `nil` (the default) to omit the tag.
+    var canonicalURL: String? { get }
+
     /// The page's markup, rendered before the ``scripts``.
     @HTMLBuilder
     var content: Content { get }
@@ -28,30 +31,41 @@ public protocol Page: HTMLDocument, Sendable {
     /// The locale the page content is localized to.
     var locale: Locale { get }
 
-    /// The markup placed in the document head after the ``stylesheets``: icon and manifest
-    /// links, extra meta tags, and the like.
+    /// The markup placed in the document head before the ``stylesheets`` links: icon and manifest links, extra meta tags, and the like.
     @HTMLBuilder
     var metadata: Metadata { get }
 
     /// The scripts loaded at the end of the document body, in order.
     var scripts: [any Asset] { get }
 
+    /// The card controlling the page's link previews, rendered as Open Graph and Twitter meta tags in the document head, or `nil` (the default)
+    /// to omit them.
+    var socialCard: SocialCard? { get }
+
     /// The stylesheets linked in the document head, in order.
     var stylesheets: [any Asset] { get }
 
+    /// The page's summary, rendered as a `meta name="description"` tag in the document head, or `nil` (the default) to omit the tag.
+    var summary: String? { get }
+
 }
 
 // MARK: - Implementations
 
 public extension Page {
-
+    
     // MARK: Computed
-
+    
+    /// The canonical URL is omitted unless the page provides one.
+    var canonicalURL: String? {
+        nil
+    }
+    
     /// The page ``content`` followed by its ``scripts``.
     @HTMLBuilder
     var body: some HTML {
         content
-
+        
         for file in scripts {
             script(.src(file.urlPath(
                 for: .js,
@@ -59,8 +73,9 @@ public extension Page {
             ))) {}
         }
     }
-
-    /// The viewport declaration and ``stylesheets`` links followed by the ``metadata``, placed in the document head.
+    
+    /// The viewport declaration, the ``summary``, ``canonicalURL``, and ``socialCard`` tags (when provided), and the ``metadata``
+    /// followed by the ``stylesheets`` links, placed in the document head.
     ///
     /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already emits `<meta charset="UTF-8">` before this markup,
     /// and HTML5 allows only one.
@@ -70,9 +85,35 @@ public extension Page {
             .name(.viewport),
             .content("width=device-width, initial-scale=1")
         )
+        
+        if let summary {
+            meta(
+                .name(.description),
+                .content(summary)
+            )
+        }
+        
+        if let canonicalURL {
+            link(
+                .rel("canonical"),
+                .href(canonicalURL)
+            )
+        }
+
+        if let socialCard {
+            for tag in socialCard.tags {
+                meta(
+                    .custom(
+                        name: tag.attribute.rawValue,
+                        value: tag.name.rawValue
+                    ),
+                    .content(tag.content)
+                )
+            }
+        }
 
         metadata
-
+        
         for file in stylesheets {
             link(
                 .rel(.stylesheet),
@@ -83,5 +124,15 @@ public extension Page {
             )
         }
     }
+    
+    /// The social card is omitted unless the page provides one.
+    var socialCard: SocialCard? {
+        nil
+    }
 
+    /// The summary is omitted unless the page provides one.
+    var summary: String? {
+        nil
+    }
+    
 }
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
new file mode 100644
index 0000000..101ef61
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
@@ -0,0 +1,138 @@
+/// The content of a page's link-preview card, rendered as Open Graph and Twitter meta tags in the document head.
+///
+/// The card carries the facts a link scraper reads — the page's title, summary, URL, and share image — and derives the meta ``tags`` expressing
+/// them. Scrapers require absolute URLs, so the card takes ``url`` and ``Image/url`` fully formed; composing them from an origin and a versioned
+/// asset path stays with the page providing the card.
+public struct SocialCard: Sendable {
+
+    // MARK: Properties
+
+    /// The card's share image, or `nil` to omit its tags.
+    public let image: Image?
+
+    /// The locale of the card's text, or `nil` to omit its tag.
+    ///
+    /// Open Graph specifies the `language_TERRITORY` form (e.g. `en_US`); scrapers also accept a bare language code (e.g. `en`).
+    public let locale: String?
+
+    /// The name of the site the card belongs to, or `nil` to omit its tag.
+    public let siteName: String?
+
+    /// The layout a Twitter card scraper gives the card.
+    public let style: Style
+
+    /// The card's summary, or `nil` to omit its tag.
+    public let summary: String?
+
+    /// The card's title.
+    public let title: String
+
+    /// The Open Graph type of the object the card describes.
+    public let type: String
+
+    /// The absolute URL the card's page is served at, or `nil` to omit its tag.
+    public let url: String?
+
+    // MARK: Initializers
+
+    /// Creates a link-preview card.
+    /// - Parameters:
+    ///   - title: the card's title.
+    ///   - summary: the card's summary, or `nil` (the default) to omit its tag.
+    ///   - url: the absolute URL the card's page is served at, or `nil` (the default) to omit its tag.
+    ///   - siteName: the name of the site the card belongs to, or `nil` (the default) to omit its tag.
+    ///   - locale: the locale of the card's text, ideally in Open Graph's `language_TERRITORY` form (e.g. `en_US`), or `nil` (the default)
+    ///     to omit its tag.
+    ///   - image: the card's share image, or `nil` (the default) to omit its tags.
+    ///   - type: the Open Graph type of the object the card describes. Defaults to `website`.
+    ///   - style: the layout a Twitter card scraper gives the card. Defaults to ``Style/summaryLargeImage``.
+    public init(
+        title: String,
+        summary: String? = nil,
+        url: String? = nil,
+        siteName: String? = nil,
+        locale: String? = nil,
+        image: Image? = nil,
+        type: String = "website",
+        style: Style = .summaryLargeImage
+    ) {
+        self.image = image
+        self.locale = locale
+        self.siteName = siteName
+        self.style = style
+        self.summary = summary
+        self.title = title
+        self.type = type
+        self.url = url
+    }
+
+    // MARK: Computed
+
+    /// The card's meta tags, in a stable order: the Open Graph type, site name, title, description, URL, and locale, then the image group, and
+    /// the Twitter card style last. A tag whose fact the card does not carry is left out.
+    public var tags: [SocialCardTag] {
+        let tags: [SocialCardTag?] = [
+            SocialCardTag(
+                attribute: .property,
+                content: type,
+                name: .type
+            ),
+            siteName.map {
+                SocialCardTag(
+                    attribute: .property,
+                    content: $0,
+                    name: .siteName
+                )
+            },
+            SocialCardTag(
+                attribute: .property,
+                content: title,
+                name: .title
+            ),
+            summary.map {
+                SocialCardTag(
+                    attribute: .property,
+                    content: $0,
+                    name: .description
+                )
+            },
+            url.map {
+                SocialCardTag(
+                    attribute: .property,
+                    content: $0,
+                    name: .url
+                )
+            },
+            locale.map {
+                SocialCardTag(
+                    attribute: .property,
+                    content: $0,
+                    name: .locale
+                )
+            },
+        ] + (image?.tags ?? []) + [
+            SocialCardTag(
+                attribute: .name,
+                content: style.rawValue,
+                name: .twitter
+            ),
+        ]
+
+        return tags.compactMap { $0 }
+    }
+
+}
+
+// MARK: - Enumerations
+
+public extension SocialCard {
+
+    /// The layout a Twitter card scraper gives a ``SocialCard``.
+    enum Style: String,  Sendable {
+        /// A compact card with a small thumbnail.
+        case summary
+        /// A card with a large image above the text.
+        case summaryLargeImage = "summary_large_image"
+    }
+
+}
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift
new file mode 100644
index 0000000..d00398f
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift
@@ -0,0 +1,72 @@
+extension SocialCard {
+    /// The share image of a ``SocialCard``.
+    public struct Image: Sendable {
+
+        // MARK: Properties
+
+        /// The image's text for assistive technologies, or `nil` to omit it.
+        public let alt: String?
+
+        /// The image's height in pixels, letting scrapers lay the card out before fetching the image.
+        public let height: Int
+
+        /// The absolute URL the image is served at.
+        public let url: String
+
+        /// The image's width in pixels, letting scrapers lay the card out before fetching the image.
+        public let width: Int
+
+        // MARK: Initializers
+
+        /// Creates a share image.
+        /// - Parameters:
+        ///   - url: the absolute URL the image is served at.
+        ///   - width: the image's width in pixels.
+        ///   - height: the image's height in pixels.
+        ///   - alt: the image's text for assistive technologies, or `nil` (the default) to omit it.
+        public init(
+            url: String,
+            width: Int,
+            height: Int,
+            alt: String? = nil
+        ) {
+            self.alt = alt
+            self.height = height
+            self.url = url
+            self.width = width
+        }
+        
+        // MARK: Computed
+        
+        /// The image's meta tags, in a stable order: its URL, width, and height, then its alt text when it carries one.
+        public var tags: [SocialCardTag] {
+            let tags: [SocialCardTag?] = [
+                SocialCardTag(
+                    attribute: .property,
+                    content: url,
+                    name: .image
+                ),
+                SocialCardTag(
+                    attribute: .property,
+                    content: String(width),
+                    name: .imageWidth
+                ),
+                SocialCardTag(
+                    attribute: .property,
+                    content: String(height),
+                    name: .imageHeight
+                ),
+                alt.map {
+                    SocialCardTag(
+                        attribute: .property,
+                        content: $0,
+                        name: .imageAlt
+                    )
+                },
+            ]
+
+            return tags.compactMap { $0 }
+        }
+
+    }
+}
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
new file mode 100644
index 0000000..414782b
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
@@ -0,0 +1,55 @@
+/// A head meta tag of a ``SocialCard``: which attribute keys it, and its name and content.
+public struct SocialCardTag: Equatable, Sendable {
+
+    // MARK: Properties
+
+    /// The attribute the tag is keyed by.
+    public let attribute: Attribute
+
+    /// The tag's value.
+    public let content: String
+
+    /// The tag's name.
+    public let name: Name
+
+}
+
+// MARK: - Enumerations
+
+extension SocialCardTag {
+    
+    /// The meta attribute a ``SocialCardTag`` is keyed by, named by its raw value.
+    public enum Attribute: String, Sendable {
+        /// The `name` attribute, keying the Twitter tags.
+        case name
+        /// The `property` attribute, keying the Open Graph tags.
+        case property
+    }
+
+    /// The name of a ``SocialCardTag``, carried in its raw value.
+    public enum Name: String, Sendable {
+        /// The `og:description` tag, carrying the card's summary.
+        case description = "og:description"
+        /// The `og:image` tag, carrying the share image's absolute URL.
+        case image = "og:image"
+        /// The `og:image:alt` tag, carrying the share image's text for assistive technologies.
+        case imageAlt = "og:image:alt"
+        /// The `og:image:width` tag, carrying the share image's width in pixels.
+        case imageWidth = "og:image:width"
+        /// The `og:image:height` tag, carrying the share image's height in pixels.
+        case imageHeight = "og:image:height"
+        /// The `og:locale` tag, carrying the locale of the card's text.
+        case locale = "og:locale"
+        /// The `og:site_name` tag, carrying the name of the site the card belongs to.
+        case siteName = "og:site_name"
+        /// The `og:title` tag, carrying the card's title.
+        case title = "og:title"
+        /// The `twitter:card` tag, carrying the layout a Twitter card scraper gives the card.
+        case twitter = "twitter:card"
+        /// The `og:type` tag, carrying the Open Graph type of the object the card describes.
+        case type = "og:type"
+        /// The `og:url` tag, carrying the absolute URL the card's page is served at.
+        case url = "og:url"
+    }
+    
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
index 485d65e..b1a10af 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
@@ -47,6 +47,56 @@ struct PageTests {
         #expect(content.lowerBound < script.lowerBound)
     }
 
+    @Test
+    func `omits the summary and canonical tags by default`() {
+        let html = StubPage().render()
+
+        #expect(!html.contains(#"name="description""#))
+        #expect(!html.contains(#"rel="canonical""#))
+    }
+
+    @Test
+    func `renders the summary and canonical tags when provided`() {
+        let html = StubPage(
+            canonicalURL: "https://stub.example/",
+            summary: "A stub page."
+        ).render()
+
+        #expect(html.contains(#"<meta name="description" content="A stub page.">"#))
+        #expect(html.contains(#"<link rel="canonical" href="https://stub.example/">"#))
+    }
+
+    @Test
+    func `omits the social card tags by default`() {
+        let html = StubPage().render()
+
+        #expect(!html.contains(#"property="og:"#))
+        #expect(!html.contains(#"name="twitter:card""#))
+    }
+
+    @Test
+    func `renders the social card tags when provided`() {
+        let html = StubPage(socialCard: .init(
+            title: "Stub Page",
+            summary: "A stub page.",
+            url: "https://stub.example/",
+            image: .init(
+                url: "https://stub.example/img/card.png",
+                width: 2400,
+                height: 1260
+            )
+        )).render()
+
+        #expect(html.contains(#"<meta property="og:type" content="website">"#))
+        #expect(html.contains(#"<meta property="og:title" content="Stub Page">"#))
+        #expect(html.contains(#"<meta property="og:description" content="A stub page.">"#))
+        #expect(html.contains(#"<meta property="og:url" content="https://stub.example/">"#))
+        #expect(html.contains(#"<meta property="og:image" content="https://stub.example/img/card.png">"#))
+        #expect(html.contains(#"<meta property="og:image:width" content="2400">"#))
+        #expect(html.contains(#"<meta property="og:image:height" content="1260">"#))
+        #expect(html.contains(#"<meta name="twitter:card" content="summary_large_image">"#))
+    }
+
     @Test
     func `appends the version token to the asset URLs`() {
         let html = StubPage(assetVersion: "0123456789abcdef").render()
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
new file mode 100644
index 0000000..1282bb9
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
@@ -0,0 +1,84 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite(
+    "SocialCard type",
+    .tags(.type)
+)
+struct SocialCardTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `derives the full tag list from a complete card`() {
+        let card = SocialCard(
+            title: "A Title",
+            summary: "A summary.",
+            url: "https://site.example/",
+            siteName: "A Site",
+            locale: "en",
+            image: .init(
+                url: "https://site.example/img/card.png",
+                width: 2400,
+                height: 1260,
+                alt: "An image."
+            )
+        )
+
+        #expect(card.tags == [
+            .init(attribute: .property, content: "website", name: .type),
+            .init(attribute: .property, content: "A Site", name: .siteName),
+            .init(attribute: .property, content: "A Title", name: .title),
+            .init(attribute: .property, content: "A summary.", name: .description),
+            .init(attribute: .property, content: "https://site.example/", name: .url),
+            .init(attribute: .property, content: "en", name: .locale),
+            .init(attribute: .property, content: "https://site.example/img/card.png", name: .image),
+            .init(attribute: .property, content: "2400", name: .imageWidth),
+            .init(attribute: .property, content: "1260", name: .imageHeight),
+            .init(attribute: .property, content: "An image.", name: .imageAlt),
+            .init(attribute: .name, content: "summary_large_image", name: .twitter),
+        ])
+    }
+
+    @Test
+    func `omits the tags of the facts a minimal card does not carry`() {
+        let card = SocialCard(title: "A Title")
+
+        #expect(card.tags == [
+            .init(attribute: .property, content: "website", name: .type),
+            .init(attribute: .property, content: "A Title", name: .title),
+            .init(attribute: .name, content: "summary_large_image", name: .twitter),
+        ])
+    }
+
+    @Test
+    func `omits the image alt tag when the image carries none`() {
+        let card = SocialCard(
+            title: "A Title",
+            image: .init(
+                url: "https://site.example/img/card.png",
+                width: 2400,
+                height: 1260
+            )
+        )
+
+        let names = card.tags.map(\.name)
+
+        #expect(names.contains(.image))
+        #expect(!names.contains(.imageAlt))
+    }
+
+    @Test
+    func `carries the type and style it is given`() {
+        let card = SocialCard(
+            title: "A Title",
+            type: "article",
+            style: .summary
+        )
+
+        #expect(card.tags.contains(.init(attribute: .property, content: "article", name: .type)))
+        #expect(card.tags.contains(.init(attribute: .name, content: "summary", name: .twitter)))
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift b/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
index 9fec14b..1117cd8 100644
--- a/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
+++ b/Packages/Infrastructure/Tests/Utils/Extensions/Tag+Constants.swift
@@ -9,6 +9,6 @@ extension Tag {
     @Tag static var middleware: Tag
     /// Tests exercising a protocol scaffolding of the Infrastructure package.
     @Tag static var `protocol`: Tag
-    /// Tests exercising an internal type of the Infrastructure package.
+    /// Tests exercising a type of the Infrastructure package.
     @Tag static var type: Tag
 }
diff --git a/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift b/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
index eae187d..68c8ac0 100644
--- a/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
+++ b/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
@@ -10,9 +10,18 @@ struct StubPage: Page {
     /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
     let assetVersion: String?
 
+    /// The canonical URL rendered in the document head, or `nil` to omit it.
+    let canonicalURL: String?
+
     /// The locale the page content is localized to.
     let locale: Locale
 
+    /// The card rendered as link-preview tags in the document head, or `nil` to omit them.
+    let socialCard: SocialCard?
+
+    /// The summary rendered in the document head, or `nil` to omit it.
+    let summary: String?
+
     // MARK: Initializers
 
     /// Creates a stub page.
@@ -20,12 +29,24 @@ struct StubPage: Page {
     ///   - locale: the locale the page content is localized to. Defaults to `en`.
     ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
     ///     default) to leave them unversioned.
+    ///   - canonicalURL: the canonical URL rendered in the document head, or `nil` (the default)
+    ///     to omit it.
+    ///   - socialCard: the card rendered as link-preview tags in the document head, or `nil`
+    ///     (the default) to omit them.
+    ///   - summary: the summary rendered in the document head, or `nil` (the default)
+    ///     to omit it.
     init(
         locale: Locale = .init(identifier: "en"),
-        assetVersion: String? = nil
+        assetVersion: String? = nil,
+        canonicalURL: String? = nil,
+        socialCard: SocialCard? = nil,
+        summary: String? = nil
     ) {
         self.assetVersion = assetVersion
+        self.canonicalURL = canonicalURL
         self.locale = locale
+        self.socialCard = socialCard
+        self.summary = summary
     }
 
     // MARK: Computed
-- 
2.54.0


From 5f4316b85b59a88de151d2ed1860b3a4c0f7b335 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 1 Aug 2026 11:15:27 +0000
Subject: [PATCH 031/117] Added the Utility package (#29)

This PR contains the work done to create the new **Utility** package within the project, and also included in it the `NormalizeEmail` method, as it's not something that belongs to the **Infrastructure** package.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/29
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Packages/Infrastructure/README.md             |  8 ++-
 Packages/Utility/Package.swift                | 31 ++++++++++
 Packages/Utility/README.md                    | 31 ++++++++++
 .../Public/Methods/NormalizeEmail.swift       | 49 ++++++++++++++++
 .../Public/Methods/NormalizeEmailTests.swift  | 57 +++++++++++++++++++
 .../Utils/Extensions/Tag+Constants.swift      |  6 ++
 Services/Website/Package.swift                | 10 +++-
 Services/Website/Tests/Website.xctestplan     |  7 +++
 8 files changed, 193 insertions(+), 6 deletions(-)
 create mode 100644 Packages/Utility/Package.swift
 create mode 100644 Packages/Utility/README.md
 create mode 100644 Packages/Utility/Sources/Public/Methods/NormalizeEmail.swift
 create mode 100644 Packages/Utility/Tests/Cases/Public/Methods/NormalizeEmailTests.swift
 create mode 100644 Packages/Utility/Tests/Utils/Extensions/Tag+Constants.swift

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index cade1d7..c7fdf23 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -8,13 +8,14 @@ The package provides, grouped by role:
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
 | Middlewares | `SecurityHeadersMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
+| Link previews | `SocialCard`, its `Image`, and the `SocialCardTag` meta tags it derives |
 | Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
 
 ## Design rules
 The package holds only what every service can reuse; anything a service owns is injected, never referenced:
-- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors.
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors — as are the `summary`, `canonicalURL`, and `socialCard` values its other head tags render, each omitted unless the page provides it. A `SocialCard` takes its URLs fully formed and absolute; composing them from an origin and a versioned asset path stays with the page providing the card.
 - **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern to follow.
 - **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
@@ -29,7 +30,8 @@ Sources/
 │   ├── Methods/           FingerprintAssets
 │   ├── Middlewares/       the five HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
-│   └── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
+│   ├── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
+│   └── Types/             SocialCard, with its image and tag types in SocialCard/
 └── Internal/
     └── Types/             implementation details (FNV1aHash)
 Tests/
@@ -43,4 +45,4 @@ Every suite carries a tag naming the kind of API it exercises — `.asset`, `.ex
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
-- macOS 15, matching the sibling `Localization` and `Persistence` packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- macOS 15, matching the sibling `Localization`, `Persistence`, and `Utility` packages (the services deploy to Linux containers; the packages carry no UI platforms).
diff --git a/Packages/Utility/Package.swift b/Packages/Utility/Package.swift
new file mode 100644
index 0000000..574189c
--- /dev/null
+++ b/Packages/Utility/Package.swift
@@ -0,0 +1,31 @@
+// swift-tools-version: 6.3
+
+import PackageDescription
+
+let package = Package(
+    name: "Utility",
+    platforms: [
+        .macOS(.v15),
+    ],
+    products: [
+        .library(
+            name: "Utility",
+            targets: [
+                "Utility"
+            ]
+        )
+    ],
+    targets: [
+        .target(
+            name: "Utility",
+            path: "Sources",
+        ),
+        .testTarget(
+            name: "UtilityTests",
+            dependencies: [
+                .byName(name: "Utility")
+            ],
+            path: "Tests"
+        ),
+    ]
+)
diff --git a/Packages/Utility/README.md b/Packages/Utility/README.md
new file mode 100644
index 0000000..168ee32
--- /dev/null
+++ b/Packages/Utility/README.md
@@ -0,0 +1,31 @@
+# Utility
+The general-purpose helpers the **Loud** services share: small, single-purpose methods with no dependencies beyond Foundation and no ties to any web framework.
+
+## Overview
+The package provides, grouped by role:
+| Role | Types |
+| --- | --- |
+| Validation | `NormalizeEmail`, which reduces a submitted email address to its canonical form |
+
+## Design rules
+- **Dependency-free.** A helper belongs here only while it needs nothing beyond Foundation; one that grows a framework dependency belongs in the package owning that framework's concerns (e.g. `Infrastructure` for Hummingbird).
+- **Method structs.** Helpers hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
+
+## Layout
+Sources are split by visibility, then by kind, one type per file:
+```
+Sources/
+└── Public/
+    └── Methods/           NormalizeEmail
+Tests/
+├── Cases/                 the test suites, mirroring the Sources/ layout
+└── Utils/                 the suite Tag constants
+```
+
+## Testing
+Every suite carries a tag naming the kind of API it exercises — `.method`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
+
+## Requirements
+- Swift 6.3 toolchain (`swift-tools-version:6.3`).
+- macOS 15, matching the sibling `Infrastructure`, `Localization`, and `Persistence` packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- No package dependencies — Foundation only.
diff --git a/Packages/Utility/Sources/Public/Methods/NormalizeEmail.swift b/Packages/Utility/Sources/Public/Methods/NormalizeEmail.swift
new file mode 100644
index 0000000..6429a6c
--- /dev/null
+++ b/Packages/Utility/Sources/Public/Methods/NormalizeEmail.swift
@@ -0,0 +1,49 @@
+import Foundation
+
+/// A validator reducing a submitted email address to its canonical form.
+///
+/// Trims surrounding whitespace, lowercases the address (so one mailbox cannot register once per spelling), caps it at the 254 bytes an address can
+/// be, and checks its shape: something before the `@`, and a domain with a dot. Control characters are rejected separately: the shape only excludes
+/// whitespace, which would let non-whitespace controls (such as `NUL`) into the stored address.
+public struct NormalizeEmail: Sendable {
+
+    // MARK: Initializers
+
+    /// Creates an email normalization method.
+    public init() {}
+
+    // MARK: Functions
+
+    /// Validates and normalizes a submitted email address.
+    /// - Parameter email: the submitted email address, if any.
+    /// - Returns: the normalized address, or `nil` when the submission is missing or invalid.
+    public func callAsFunction(
+        _ email: String?
+    ) -> String? {
+        guard
+            let email = email?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+                .lowercased(),
+            email.utf8.count <= Constant.Length.maxEmail,
+            !email.unicodeScalars.contains(where: {
+                $0.properties.generalCategory == .control
+            }),
+            email.wholeMatch(of: /[^\s@]+@[^\s@]+\.[^\s@]+/) != nil
+        else {
+            return nil
+        }
+
+        return email
+    }
+
+}
+
+// MARK: - Constants
+
+private enum Constant {
+    /// A namespace for the length constants.
+    enum Length {
+        /// The longest an email address can be, in bytes, per RFC 5321's path limit.
+        static let maxEmail = 254
+    }
+}
diff --git a/Packages/Utility/Tests/Cases/Public/Methods/NormalizeEmailTests.swift b/Packages/Utility/Tests/Cases/Public/Methods/NormalizeEmailTests.swift
new file mode 100644
index 0000000..a26372e
--- /dev/null
+++ b/Packages/Utility/Tests/Cases/Public/Methods/NormalizeEmailTests.swift
@@ -0,0 +1,57 @@
+import Testing
+
+@testable import Utility
+
+@Suite(
+    "NormalizeEmail method",
+    .tags(.method)
+)
+struct NormalizeEmailTests {
+
+    // MARK: Properties
+
+    private let normalize = NormalizeEmail()
+
+    // MARK: Functional tests
+
+    @Test(arguments: [
+        ("fan@loudmail.nl", "fan@loudmail.nl"),
+        ("Fan@LoudMail.NL", "fan@loudmail.nl"),
+        (" fan@loudmail.nl\n", "fan@loudmail.nl"),
+        ("fan+gigs@loudmail.nl", "fan+gigs@loudmail.nl"),
+        // Exactly 254 bytes: the longest address the validator accepts.
+        (String(repeating: "a", count: 242) + "@loudmail.nl", String(repeating: "a", count: 242) + "@loudmail.nl"),
+    ])
+    func `normalizes a valid address`(
+        submitted: String,
+        expected: String
+    ) {
+        #expect(normalize(submitted) == expected)
+    }
+
+    @Test(arguments: [
+        nil,
+        "",
+        "   ",
+        "not-an-email",
+        "missing@dot",
+        "@loudmail.nl",
+        "fan@",
+        "fan@.nl",
+        "spaced out@loudmail.nl",
+        "fan@loud mail.nl",
+        // One byte over the 254-byte limit.
+        String(repeating: "a", count: 243) + "@loudmail.nl",
+        // Few enough characters, but multibyte ones put it over the byte limit.
+        String(repeating: "é", count: 130) + "@loudmail.nl",
+        // Control characters are not whitespace, so only the dedicated check catches them.
+        "fan\u{00}@loudmail.nl",
+        "fan@loudmail.nl\u{7F}",
+    ] as [String?])
+    func `rejects a missing or invalid address`(
+        submitted: String?
+    ) {
+        #expect(normalize(submitted) == nil)
+    }
+
+}
diff --git a/Packages/Utility/Tests/Utils/Extensions/Tag+Constants.swift b/Packages/Utility/Tests/Utils/Extensions/Tag+Constants.swift
new file mode 100644
index 0000000..877f053
--- /dev/null
+++ b/Packages/Utility/Tests/Utils/Extensions/Tag+Constants.swift
@@ -0,0 +1,6 @@
+import Testing
+
+extension Tag {
+    /// Tests exercising a method of the Utility package.
+    @Tag static var method: Tag
+}
diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index 71e1f67..f3539f9 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -20,6 +20,9 @@ let package = Package(
         )
     ],
     dependencies: [
+        .package(
+            path: "../../Packages/Infrastructure"
+        ),
         .package(
             path: "../../Packages/Localization"
         ),
@@ -27,7 +30,7 @@ let package = Package(
             path: "../../Packages/Persistence"
         ),
         .package(
-            path: "../../Packages/Infrastructure"
+            path: "../../Packages/Utility"
         ),
         .package(
             url: "https://github.com/elementary-swift/elementary.git",
@@ -79,9 +82,10 @@ let package = Package(
         .target(
             name: "WebsiteLibrary",
             dependencies: [
+                .byName(name: "Infrastructure"),
                 .byName(name: "Localization"),
                 .byName(name: "Persistence"),
-                .byName(name: "Infrastructure"),
+                .byName(name: "Utility"),
                 .product(
                     name: "Configuration",
                     package: "swift-configuration"
@@ -121,8 +125,8 @@ let package = Package(
         .testTarget(
             name: "WebsiteLibraryTests",
             dependencies: [
-                .byName(name: "Persistence"),
                 .byName(name: "Infrastructure"),
+                .byName(name: "Persistence"),
                 .byName(name: "WebsiteLibrary"),
                 .product(
                     name: "Elementary",
diff --git a/Services/Website/Tests/Website.xctestplan b/Services/Website/Tests/Website.xctestplan
index b82c471..a16d3f0 100644
--- a/Services/Website/Tests/Website.xctestplan
+++ b/Services/Website/Tests/Website.xctestplan
@@ -52,6 +52,13 @@
         "identifier" : "InfrastructureTests",
         "name" : "InfrastructureTests"
       }
+    },
+    {
+      "target" : {
+        "containerPath" : "container:..\/..\/Packages\/Utility",
+        "identifier" : "UtilityTests",
+        "name" : "UtilityTests"
+      }
     }
   ],
   "version" : 1
-- 
2.54.0


From 5c9fde9d41ffd4af36b2fe7a87afd91b75d82f31 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 1 Aug 2026 11:25:36 +0000
Subject: [PATCH 032/117] Social Card tweaks in the Infrastructure package.
 (#30)

This PR contains the work done to address certain tweaks in the newly-introduced _Social Card_ types in the **Infrastructure** package.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/30
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Packages/Infrastructure/README.md             |  2 +-
 .../Sources/Public/Types/SocialCard.swift     | 54 +++------------
 .../Types/SocialCard/SocialCardImage.swift    | 30 ++-------
 .../Types/SocialCard/SocialCardTag.swift      | 65 ++++++++++++++-----
 .../Cases/Public/Types/SocialCardTests.swift  | 39 ++++++-----
 5 files changed, 88 insertions(+), 102 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index c7fdf23..5028528 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -8,7 +8,7 @@ The package provides, grouped by role:
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
 | Middlewares | `SecurityHeadersMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
-| Link previews | `SocialCard`, its `Image`, and the `SocialCardTag` meta tags it derives |
+| Link previews | `SocialCard`, its `Image`, and the `Tag` meta tags it derives |
 | Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
index 101ef61..0fe4a74 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
@@ -70,52 +70,16 @@ public struct SocialCard: Sendable {
 
     /// The card's meta tags, in a stable order: the Open Graph type, site name, title, description, URL, and locale, then the image group, and
     /// the Twitter card style last. A tag whose fact the card does not carry is left out.
-    public var tags: [SocialCardTag] {
-        let tags: [SocialCardTag?] = [
-            SocialCardTag(
-                attribute: .property,
-                content: type,
-                name: .type
-            ),
-            siteName.map {
-                SocialCardTag(
-                    attribute: .property,
-                    content: $0,
-                    name: .siteName
-                )
-            },
-            SocialCardTag(
-                attribute: .property,
-                content: title,
-                name: .title
-            ),
-            summary.map {
-                SocialCardTag(
-                    attribute: .property,
-                    content: $0,
-                    name: .description
-                )
-            },
-            url.map {
-                SocialCardTag(
-                    attribute: .property,
-                    content: $0,
-                    name: .url
-                )
-            },
-            locale.map {
-                SocialCardTag(
-                    attribute: .property,
-                    content: $0,
-                    name: .locale
-                )
-            },
+    public var tags: [Tag] {
+        let tags: [Tag?] = [
+            Tag(type, name: .type),
+            siteName.map { Tag($0, name: .siteName) },
+            Tag(title, name: .title),
+            summary.map { Tag($0, name: .description) },
+            url.map { Tag($0, name: .url) },
+            locale.map { Tag($0, name: .locale) },
         ] + (image?.tags ?? []) + [
-            SocialCardTag(
-                attribute: .name,
-                content: style.rawValue,
-                name: .twitter
-            ),
+            Tag(style.rawValue, name: .twitter),
         ]
 
         return tags.compactMap { $0 }
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift
index d00398f..43f8575 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardImage.swift
@@ -39,30 +39,12 @@ extension SocialCard {
         // MARK: Computed
         
         /// The image's meta tags, in a stable order: its URL, width, and height, then its alt text when it carries one.
-        public var tags: [SocialCardTag] {
-            let tags: [SocialCardTag?] = [
-                SocialCardTag(
-                    attribute: .property,
-                    content: url,
-                    name: .image
-                ),
-                SocialCardTag(
-                    attribute: .property,
-                    content: String(width),
-                    name: .imageWidth
-                ),
-                SocialCardTag(
-                    attribute: .property,
-                    content: String(height),
-                    name: .imageHeight
-                ),
-                alt.map {
-                    SocialCardTag(
-                        attribute: .property,
-                        content: $0,
-                        name: .imageAlt
-                    )
-                },
+        public var tags: [Tag] {
+            let tags: [Tag?] = [
+                Tag(url, name: .image),
+                Tag(String(width), name: .imageWidth),
+                Tag(String(height), name: .imageHeight),
+                alt.map { Tag($0, name: .imageAlt) },
             ]
 
             return tags.compactMap { $0 }
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
index 414782b..ec446a5 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
@@ -1,24 +1,44 @@
-/// A head meta tag of a ``SocialCard``: which attribute keys it, and its name and content.
-public struct SocialCardTag: Equatable, Sendable {
+extension SocialCard {
+    /// A head meta tag of a ``SocialCard``: its name and content, keyed by the attribute its ``name`` dictates.
+    public struct Tag: Equatable, Sendable {
 
-    // MARK: Properties
+        // MARK: Properties
 
-    /// The attribute the tag is keyed by.
-    public let attribute: Attribute
+        /// The tag's value.
+        public let content: String
 
-    /// The tag's value.
-    public let content: String
+        /// The tag's name.
+        public let name: Name
+        
+        // MARK: Initializers
 
-    /// The tag's name.
-    public let name: Name
+        /// Creates a head meta tag.
+        /// - Parameters:
+        ///   - content: the tag's value.
+        ///   - name: the tag's name, dictating the attribute the tag is keyed by.
+        public init(
+            _ content: String,
+            name: Name
+        ) {
+            self.content = content
+            self.name = name
+        }
 
+        // MARK: Computed
+
+        /// The attribute the tag is keyed by, dictated by its ``name``.
+        public var attribute: Attribute {
+            name.attribute
+        }
+
+    }
 }
 
 // MARK: - Enumerations
 
-extension SocialCardTag {
-    
-    /// The meta attribute a ``SocialCardTag`` is keyed by, named by its raw value.
+extension SocialCard.Tag {
+
+    /// The meta attribute a ``SocialCard/Tag`` is keyed by, named by its raw value.
     public enum Attribute: String, Sendable {
         /// The `name` attribute, keying the Twitter tags.
         case name
@@ -26,7 +46,7 @@ extension SocialCardTag {
         case property
     }
 
-    /// The name of a ``SocialCardTag``, carried in its raw value.
+    /// The name of a ``SocialCard/Tag``, carried in its raw value.
     public enum Name: String, Sendable {
         /// The `og:description` tag, carrying the card's summary.
         case description = "og:description"
@@ -34,10 +54,10 @@ extension SocialCardTag {
         case image = "og:image"
         /// The `og:image:alt` tag, carrying the share image's text for assistive technologies.
         case imageAlt = "og:image:alt"
-        /// The `og:image:width` tag, carrying the share image's width in pixels.
-        case imageWidth = "og:image:width"
         /// The `og:image:height` tag, carrying the share image's height in pixels.
         case imageHeight = "og:image:height"
+        /// The `og:image:width` tag, carrying the share image's width in pixels.
+        case imageWidth = "og:image:width"
         /// The `og:locale` tag, carrying the locale of the card's text.
         case locale = "og:locale"
         /// The `og:site_name` tag, carrying the name of the site the card belongs to.
@@ -51,5 +71,18 @@ extension SocialCardTag {
         /// The `og:url` tag, carrying the absolute URL the card's page is served at.
         case url = "og:url"
     }
-    
+
+}
+
+// MARK: - Implementations
+
+public extension SocialCard.Tag.Name {
+
+    // MARK: Computed
+
+    /// The attribute keying a tag with this name: `property` for the Open Graph names, `name` for the Twitter ones.
+    var attribute: SocialCard.Tag.Attribute {
+        self == .twitter ? .name : .property
+    }
+
 }
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
index 1282bb9..6849302 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
@@ -27,17 +27,17 @@ struct SocialCardTests {
         )
 
         #expect(card.tags == [
-            .init(attribute: .property, content: "website", name: .type),
-            .init(attribute: .property, content: "A Site", name: .siteName),
-            .init(attribute: .property, content: "A Title", name: .title),
-            .init(attribute: .property, content: "A summary.", name: .description),
-            .init(attribute: .property, content: "https://site.example/", name: .url),
-            .init(attribute: .property, content: "en", name: .locale),
-            .init(attribute: .property, content: "https://site.example/img/card.png", name: .image),
-            .init(attribute: .property, content: "2400", name: .imageWidth),
-            .init(attribute: .property, content: "1260", name: .imageHeight),
-            .init(attribute: .property, content: "An image.", name: .imageAlt),
-            .init(attribute: .name, content: "summary_large_image", name: .twitter),
+            .init("website", name: .type),
+            .init("A Site", name: .siteName),
+            .init("A Title", name: .title),
+            .init("A summary.", name: .description),
+            .init("https://site.example/", name: .url),
+            .init("en", name: .locale),
+            .init("https://site.example/img/card.png", name: .image),
+            .init("2400", name: .imageWidth),
+            .init("1260", name: .imageHeight),
+            .init("An image.", name: .imageAlt),
+            .init("summary_large_image", name: .twitter),
         ])
     }
 
@@ -46,9 +46,9 @@ struct SocialCardTests {
         let card = SocialCard(title: "A Title")
 
         #expect(card.tags == [
-            .init(attribute: .property, content: "website", name: .type),
-            .init(attribute: .property, content: "A Title", name: .title),
-            .init(attribute: .name, content: "summary_large_image", name: .twitter),
+            .init("website", name: .type),
+            .init("A Title", name: .title),
+            .init("summary_large_image", name: .twitter),
         ])
     }
 
@@ -77,8 +77,15 @@ struct SocialCardTests {
             style: .summary
         )
 
-        #expect(card.tags.contains(.init(attribute: .property, content: "article", name: .type)))
-        #expect(card.tags.contains(.init(attribute: .name, content: "summary", name: .twitter)))
+        #expect(card.tags.contains(.init("article", name: .type)))
+        #expect(card.tags.contains(.init("summary", name: .twitter)))
+    }
+
+    @Test
+    func `keys a tag by the attribute its name dictates`() {
+        #expect(SocialCard.Tag.Name.twitter.attribute == .name)
+        #expect(SocialCard.Tag.Name.title.attribute == .property)
+        #expect(SocialCard.Tag("website", name: .type).attribute == .property)
     }
 
 }
-- 
2.54.0


From 1d1f0a9dc9ddffd9067cb984e5cd432de666cab0 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 1 Aug 2026 11:53:36 +0000
Subject: [PATCH 033/117] Utility package docker fix in the Website service
 target (#31)

This PR contains the work done to included the Utility package into the Docker deployment process in the Website service target.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/31
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Services/Website/Dockerfile | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index 9693882..0714bda 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -48,6 +48,7 @@ WORKDIR /build
 COPY ./Packages/Localization/Package.swift ./Packages/Localization/
 COPY ./Packages/Persistence/Package.swift ./Packages/Persistence/
 COPY ./Packages/Infrastructure/Package.swift ./Packages/Infrastructure/
+COPY ./Packages/Utility/Package.swift ./Packages/Utility/
 COPY ./Services/Website/Package.swift ./Services/Website/Package.resolved ./Services/Website/
 RUN swift package --package-path ./Services/Website resolve
 
@@ -56,6 +57,7 @@ RUN swift package --package-path ./Services/Website resolve
 COPY ./Packages/Infrastructure/Sources ./Packages/Infrastructure/Sources
 COPY ./Packages/Localization/Sources ./Packages/Localization/Sources
 COPY ./Packages/Persistence/Sources ./Packages/Persistence/Sources
+COPY ./Packages/Utility/Sources ./Packages/Utility/Sources
 COPY ./Services/Website/Sources ./Services/Website/Sources
 COPY ./Services/Website/Tests ./Services/Website/Tests
 
-- 
2.54.0


From b680ae0689b337929087c49afd4fc057795ba161 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 1 Aug 2026 17:21:16 +0000
Subject: [PATCH 034/117] Structured Data support for the Page protocol in the
 Infrastructure package (#32)

This PR contains the work done to introduce a `StructuredData` type that pages use to describe themselves to search engines as schema.org JSON-LD, and wires it into the Page protocol so the payload renders automatically in the document head.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/32
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
---
 Packages/Infrastructure/README.md             |   8 +-
 .../Extensions/String+Separators.swift        |   5 +
 .../Sources/Public/Protocols/Page.swift       |  28 ++-
 .../Sources/Public/Types/StructuredData.swift | 106 ++++++++++++
 .../StructuredData/StructuredDataNode.swift   |  92 ++++++++++
 .../StructuredDataProperty.swift              |  82 +++++++++
 .../StructuredData/StructuredDataValue.swift  |  67 ++++++++
 .../Cases/Public/Protocols/PageTests.swift    |  25 +++
 .../Public/Types/StructuredDataTests.swift    | 159 ++++++++++++++++++
 .../Tests/Utils/Pages/StubPage.swift          |   7 +
 10 files changed, 572 insertions(+), 7 deletions(-)
 create mode 100644 Packages/Infrastructure/Sources/Internal/Extensions/String+Separators.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataNode.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataValue.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 5028528..b724c15 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -9,14 +9,15 @@ The package provides, grouped by role:
 | Middlewares | `SecurityHeadersMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
 | Link previews | `SocialCard`, its `Image`, and the `Tag` meta tags it derives |
+| Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, and the open `Name` and `Kind` vocabularies |
 | Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
 
 ## Design rules
 The package holds only what every service can reuse; anything a service owns is injected, never referenced:
-- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors — as are the `summary`, `canonicalURL`, and `socialCard` values its other head tags render, each omitted unless the page provides it. A `SocialCard` takes its URLs fully formed and absolute; composing them from an origin and a versioned asset path stays with the page providing the card.
-- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern to follow.
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors — as are the `summary`, `canonicalURL`, `socialCard`, and `structuredData` values its other head tags render, each omitted unless the page provides it. A `SocialCard` and a `StructuredData` node take their URLs fully formed and absolute; composing them from an origin and a versioned asset path stays with the page providing them.
+- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern to follow. The open schema.org vocabularies extend the same way: the package declares only the `Property.Name` and `Node.Kind` constants every service shares, and a service adds the ones its own node shapes need.
 - **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
 ## Layout
@@ -31,8 +32,9 @@ Sources/
 │   ├── Middlewares/       the five HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
 │   ├── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
-│   └── Types/             SocialCard, with its image and tag types in SocialCard/
+│   └── Types/             SocialCard and StructuredData, with their nested types in SocialCard/ and StructuredData/
 └── Internal/
+    ├── Extensions/        implementation details (the String separators)
     └── Types/             implementation details (FNV1aHash)
 Tests/
 ├── Cases/                 the test suites, mirroring the Sources/ layout
diff --git a/Packages/Infrastructure/Sources/Internal/Extensions/String+Separators.swift b/Packages/Infrastructure/Sources/Internal/Extensions/String+Separators.swift
new file mode 100644
index 0000000..758fc4d
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Internal/Extensions/String+Separators.swift
@@ -0,0 +1,5 @@
+extension String {
+    enum Separator {
+        static let comma = ","
+    }
+}
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
index 7ab842e..30c25e1 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
@@ -4,8 +4,8 @@ import Foundation
 /// A page of a website: an HTML document with the shared scaffolding assembled around the page's content.
 ///
 /// A conforming page supplies its locale, its title, the stylesheets and scripts it needs, its head metadata, and its content; the protocol assembles the
-/// rest of the document around them: the viewport declaration, the summary, canonical, and social card tags, and the metadata followed by the
-/// stylesheet links in the head, and the content followed by the script tags in the body.
+/// rest of the document around them: the viewport declaration, the summary, canonical, and social card tags, the structured data script, and the
+/// metadata followed by the stylesheet links in the head, and the content followed by the script tags in the body.
 public protocol Page: HTMLDocument, Sendable {
 
     // MARK: Associated types
@@ -42,6 +42,9 @@ public protocol Page: HTMLDocument, Sendable {
     /// to omit them.
     var socialCard: SocialCard? { get }
 
+    /// The page's structured data, rendered as a JSON-LD script in the document head, or `nil` (the default) to omit it.
+    var structuredData: StructuredData? { get }
+
     /// The stylesheets linked in the document head, in order.
     var stylesheets: [any Asset] { get }
 
@@ -74,11 +77,14 @@ public extension Page {
         }
     }
     
-    /// The viewport declaration, the ``summary``, ``canonicalURL``, and ``socialCard`` tags (when provided), and the ``metadata``
-    /// followed by the ``stylesheets`` links, placed in the document head.
+    /// The viewport declaration, the ``summary``, ``canonicalURL``, and ``socialCard`` tags and the ``structuredData`` script
+    /// (when provided), and the ``metadata`` followed by the ``stylesheets`` links, placed in the document head.
     ///
     /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already emits `<meta charset="UTF-8">` before this markup,
     /// and HTML5 allows only one.
+    ///
+    /// The structured data is an inert data block — browsers never execute it, so a site's `Content-Security-Policy` does not apply to it —
+    /// that search engines read for the organization's name, logo, and profiles.
     @HTMLBuilder
     var head: some HTML {
         meta(
@@ -112,6 +118,15 @@ public extension Page {
             }
         }
 
+        if let structuredData {
+            script(.custom(
+                name: "type",
+                value: "application/ld+json"
+            )) {
+                HTMLRaw(structuredData.payload)
+            }
+        }
+
         metadata
         
         for file in stylesheets {
@@ -130,6 +145,11 @@ public extension Page {
         nil
     }
 
+    /// The structured data is omitted unless the page provides one.
+    var structuredData: StructuredData? {
+        nil
+    }
+
     /// The summary is omitted unless the page provides one.
     var summary: String? {
         nil
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
new file mode 100644
index 0000000..5e5addb
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
@@ -0,0 +1,106 @@
+/// The structured data of a page, rendered as a JSON-LD script in the document head.
+///
+/// The data is a graph of schema.org ``Node`` values — each a ``Node/type``, an optional ``Node/id``, and ``Property`` values in render
+/// order — and derives the ``payload`` embedding them for the search engines that read it. A page either composes the nodes of its own
+/// shape directly, or uses ``init(name:url:logo:profiles:)`` for the site-wide pair every page shares.
+///
+/// Search engines require absolute URLs, so a node takes its URLs fully formed; composing them from an origin and a versioned asset path stays with the
+/// page providing the data.
+public struct StructuredData: Equatable, Sendable {
+
+    // MARK: Properties
+
+    /// The schema.org nodes of the data's graph, in the order they render.
+    public let nodes: [Node]
+
+    // MARK: Initializers
+
+    /// Creates structured data from the nodes of its graph.
+    /// - Parameter nodes: the schema.org nodes of the data's graph, in the order they render.
+    public init(
+        nodes: [Node]
+    ) {
+        self.nodes = nodes
+    }
+
+    // MARK: Computed
+
+    /// The minified JSON-LD payload: the schema.org `@context`, and the ``nodes`` in a `@graph`.
+    ///
+    /// The values are rendered as JSON string literals with `<` escaped as well, so a value can never close the `script` tag embedding
+    /// the payload.
+    public var payload: String {
+        #"{"@context":"https://schema.org","@graph":[\#(fragments)]}"#
+    }
+
+}
+
+// MARK: - Initializers
+
+public extension StructuredData {
+
+    /// Creates the site-wide structured data: an `Organization` node carrying the name, URL, logo, and profiles, and a `WebSite` node
+    /// carrying the name and URL and referencing the organization as its `publisher`. The nodes are linked through an `@id` derived
+    /// from the URL, so search engines read the site as published by the organization rather than as two unrelated assertions.
+    /// A property whose fact the data does not carry is left out.
+    /// - Parameters:
+    ///   - name: the name of the organization and the site.
+    ///   - url: the absolute URL the site is served at.
+    ///   - logo: the absolute URL of the organization's logo, or `nil` (the default) to omit its property.
+    ///   - profiles: the absolute URLs of the organization's public profiles, or empty (the default) to omit their property.
+    init(
+        name: String,
+        url: String,
+        logo: String? = nil,
+        profiles: [String] = []
+    ) {
+        let id = url + "#organization"
+
+        var organization: [Property] = [
+            .init(.name, value: .string(name)),
+            .init(.url, value: .string(url)),
+        ]
+
+        if let logo {
+            organization.append(.init(.logo, value:.string(logo)))
+        }
+
+        if !profiles.isEmpty {
+            organization.append(.init(
+                .sameAs,
+                value: .array(profiles.map(Value.string))
+            ))
+        }
+
+        self.init(nodes: [
+            .init(
+                type: .organization,
+                id: id,
+                properties: organization
+            ),
+            .init(
+                type: .website,
+                properties: [
+                    .init(.name, value: .string(name)),
+                    .init(.url, value: .string(url)),
+                    .init(.publisher, value: .reference(id)),
+                ]
+            ),
+        ])
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension StructuredData {
+
+    // MARK: Computed
+
+    var fragments: String {
+        nodes
+            .map(\.fragment)
+            .joined(separator: .Separator.comma)
+    }
+
+}
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataNode.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataNode.swift
new file mode 100644
index 0000000..6ba19af
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataNode.swift
@@ -0,0 +1,92 @@
+extension StructuredData {
+    /// A schema.org node of a ``StructuredData`` graph: its type, its optional identifier, and its properties.
+    public struct Node: Equatable, Sendable {
+
+        // MARK: Properties
+
+        /// The node's identifier, rendered as its `@id` property, or `nil` to omit it.
+        ///
+        /// Another node references this node through ``Value/reference(_:)`` with the same identifier.
+        public let id: String?
+
+        /// The node's properties, in the order they render after the type and identifier.
+        public let properties: [Property]
+
+        /// The node's schema.org type (e.g. ``Kind/organization``), rendered as its `@type` property.
+        public let type: Kind
+
+        // MARK: Initializers
+
+        /// Creates a node.
+        /// - Parameters:
+        ///   - type: the node's schema.org type (e.g. ``Kind/organization``).
+        ///   - id: the node's identifier, or `nil` (the default) to omit it.
+        ///   - properties: the node's properties, in the order they render.
+        public init(
+            type: Kind,
+            id: String? = nil,
+            properties: [Property]
+        ) {
+            self.id = id
+            self.properties = properties
+            self.type = type
+        }
+
+        // MARK: Computed
+
+        /// The node's minified JSON object: the `@type`, the `@id` (when the node carries one), and the ``properties`` in order.
+        var fragment: String {
+            var members = [#""@type":\#(Value.literal(type.rawValue))"#]
+
+            if let id {
+                members.append(#""@id":\#(Value.literal(id))"#)
+            }
+
+            members += properties.map(\.fragment)
+
+            return "{\(members.joined(separator: .Separator.comma))}"
+        }
+
+    }
+}
+
+// MARK: - Structures
+
+extension StructuredData.Node {
+    /// The schema.org type of a ``StructuredData/Node``.
+    ///
+    /// Schema.org's vocabulary is open, so the kind is a typed string rather than a closed enumeration: the kinds every service shares
+    /// come as constants, a service declares the kinds its own node shapes need in an extension, and a one-off kind can be spelled as a
+    /// string literal.
+    public struct Kind: Equatable, ExpressibleByStringLiteral, Sendable {
+
+        // MARK: Properties
+
+        /// The type as it renders in the payload.
+        public let rawValue: String
+
+        // MARK: Initializers
+
+        /// Creates a kind.
+        /// - Parameter rawValue: the type as it renders in the payload.
+        public init(_ rawValue: String) {
+            self.rawValue = rawValue
+        }
+
+        /// Creates a kind from a string literal.
+        /// - Parameter value: the type as it renders in the payload.
+        public init(stringLiteral value: String) {
+            self.init(value)
+        }
+
+    }
+}
+
+// MARK: - Constants
+
+public extension StructuredData.Node.Kind {
+    /// An organization, e.g. the one publishing a website.
+    static let organization: Self = "Organization"
+    /// A website.
+    static let website: Self = "WebSite"
+}
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
new file mode 100644
index 0000000..fb52cb0
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
@@ -0,0 +1,82 @@
+extension StructuredData {
+    /// A named property of a ``Node``, in the position it renders.
+    public struct Property: Equatable, Sendable {
+
+        // MARK: Properties
+
+        /// The property's schema.org name (e.g. `sameAs`).
+        public let name: Name
+
+        /// The property's value.
+        public let value: Value
+
+        // MARK: Initializers
+
+        /// Creates a property.
+        /// - Parameters:
+        ///   - name: the property's schema.org name (e.g. `sameAs`).
+        ///   - value: the property's value.
+        public init(
+            _ name: Name,
+            value: Value
+        ) {
+            self.name = name
+            self.value = value
+        }
+
+        // MARK: Computed
+
+        /// The property's minified JSON member: its name and its rendered value.
+        var fragment: String {
+            #"\#(Value.literal(name.rawValue)):\#(value.fragment)"#
+        }
+
+    }
+}
+
+// MARK: - Structures
+
+extension StructuredData.Property {
+    /// The schema.org name of a ``StructuredData/Property``.
+    ///
+    /// Schema.org's vocabulary is open, so the name is a typed string rather than a closed enumeration: the names every service shares
+    /// come as constants, a service declares the names its own node shapes need in an extension, and a one-off name can be spelled as a
+    /// string literal.
+    public struct Name: Equatable, ExpressibleByStringLiteral, Sendable {
+
+        // MARK: Properties
+
+        /// The name as it renders in the payload.
+        public let rawValue: String
+
+        // MARK: Initializers
+
+        /// Creates a name.
+        /// - Parameter rawValue: the name as it renders in the payload.
+        public init(_ rawValue: String) {
+            self.rawValue = rawValue
+        }
+
+        /// Creates a name from a string literal.
+        /// - Parameter value: the name as it renders in the payload.
+        public init(stringLiteral value: String) {
+            self.init(value)
+        }
+
+    }
+}
+
+// MARK: - Constants
+
+public extension StructuredData.Property.Name {
+    /// The absolute URL of an organization's logo.
+    static let logo: Self = "logo"
+    /// The name of the thing a node describes.
+    static let name: Self = "name"
+    /// The organization publishing a website.
+    static let publisher: Self = "publisher"
+    /// The absolute URLs of the profiles that also identify the thing a node describes.
+    static let sameAs: Self = "sameAs"
+    /// The absolute URL of the thing a node describes.
+    static let url: Self = "url"
+}
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataValue.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataValue.swift
new file mode 100644
index 0000000..4ee5324
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataValue.swift
@@ -0,0 +1,67 @@
+extension StructuredData {
+    /// A value of a ``Property``: a string, a list, a nested node, or a reference to another node.
+    ///
+    /// Every string a value renders is escaped as a JSON literal with `<` escaped as well, so a value can never close the `script`
+    /// tag embedding the payload it renders into.
+    public indirect enum Value: Equatable, Sendable {
+        /// A list of values.
+        case array([Value])
+        /// A nested node, e.g. the place a schema.org event is located at.
+        case node(Node)
+        /// A reference to the ``Node/id`` of another node in the graph, rendered as an `@id` object.
+        case reference(String)
+        /// A string value.
+        case string(String)
+    }
+}
+
+// MARK: - Extensions
+
+extension StructuredData.Value {
+
+    // MARK: Computed
+
+    /// The value's minified JSON fragment.
+    var fragment: String {
+        switch self {
+        case .array(let values):
+            "[\(values.map(\.fragment).joined(separator: .Separator.comma))]"
+        case .node(let node):
+            node.fragment
+        case .reference(let id):
+            #"{"@id":\#(Self.literal(id))}"#
+        case .string(let string):
+            Self.literal(string)
+        }
+    }
+
+    // MARK: Methods
+
+    /// Renders a string as a JSON string literal, escaping `<` as well since the payload is embedded in a `script` tag the string
+    /// could otherwise close.
+    /// - Parameter value: the string to render.
+    /// - Returns: the quoted and escaped literal.
+    static func literal(_ value: String) -> String {
+        var literal = "\""
+
+        for scalar in value.unicodeScalars {
+            switch scalar {
+            case "\"":
+                literal += #"\""#
+            case "\\":
+                literal += #"\\"#
+            case "<":
+                literal += #"\u003c"#
+            case let scalar where scalar.value < 0x20:
+                let hex = String(scalar.value, radix: 16)
+
+                literal += #"\u"# + String(repeating: "0", count: 4 - hex.count) + hex
+            default:
+                literal.unicodeScalars.append(scalar)
+            }
+        }
+
+        return literal + "\""
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
index b1a10af..e0fc405 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
@@ -97,6 +97,31 @@ struct PageTests {
         #expect(html.contains(#"<meta name="twitter:card" content="summary_large_image">"#))
     }
 
+    @Test
+    func `omits the structured data script by default`() {
+        let html = StubPage().render()
+
+        #expect(!html.contains("application/ld+json"))
+    }
+
+    @Test
+    func `renders the structured data script when provided`() {
+        let html = StubPage(structuredData: .init(
+            name: "Stub Site",
+            url: "https://stub.example/",
+            logo: "https://stub.example/logo.png",
+            profiles: ["https://social.example/stub"]
+        )).render()
+
+        #expect(html.contains(
+            #"<script type="application/ld+json">"# +
+            #"{"@context":"https://schema.org","@graph":["# +
+            #"{"@type":"Organization","@id":"https://stub.example/#organization","name":"Stub Site","url":"https://stub.example/","logo":"https://stub.example/logo.png","sameAs":["https://social.example/stub"]},"# +
+            #"{"@type":"WebSite","name":"Stub Site","url":"https://stub.example/","publisher":{"@id":"https://stub.example/#organization"}}]}"# +
+            #"</script>"#
+        ))
+    }
+
     @Test
     func `appends the version token to the asset URLs`() {
         let html = StubPage(assetVersion: "0123456789abcdef").render()
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
new file mode 100644
index 0000000..f0bfcb3
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
@@ -0,0 +1,159 @@
+import Foundation
+import Testing
+
+@testable import Infrastructure
+
+@Suite(
+    "StructuredData type",
+    .tags(.type)
+)
+struct StructuredDataTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `derives the full payload from complete data`() {
+        let data = StructuredData(
+            name: "A Site",
+            url: "https://site.example/",
+            logo: "https://site.example/logo.png",
+            profiles: [
+                "https://social.example/a-site",
+                "https://videos.example/a-site",
+            ]
+        )
+
+        #expect(data.payload == #"{"@context":"https://schema.org","@graph":["# +
+            #"{"@type":"Organization","@id":"https://site.example/#organization","name":"A Site","url":"https://site.example/","logo":"https://site.example/logo.png","# +
+            #""sameAs":["https://social.example/a-site","https://videos.example/a-site"]},"# +
+            #"{"@type":"WebSite","name":"A Site","url":"https://site.example/","publisher":{"@id":"https://site.example/#organization"}}]}"#
+        )
+    }
+
+    @Test
+    func `omits the properties of the facts minimal data does not carry`() {
+        let data = StructuredData(
+            name: "A Site",
+            url: "https://site.example/"
+        )
+
+        #expect(data.payload == #"{"@context":"https://schema.org","@graph":["# +
+            #"{"@type":"Organization","@id":"https://site.example/#organization","name":"A Site","url":"https://site.example/"},"# +
+            #"{"@type":"WebSite","name":"A Site","url":"https://site.example/","publisher":{"@id":"https://site.example/#organization"}}]}"#
+        )
+    }
+
+    @Test
+    func `renders a composed node graph`() {
+        let data = StructuredData(nodes: [
+            .init(
+                type: "MusicEvent",
+                properties: [
+                    .init(.name, value: .string("A Gig")),
+                    .init("location", value: .node(.init(
+                        type: "Place",
+                        properties: [
+                            .init(.name, value: .string("A Venue")),
+                        ]
+                    ))),
+                    .init("organizer", value: .reference("https://site.example/#organization")),
+                ]
+            ),
+        ])
+
+        #expect(data.payload == #"{"@context":"https://schema.org","@graph":["# +
+            #"{"@type":"MusicEvent","name":"A Gig","location":{"@type":"Place","name":"A Venue"},"# +
+            #""organizer":{"@id":"https://site.example/#organization"}}]}"#
+        )
+    }
+
+    @Test
+    func `escapes the values it embeds in the payload`() {
+        let data = StructuredData(
+            name: #"A "Quoted" \ Site"#,
+            url: "https://site.example/</script>"
+        )
+
+        #expect(data.payload.contains(#""name":"A \"Quoted\" \\ Site""#))
+        // The `<` is escaped so a value can never close the script tag embedding the payload.
+        #expect(!data.payload.contains("</script>"))
+        #expect(data.payload.contains("\\" + "u003c/script>"))
+    }
+
+    @Test
+    func `renders a node fragment with its identifier`() {
+        let node = StructuredData.Node(
+            type: "Organization",
+            id: "https://site.example/#organization",
+            properties: [
+                .init(.name, value: .string("A Site")),
+            ]
+        )
+
+        #expect(node.fragment == #"{"@type":"Organization","@id":"https://site.example/#organization","name":"A Site"}"#)
+    }
+
+    @Test
+    func `renders a node fragment without an identifier or properties`() {
+        let node = StructuredData.Node(
+            type: "Organization",
+            properties: []
+        )
+
+        #expect(node.fragment == #"{"@type":"Organization"}"#)
+    }
+
+    @Test
+    func `renders the common names and kinds by their schema.org spelling`() {
+        #expect(StructuredData.Property.Name.logo.rawValue == "logo")
+        #expect(StructuredData.Property.Name.name.rawValue == "name")
+        #expect(StructuredData.Property.Name.publisher.rawValue == "publisher")
+        #expect(StructuredData.Property.Name.sameAs.rawValue == "sameAs")
+        #expect(StructuredData.Property.Name.url.rawValue == "url")
+        #expect(StructuredData.Node.Kind.organization.rawValue == "Organization")
+        #expect(StructuredData.Node.Kind.website.rawValue == "WebSite")
+    }
+
+    @Test
+    func `renders the fragment of every value case`() {
+        #expect(StructuredData.Value.string("A Value").fragment == #""A Value""#)
+        #expect(StructuredData.Value.array([.string("A"), .string("B")]).fragment == #"["A","B"]"#)
+        #expect(StructuredData.Value.reference("https://site.example/#organization").fragment == #"{"@id":"https://site.example/#organization"}"#)
+        #expect(StructuredData.Value.node(.init(type: "Place", properties: [])).fragment == #"{"@type":"Place"}"#)
+    }
+
+    @Test
+    func `renders a string as a quoted literal`() {
+        #expect(StructuredData.Value.literal("A Value") == #""A Value""#)
+        #expect(StructuredData.Value.literal("") == "\"\"")
+    }
+
+    @Test
+    func `pads the escape of a control character to four digits`() {
+        #expect(StructuredData.Value.literal("\u{0}") == "\"" + "\\" + "u0000" + "\"")
+        #expect(StructuredData.Value.literal("\u{1f}") == "\"" + "\\" + "u001f" + "\"")
+        #expect(StructuredData.Value.literal("\u{a}") == "\"" + "\\" + "u000a" + "\"")
+        // The first scalar past the control range passes through untouched.
+        #expect(StructuredData.Value.literal(" ") == #"" ""#)
+    }
+
+    @Test
+    func `derives a payload that parses back to the facts it carries`() throws {
+        let name = "A \"Site\"\nwith \\ every <hazard>"
+        let data = StructuredData(
+            name: name,
+            url: "https://site.example/</script>",
+            logo: "https://site.example/logo.png",
+            profiles: ["https://social.example/a-site"]
+        )
+
+        let object = try JSONSerialization.jsonObject(with: Data(data.payload.utf8))
+        let graph = try #require((object as? [String: Any])?["@graph"] as? [[String: Any]])
+
+        #expect(graph.count == 2)
+        #expect(graph[0]["name"] as? String == name)
+        #expect(graph[0]["sameAs"] as? [String] == ["https://social.example/a-site"])
+        #expect(graph[1]["url"] as? String == "https://site.example/</script>")
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift b/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
index 68c8ac0..ffc755e 100644
--- a/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
+++ b/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
@@ -19,6 +19,9 @@ struct StubPage: Page {
     /// The card rendered as link-preview tags in the document head, or `nil` to omit them.
     let socialCard: SocialCard?
 
+    /// The structured data rendered as a JSON-LD script in the document head, or `nil` to omit it.
+    let structuredData: StructuredData?
+
     /// The summary rendered in the document head, or `nil` to omit it.
     let summary: String?
 
@@ -33,6 +36,8 @@ struct StubPage: Page {
     ///     to omit it.
     ///   - socialCard: the card rendered as link-preview tags in the document head, or `nil`
     ///     (the default) to omit them.
+    ///   - structuredData: the structured data rendered as a JSON-LD script in the document
+    ///     head, or `nil` (the default) to omit it.
     ///   - summary: the summary rendered in the document head, or `nil` (the default)
     ///     to omit it.
     init(
@@ -40,12 +45,14 @@ struct StubPage: Page {
         assetVersion: String? = nil,
         canonicalURL: String? = nil,
         socialCard: SocialCard? = nil,
+        structuredData: StructuredData? = nil,
         summary: String? = nil
     ) {
         self.assetVersion = assetVersion
         self.canonicalURL = canonicalURL
         self.locale = locale
         self.socialCard = socialCard
+        self.structuredData = structuredData
         self.summary = summary
     }
 
-- 
2.54.0


From 2c571233bc22254ee0b364af9ca0c55446a5c090 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 1 Aug 2026 23:06:22 +0200
Subject: [PATCH 035/117] Renamed the Error page in the Website library target
 as NotFound.

---
 .../Library/Catalogs/Localizable.xcstrings    | 66 +++++++++----------
 .../{ErrorPage.swift => NotFoundPage.swift}   | 14 ++--
 .../NotFoundMiddleware+Defaults.swift         |  2 +-
 ...ageTests.swift => NotFoundPageTests.swift} |  6 +-
 4 files changed, 44 insertions(+), 44 deletions(-)
 rename Services/Website/Sources/Library/Internal/Pages/{ErrorPage.swift => NotFoundPage.swift} (80%)
 rename Services/Website/Tests/Library/Cases/Internal/Pages/{ErrorPageTests.swift => NotFoundPageTests.swift} (89%)

diff --git a/Services/Website/Sources/Library/Catalogs/Localizable.xcstrings b/Services/Website/Sources/Library/Catalogs/Localizable.xcstrings
index 9a6ccec..729eda6 100644
--- a/Services/Website/Sources/Library/Catalogs/Localizable.xcstrings
+++ b/Services/Website/Sources/Library/Catalogs/Localizable.xcstrings
@@ -1,39 +1,6 @@
 {
   "sourceLanguage" : "en",
   "strings" : {
-    "error.heading" : {
-      "comment" : "The not-found page's main heading.",
-      "localizations" : {
-        "en" : {
-          "stringUnit" : {
-            "state" : "translated",
-            "value" : "Page Not Found"
-          }
-        }
-      }
-    },
-    "error.message" : {
-      "comment" : "The not-found page's body text.",
-      "localizations" : {
-        "en" : {
-          "stringUnit" : {
-            "state" : "translated",
-            "value" : "Sorry, but the page you were trying to view does not exist."
-          }
-        }
-      }
-    },
-    "error.title" : {
-      "comment" : "The not-found page's document title.",
-      "localizations" : {
-        "en" : {
-          "stringUnit" : {
-            "state" : "translated",
-            "value" : "Page Not Found"
-          }
-        }
-      }
-    },
     "index.greeting" : {
       "comment" : "The landing page's greeting paragraph.",
       "localizations" : {
@@ -55,6 +22,39 @@
           }
         }
       }
+    },
+    "notFound.heading" : {
+      "comment" : "The not-found page's main heading.",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Page Not Found"
+          }
+        }
+      }
+    },
+    "notFound.message" : {
+      "comment" : "The not-found page's body text.",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Sorry, but the page you were trying to view does not exist."
+          }
+        }
+      }
+    },
+    "notFound.title" : {
+      "comment" : "The not-found page's document title.",
+      "localizations" : {
+        "en" : {
+          "stringUnit" : {
+            "state" : "translated",
+            "value" : "Page Not Found"
+          }
+        }
+      }
     }
   },
   "version" : "1.0"
diff --git a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift b/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
similarity index 80%
rename from Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
rename to Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
index 2b19f7b..f49730c 100644
--- a/Services/Website/Sources/Library/Internal/Pages/ErrorPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
@@ -4,7 +4,7 @@ import Infrastructure
 import Localization
 
 /// The HTML page rendered for a not-found response, with its text localized to a given locale.
-struct ErrorPage {
+struct NotFoundPage {
 
     // MARK: Properties
 
@@ -36,29 +36,29 @@ struct ErrorPage {
 
 // MARK: Page
 
-extension ErrorPage: Page {
+extension NotFoundPage: Page {
 
     // MARK: Properties
 
     var content: some HTML {
         h1 {
-            localize("error.heading", locale: locale)
+            localize("notFound.heading", locale: locale)
         }
         p {
-            localize("error.message", locale: locale)
+            localize("notFound.message", locale: locale)
         }
     }
 
     var scripts: [any Asset] {
-        [StaticFile.error, StaticFile.shared]
+        [StaticFile.notFound, StaticFile.shared]
     }
 
     var stylesheets: [any Asset] {
-        [StaticFile.shared, StaticFile.error]
+        [StaticFile.shared, StaticFile.notFound]
     }
 
     var title: String {
-        localize("error.title", locale: locale)
+        localize("notFound.title", locale: locale)
     }
 
 }
diff --git a/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift b/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
index 545dd1f..5c850f9 100644
--- a/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
@@ -11,7 +11,7 @@ public extension NotFoundMiddleware {
         assetVersion: String? = nil
     ) {
         self.init(bundle: .module) {
-            ErrorPage(
+            NotFoundPage(
                 locale: $0,
                 assetVersion: assetVersion
             )
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/NotFoundPageTests.swift
similarity index 89%
rename from Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
rename to Services/Website/Tests/Library/Cases/Internal/Pages/NotFoundPageTests.swift
index 4a2771c..d29b2d0 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/ErrorPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/NotFoundPageTests.swift
@@ -5,16 +5,16 @@ import Testing
 @testable import WebsiteLibrary
 
 @Suite(
-    "ErrorPage page",
+    "NotFoundPage page",
     .tags(.page)
 )
-struct ErrorPageTests {
+struct NotFoundPageTests {
     
     // MARK: Functional tests
 
     @Test
     func `renders its markup`() {
-        let html = ErrorPage(
+        let html = NotFoundPage(
             locale: .init(identifier: "en")
         ).render()
 
-- 
2.54.0


From a056f7f69ac9044dd5b66c54d16b6f2d55dd8f9f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 1 Aug 2026 23:07:04 +0200
Subject: [PATCH 036/117] Renamed the "error" static assets at the Resources
 folder in the Website service target as "not-found".

---
 .../Resources/Static/css/{error.css => not-found.css}  |  0
 .../Resources/Static/js/{error.js => not-found.js}     |  0
 .../Library/Internal/Enumerations/StaticFile.swift     | 10 +++++-----
 Services/Website/Tests/App/AppTests.swift              |  2 +-
 .../Cases/Internal/Enumerations/StaticFileTests.swift  |  4 ++--
 .../Cases/Internal/Pages/NotFoundPageTests.swift       |  4 ++--
 6 files changed, 10 insertions(+), 10 deletions(-)
 rename Services/Website/Resources/Static/css/{error.css => not-found.css} (100%)
 rename Services/Website/Resources/Static/js/{error.js => not-found.js} (100%)

diff --git a/Services/Website/Resources/Static/css/error.css b/Services/Website/Resources/Static/css/not-found.css
similarity index 100%
rename from Services/Website/Resources/Static/css/error.css
rename to Services/Website/Resources/Static/css/not-found.css
diff --git a/Services/Website/Resources/Static/js/error.js b/Services/Website/Resources/Static/js/not-found.js
similarity index 100%
rename from Services/Website/Resources/Static/js/error.js
rename to Services/Website/Resources/Static/js/not-found.js
diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
index 3196f8f..945ca74 100644
--- a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
@@ -7,8 +7,6 @@ import Infrastructure
 enum StaticFile: Asset, CaseIterable {
     /// The `apple-touch-icon.png` icon.
     case appleTouchIcon
-    /// The `css/error.css` stylesheet and `js/error.js` script for the not-found page.
-    case error
     /// The `favicon.ico` icon.
     case favicon
     /// The `icon.svg` icon.
@@ -19,6 +17,8 @@ enum StaticFile: Asset, CaseIterable {
     case icon512
     /// The `css/index.css` stylesheet and `js/index.js` script for the landing page.
     case index
+    /// The `css/not-found.css` stylesheet and `js/not-found.js` script for the not-found page.
+    case notFound
     /// The `robots.txt` crawler directives.
     case robots
     /// The `css/shared.css` stylesheet and `js/shared.js` script shared across pages.
@@ -41,8 +41,8 @@ extension StaticFile {
         case .appleTouchIcon,
              .icon192,
              .icon512: [.png]
-        case .error,
-             .index,
+        case .index,
+             .notFound,
              .shared: [.css, .js]
         case .favicon: [.ico]
         case .icon: [.svg]
@@ -56,12 +56,12 @@ extension StaticFile {
     var fileName: String {
         switch self {
         case .appleTouchIcon: "apple-touch-icon"
-        case .error: "error"
         case .favicon: "favicon"
         case .icon: "icon"
         case .icon192: "icon-192"
         case .icon512: "icon-512"
         case .index: "index"
+        case .notFound: "not-found"
         case .robots: "robots"
         case .shared: "shared"
         case .site: "site"
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 70fce3c..846ccf2 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -268,7 +268,7 @@ struct AppTests {
             ) { response in
                 let body = String(buffer: response.body)
 
-                #expect(body.contains("/css/error.css?v="))
+                #expect(body.contains("/css/not-found.css?v="))
                 #expect(body.contains("/js/shared.js?v="))
             }
         }
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
index 0c141e5..b675544 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
@@ -54,12 +54,12 @@ private extension StaticFileTests {
 
     static let fileExtensions: [[AssetExtension]] = [
         [.png],
-        [.css, .js],
         [.ico],
         [.svg],
         [.png],
         [.png],
         [.css, .js],
+        [.css, .js],
         [.txt],
         [.css, .js],
         [.webmanifest],
@@ -67,12 +67,12 @@ private extension StaticFileTests {
     ]
     static let fileNames: [String] = [
         "apple-touch-icon",
-        "error",
         "favicon",
         "icon",
         "icon-192",
         "icon-512",
         "index",
+        "not-found",
         "robots",
         "shared",
         "site",
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/NotFoundPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/NotFoundPageTests.swift
index d29b2d0..21786cd 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/NotFoundPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/NotFoundPageTests.swift
@@ -23,8 +23,8 @@ struct NotFoundPageTests {
         #expect(html.contains("Page Not Found"))
         #expect(html.contains("Sorry, but the page you were trying to view does not exist."))
         #expect(html.contains("/css/shared.css"))
-        #expect(html.contains("/css/error.css"))
-        #expect(html.contains("/js/error.js"))
+        #expect(html.contains("/css/not-found.css"))
+        #expect(html.contains("/js/not-found.js"))
         #expect(html.contains("/js/shared.js"))
     }
 
-- 
2.54.0


From 64d2d5943af7ca6a603b7fd23af55c737a118147 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 2 Aug 2026 00:58:11 +0200
Subject: [PATCH 037/117] Updated the documentation of the README file in the
 Website service target.

---
 Services/Website/README.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Services/Website/README.md b/Services/Website/README.md
index ec2eaaa..f2325ac 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -7,7 +7,7 @@ The service:
 - Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
 - Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
 - Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`; the production image ships minified copies (see [Static assets](#static-assets)).
-- Returns a custom HTML 404 page, localized like the landing page, for any request that matches neither a route nor a static file.
+- Returns a custom not-found (404) HTML page, localized like the landing page, for any request that matches neither a route nor a static file.
 - Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
 - Stamps a hardened set of security headers on every response.
 - Persists data through [Fluent](https://github.com/hummingbird-project/hummingbird-fluent), against either an ephemeral in-memory SQLite database (the default — no external infrastructure) or a MySQL/MariaDB server, selected by a single configuration key.
@@ -22,12 +22,13 @@ Two SwiftPM targets:
 | Target | Kind | Path | Role |
 | --- | --- | --- | --- |
 | `Website` | executable | `Sources/App` | Entry point: reads configuration, builds the persistence service, and either serves the website or runs the migrate-and-exit mode. |
-| `WebsiteLibrary` | library | `Sources/Library` | Controllers, middlewares, pages, cached responses, and configuration helpers. |
+| `WebsiteLibrary` | library | `Sources/Library` | Controllers, the pages, the `StaticFile` asset catalog, the request context, and the `*+Defaults` extensions and configuration-key constants that supply the site's specifics to `Infrastructure`. |
 
-The `Website` executable depends on three local packages:
+The `Website` executable depends on four local packages:
 - `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteLibrary`).
 - `Infrastructure` (`Packages/Infrastructure`) — the shared Hummingbird toolkit: the `RouterController` protocol and `addController` result-builder extension for declarative routing, the security/vary/rate-limit/localization/not-found middlewares, the `Page` and `Asset` scaffolding, the pre-rendered localized HTML responses, and the `FingerprintAssets` version-token derivation. The service supplies its specifics (String Catalog bundle, pages, icon metadata) through the `*+Defaults` extensions in `WebsiteLibrary`.
 - `Persistence` (`Packages/Persistence`) — the Fluent-based data layer: the `Driver` selector, the `Service` factory that builds the `Fluent` service, the `PrepareDB` registrar that declares the migrations, and the `Probe` consulted by the readiness check; the models, migrations, and repositories stay internal to the package. It has no dependency on `swift-configuration`; the executable maps the `database.*` keys onto the driver.
+- `Utility` (`Packages/Utility`) — small shared helpers with no server dependencies, currently the `NormalizeEmail` method.
 
 The persistence backend runs as a `Fluent` service inside the application's ServiceLifecycle group, so it starts and stops alongside the HTTP server (which owns its connection-pool shutdown on graceful termination).
 
@@ -38,7 +39,7 @@ LogRequestsMiddleware
     → VaryMiddleware                 (marks every response as varying on Accept-Encoding)
       → ResponseCompressionMiddleware (gzip/deflate above the size threshold)
         → LocalizationMiddleware      (negotiates the request's language)
-          → NotFoundMiddleware        (renders the localized 404 page on .notFound)
+          → NotFoundMiddleware        (renders the localized not-found page on .notFound)
             → FileMiddleware          (serves Resources/Static)
 RootController                        (GET / → landing page)
 HealthController                      (GET /health → liveness, GET /health/ready → readiness)
@@ -184,7 +185,7 @@ make pkg-test
 # = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
 ```
 
-Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Tests/Website.xctestplan` covers the service's two targets — `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests) — plus the local packages' suites: `InfrastructureTests`, `PersistenceTests`, and `LocalizationTests`.
+Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Tests/Website.xctestplan` covers the service's two targets — `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests) — plus the local packages' suites: `InfrastructureTests`, `PersistenceTests`, `LocalizationTests`, and `UtilityTests`.
 
 The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the MySQL integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
 ```sh
-- 
2.54.0


From a5ee02bb0b79a447370b2de840afb33acbddfa3f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 2 Aug 2026 02:41:46 +0200
Subject: [PATCH 038/117] Improved the PNG assets optimization on the
 Dockerfile in the Website service target to do it recursively.

---
 Services/Website/Dockerfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index 0714bda..c1c6879 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -19,7 +19,7 @@ WORKDIR /static
 COPY ./Services/Website/Resources/Static .
 RUN esbuild --minify --allow-overwrite --outdir=css css/*.css \
     && esbuild --minify --allow-overwrite --outdir=js js/*.js \
-    && oxipng --opt max --strip safe *.png \
+    && oxipng --opt max --strip safe --recursive . \
     && svgo --recursive --folder .
 
 # Export stage: `docker build --target assets-export --output <dir>` writes the minified static files to <dir> for
-- 
2.54.0


From 422560ec1090e21cde0addbaaa58ae66a293c490 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 2 Aug 2026 02:57:43 +0200
Subject: [PATCH 039/117] Prompt the canonical site URL during bootstrap script
 to rewrite website crawlers.

---
 README.md                                     |  8 +-
 Scripts/bootstrap                             | 45 ++++++++++++
 Services/Website/README.md                    | 73 +++++++++++++++----
 Services/Website/Resources/Static/robots.txt  |  2 +-
 Services/Website/Resources/Static/sitemap.xml |  2 +-
 5 files changed, 112 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 63eb852..1fa7fe0 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,11 @@ You'll be asked for:
 | --- | --- | --- |
 | **Site display name** (PascalCase) | `Loud` | Server name (`LoudWebsite`), `Loud.xcodeproj`, README title. |
 | **Project slug** (lowercase) | `loud-ams` | Container owner, database name/user, Compose project name. |
+| **Canonical site URL** (scheme + host) | `https://loud.amsterdam` | The `Sitemap:` reference in `robots.txt` and the `<loc>` entry in `sitemap.xml`. |
+
+The canonical URL defaults to the reserved placeholder `https://site.example.com`;
+leaving it there is allowed (the script warns), so you can bootstrap before the
+domain is decided and set it later in the two crawler files.
 
 The script rewrites the placeholder occurrences in place, renames
 `Site.xcodeproj`, optionally starts a fresh git history, and then removes
@@ -57,7 +62,8 @@ Bootstrap leaves reminders, but in short:
 
 1. **Copy & localization** — `Services/Website/Sources/Library/Catalogs/Localizable.xcstrings`
    and the landing / 404 pages under `Services/Website/Sources/Library`.
-2. **Static assets** — `Services/Website/Resources/Static` (CSS, JS, favicon, icons, manifest).
+2. **Static assets** — `Services/Website/Resources/Static` (CSS, JS, favicon, icons).
+   The manifest's `name` / `short_name` are empty and are not rewritten by bootstrap.
 3. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
    `Services/Website/.env` (the committed `.env.local` is an example only).
 4. **Domain models** — the `Persistence` package ships a sample
diff --git a/Scripts/bootstrap b/Scripts/bootstrap
index 10aba68..8d44d58 100755
--- a/Scripts/bootstrap
+++ b/Scripts/bootstrap
@@ -24,6 +24,11 @@ fi
 
 XCODEPROJ="./Site.xcodeproj"
 
+# The placeholder origin the crawler files ship with. It is an RFC 2606 reserved
+# domain, so an un-bootstrapped copy can never point a crawler at a real site.
+PLACEHOLDER_URL="https://site.example.com"
+PLACEHOLDER_URL_PATTERN='https://site\.example\.com'
+
 # --- Prompts ------------------------------------------------------------------
 
 printf 'Site display name (PascalCase, e.g. Berlin) [Site]: '
@@ -35,9 +40,31 @@ printf 'Project slug (lowercase, used for owner/db/compose, e.g. loud-berlin) [%
 read -r SLUG
 SLUG="${SLUG:-$DEFAULT_SLUG}"
 
+printf 'Canonical site URL (scheme + host, e.g. https://berlin.example.com) [%s]: ' "$PLACEHOLDER_URL"
+read -r URL
+URL="${URL:-$PLACEHOLDER_URL}"
+URL="${URL%/}" # the rewrites append their own path, so drop a trailing slash
+
+# The URL is interpolated into a sed replacement (with `|` as the delimiter) and
+# into the crawler files, so reject anything that is not a plain scheme + host.
+case "$URL" in
+	http://* | https://*) ;;
+	*)
+		echo "error: the canonical site URL must start with http:// or https:// (got \"$URL\")." >&2
+		exit 1
+		;;
+esac
+case "$URL" in
+	*[!-A-Za-z0-9:/._~]*)
+		echo "error: the canonical site URL contains unexpected characters (got \"$URL\")." >&2
+		exit 1
+		;;
+esac
+
 echo
 echo "  display name : $NAME       (server name \"${NAME}Website\", ${NAME}.xcodeproj)"
 echo "  slug         : $SLUG       (container owner, database name/user, compose project)"
+echo "  canonical URL: $URL       (robots.txt sitemap reference, sitemap.xml entry)"
 echo
 printf 'Apply these values? [y/N]: '
 read -r CONFIRM
@@ -95,6 +122,14 @@ rewrite "$W/docker-compose.override.yml" \
 rewrite "$W/Makefile" \
 	-e "s/),site)/),${SLUG})/g"
 
+# Crawler files: the absolute origin they must carry. `|` is the sed delimiter,
+# since both the placeholder and the replacement contain slashes.
+rewrite "$W/Resources/Static/robots.txt" \
+	-e "s|${PLACEHOLDER_URL_PATTERN}|${URL}|g"
+
+rewrite "$W/Resources/Static/sitemap.xml" \
+	-e "s|${PLACEHOLDER_URL_PATTERN}|${URL}|g"
+
 # Service README.
 rewrite "$W/README.md" \
 	-e "s/^# Site Website\$/# ${NAME} Website/" \
@@ -147,6 +182,7 @@ Next steps:
        - $W/Sources/Library/Catalogs/Localizable.xcstrings   (copy)
        - $W/Sources/Library                                   (landing / 404 pages)
        - $W/Resources/Static                                  (css, js, favicon, icons)
+       - $W/Resources/Static/site.webmanifest                 (name / short_name)
   2. Set a real database password in a git-ignored $W/.env
      (the committed .env.local defaults the password to the slug — do NOT ship that).
   3. Point the git remote at your new repository:
@@ -157,3 +193,12 @@ Next steps:
 The Persistence package still ships an ExampleRecord / ExampleRepository sample
 model — replace it with your real domain models when you add persistence.
 EOF
+
+if [ "$URL" = "$PLACEHOLDER_URL" ]; then
+	cat <<EOF
+
+WARNING: the canonical site URL was left as the placeholder "${PLACEHOLDER_URL}".
+Set the real origin in $W/Resources/Static/robots.txt and sitemap.xml before
+going live, or crawlers will be pointed at a reserved example domain.
+EOF
+fi
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 18c0057..d397119 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -5,8 +5,10 @@ The **Site** public website service — a [Hummingbird](https://github.com/hummi
 The service:
 - Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
 - Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
+- Builds every page on the shared `Page` scaffolding from `Infrastructure`, which assembles the document head around the page's own markup: the viewport declaration, the optional `description` summary and `rel="canonical"` link, the Open Graph / Twitter link-preview tags, and the JSON-LD structured-data script (see [Page metadata](#page-metadata)).
 - Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
-- Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`; the production image ships minified copies (see [Static assets](#static-assets)).
+- Answers `HEAD` on every `GET` route: the router is built with `.autoGenerateHeadEndpoints`, so uptime monitors and crawlers probing with `HEAD` get the route's status and headers instead of a `404`.
+- Serves static files (CSS, JS, icons, manifest, `robots.txt`, `sitemap.xml`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`; the production image ships minified copies (see [Static assets](#static-assets)).
 - Returns a custom not-found (404) HTML page, localized like the landing page, for any request that matches neither a route nor a static file.
 - Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
 - Stamps a hardened set of security headers on every response.
@@ -22,11 +24,11 @@ Two SwiftPM targets:
 | Target | Kind | Path | Role |
 | --- | --- | --- | --- |
 | `Website` | executable | `Sources/App` | Entry point: reads configuration, builds the persistence service, and either serves the website or runs the migrate-and-exit mode. |
-| `WebsiteLibrary` | library | `Sources/Library` | Controllers, the pages, the `StaticFile` asset catalog, the request context, and the `*+Defaults` extensions and configuration-key constants that supply the site's specifics to `Infrastructure`. |
+| `WebsiteLibrary` | library | `Sources/Library` | Controllers, the pages (`IndexPage`, `NotFoundPage`) and their shared `Page` defaults, the `StaticFile` asset catalog, the request context, the String Catalog, and the `*+Defaults` extensions and configuration-key constants that supply the site's specifics to `Infrastructure`. |
 
 The `Website` executable depends on four local packages:
 - `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteLibrary`).
-- `Infrastructure` (`Packages/Infrastructure`) — the shared Hummingbird toolkit: the `RouterController` protocol and `addController` result-builder extension for declarative routing, the security/vary/rate-limit/localization/not-found middlewares, the `Page` and `Asset` scaffolding, the pre-rendered localized HTML responses, and the `FingerprintAssets` version-token derivation. The service supplies its specifics (String Catalog bundle, pages, icon metadata) through the `*+Defaults` extensions in `WebsiteLibrary`.
+- `Infrastructure` (`Packages/Infrastructure`) — the shared Hummingbird toolkit: the `RouterController` protocol and `addController` result-builder extension for declarative routing, the security/vary/rate-limit/localization/not-found middlewares, the `Page` and `Asset` scaffolding, the `SocialCard` and `StructuredData` head-metadata types, the pre-rendered localized HTML responses, and the `FingerprintAssets` version-token derivation. The service supplies its specifics (String Catalog bundle, pages, icon metadata) through the `*+Defaults` extensions in `WebsiteLibrary`.
 - `Persistence` (`Packages/Persistence`) — the Fluent-based data layer: the `Driver` selector, the `Service` factory that builds the `Fluent` service, the `PrepareDB` registrar that declares the migrations, and the `Probe` consulted by the readiness check; the models, migrations, and repositories stay internal to the package. It has no dependency on `swift-configuration`; the executable maps the `database.*` keys onto the driver.
 - `Utility` (`Packages/Utility`) — small shared helpers with no server dependencies, currently the `NormalizeEmail` method.
 
@@ -45,6 +47,21 @@ RootController                        (GET / → landing page)
 HealthController                      (GET /health → liveness, GET /health/ready → readiness)
 ```
 
+The router is created with `.autoGenerateHeadEndpoints`, so each of those `GET` routes gets a `HEAD` sibling for free.
+
+### Page metadata
+Each page conforms to `Infrastructure`'s `Page` protocol and supplies only its `title`, `content`, `stylesheets`, and `scripts`; the protocol assembles the document around them and renders the head in a fixed order: the viewport declaration, the `summary`, the `canonicalURL` link, the `socialCard` tags, the `structuredData` script, then the page `metadata` and the stylesheet links. The body is the content followed by the script tags.
+
+Four of those are optional and **omitted by default** — the reference site leaves them unset, so a generated site fills in what it needs by overriding them on `IndexPage` (or on the shared `Page+Defaults` extension, for site-wide values):
+| Property | Renders as | Notes |
+| --- | --- | --- |
+| `summary` | `<meta name="description">` | The page's one-line description. |
+| `canonicalURL` | `<link rel="canonical">` | Absolute URL. |
+| `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, share image. Scrapers require absolute URLs, so the page composes them from its own origin. |
+| `structuredData` | `<script type="application/ld+json">` | A `StructuredData` graph of schema.org nodes; `StructuredData(name:url:logo:profiles:)` builds the site-wide `Organization` + `WebSite` pair. The payload is an inert data block, so the `Content-Security-Policy` does not apply to it. |
+
+What the pages *do* ship is in `Page+Defaults` (`Sources/Library/Internal/Extensions`), shared by every page: the document `lang`, the favicon / SVG icon / apple-touch-icon / web-manifest links, and the two `theme-color` metas.
+
 ## Configuration
 Configuration is read through [swift-configuration](https://github.com/apple/swift-configuration) from
 the following sources, **highest precedence first**:
@@ -68,9 +85,11 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
 | `cache.maxAge.asset` | `CACHE_MAX_AGE_ASSET` | `31536000` (1 year) | `max-age` for fingerprinted assets (CSS, JS) and fonts; also marked `immutable`. The pages reference CSS/JS through content-versioned URLs (`?v=<token>`), so a deploy busts them by changing the URL. |
-| `cache.maxAge.text` | `CACHE_MAX_AGE_TEXT` | `3600` (1 hour) | `max-age` for unversioned text assets (e.g. `robots.txt`); also marked `must-revalidate`. |
+| `cache.maxAge.text` | `CACHE_MAX_AGE_TEXT` | `3600` (1 hour) | `max-age` for the remaining `text/*` assets (e.g. `robots.txt`), which keep unversioned URLs; also marked `must-revalidate`. |
 | `cache.maxAge.image` | `CACHE_MAX_AGE_IMAGE` | `604800` (1 week) | `max-age` for images (ICO, PNG, SVG). |
-| `cache.maxAge.default` | `CACHE_MAX_AGE_DEFAULT` | `86400` (1 day) | `max-age` for everything else (e.g. the web manifest). |
+| `cache.maxAge.default` | `CACHE_MAX_AGE_DEFAULT` | `86400` (1 day) | `max-age` for everything else — including `site.webmanifest` (`application/manifest+json`) and `sitemap.xml` (`application/xml`), neither of which is `text/*`. |
+
+The groups are matched in order, so the specific media types (`text/css`, `text/javascript`, `font/*`) are resolved before the general `text/*` category.
 
 ### Response compression
 | Config key | Environment variable | Default | Description |
@@ -141,6 +160,8 @@ A direct run picks up the local development overrides from `.env.local` (in-memo
 Or via the Makefile / Docker (uses `docker-compose.override.yml`, which builds from source and sets `LOG_LEVEL=debug`):
 ```sh
 make pkg-build        # swift build
+make pkg-outdated     # list the SPM dependencies that can be updated
+make pkg-update       # update the SPM dependencies
 make site-run         # run locally with hot reload (hb watch)
 make site-mount       # docker compose up --build --detach
 make site-unmount     # docker compose down + remove the local image
@@ -168,8 +189,8 @@ A local MariaDB for development lives behind the `database` Compose profile (so
 make db-mount     # start MariaDB (docker compose --profile database up --wait mariadb)
 make db-migrate   # run migrations against it
 make db-shell     # open a SQL shell on it
-make db-unmount   # stop and remove the container (data kept in Tests/DB)
-make db-reset     # stop and remove the container
+make db-unmount   # stop and remove the container (keeps the data volume)
+make db-reset     # stop and remove the container, and delete its data volume
 DATABASE_DRIVER=mysql make site-mount   # run the site against MariaDB
 ```
 > **Note:** because the data lives in the bind-mounted `Tests/DB` folder rather than a named volume, `db-reset`'s `--volumes` flag does **not** clear it. To start from an empty database, delete `Tests/DB` by hand.
@@ -185,7 +206,9 @@ make pkg-test
 # = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
 ```
 
-Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Tests/Website.xctestplan` covers the service's two targets — `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests) — plus the local packages' suites: `InfrastructureTests`, `PersistenceTests`, `LocalizationTests`, and `UtilityTests`.
+Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. `make pkg-test` runs the service package's own two targets: `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests).
+
+`Tests/Website.xctestplan` — the plan the `Site.xcodeproj` scheme runs — adds the vendored packages' suites on top of those two: `InfrastructureTests`, `PersistenceTests`, `LocalizationTests`, and `UtilityTests`. From the command line, each of those is run from its own package directory (`swift test` in `Packages/<Name>`).
 
 The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the MySQL integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
 ```sh
@@ -195,7 +218,14 @@ cd ../../Packages/Persistence && MYSQL_TEST_HOST=127.0.0.1 swift test
 ```
 
 ## Deployment
-The production image is built for `linux/amd64` in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080` (`ENTRYPOINT ./Website --http-host 0.0.0.0 --http-port 8080`).
+The production image is built in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080`. `make img-check` pins the build to `linux/amd64`; `make img-release` builds for `IMAGE_PLATFORM`.
+
+The executable is the `ENTRYPOINT` and its serving flags are the `CMD`:
+```dockerfile
+ENTRYPOINT ["./Website"]
+CMD ["--http-host", "0.0.0.0", "--http-port", "8080"]
+```
+The split is what makes the migrate-and-exit invocation below work: `docker compose run --rm website --database-migrate` replaces the `CMD` flags without having to override the entrypoint.
 
 Verify the image builds for its `linux/amd64` target without tagging or publishing:
 ```sh
@@ -214,10 +244,14 @@ docker compose -f docker-compose.yml up -d
 ```
 
 ### Static assets
+`Resources/Static` holds the site's stylesheets and scripts under `css/` and `js/`, paired by name: `shared.*` is loaded by every page, alongside a per-page `index.*` and `not-found.*`. The remaining files — the icons, `site.webmanifest`, `robots.txt`, and `sitemap.xml` — sit at the root. Every one of them is a case of the `StaticFile` enumeration, which is what the pages derive their URLs from.
+
 The image build optimizes the files under `Resources/Static` in its `assets` stage, in place, with pinned optimizer versions so asset output is reproducible for a given Dockerfile commit:
-- CSS and JS are minified with [esbuild](https://esbuild.github.io).
-- PNG images are losslessly recompressed with [oxipng](https://github.com/oxipng/oxipng) — the output is pixel-identical, only encoded smaller.
-- The SVG icon is minified with [svgo](https://github.com/svg/svgo).
+- CSS and JS are minified with [esbuild](https://esbuild.github.io) (every file in `css/` and `js/`).
+- PNG images are losslessly recompressed with [oxipng](https://github.com/oxipng/oxipng), recursively — the output is pixel-identical, only encoded smaller.
+- SVGs are minified with [svgo](https://github.com/svg/svgo), recursively.
+
+The PNG and SVG passes walk the tree (`--recursive`), so images added in a subdirectory are optimized without touching the Dockerfile.
 
 Files keep their names and paths, so the URLs derived from the `StaticFile` enumeration are unaffected. The sources in the repository stay readable and unminified: a direct `swift run` serves them as-is, while any image build — including the local `make site-mount` one, which builds the same Dockerfile — serves the optimized copies.
 
@@ -228,6 +262,13 @@ Preview the optimized output locally — requires only Docker and writes to the
 make ast-minify
 ```
 
+#### Crawler files
+`robots.txt` and `sitemap.xml` need an absolute origin, which the template ships as the placeholder `https://site.example.com` — an [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606) reserved domain, so an un-bootstrapped copy can never point a crawler at a real site. The bootstrap script prompts for the canonical site URL and rewrites both files with it; it warns if the placeholder is left in place.
+
+To change the origin later, edit the `Sitemap:` line in `robots.txt` and the `<loc>` entries in `sitemap.xml`. Add a `<loc>` per public page as the site grows — nothing generates the sitemap at runtime.
+
+> **Still manual:** `site.webmanifest` ships empty `name` / `short_name` fields; bootstrap does not fill them in.
+
 ### Icons
 All icons are renditions of the star mark in `icon.svg`, which is the canonical source — there is no external design file to regenerate from.
 
@@ -238,7 +279,9 @@ All icons are renditions of the star mark in `icon.svg`, which is the canonical
 | `icon-192.png`, `icon-512.png` | 192/512 | `site.webmanifest` install icons and splash screens | None (no platform mechanism); full artwork, light rendering, on a transparent background. |
 | `apple-touch-icon.png` | 180×180 | iOS home-screen bookmarks | None (fetched once, outside any page context); full artwork, deliberately opaque — iOS fills transparent regions with black. |
 
-The landing page pairs the icons with two `theme-color` metas: `#0c0710` (media-qualified for dark, listed first — the first matching entry wins) and `#fafafa` as the fallback.
+The icon and manifest links come from the shared `Page+Defaults` extension, so every page carries them, alongside two `theme-color` metas: `#fafafa` unqualified, then `#0c0710` qualified with `(prefers-color-scheme: dark)`.
+
+> **Note:** a browser applies the *first* `theme-color` whose media query matches, so the unqualified light value currently wins on both themes. Put the dark, media-qualified meta first in `Page+Defaults` if the dark value should take effect.
 
 The raster icons are committed binaries, regenerated from `icon.svg` on demand via a throwaway container (no local toolchain needed) — e.g. for the 512px rendition:
 ```sh
@@ -256,8 +299,8 @@ The Makefile and Compose files read these from a `.env` file (or the environment
 | `HOST_CONTAINER` | Container registry host (e.g. `registry.example.com`). |
 | `HOST_OWNER` | Registry namespace / owner. |
 | `HOST_USER`, `HOST_PASSWORD` | Registry credentials for `make img-release`. |
-| `IMAGE_NAME`, `IMAGE_TAG` | Image name and tag. |
-| `IMAGE_PLATFORM` | Build platform (e.g. `linux/amd64`). |
+| `IMAGE_NAME`, `IMAGE_TAG` | Image name and tag. `IMAGE_TAG` is the fallback for `make img-release`'s `version=` argument. |
+| `IMAGE_PLATFORM` | Build platform for `make img-release` (e.g. `linux/amd64`). `make img-check` pins `linux/amd64` regardless. |
 | `HOST_PORT` | Host port mapped to the container's `8080` (default `8080`). |
 | `LOG_LEVEL` | Runtime log level (default `info`). |
 | `HTTP_SERVER_NAME` | Runtime server name (default `SiteWebsite`). |
diff --git a/Services/Website/Resources/Static/robots.txt b/Services/Website/Resources/Static/robots.txt
index e7c9f38..e0aecf5 100644
--- a/Services/Website/Resources/Static/robots.txt
+++ b/Services/Website/Resources/Static/robots.txt
@@ -4,4 +4,4 @@
 User-agent: *
 Disallow:
 
-Sitemap: https://loud.amsterdam/sitemap.xml
+Sitemap: https://site.example.com/sitemap.xml
diff --git a/Services/Website/Resources/Static/sitemap.xml b/Services/Website/Resources/Static/sitemap.xml
index 8bfaeae..01242ae 100644
--- a/Services/Website/Resources/Static/sitemap.xml
+++ b/Services/Website/Resources/Static/sitemap.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
-    <loc>https://loud.amsterdam/</loc>
+    <loc>https://site.example.com/</loc>
   </url>
 </urlset>
-- 
2.54.0


From d10ced84a86e3e6a84c90b04d8c763d3fefdee5b Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 2 Aug 2026 02:59:53 +0200
Subject: [PATCH 040/117] Fixed an issue in the bootstrap script when project
 name left as placeholder.

---
 Scripts/bootstrap | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/Scripts/bootstrap b/Scripts/bootstrap
index 8d44d58..34a1120 100755
--- a/Scripts/bootstrap
+++ b/Scripts/bootstrap
@@ -140,10 +140,19 @@ rewrite "$W/README.md" \
 # Xcode project: PBXProject name + directory.
 if [ -d "$XCODEPROJ" ]; then
 	rewrite "$XCODEPROJ/project.pbxproj" -e "s/\"Site\"/\"${NAME}\"/g"
-	if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-		git mv "$XCODEPROJ" "./${NAME}.xcodeproj" 2>/dev/null || mv "$XCODEPROJ" "./${NAME}.xcodeproj"
-	else
-		mv "$XCODEPROJ" "./${NAME}.xcodeproj"
+
+	# Skip the rename when the display name was left as the placeholder: the
+	# source and destination are then the same path, and `mv dir dir` fails
+	# (it moves the directory into itself), which would abort the run here —
+	# after the rewrites, but before the self-cleanup.
+	XCODEPROJ_RENAMED="./${NAME}.xcodeproj"
+
+	if [ "$XCODEPROJ" != "$XCODEPROJ_RENAMED" ]; then
+		if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+			git mv "$XCODEPROJ" "$XCODEPROJ_RENAMED" 2>/dev/null || mv "$XCODEPROJ" "$XCODEPROJ_RENAMED"
+		else
+			mv "$XCODEPROJ" "$XCODEPROJ_RENAMED"
+		fi
 	fi
 fi
 
-- 
2.54.0


From a4db1fe29cea47d7aa189f6cd15e4b5485c8562b Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 2 Aug 2026 03:04:50 +0200
Subject: [PATCH 041/117] Updated the documentation for the README file of the
 template.

---
 README.md         | 75 +++++++++++++++++++++++++++++++++++++----------
 Scripts/bootstrap |  2 +-
 2 files changed, 60 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 1fa7fe0..a415db4 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,37 @@
 
 This repository is a **template** for the platform's websites. It ships as a
 complete, buildable reference site whose identity is the neutral placeholder
-**`Site`** / **`site`**. You generate a real site from it in two steps:
-generate a fresh repository, then run the bootstrap script to stamp in your
-site's name and slug.
+**`Site`** / **`site`**. You generate a real site from it in two steps: create
+a fresh repository, then run the bootstrap script to stamp in your site's
+display name, slug, and canonical URL.
 
 ## What's in here
 
 | Path | Role |
 | --- | --- |
-| `Services/Website` | The Hummingbird website service (the engine + placeholder content). |
-| `Packages/Localization`, `Packages/Persistence` | Reusable packages, **vendored** into every site — each generated repo owns its own copy. |
+| [`Services/Website`](Services/Website/README.md) | The Hummingbird website service — the executable, the pages, the static assets, and the Docker/Compose deployment. Its README is the operational reference. |
+| [`Packages/Infrastructure`](Packages/Infrastructure/README.md) | Shared Hummingbird toolkit: declarative routing, the hardened middlewares, the `Page`/`Asset` scaffolding, and the pre-rendered localized responses. |
+| [`Packages/Localization`](Packages/Localization/README.md) | String Catalog lookups, `Accept-Language` negotiation, and the catalog-derived language list. |
+| [`Packages/Persistence`](Packages/Persistence/README.md) | The Fluent data layer: driver selection, migration registration, and the readiness probe. |
+| [`Packages/Utility`](Packages/Utility/README.md) | Dependency-free helpers shared across the services. |
 | `Site.xcodeproj` | The umbrella Xcode project (renamed to your site by bootstrap). |
 | `Scripts/bootstrap` | The generator. Rewrites placeholders, then deletes itself. |
+| `Makefile` | Bootstrap convenience only (`make bootstrap`); removed by the script. |
 
-The engine is intentionally copied into each site rather than shared as a
-remote dependency: a generated site is fully self-contained and can diverge
-freely. Engine fixes are propagated to existing sites by hand (or by
-re-generating and porting content).
+All four packages are **vendored**, not fetched: the service depends on them by
+relative path, so each generated repository owns its own copy. That is
+deliberate — a generated site is fully self-contained and can diverge freely.
+The trade-off is that engine fixes are propagated to existing sites by hand (or
+by re-generating and porting content).
+
+## Requirements
+
+- Swift 6.3 toolchain (every manifest is `swift-tools-version:6.3`).
+- Docker — optional, for the containerized run/deploy workflow.
+- The Hummingbird CLI (`hb`) — optional, only for `make site-run`.
+
+See [the service README](Services/Website/README.md) for configuration keys,
+persistence, testing, and deployment.
 
 ## Generating a new site
 
@@ -54,19 +68,29 @@ domain is decided and set it later in the two crawler files.
 
 The script rewrites the placeholder occurrences in place, renames
 `Site.xcodeproj`, optionally starts a fresh git history, and then removes
-itself along with this file and the root `Makefile`.
+itself along with this file and the root `Makefile`. It refuses to run outside
+the repository root, and validates the URL before touching anything — a
+rejected value leaves the tree untouched, so it is safe to re-run.
+
+Accepting the default display name (`Site`) is supported: the rename is skipped
+and the placeholders simply stay in place.
 
 ### 3. Fill in the content
 
 Bootstrap leaves reminders, but in short:
 
 1. **Copy & localization** — `Services/Website/Sources/Library/Catalogs/Localizable.xcstrings`
-   and the landing / 404 pages under `Services/Website/Sources/Library`.
+   (English only out of the box) and the landing / 404 pages under
+   `Services/Website/Sources/Library`.
 2. **Static assets** — `Services/Website/Resources/Static` (CSS, JS, favicon, icons).
    The manifest's `name` / `short_name` are empty and are not rewritten by bootstrap.
-3. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
+3. **Head metadata** — the pages ship no `summary`, `canonicalURL`, `socialCard`, or
+   `structuredData`, so there is no meta description, no link preview, and no JSON-LD
+   until you supply them. See
+   [Page metadata](Services/Website/README.md#page-metadata).
+4. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
    `Services/Website/.env` (the committed `.env.local` is an example only).
-4. **Domain models** — the `Persistence` package ships a sample
+5. **Domain models** — the `Persistence` package ships a sample
    `ExampleRecord` / `ExampleRepository`; replace it when you add real data.
 
 ### 4. Build & run
@@ -83,10 +107,29 @@ make site-mount        # docker compose up --build
 - Organisation (`Röck+Cöde VoF`) and Xcode `DEVELOPMENT_TEAM` — shared across all sites.
 - The package architecture, middleware, security headers, and persistence layer.
 - The generic `website` image name and `Makefile` command names (`site-run`, `site-mount`, …).
+- The four `Packages/*/README.md` files — no rewrite line covers them, so whatever
+  site name they mention ships as-is into every generated repository.
 
 ## Maintaining the template itself
 
 Edit and test the reference site directly — it builds and its tests pass with
-the `Site` / `site` placeholders in place. Keep the placeholders intact so the
-bootstrap script's targeted replacements keep matching; if you introduce a new
-site-specific value, add a matching rewrite line in `Scripts/bootstrap`.
+the `Site` / `site` placeholders in place:
+
+```sh
+(cd Services/Website && make pkg-test)      # the service's own two test targets
+(cd Packages/Infrastructure && swift test)  # and likewise for each vendored package
+```
+
+Keep the placeholders intact so the bootstrap script's targeted replacements
+keep matching. They are:
+
+| Placeholder | Appears in |
+| --- | --- |
+| `Site` | Xcode project name and `project.pbxproj`, the service README title |
+| `SiteWebsite` | `String+Constants.swift`, `.env.local`, `docker-compose.yml`, the service README |
+| `site` | `String+Constants.swift` defaults, `HOST_OWNER` / `DATABASE_*` in `.env.local` and Compose, the `site-platform` Compose project, the `Makefile` `db-shell` fallbacks |
+| `https://site.example.com` | `Resources/Static/robots.txt`, `Resources/Static/sitemap.xml` |
+
+If you introduce a new site-specific value, give it a placeholder from this set
+and add a matching rewrite line in `Scripts/bootstrap` — a value that no rewrite
+covers ships verbatim into every generated site.
diff --git a/Scripts/bootstrap b/Scripts/bootstrap
index 34a1120..9660f1e 100755
--- a/Scripts/bootstrap
+++ b/Scripts/bootstrap
@@ -8,7 +8,7 @@
 #
 # Run once, from the repository root:
 #
-#   ./Tools/bootstrap
+#   ./Scripts/bootstrap        # or: make bootstrap
 #
 # It is idempotent only in the sense that it self-destructs: once run, the
 # placeholders are gone and the script (and its scaffolding) are deleted.
-- 
2.54.0


From fd5aa849243ddbd7f162e0a2b0824b9d1ba2286b Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 2 Aug 2026 02:41:46 +0200
Subject: [PATCH 042/117] Improved the PNG assets optimization on the
 Dockerfile in the Website service target to do it recursively.

---
 Services/Website/Dockerfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index 0714bda..c1c6879 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -19,7 +19,7 @@ WORKDIR /static
 COPY ./Services/Website/Resources/Static .
 RUN esbuild --minify --allow-overwrite --outdir=css css/*.css \
     && esbuild --minify --allow-overwrite --outdir=js js/*.js \
-    && oxipng --opt max --strip safe *.png \
+    && oxipng --opt max --strip safe --recursive . \
     && svgo --recursive --folder .
 
 # Export stage: `docker build --target assets-export --output <dir>` writes the minified static files to <dir> for
-- 
2.54.0


From 5c070c2b1ab691129cab876c7ad1961fd10e712c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 09:22:40 +0000
Subject: [PATCH 043/117] Integrated Analytics into the Infrastructure package
 (#40)

This PR contains the work done to define the `Analytics` type into the _Infrastructure_ package and also, to integrate this type into its `Page` protocol.

Reviewed-on: https://repo.rock-n-code.com/rock-n-code/loud-amsterdam/pulls/40
Co-authored-by: Javier Cicchelli <javier@rock-n-code.com>
---
 .../Sources/Public/Protocols/Page.swift       | 32 +++++-
 .../Sources/Public/Types/Analytics.swift      | 97 +++++++++++++++++++
 .../Cases/Public/Protocols/PageTests.swift    | 34 +++++++
 .../Cases/Public/Types/AnalyticsTests.swift   | 55 +++++++++++
 .../Tests/Utils/Pages/StubPage.swift          |  7 ++
 5 files changed, 220 insertions(+), 5 deletions(-)
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/Analytics.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift

diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
index 30c25e1..e925ac3 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
@@ -4,8 +4,8 @@ import Foundation
 /// A page of a website: an HTML document with the shared scaffolding assembled around the page's content.
 ///
 /// A conforming page supplies its locale, its title, the stylesheets and scripts it needs, its head metadata, and its content; the protocol assembles the
-/// rest of the document around them: the viewport declaration, the summary, canonical, and social card tags, the structured data script, and the
-/// metadata followed by the stylesheet links in the head, and the content followed by the script tags in the body.
+/// rest of the document around them: the viewport declaration, the summary, canonical, and social card tags, the structured data script, the analytics
+/// tracker script, and the metadata followed by the stylesheet links in the head, and the content followed by the script tags in the body.
 public protocol Page: HTMLDocument, Sendable {
 
     // MARK: Associated types
@@ -18,6 +18,9 @@ public protocol Page: HTMLDocument, Sendable {
 
     // MARK: Properties
 
+    /// The analytics tracker embedded as a deferred script in the document head, or `nil` (the default) to omit it.
+    var analytics: Analytics? { get }
+
     /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
     var assetVersion: String? { get }
 
@@ -77,14 +80,15 @@ public extension Page {
         }
     }
     
-    /// The viewport declaration, the ``summary``, ``canonicalURL``, and ``socialCard`` tags and the ``structuredData`` script
-    /// (when provided), and the ``metadata`` followed by the ``stylesheets`` links, placed in the document head.
+    /// The viewport declaration, the ``summary``, ``canonicalURL``, and ``socialCard`` tags, the ``structuredData`` script and the
+    /// ``analytics`` tracker script (when provided), and the ``metadata`` followed by the ``stylesheets`` links, placed in the document head.
     ///
     /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already emits `<meta charset="UTF-8">` before this markup,
     /// and HTML5 allows only one.
     ///
     /// The structured data is an inert data block — browsers never execute it, so a site's `Content-Security-Policy` does not apply to it —
-    /// that search engines read for the organization's name, logo, and profiles.
+    /// that search engines read for the organization's name, logo, and profiles. The analytics tracker, by contrast, is an executable script the
+    /// policy must allow, and it is `defer`red so it never delays the page render; each behavior flag renders its `data-` attribute only when enabled.
     @HTMLBuilder
     var head: some HTML {
         meta(
@@ -127,6 +131,19 @@ public extension Page {
             }
         }
 
+        if let analytics {
+            script(
+                .defer,
+                .src(analytics.scriptURL)
+            ) {}
+            .attributes(contentsOf: analytics.attributes.map {
+                .custom(
+                    name: $0.name,
+                    value: $0.value
+                )
+            })
+        }
+
         metadata
         
         for file in stylesheets {
@@ -140,6 +157,11 @@ public extension Page {
         }
     }
     
+    /// The analytics tracker is omitted unless the page provides one.
+    var analytics: Analytics? {
+        nil
+    }
+
     /// The social card is omitted unless the page provides one.
     var socialCard: SocialCard? {
         nil
diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
new file mode 100644
index 0000000..4df4997
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
@@ -0,0 +1,97 @@
+/// The analytics tracker a page embeds: where the script loads from, which site it reports as, which domains it reports from, and how it behaves.
+///
+/// A page carries it as an optional value so the ``Page`` scaffolding renders the tracker's deferred `<script>` in the document head, or omits it
+/// when the page has none. The attribute names follow the Umami tracker convention. The three behavior flags default to on, and each renders its
+/// `data-` attribute only when enabled, since the tracker treats an absent attribute as off.
+public struct Analytics: Sendable {
+    
+    // MARK: Type aliases
+    
+    public typealias Attribute = (name: String, value: String)
+
+    // MARK: Properties
+
+    /// Whether the tracker drops the URL fragment from reported pageviews, so fragment navigation does not split a page's views.
+    public let excludeHash: Bool
+
+    /// Whether the tracker honors the visitor's browser Do Not Track preference.
+    public let doNotTrack: Bool
+
+    /// The comma-delimited domains the tracker reports from; visits from any other host are ignored.
+    public let domains: String
+
+    /// Whether the tracker collects Core Web Vitals from visitors (requires an Umami instance at v3.1 or newer).
+    public let performance: Bool
+
+    /// The URL the tracker script is loaded from.
+    public let scriptURL: String
+
+    /// The analytics website identifier the tracker reports as.
+    public let websiteID: String
+
+    // MARK: Initializers
+
+    /// Creates an analytics configuration.
+    /// - Parameters:
+    ///   - scriptURL: the URL the tracker script is loaded from.
+    ///   - websiteID: the analytics website identifier the tracker reports as.
+    ///   - domains: the comma-delimited domains the tracker reports from; visits from any other host are ignored.
+    ///   - excludeHash: whether the tracker drops the URL fragment from reported pageviews; defaults to `true`.
+    ///   - doNotTrack: whether the tracker honors the visitor's browser Do Not Track preference; defaults to `true`.
+    ///   - performance: whether the tracker collects Core Web Vitals (requires Umami v3.1 or newer); defaults to `true`.
+    public init(
+        scriptURL: String,
+        websiteID: String,
+        domains: String,
+        excludeHash: Bool = true,
+        doNotTrack: Bool = true,
+        performance: Bool = true
+    ) {
+        self.scriptURL = scriptURL
+        self.websiteID = websiteID
+        self.domains = domains
+        self.excludeHash = excludeHash
+        self.doNotTrack = doNotTrack
+        self.performance = performance
+    }
+
+    // MARK: Computed
+
+    /// The tracker script's attributes, in a stable order: the website id and the reporting domains, then each enabled behavior flag.
+    ///
+    /// A disabled flag is left out entirely, since the tracker treats an absent attribute as off. Each `name` is a full attribute name following the
+    /// Umami `data-` convention, which a page applies to the deferred script verbatim — so the page renders the tracker without knowing its shape.
+    public var attributes: [Attribute] {
+        var attributes = [(
+            name: "data-website-id",
+            value: websiteID
+        ), (
+            name: "data-domains",
+            value: domains
+        )]
+
+        if excludeHash {
+            attributes.append((
+                name: "data-exclude-hash",
+                value: "true"
+            ))
+        }
+
+        if doNotTrack {
+            attributes.append((
+                name: "data-do-not-track",
+                value: "true"
+            ))
+        }
+
+        if performance {
+            attributes.append((
+                name: "data-performance",
+                value: "true"
+            ))
+        }
+
+        return attributes
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
index e0fc405..2540ec2 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
@@ -122,6 +122,40 @@ struct PageTests {
         ))
     }
 
+    @Test
+    func `omits the analytics tracker by default`() {
+        let html = StubPage().render()
+
+        #expect(!html.contains("data-website-id"))
+    }
+
+    @Test
+    func `renders the analytics tracker when provided`() {
+        let html = StubPage(analytics: .init(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "0000-website-id",
+            domains: "example.com"
+        )).render()
+
+        #expect(html.contains(#"<script defer src="https://analytics.example.com/script" data-website-id="0000-website-id" data-domains="example.com" data-exclude-hash="true" data-do-not-track="true" data-performance="true"></script>"#))
+    }
+
+    @Test
+    func `omits the analytics behavior flags that are disabled`() {
+        let html = StubPage(analytics: .init(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "0000-website-id",
+            domains: "example.com",
+            excludeHash: true,
+            doNotTrack: false,
+            performance: false
+        )).render()
+
+        #expect(html.contains(#"<script defer src="https://analytics.example.com/script" data-website-id="0000-website-id" data-domains="example.com" data-exclude-hash="true"></script>"#))
+        #expect(!html.contains("data-do-not-track"))
+        #expect(!html.contains("data-performance"))
+    }
+
     @Test
     func `appends the version token to the asset URLs`() {
         let html = StubPage(assetVersion: "0123456789abcdef").render()
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
new file mode 100644
index 0000000..1ee9a42
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
@@ -0,0 +1,55 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite(
+    "Analytics type",
+    .tags(.type)
+)
+struct AnalyticsTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `lists the website id and domains with every behavior flag on by default`() {
+        let analytics = Analytics(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "id-123",
+            domains: "example.com"
+        )
+
+        #expect(analytics.attributes.map(\.name) == [
+            "data-website-id",
+            "data-domains",
+            "data-exclude-hash",
+            "data-do-not-track",
+            "data-performance",
+        ])
+        #expect(analytics.attributes.map(\.value) == [
+            "id-123",
+            "example.com",
+            "true",
+            "true",
+            "true",
+        ])
+    }
+
+    @Test
+    func `omits the disabled behavior flags`() {
+        let analytics = Analytics(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "id-123",
+            domains: "example.com",
+            excludeHash: true,
+            doNotTrack: false,
+            performance: false
+        )
+
+        #expect(analytics.attributes.map(\.name) == [
+            "data-website-id",
+            "data-domains",
+            "data-exclude-hash",
+        ])
+    }
+
+}
diff --git a/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift b/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
index ffc755e..d719f1d 100644
--- a/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
+++ b/Packages/Infrastructure/Tests/Utils/Pages/StubPage.swift
@@ -7,6 +7,9 @@ struct StubPage: Page {
 
     // MARK: Properties
 
+    /// The analytics tracker rendered as a deferred script in the document head, or `nil` to omit it.
+    let analytics: Analytics?
+
     /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
     let assetVersion: String?
 
@@ -34,6 +37,8 @@ struct StubPage: Page {
     ///     default) to leave them unversioned.
     ///   - canonicalURL: the canonical URL rendered in the document head, or `nil` (the default)
     ///     to omit it.
+    ///   - analytics: the analytics tracker rendered as a deferred script in the document head,
+    ///     or `nil` (the default) to omit it.
     ///   - socialCard: the card rendered as link-preview tags in the document head, or `nil`
     ///     (the default) to omit them.
     ///   - structuredData: the structured data rendered as a JSON-LD script in the document
@@ -44,10 +49,12 @@ struct StubPage: Page {
         locale: Locale = .init(identifier: "en"),
         assetVersion: String? = nil,
         canonicalURL: String? = nil,
+        analytics: Analytics? = nil,
         socialCard: SocialCard? = nil,
         structuredData: StructuredData? = nil,
         summary: String? = nil
     ) {
+        self.analytics = analytics
         self.assetVersion = assetVersion
         self.canonicalURL = canonicalURL
         self.locale = locale
-- 
2.54.0


From c603421c28858701c137ef1032e17c69c573d82e Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 12:06:47 +0200
Subject: [PATCH 044/117] Implemented the scripts' deferral on the Page
 protocol in the Infrastructure package.

---
 .../Sources/Public/Protocols/Page.swift       | 31 ++++++++++++-------
 .../Cases/Public/Protocols/PageTests.swift    | 12 ++++---
 2 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
index e925ac3..5f71622 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
@@ -5,7 +5,7 @@ import Foundation
 ///
 /// A conforming page supplies its locale, its title, the stylesheets and scripts it needs, its head metadata, and its content; the protocol assembles the
 /// rest of the document around them: the viewport declaration, the summary, canonical, and social card tags, the structured data script, the analytics
-/// tracker script, and the metadata followed by the stylesheet links in the head, and the content followed by the script tags in the body.
+/// tracker script, and the metadata followed by the stylesheet links and the deferred script tags in the head, and the content as the body.
 public protocol Page: HTMLDocument, Sendable {
 
     // MARK: Associated types
@@ -27,7 +27,7 @@ public protocol Page: HTMLDocument, Sendable {
     /// The canonical URL the page is served at, rendered as a `link rel="canonical"` tag in the document head, or `nil` (the default) to omit the tag.
     var canonicalURL: String? { get }
 
-    /// The page's markup, rendered before the ``scripts``.
+    /// The page's markup, rendered as the document body.
     @HTMLBuilder
     var content: Content { get }
 
@@ -38,7 +38,10 @@ public protocol Page: HTMLDocument, Sendable {
     @HTMLBuilder
     var metadata: Metadata { get }
 
-    /// The scripts loaded at the end of the document body, in order.
+    /// The scripts loaded from the document head, in order.
+    ///
+    /// Rendered as `defer`red tags: the downloads start while the head is parsed, and the scripts still execute in order only after the
+    /// document is fully parsed — the same semantics end-of-body tags would give, minus the late download start.
     var scripts: [any Asset] { get }
 
     /// The card controlling the page's link previews, rendered as Open Graph and Twitter meta tags in the document head, or `nil` (the default)
@@ -67,21 +70,15 @@ public extension Page {
         nil
     }
     
-    /// The page ``content`` followed by its ``scripts``.
+    /// The page ``content``; the ``scripts`` load deferred from the ``head``.
     @HTMLBuilder
     var body: some HTML {
         content
-        
-        for file in scripts {
-            script(.src(file.urlPath(
-                for: .js,
-                version: assetVersion
-            ))) {}
-        }
     }
     
     /// The viewport declaration, the ``summary``, ``canonicalURL``, and ``socialCard`` tags, the ``structuredData`` script and the
-    /// ``analytics`` tracker script (when provided), and the ``metadata`` followed by the ``stylesheets`` links, placed in the document head.
+    /// ``analytics`` tracker script (when provided), and the ``metadata`` followed by the ``stylesheets`` links and the deferred
+    /// ``scripts`` tags, placed in the document head.
     ///
     /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already emits `<meta charset="UTF-8">` before this markup,
     /// and HTML5 allows only one.
@@ -155,6 +152,16 @@ public extension Page {
                 ))
             )
         }
+
+        for file in scripts {
+            script(
+                .defer,
+                .src(file.urlPath(
+                    for: .js,
+                    version: assetVersion
+                ))
+            ) {}
+        }
     }
     
     /// The analytics tracker is omitted unless the page provides one.
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
index 2540ec2..38787fa 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
@@ -21,7 +21,7 @@ struct PageTests {
         #expect(html.contains(#"name="viewport""#))
         #expect(html.contains(#"<meta name="stub" content="marker">"#))
         #expect(html.contains(#"<link rel="stylesheet" href="/css/stub.css">"#))
-        #expect(html.contains(#"<script src="/js/stub.js"></script>"#))
+        #expect(html.contains(#"<script defer src="/js/stub.js"></script>"#))
         #expect(html.contains("Stub content"))
     }
 
@@ -38,13 +38,17 @@ struct PageTests {
     }
 
     @Test
-    func `renders the scripts after the content`() throws {
+    func `renders the scripts deferred in the head, after the stylesheets`() throws {
         let html = StubPage().render()
 
-        let content = try #require(html.range(of: "Stub content"))
+        let stylesheet = try #require(html.range(of: "/css/stub.css"))
         let script = try #require(html.range(of: "/js/stub.js"))
+        let content = try #require(html.range(of: "Stub content"))
 
-        #expect(content.lowerBound < script.lowerBound)
+        // Deferred head scripts start downloading during head parsing but still execute, in order, only after the
+        // document is parsed — the semantics end-of-body tags gave, minus the late download start.
+        #expect(stylesheet.lowerBound < script.lowerBound)
+        #expect(script.lowerBound < content.lowerBound)
     }
 
     @Test
-- 
2.54.0


From 16acdf0f3d992a18732842693547484d4106f2d5 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 12:11:57 +0200
Subject: [PATCH 045/117] Implemented the analytics preconnect hint on the Page
 protocol in the Infrastructure package.

---
 .../Sources/Public/Protocols/Page.swift       | 16 ++++++---
 .../Sources/Public/Types/Analytics.swift      | 20 +++++++++++
 .../Cases/Public/Protocols/PageTests.swift    |  9 ++++-
 .../Cases/Public/Types/AnalyticsTests.swift   | 33 +++++++++++++++++++
 4 files changed, 73 insertions(+), 5 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
index 5f71622..952ea4c 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
@@ -76,9 +76,9 @@ public extension Page {
         content
     }
     
-    /// The viewport declaration, the ``summary``, ``canonicalURL``, and ``socialCard`` tags, the ``structuredData`` script and the
-    /// ``analytics`` tracker script (when provided), and the ``metadata`` followed by the ``stylesheets`` links and the deferred
-    /// ``scripts`` tags, placed in the document head.
+    /// The viewport declaration, the ``analytics`` origin preconnect hint, the ``summary``, ``canonicalURL``, and ``socialCard``
+    /// tags, the ``structuredData`` script and the ``analytics`` tracker script (when provided), and the ``metadata`` followed by the
+    /// ``stylesheets`` links and the deferred ``scripts`` tags, placed in the document head.
     ///
     /// The charset declaration is omitted: Elementary's `HTMLDocument` scaffolding already emits `<meta charset="UTF-8">` before this markup,
     /// and HTML5 allows only one.
@@ -92,7 +92,15 @@ public extension Page {
             .name(.viewport),
             .content("width=device-width, initial-scale=1")
         )
-        
+
+        // Rendered first so the cross-origin handshake starts before the parser reaches the tracker script tag.
+        if let origin = analytics?.origin {
+            link(
+                .rel("preconnect"),
+                .href(origin)
+            )
+        }
+
         if let summary {
             meta(
                 .name(.description),
diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
index 4df4997..378df23 100644
--- a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
@@ -1,3 +1,5 @@
+import Foundation
+
 /// The analytics tracker a page embeds: where the script loads from, which site it reports as, which domains it reports from, and how it behaves.
 ///
 /// A page carries it as an optional value so the ``Page`` scaffolding renders the tracker's deferred `<script>` in the document head, or omits it
@@ -94,4 +96,22 @@ public struct Analytics: Sendable {
         return attributes
     }
 
+    /// The origin the tracker is served from (scheme and host, plus any explicit port), derived from the ``scriptURL``, or `nil` when the
+    /// URL carries no scheme or host.
+    ///
+    /// A page renders it as a `preconnect` hint before the tracker script, so the connection handshake starts as early as possible.
+    public var origin: String? {
+        guard
+            let url = URL(string: scriptURL),
+            let scheme = url.scheme,
+            let host = url.host
+        else {
+            return nil
+        }
+
+        let port = url.port.map { ":\($0)" } ?? ""
+
+        return "\(scheme)://\(host)\(port)"
+    }
+
 }
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
index 38787fa..8e6f1fc 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
@@ -131,10 +131,11 @@ struct PageTests {
         let html = StubPage().render()
 
         #expect(!html.contains("data-website-id"))
+        #expect(!html.contains(#"rel="preconnect""#))
     }
 
     @Test
-    func `renders the analytics tracker when provided`() {
+    func `renders the analytics tracker when provided`() throws {
         let html = StubPage(analytics: .init(
             scriptURL: "https://analytics.example.com/script",
             websiteID: "0000-website-id",
@@ -142,6 +143,12 @@ struct PageTests {
         )).render()
 
         #expect(html.contains(#"<script defer src="https://analytics.example.com/script" data-website-id="0000-website-id" data-domains="example.com" data-exclude-hash="true" data-do-not-track="true" data-performance="true"></script>"#))
+
+        // The preconnect hint warms the tracker origin's connection before the parser reaches the script tag.
+        let preconnect = try #require(html.range(of: #"<link rel="preconnect" href="https://analytics.example.com">"#))
+        let script = try #require(html.range(of: #"<script defer src="https://analytics.example.com/script""#))
+
+        #expect(preconnect.lowerBound < script.lowerBound)
     }
 
     @Test
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
index 1ee9a42..6330f9f 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
@@ -34,6 +34,39 @@ struct AnalyticsTests {
         ])
     }
 
+    @Test
+    func `derives its origin from the script URL`() {
+        let analytics = Analytics(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "id-123",
+            domains: "example.com"
+        )
+
+        #expect(analytics.origin == "https://analytics.example.com")
+    }
+
+    @Test
+    func `keeps an explicit port in its origin`() {
+        let analytics = Analytics(
+            scriptURL: "http://localhost:3000/script",
+            websiteID: "id-123",
+            domains: "localhost"
+        )
+
+        #expect(analytics.origin == "http://localhost:3000")
+    }
+
+    @Test
+    func `carries no origin for a script URL without a scheme or host`() {
+        let analytics = Analytics(
+            scriptURL: "/script",
+            websiteID: "id-123",
+            domains: "example.com"
+        )
+
+        #expect(analytics.origin == nil)
+    }
+
     @Test
     func `omits the disabled behavior flags`() {
         let analytics = Analytics(
-- 
2.54.0


From 3463556c133676d634222c0723c1ee29ad073807 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 12:18:26 +0200
Subject: [PATCH 046/117] Updated the documentation of the README file in the
 Infrastructure package.

---
 Packages/Infrastructure/README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index b724c15..dfc8bd7 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -10,13 +10,15 @@ The package provides, grouped by role:
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
 | Link previews | `SocialCard`, its `Image`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, and the open `Name` and `Kind` vocabularies |
+| Analytics | `Analytics`, the tracker script `Attribute`s it derives, and the `origin` its preconnect hint targets |
 | Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
 
 ## Design rules
 The package holds only what every service can reuse; anything a service owns is injected, never referenced:
-- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors — as are the `summary`, `canonicalURL`, `socialCard`, and `structuredData` values its other head tags render, each omitted unless the page provides it. A `SocialCard` and a `StructuredData` node take their URLs fully formed and absolute; composing them from an origin and a versioned asset path stays with the page providing them.
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors — as are the `summary`, `canonicalURL`, `socialCard`, `structuredData`, and `analytics` values its other head tags render, each omitted unless the page provides it. A `SocialCard` and a `StructuredData` node take their URLs fully formed and absolute, as does an `Analytics` its script URL; composing them from an origin and a versioned asset path stays with the page providing them.
+- **Types own their format; `Page` renders generically.** Each optional head concern derives its own render-ready representation — the `SocialCard.tags` meta tags, the `StructuredData.payload` JSON-LD, the `Analytics.attributes` script attributes — and the `Page` scaffolding applies it without knowing the vocabulary (Open Graph, schema.org, or the Umami tracker convention). The page ``scripts`` and the analytics tracker render as `defer`red head tags, with a `preconnect` hint for the tracker's cross-origin host.
 - **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern to follow. The open schema.org vocabularies extend the same way: the package declares only the `Property.Name` and `Node.Kind` constants every service shares, and a service adds the ones its own node shapes need.
 - **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
@@ -32,7 +34,7 @@ Sources/
 │   ├── Middlewares/       the five HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
 │   ├── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
-│   └── Types/             SocialCard and StructuredData, with their nested types in SocialCard/ and StructuredData/
+│   └── Types/             Analytics, SocialCard, and StructuredData, the latter two with their nested types in SocialCard/ and StructuredData/
 └── Internal/
     ├── Extensions/        implementation details (the String separators)
     └── Types/             implementation details (FNV1aHash)
-- 
2.54.0


From 02ab9671b10cee80c898b24615b0a3dd1228a28e Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 15:34:21 +0200
Subject: [PATCH 047/117] Swapped the MySQL package dependencies for PostgreSQL
 in Persistence package.

---
 Packages/Persistence/Package.swift | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/Packages/Persistence/Package.swift b/Packages/Persistence/Package.swift
index 5d83c1f..8317309 100644
--- a/Packages/Persistence/Package.swift
+++ b/Packages/Persistence/Package.swift
@@ -21,8 +21,8 @@ let package = Package(
             from: "2.0.0"
         ),
         .package(
-            url: "https://github.com/vapor/fluent-mysql-driver.git",
-            from: "4.8.0"
+            url: "https://github.com/vapor/fluent-postgres-driver.git",
+            from: "2.12.0"
         ),
         .package(
             url: "https://github.com/vapor/fluent-sqlite-driver.git",
@@ -33,12 +33,16 @@ let package = Package(
             from: "3.36.0"
         ),
         .package(
-            url: "https://github.com/vapor/mysql-nio.git",
-            from: "1.7.0"
+            url: "https://github.com/vapor/postgres-nio.git",
+            from: "1.33.0"
         ),
         .package(
             url: "https://github.com/apple/swift-nio.git",
-            from: "2.65.0"
+            from: "2.81.0"
+        ),
+        .package(
+            url: "https://github.com/apple/swift-nio-ssl.git",
+            from: "2.25.0"
         ),
     ],
     targets: [
@@ -50,8 +54,8 @@ let package = Package(
                     package: "hummingbird-fluent"
                 ),
                 .product(
-                    name: "FluentMySQLDriver",
-                    package: "fluent-mysql-driver"
+                    name: "FluentPostgresDriver",
+                    package: "fluent-postgres-driver"
                 ),
                 .product(
                     name: "FluentSQLiteDriver",
@@ -69,8 +73,8 @@ let package = Package(
             dependencies: [
                 .byName(name: "Persistence"),
                 .product(
-                    name: "MySQLNIO",
-                    package: "mysql-nio"
+                    name: "PostgresNIO",
+                    package: "postgres-nio"
                 ),
                 .product(
                     name: "NIOCore",
@@ -80,6 +84,10 @@ let package = Package(
                     name: "NIOPosix",
                     package: "swift-nio"
                 ),
+                .product(
+                    name: "NIOSSL",
+                    package: "swift-nio-ssl"
+                ),
             ],
             path: "Tests"
         ),
-- 
2.54.0


From d7d2709f8838dafbb00d36a81d1d36920fae2562 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 15:40:11 +0200
Subject: [PATCH 048/117] Migrated the Driver and TLS enumerations in the
 Persistence package to use PostgreSQL instead.

---
 .../Sources/Public/Enumerations/Driver.swift  |   4 +-
 .../Sources/Public/Enumerations/TLS.swift     |  28 ++---
 .../Cases/Public/Enumerations/TLSTests.swift  | 102 ++++++++++++------
 3 files changed, 84 insertions(+), 50 deletions(-)

diff --git a/Packages/Persistence/Sources/Public/Enumerations/Driver.swift b/Packages/Persistence/Sources/Public/Enumerations/Driver.swift
index 60f053b..a86c51b 100644
--- a/Packages/Persistence/Sources/Public/Enumerations/Driver.swift
+++ b/Packages/Persistence/Sources/Public/Enumerations/Driver.swift
@@ -4,10 +4,10 @@
 /// that default and stay agnostic of which backend is in use.
 public enum Driver: Sendable {
 
-    /// A MySQL/MariaDB server, reached with the given connection parameters.
+    /// A PostgreSQL server, reached with the given connection parameters.
     ///
     /// - Parameter configuration: the host, credentials, TLS posture, and pooling limits the connection is opened with.
-    case mysql(Configuration)
+    case postgres(Configuration)
 
     /// An ephemeral, in-process SQLite database held entirely in memory.
     ///
diff --git a/Packages/Persistence/Sources/Public/Enumerations/TLS.swift b/Packages/Persistence/Sources/Public/Enumerations/TLS.swift
index be6f492..faf5777 100644
--- a/Packages/Persistence/Sources/Public/Enumerations/TLS.swift
+++ b/Packages/Persistence/Sources/Public/Enumerations/TLS.swift
@@ -1,9 +1,10 @@
 import NIOSSL
+import PostgresNIO
 
 /// The TLS posture used when connecting to the database.
 ///
-/// The executable derives a posture from its `database.tls` configuration and passes it along as part of ``Configuration``; the MySQL driver
-/// receives the resulting `TLSConfiguration` through ``tlsConfiguration``.
+/// The executable derives a posture from its `database.tls` configuration and passes it along as part of ``Configuration``; the PostgreSQL driver
+/// receives the resulting connection TLS mode through ``postgresTLS()``.
 public enum TLS: Sendable {
 
     /// Connect without TLS, in plaintext.
@@ -13,28 +14,27 @@ public enum TLS: Sendable {
     case prefer
 
     /// Connect only over TLS, refusing the connection when the server offers none.
-    ///
-    /// - Important: the refusal is not yet enforced — until it is, `require` behaves like ``prefer`` and silently falls back to plaintext when the
-    ///   server offers no TLS.
     case require
 
 }
 
-// MARK: - Properties
+// MARK: - Methods
 
 extension TLS {
 
-    /// The NIO TLS configuration passed to the MySQL driver for this posture.
+    /// The connection TLS mode passed to the PostgreSQL driver for this posture.
     ///
-    /// Returns `nil` for ``off`` (connect in plaintext) and the default client configuration for ``prefer`` and ``require``.
+    /// Returns `.disable` for ``off`` (connect in plaintext) and the default client configuration for ``prefer`` and ``require``. The driver enforces
+    /// both semantics natively: `prefer` upgrades to TLS only when the server advertises support and continues in plaintext otherwise, while `require`
+    /// refuses the connection when the server offers no TLS.
     ///
-    /// - Note: the driver gives a supplied configuration ``prefer`` semantics natively — it upgrades to TLS only when the server advertises support,
-    ///   and continues in plaintext otherwise — so `prefer` is fully enforced. `require` maps to the same configuration and therefore currently
-    ///   behaves like ``prefer``: the refusal when the server offers no TLS is not yet enforced.
-    var tlsConfiguration: TLSConfiguration? {
+    /// - Throws: an error when the TLS context cannot be built from the default client configuration.
+    /// - Returns: the connection TLS mode for this posture.
+    func postgresTLS() throws -> PostgresConnection.Configuration.TLS {
         switch self {
-        case .off: nil
-        default: .makeClientConfiguration()
+        case .off: .disable
+        case .prefer: .prefer(try NIOSSLContext(configuration: .makeClientConfiguration()))
+        case .require: .require(try NIOSSLContext(configuration: .makeClientConfiguration()))
         }
     }
 
diff --git a/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift b/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
index 0cd7d4e..37a20c6 100644
--- a/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Enumerations/TLSTests.swift
@@ -1,8 +1,7 @@
 import Logging
-import MySQLNIO
 import NIOCore
 import NIOPosix
-import NIOSSL
+import PostgresNIO
 import Testing
 
 @testable import Persistence
@@ -13,46 +12,81 @@ import Testing
 )
 struct TLSTests {
 
-    // MARK: Properties tests
+    // MARK: Methods tests
 
     @Test
-    func `off has no TLS configuration`() {
-        #expect(TLS.off.tlsConfiguration == nil)
-    }
-
-    @Test(arguments: [
-        TLS.prefer,
-        TLS.require
-    ])
-    func `maps to the default client configuration`(
-        for tls: TLS
-    ) throws {
-        let configuration = try #require(tls.tlsConfiguration)
-
-        #expect(configuration.bestEffortEquals(.makeClientConfiguration()))
-    }
-
-    @Test
-    func `prefer falls back to plaintext when the server offers no TLS`() async throws {
-        // The fake server never advertises `CLIENT_SSL`, so this connection can only succeed by downgrading to
-        // plaintext — pinning the driver behavior the `prefer` posture relies on.
-        let server = try await PlaintextMySQLServer.start()
-        let tlsConfiguration = try #require(TLS.prefer.tlsConfiguration)
-        let connection = try await MySQLConnection.connect(
-            to: .init(ipAddress: "127.0.0.1", port: server.port),
-            username: "loud",
-            database: "loud",
-            tlsConfiguration: tlsConfiguration,
-            logger: Logger(label: "test"),
-            on: MultiThreadedEventLoopGroup.singleton.any()
-        ).get()
+    func `off connects in plaintext`() async throws {
+        // With TLS disabled the client skips the `SSLRequest` and sends its startup message directly,
+        // which the fake server answers in plaintext.
+        let server = try await PlaintextPostgresServer.start()
+        let connection = try await connect(to: server, tls: .off)
 
         let isConnected = !connection.isClosed
 
-        try await connection.close().get()
+        try await connection.close()
         try await server.stop()
 
         #expect(isConnected)
     }
 
+    @Test
+    func `prefer falls back to plaintext when the server offers no TLS`() async throws {
+        // The fake server refuses the `SSLRequest`, so this connection can only succeed by downgrading
+        // to plaintext — pinning the driver behavior the `prefer` posture relies on.
+        let server = try await PlaintextPostgresServer.start()
+        let connection = try await connect(to: server, tls: .prefer)
+
+        let isConnected = !connection.isClosed
+
+        try await connection.close()
+        try await server.stop()
+
+        #expect(isConnected)
+    }
+
+    @Test
+    func `require refuses the connection when the server offers no TLS`() async throws {
+        // The fake server refuses the `SSLRequest`, so the driver must fail the connection instead of
+        // downgrading — pinning the refusal the `require` posture promises.
+        let server = try await PlaintextPostgresServer.start()
+
+        let error = await #expect(throws: PSQLError.self) {
+            _ = try await connect(to: server, tls: .require)
+        }
+
+        try await server.stop()
+
+        #expect(error?.code == .sslUnsupported)
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension TLSTests {
+
+    /// Opens a connection to the given fake server with the given TLS posture.
+    /// - Parameters:
+    ///   - server: the fake server to connect to.
+    ///   - tls: the TLS posture to connect with.
+    /// - Returns: the open connection, to be closed by the caller.
+    func connect(
+        to server: PlaintextPostgresServer,
+        tls: TLS
+    ) async throws -> PostgresConnection {
+        try await PostgresConnection.connect(
+            on: MultiThreadedEventLoopGroup.singleton.any(),
+            configuration: .init(
+                host: "127.0.0.1",
+                port: server.port,
+                username: "loud",
+                password: "loud",
+                database: "loud",
+                tls: tls.postgresTLS()
+            ),
+            id: 1,
+            logger: Logger(label: "test")
+        )
+    }
+
 }
-- 
2.54.0


From 1fe7ef2049c9bada72654ab5d558f63e1d6aa03c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 15:42:49 +0200
Subject: [PATCH 049/117] Migrated the Service method in the Persistence
 package to use PostgreSQL instead.

---
 .../Sources/Public/Methods/Service.swift      | 13 +++---
 .../Cases/Public/Methods/ServiceTests.swift   | 46 +++++++++----------
 2 files changed, 30 insertions(+), 29 deletions(-)

diff --git a/Packages/Persistence/Sources/Public/Methods/Service.swift b/Packages/Persistence/Sources/Public/Methods/Service.swift
index a8953f2..67bf4de 100644
--- a/Packages/Persistence/Sources/Public/Methods/Service.swift
+++ b/Packages/Persistence/Sources/Public/Methods/Service.swift
@@ -1,4 +1,4 @@
-import FluentMySQLDriver
+import FluentPostgresDriver
 import FluentSQLiteDriver
 import HummingbirdFluent
 import Logging
@@ -37,27 +37,28 @@ public struct Service: Sendable {
     /// The selected backend is registered as the *default* database, so repositories resolve it with a plain `fluent.db()` and stay agnostic of which
     /// driver is in use. The returned service is not yet running; add it to the application's service group (`app.addServices(_:)`) so it starts and shuts
     /// its connection pool down alongside the server.
+    /// - Throws: an error when the TLS context for the PostgreSQL backend cannot be built.
     /// - Returns: the configured `Fluent` service, ready to be added to the service group.
-    public func callAsFunction() -> Fluent {
+    public func callAsFunction() throws -> Fluent {
         let fluent = Fluent(
             logger: logger
         )
 
         switch driver {
-        case .mysql(let configuration):
+        case .postgres(let configuration):
             fluent.databases.use(
-                .mysql(
+                .postgres(
                     configuration: .init(
                         hostname: configuration.host,
                         port: configuration.port,
                         username: configuration.username,
                         password: configuration.password,
                         database: configuration.name,
-                        tlsConfiguration: configuration.tls.tlsConfiguration
+                        tls: try configuration.tls.postgresTLS()
                     ),
                     maxConnectionsPerEventLoop: configuration.maxConnectionsPerEventLoop
                 ),
-                as: .mysql,
+                as: .psql,
                 isDefault: true
             )
         case .inMemory:
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
index b52dbf9..6b84904 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
@@ -20,7 +20,7 @@ struct ServiceTests {
             logger: Logger(label: "test")
         )
 
-        let fluent = service()
+        let fluent = try service()
         let database = fluent.db() as? any SQLDatabase
 
         try await fluent.shutdown()
@@ -31,14 +31,14 @@ struct ServiceTests {
     }
 
     @Test
-    func `registers a MySQL database as the default for the mysql driver`() async throws {
+    func `registers a PostgreSQL database as the default for the postgres driver`() async throws {
         // Resolving the default database opens no connection — pooling is lazy — so no server
         // needs to be listening on the configured host and port.
         let service = Service(
-            driver: .mysql(
+            driver: .postgres(
                 .init(
                     host: "127.0.0.1",
-                    port: 3306,
+                    port: 5432,
                     name: "loud",
                     username: "loud",
                     password: "loud",
@@ -49,14 +49,14 @@ struct ServiceTests {
             logger: Logger(label: "test")
         )
 
-        let fluent = service()
+        let fluent = try service()
         let database = fluent.db() as? any SQLDatabase
 
         try await fluent.shutdown()
 
         let dialect = try #require(database?.dialect)
 
-        #expect(dialect.name == "mysql")
+        #expect(dialect.name == "postgresql")
     }
 
     @Test
@@ -66,7 +66,7 @@ struct ServiceTests {
             logger: Logger(label: "test")
         )
 
-        let fluent = service()
+        let fluent = try service()
 
         do {
             let database = try #require(fluent.db() as? any SQLDatabase)
@@ -87,12 +87,12 @@ struct ServiceTests {
     }
 
     @Test(
-        "mysql: migrate, insert, read back",
-        .enabled(if: mysqlDriver != nil)
+        "postgres: migrate, insert, read back",
+        .enabled(if: postgresDriver != nil)
     )
-    func mysqlRoundTrip() async throws {
+    func postgresRoundTrip() async throws {
         try await roundTrip(
-            driver: mysqlDriver!,
+            driver: postgresDriver!,
             revertAfter: true
         )
     }
@@ -120,8 +120,8 @@ private extension ServiceTests {
             driver: driver,
             logger: Logger(label: "test")
         )
-        
-        let fluent = service()
+
+        let fluent = try service()
 
         do {
             await prepareDB(for: fluent)
@@ -147,23 +147,23 @@ private extension ServiceTests {
 
 }
 
-/// The MySQL/MariaDB driver built from the `MYSQL_TEST_*` environment variables, or `nil` when the gate
-/// variable `MYSQL_TEST_HOST` is unset — in which case the MySQL integration test is skipped, so the suite
-/// stays runnable with no database available.
-private let mysqlDriver: Persistence.Driver? = {
+/// The PostgreSQL driver built from the `POSTGRES_TEST_*` environment variables, or `nil` when the gate
+/// variable `POSTGRES_TEST_HOST` is unset — in which case the PostgreSQL integration test is skipped, so
+/// the suite stays runnable with no database available.
+private let postgresDriver: Persistence.Driver? = {
     let environment = ProcessInfo.processInfo.environment
 
-    guard let host = environment["MYSQL_TEST_HOST"] else {
+    guard let host = environment["POSTGRES_TEST_HOST"] else {
         return nil
     }
 
-    return .mysql(
+    return .postgres(
         .init(
             host: host,
-            port: environment["MYSQL_TEST_PORT"].flatMap(Int.init) ?? 3306,
-            name: environment["MYSQL_TEST_NAME"] ?? "loud",
-            username: environment["MYSQL_TEST_USERNAME"] ?? "loud",
-            password: environment["MYSQL_TEST_PASSWORD"] ?? "loud",
+            port: environment["POSTGRES_TEST_PORT"].flatMap(Int.init) ?? 5432,
+            name: environment["POSTGRES_TEST_NAME"] ?? "loud",
+            username: environment["POSTGRES_TEST_USERNAME"] ?? "loud",
+            password: environment["POSTGRES_TEST_PASSWORD"] ?? "loud",
             tls: .off,
             maxConnectionsPerEventLoop: 2
         )
-- 
2.54.0


From 8ca31e415ca7d379dbdfdf3cfb3866f81103d6bb Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 15:44:23 +0200
Subject: [PATCH 050/117] Migrated the fake plaintext server in the Persistence
 tests target to use PostgreSQL instead.

---
 .../Utils/Fakes/PlaintextMySQLServer.swift    | 162 -----------------
 .../Utils/Fakes/PlaintextPostgresServer.swift | 170 ++++++++++++++++++
 2 files changed, 170 insertions(+), 162 deletions(-)
 delete mode 100644 Packages/Persistence/Tests/Utils/Fakes/PlaintextMySQLServer.swift
 create mode 100644 Packages/Persistence/Tests/Utils/Fakes/PlaintextPostgresServer.swift

diff --git a/Packages/Persistence/Tests/Utils/Fakes/PlaintextMySQLServer.swift b/Packages/Persistence/Tests/Utils/Fakes/PlaintextMySQLServer.swift
deleted file mode 100644
index 27973c7..0000000
--- a/Packages/Persistence/Tests/Utils/Fakes/PlaintextMySQLServer.swift
+++ /dev/null
@@ -1,162 +0,0 @@
-import NIOCore
-import NIOPosix
-
-/// A fake MySQL server speaking just enough of the wire protocol to complete a plaintext handshake.
-///
-/// Its greeting advertises the `mysql_native_password` plugin but **not** the `CLIENT_SSL` capability, and
-/// it answers the client's handshake response with a bare OK packet — so a client asking for TLS can only
-/// end up connected in plaintext. This is what the `prefer` fallback test connects to, proving the driver
-/// downgrades to plaintext rather than refusing the connection.
-final class PlaintextMySQLServer {
-
-    // MARK: Properties
-
-    /// The port the server listens on, assigned by the system at bind time.
-    let port: Int
-
-    /// The listening channel the server accepts connections through.
-    private let channel: Channel
-
-    // MARK: Initializers
-
-    private init(
-        channel: Channel,
-        port: Int
-    ) {
-        self.channel = channel
-        self.port = port
-    }
-
-    // MARK: Functions
-
-    /// Starts a server on the loopback interface, on a system-assigned port.
-    /// - Returns: the running server, ready to be connected to at ``port``.
-    static func start() async throws -> PlaintextMySQLServer {
-        let channel = try await ServerBootstrap(group: MultiThreadedEventLoopGroup.singleton)
-            .childChannelInitializer { channel in
-                channel.eventLoop.makeCompletedFuture {
-                    try channel.pipeline.syncOperations.addHandler(Handler())
-                }
-            }
-            .bind(host: "127.0.0.1", port: 0)
-            .get()
-
-        guard let port = channel.localAddress?.port else {
-            throw ChannelError.unknownLocalAddress
-        }
-
-        return .init(
-            channel: channel,
-            port: port
-        )
-    }
-
-    /// Stops the server, closing its listening channel.
-    func stop() async throws {
-        try await channel.close().get()
-    }
-
-}
-
-// MARK: - Handlers
-
-private extension PlaintextMySQLServer {
-
-    /// Greets a freshly accepted connection, accepts whatever authentication response arrives,
-    /// and closes on anything after that (e.g. a `COM_QUIT`).
-    final class Handler: ChannelInboundHandler {
-
-        // MARK: Type aliases
-
-        typealias InboundIn = ByteBuffer
-        typealias OutboundOut = ByteBuffer
-
-        // MARK: Properties
-
-        /// Whether the client's handshake response has already been answered with an OK packet.
-        private var didAuthenticate = false
-
-        // MARK: Functions
-
-        func channelActive(context: ChannelHandlerContext) {
-            context.writeAndFlush(
-                wrapOutboundOut(Self.greeting(allocator: context.channel.allocator)),
-                promise: nil
-            )
-        }
-
-        func channelRead(
-            context: ChannelHandlerContext,
-            data: NIOAny
-        ) {
-            guard didAuthenticate else {
-                didAuthenticate = true
-
-                context.writeAndFlush(
-                    wrapOutboundOut(Self.ok(allocator: context.channel.allocator)),
-                    promise: nil
-                )
-
-                return
-            }
-
-            context.close(promise: nil)
-        }
-
-        // MARK: Helpers
-
-        /// The `HandshakeV10` greeting, framed and ready to send as the connection's first packet.
-        ///
-        /// The advertised capabilities are `CLIENT_LONG_PASSWORD`, `CLIENT_PROTOCOL_41`,
-        /// `CLIENT_SECURE_CONNECTION`, and `CLIENT_PLUGIN_AUTH` — deliberately **not** `CLIENT_SSL`,
-        /// so the client cannot upgrade the connection to TLS.
-        private static func greeting(allocator: ByteBufferAllocator) -> ByteBuffer {
-            var payload = allocator.buffer(capacity: 80)
-
-            payload.writeInteger(10, endianness: .little, as: UInt8.self)     // protocol version
-            payload.writeNullTerminatedString("8.0.0")                       // server version
-            payload.writeInteger(1, endianness: .little, as: UInt32.self)    // connection id
-            payload.writeBytes([1, 2, 3, 4, 5, 6, 7, 8])                     // auth plugin data, part 1
-            payload.writeInteger(0, endianness: .little, as: UInt8.self)     // filler
-            payload.writeInteger(0x8201, endianness: .little, as: UInt16.self) // capabilities, lower: LONG_PASSWORD | PROTOCOL_41 | SECURE_CONNECTION
-            payload.writeInteger(0x21, endianness: .little, as: UInt8.self)  // character set (utf8)
-            payload.writeInteger(0x0002, endianness: .little, as: UInt16.self) // status flags (autocommit)
-            payload.writeInteger(0x0008, endianness: .little, as: UInt16.self) // capabilities, upper: PLUGIN_AUTH
-            payload.writeInteger(21, endianness: .little, as: UInt8.self)    // auth plugin data length
-            payload.writeBytes([UInt8](repeating: 0, count: 10))             // reserved
-            payload.writeBytes([9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 0]) // auth plugin data, part 2
-            payload.writeNullTerminatedString("mysql_native_password")       // auth plugin name
-
-            return framed(payload, sequence: 0, allocator: allocator)
-        }
-
-        /// A bare OK packet, framed as the reply to the client's handshake response.
-        private static func ok(allocator: ByteBufferAllocator) -> ByteBuffer {
-            var payload = allocator.buffer(capacity: 8)
-
-            payload.writeBytes([0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00])  // OK, no rows, autocommit, no warnings
-
-            return framed(payload, sequence: 2, allocator: allocator)
-        }
-
-        /// Wraps a payload in the MySQL packet frame: a 3-byte little-endian length and a sequence byte.
-        private static func framed(
-            _ payload: ByteBuffer,
-            sequence: UInt8,
-            allocator: ByteBufferAllocator
-        ) -> ByteBuffer {
-            var packet = allocator.buffer(capacity: payload.readableBytes + 4)
-            var payload = payload
-
-            packet.writeInteger(UInt8(payload.readableBytes & 0xff))
-            packet.writeInteger(UInt8((payload.readableBytes >> 8) & 0xff))
-            packet.writeInteger(UInt8((payload.readableBytes >> 16) & 0xff))
-            packet.writeInteger(sequence)
-            packet.writeBuffer(&payload)
-
-            return packet
-        }
-
-    }
-
-}
diff --git a/Packages/Persistence/Tests/Utils/Fakes/PlaintextPostgresServer.swift b/Packages/Persistence/Tests/Utils/Fakes/PlaintextPostgresServer.swift
new file mode 100644
index 0000000..d19762a
--- /dev/null
+++ b/Packages/Persistence/Tests/Utils/Fakes/PlaintextPostgresServer.swift
@@ -0,0 +1,170 @@
+import NIOCore
+import NIOPosix
+
+/// A fake PostgreSQL server speaking just enough of the wire protocol to complete a plaintext startup.
+///
+/// It answers the client's `SSLRequest` with `'N'` (no SSL) and the subsequent startup message with
+/// `AuthenticationOk`, `BackendKeyData`, and `ReadyForQuery` — so a client asking for TLS can only end up
+/// connected in plaintext. This is what the `prefer` fallback test connects to, proving the driver
+/// downgrades to plaintext rather than refusing the connection, and what the `require` test connects to,
+/// proving the driver refuses the connection instead of downgrading.
+final class PlaintextPostgresServer {
+
+    // MARK: Properties
+
+    /// The port the server listens on, assigned by the system at bind time.
+    let port: Int
+
+    /// The listening channel the server accepts connections through.
+    private let channel: Channel
+
+    // MARK: Initializers
+
+    private init(
+        channel: Channel,
+        port: Int
+    ) {
+        self.channel = channel
+        self.port = port
+    }
+
+    // MARK: Functions
+
+    /// Starts a server on the loopback interface, on a system-assigned port.
+    /// - Returns: the running server, ready to be connected to at ``port``.
+    static func start() async throws -> PlaintextPostgresServer {
+        let channel = try await ServerBootstrap(group: MultiThreadedEventLoopGroup.singleton)
+            .childChannelInitializer { channel in
+                channel.eventLoop.makeCompletedFuture {
+                    try channel.pipeline.syncOperations.addHandler(Handler())
+                }
+            }
+            .bind(host: "127.0.0.1", port: 0)
+            .get()
+
+        guard let port = channel.localAddress?.port else {
+            throw ChannelError.unknownLocalAddress
+        }
+
+        return .init(
+            channel: channel,
+            port: port
+        )
+    }
+
+    /// Stops the server, closing its listening channel.
+    func stop() async throws {
+        try await channel.close().get()
+    }
+
+}
+
+// MARK: - Handlers
+
+private extension PlaintextPostgresServer {
+
+    /// Refuses the client's `SSLRequest`, accepts whatever startup message arrives, and closes on anything
+    /// after that (e.g. a `Terminate`).
+    ///
+    /// Unlike MySQL, the PostgreSQL client speaks first, so nothing is written on `channelActive`.
+    final class Handler: ChannelInboundHandler {
+
+        // MARK: Type aliases
+
+        typealias InboundIn = ByteBuffer
+        typealias OutboundOut = ByteBuffer
+
+        // MARK: Enumerations
+
+        /// The startup phases the connection moves through.
+        private enum State {
+            case awaitingSSLRequest
+            case awaitingStartup
+            case established
+        }
+
+        // MARK: Constants
+
+        /// The magic code identifying an `SSLRequest` message.
+        private static let sslRequestCode: Int32 = 80877103
+
+        // MARK: Properties
+
+        /// The startup phase the connection is currently in.
+        private var state: State = .awaitingSSLRequest
+
+        // MARK: Functions
+
+        func channelRead(
+            context: ChannelHandlerContext,
+            data: NIOAny
+        ) {
+            var buffer = unwrapInboundIn(data)
+
+            switch state {
+            case .awaitingSSLRequest:
+                // Peek past the Int32 length at the Int32 code: an `SSLRequest` is refused with a bare
+                // 'N', while a direct startup message (a client connecting with TLS disabled) is
+                // answered straight away.
+                guard buffer.getInteger(at: buffer.readerIndex + 4, as: Int32.self) == Self.sslRequestCode else {
+                    state = .established
+
+                    context.writeAndFlush(
+                        wrapOutboundOut(Self.startupResponse(allocator: context.channel.allocator)),
+                        promise: nil
+                    )
+
+                    return
+                }
+
+                state = .awaitingStartup
+
+                var refusal = context.channel.allocator.buffer(capacity: 1)
+
+                refusal.writeInteger(UInt8(ascii: "N"))
+
+                context.writeAndFlush(
+                    wrapOutboundOut(refusal),
+                    promise: nil
+                )
+            case .awaitingStartup:
+                state = .established
+
+                context.writeAndFlush(
+                    wrapOutboundOut(Self.startupResponse(allocator: context.channel.allocator)),
+                    promise: nil
+                )
+            case .established:
+                context.close(promise: nil)
+            }
+        }
+
+        // MARK: Helpers
+
+        /// The reply completing a plaintext startup: `AuthenticationOk`, `BackendKeyData`, and
+        /// `ReadyForQuery` in a single flush.
+        ///
+        /// `BackendKeyData` is not optional filler — the client requires it before `ReadyForQuery` by
+        /// default and fails the connection when it is missing.
+        private static func startupResponse(allocator: ByteBufferAllocator) -> ByteBuffer {
+            var buffer = allocator.buffer(capacity: 32)
+
+            buffer.writeInteger(UInt8(ascii: "R"))   // AuthenticationOk
+            buffer.writeInteger(Int32(8))
+            buffer.writeInteger(Int32(0))
+
+            buffer.writeInteger(UInt8(ascii: "K"))   // BackendKeyData
+            buffer.writeInteger(Int32(12))
+            buffer.writeInteger(Int32(1))            // process id
+            buffer.writeInteger(Int32(0))            // secret key
+
+            buffer.writeInteger(UInt8(ascii: "Z"))   // ReadyForQuery
+            buffer.writeInteger(Int32(5))
+            buffer.writeInteger(UInt8(ascii: "I"))   // idle
+
+            return buffer
+        }
+
+    }
+
+}
-- 
2.54.0


From 3d27a27cb115d448c22a1ece0cec3f5cc1daf82d Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 15:48:13 +0200
Subject: [PATCH 051/117] Migrated the documentations and test cases in the
 Persistence package to use/name PostgreSQL instead.

---
 Packages/Persistence/README.md                 | 18 +++++++++---------
 .../Sources/Public/Methods/Probe.swift         |  2 +-
 .../Sources/Public/Types/Configuration.swift   |  4 ++--
 .../Cases/Public/Methods/ProbeTests.swift      |  6 +++---
 4 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/Packages/Persistence/README.md b/Packages/Persistence/README.md
index 571fdac..f0ddddb 100644
--- a/Packages/Persistence/README.md
+++ b/Packages/Persistence/README.md
@@ -1,11 +1,11 @@
 # Persistence
-The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based data layer the **Loud** services build on: runtime selection between a MySQL/MariaDB backend and an ephemeral in-memory SQLite one, single-place migration registration, and a database readiness probe.
+The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based data layer the **Loud** services build on: runtime selection between a PostgreSQL backend and an ephemeral in-memory SQLite one, single-place migration registration, and a database readiness probe.
 
 ## Overview
 The package provides, grouped by role:
 | Role | Types |
 | --- | --- |
-| Backend selection | `Driver` (`mysql` or `inMemory`), `Configuration` (the MySQL/MariaDB connection parameters), `TLS` (the connection's TLS posture) |
+| Backend selection | `Driver` (`postgres` or `inMemory`), `Configuration` (the PostgreSQL connection parameters), `TLS` (the connection's TLS posture) |
 | Service | `Service`, which builds the `Fluent` service configured for the chosen driver |
 | Migrations | `PrepareDB`, the single registrar declaring every migration, in order |
 | Readiness | `Probe`, which reports whether the default database answers a `SELECT 1` |
@@ -14,13 +14,13 @@ The package provides, grouped by role:
 ## Design rules
 - **The package reads no configuration.** The executable maps its `database.*` keys onto a `Driver` and hands it over; connection values arrive as plain data. See the Website service's `ConfigReader+Properties` for the mapping.
 - **One default database.** `Service` registers the selected backend as the *default* database, so repositories resolve it with a plain `fluent.db()` and stay agnostic of which driver is in use.
-- **Migrations are declared once, and append-only.** `PrepareDB` is the single place migrations are registered, in the order they must run; alter the schema by adding a new migration, never by editing one that has already run. Registering does not apply them — the in-memory backend is migrated on startup, while a shared MySQL/MariaDB database is migrated out of band (the executable's migrate-and-exit mode), so multiple booting instances never race.
+- **Migrations are declared once, and append-only.** `PrepareDB` is the single place migrations are registered, in the order they must run; alter the schema by adding a new migration, never by editing one that has already run. Registering does not apply them — the in-memory backend is migrated on startup, while a shared PostgreSQL database is migrated out of band (the executable's migrate-and-exit mode), so multiple booting instances never race.
 - **Models never cross a concurrency boundary.** FluentKit models are mutable reference types; repositories map them to `Sendable` value-type snapshots (e.g. `Example`) before returning, and the models themselves stay internal to the package.
 - **Readiness never throws.** `Probe` runs a `SELECT 1` — the cheapest statement both backends understand, independent of any schema — and maps every failure to `false`, so callers translate it straight into a readiness response.
 - **A single connection for the in-memory store.** The SQLite backend is capped at one connection per event loop so every query reaches the same in-memory database, rather than each pooled connection getting its own private one.
 - **Method structs.** `Service`, `PrepareDB`, and `Probe` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
-> **Note:** the `prefer` TLS posture is enforced by the driver itself: a supplied TLS configuration upgrades the connection only when the server advertises TLS, and continues in plaintext otherwise (pinned by a test against a fake server that offers no TLS). `require` currently maps to the same configuration and therefore behaves like `prefer` — the refusal when the server offers no TLS is not yet enforced.
+> **Note:** both TLS postures are enforced by the driver itself: `prefer` upgrades the connection only when the server advertises TLS and continues in plaintext otherwise, while `require` refuses the connection when the server offers none. Both behaviors are pinned by tests against a fake server that offers no TLS.
 
 ## Layout
 Sources are split by visibility, then by kind, one type per file:
@@ -37,17 +37,17 @@ Sources/
 Tests/
 ├── Cases/                 the test suites, mirroring the Sources/ layout
 └── Utils/                 the NotSQL* fakes backing the probe's non-SQL-database case, the
-                           plaintext-only fake MySQL server, and the suite Tag constants
+                           plaintext-only fake PostgreSQL server, and the suite Tag constants
 ```
 
 ## Testing
-The suite runs against the in-memory backend by default, so `swift test` needs no database. The MySQL/MariaDB integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`, `MYSQL_TEST_NAME`, `MYSQL_TEST_USERNAME`, and `MYSQL_TEST_PASSWORD`); it reverts its migrations afterwards, so the shared database is left as it was found:
+The suite runs against the in-memory backend by default, so `swift test` needs no database. The PostgreSQL integration test is skipped unless a database is pointed at via `POSTGRES_TEST_HOST` (with optional `POSTGRES_TEST_PORT`, `POSTGRES_TEST_NAME`, `POSTGRES_TEST_USERNAME`, and `POSTGRES_TEST_PASSWORD`); it reverts its migrations afterwards, so the shared database is left as it was found:
 ```sh
 # in-memory only
 swift test                                
 # or
-# with the local MariaDB up (make db-mount):
-MYSQL_TEST_HOST=127.0.0.1 swift test
+# with the local PostgreSQL up (make db-mount):
+POSTGRES_TEST_HOST=127.0.0.1 swift test
 ```
 
 Outside the application's service group, a built `Fluent` service must be shut down explicitly — even on failure — or its connection pool asserts on `deinit`; the suites' `do`/`catch` pattern around `fluent.shutdown()` is the shape to follow.
@@ -57,4 +57,4 @@ Every suite carries a tag naming the kind of API it exercises — `.enumeration`
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
 - macOS 15, matching the sibling `Infrastructure` and `Localization` packages (the services deploy to Linux containers; the packages carry no UI platforms).
-- Package dependencies: `hummingbird-fluent`, `fluent-mysql-driver`, `fluent-sqlite-driver`, and `sql-kit`; the test target additionally depends on `mysql-nio` and `swift-nio` for the TLS fallback test.
+- Package dependencies: `hummingbird-fluent`, `fluent-postgres-driver`, `fluent-sqlite-driver`, and `sql-kit`; the test target additionally depends on `postgres-nio`, `swift-nio`, and `swift-nio-ssl` for the TLS fallback tests.
diff --git a/Packages/Persistence/Sources/Public/Methods/Probe.swift b/Packages/Persistence/Sources/Public/Methods/Probe.swift
index 8abbc8b..78a096d 100644
--- a/Packages/Persistence/Sources/Public/Methods/Probe.swift
+++ b/Packages/Persistence/Sources/Public/Methods/Probe.swift
@@ -26,7 +26,7 @@ public struct Probe: Sendable {
 
     /// Reports whether the database behind the `Fluent` service is reachable.
     ///
-    /// Runs a trivial `SELECT 1` against the default database — the cheapest statement both the MySQL/MariaDB and SQLite backends understand — so
+    /// Runs a trivial `SELECT 1` against the default database — the cheapest statement both the PostgreSQL and SQLite backends understand — so
     /// a readiness check does not depend on any particular schema or model. Any failure (connection refused, authentication error, pool exhausted) is
     /// reported as not reachable rather than thrown, so callers can map it straight onto a readiness response. A default database that is not an SQL
     /// database is likewise reported as not reachable.
diff --git a/Packages/Persistence/Sources/Public/Types/Configuration.swift b/Packages/Persistence/Sources/Public/Types/Configuration.swift
index 8867228..1cdfc2f 100644
--- a/Packages/Persistence/Sources/Public/Types/Configuration.swift
+++ b/Packages/Persistence/Sources/Public/Types/Configuration.swift
@@ -1,4 +1,4 @@
-/// The connection parameters for the MySQL/MariaDB backend.
+/// The connection parameters for the PostgreSQL backend.
 ///
 /// The executable builds this from its `database.*` configuration; the package itself reads no configuration, so these values arrive as plain data.
 public struct Configuration: Sendable {
@@ -28,7 +28,7 @@ public struct Configuration: Sendable {
 
     // MARK: Initializers
 
-    /// Creates a set of MySQL/MariaDB connection parameters.
+    /// Creates a set of PostgreSQL connection parameters.
     /// - Parameters:
     ///   - host: the host the database server is reached at.
     ///   - port: the port the database server listens on.
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
index 6f44afa..64971b6 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
@@ -19,7 +19,7 @@ struct ProbeTests {
             driver: .inMemory,
             logger: Logger(label: "test")
         )
-        let fluent = service()
+        let fluent = try service()
         let probe = Probe(fluent: fluent)
 
         let isReachable = await probe()
@@ -34,7 +34,7 @@ struct ProbeTests {
         // Port 1 on the loopback interface has nothing listening, so the connection is refused
         // immediately instead of timing out.
         let service = Service(
-            driver: .mysql(
+            driver: .postgres(
                 .init(
                     host: "127.0.0.1",
                     port: 1,
@@ -47,7 +47,7 @@ struct ProbeTests {
             ),
             logger: Logger(label: "test")
         )
-        let fluent = service()
+        let fluent = try service()
         let probe = Probe(fluent: fluent)
 
         let isReachable = await probe()
-- 
2.54.0


From 9b4a780ea3c47a271d115d24e28b7f93234d575a Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 16:17:32 +0200
Subject: [PATCH 052/117] Migrated the Website service and library targets to
 use Persistence package with PostgreSQL instead.

---
 Services/Website/Sources/App/App.swift              |  2 +-
 .../Website/Sources/App/Extensions/App+Build.swift  | 13 +++++++------
 .../App/Extensions/ConfigReader+Properties.swift    |  8 ++++----
 .../Extensions/AbsoluteConfigKey+Constants.swift    |  4 ++--
 .../Public/Extensions/ConfigKey+Constants.swift     |  6 +++---
 .../Library/Public/Extensions/Int+Constants.swift   |  4 ++--
 .../Public/Extensions/String+Constants.swift        |  6 +++---
 Services/Website/Tests/App/AppTests.swift           |  4 ++--
 .../Public/Controllers/HealthControllerTests.swift  |  6 +++---
 9 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/Services/Website/Sources/App/App.swift b/Services/Website/Sources/App/App.swift
index d75a38f..f6b2409 100644
--- a/Services/Website/Sources/App/App.swift
+++ b/Services/Website/Sources/App/App.swift
@@ -42,7 +42,7 @@ struct App {
             return
         }
 
-        let app = await application(
+        let app = try await application(
             reader: reader
         )
 
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 2164f29..61c5894 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -12,13 +12,14 @@ import WebsiteLibrary
 /// Reads the log level, server name, static files location, minimum response size to compress, and security headers from the configuration, then assembles
 /// the router, server configuration, and logger. It warns when the localization catalog cannot be read, since pages would serve raw localization keys.
 /// It also builds the persistence driver, registers its migrations, and attaches the `Fluent` service so it starts
-/// and stops alongside the HTTP server; the ephemeral in-memory backend is migrated on startup, while a MySQL/MariaDB backend is migrated out of
+/// and stops alongside the HTTP server; the ephemeral in-memory backend is migrated on startup, while a PostgreSQL backend is migrated out of
 /// band (so a shared database is never migrated on boot).
 /// - Parameter reader: the configuration reader the values are read from.
 /// - Returns: the configured application, ready to run as a service.
+/// - Throws: an error when the persistence service cannot be built (e.g. its TLS context fails to build).
 func application(
     reader: ConfigReader
-) async -> some ApplicationProtocol {
+) async throws -> some ApplicationProtocol {
     let languages = LanguageList()
     let logger = logger(
         serverName: reader.serverName,
@@ -37,7 +38,7 @@ func application(
         driver: reader.driver,
         logger: logger
     )
-    let fluent = persistence()
+    let fluent = try persistence()
 
     let fingerprintAssets = FingerprintAssets(logger: logger)
     let prepareDB = PrepareDB()
@@ -63,7 +64,7 @@ func application(
 
     app.addServices(fluent)
 
-    // The in-memory backend is recreated on every launch, so it is migrated on startup. The MySQL/MariaDB backend is
+    // The in-memory backend is recreated on every launch, so it is migrated on startup. The PostgreSQL backend is
     // left untouched here: a shared database is migrated out of band to avoid multi-instance races.
     if case .inMemory = reader.driver {
         app.beforeServerStarts {
@@ -77,7 +78,7 @@ func application(
 /// Runs every registered migration against the configured backend, then exits.
 ///
 /// This is the out-of-band migration path selected by the `database.migrate` flag: it builds the same driver the service would run against, applies the
-/// migrations, and shuts the database down — so a shared MySQL/MariaDB database is migrated by a single deliberate invocation rather than by every
+/// migrations, and shuts the database down — so a shared PostgreSQL database is migrated by a single deliberate invocation rather than by every
 /// booting instance.
 /// - Parameter reader: the configuration reader the values are read from.
 func migration(
@@ -92,7 +93,7 @@ func migration(
         logger: logger
     )
 
-    let fluent = service()
+    let fluent = try service()
     let prepareDB = PrepareDB()
 
     await prepareDB(for: fluent)
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index c596d3f..4f5bb32 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -59,7 +59,7 @@ package extension ConfigReader {
 
     /// The persistence backend the service runs against, derived from the `database.*` keys.
     ///
-    /// When `database.driver` selects MySQL, the connection parameters are assembled from the `database.host`, `database.port`,
+    /// When `database.driver` selects PostgreSQL, the connection parameters are assembled from the `database.host`, `database.port`,
     /// `database.name`, `database.username`, `database.password` (empty when unset), `database.tls`, and
     /// `database.pool.maxPerEventLoop` keys. Any other driver value falls back to the in-memory database.
     var driver: Driver {
@@ -67,8 +67,8 @@ package extension ConfigReader {
             forKey: .Database.driver,
             default: .Database.driver
         ) {
-        case .Database.driverMySQL:
-            return .mysql(
+        case .Database.driverPostgres:
+            return .postgres(
                 .init(
                     host: string(
                         forKey: .Database.host,
@@ -199,7 +199,7 @@ private extension ConfigReader {
 
     // MARK: Properties
 
-    /// The TLS posture for the MySQL connection, mapped from the `database.tls` key: `off` and `require` map to their postures, and any
+    /// The TLS posture for the PostgreSQL connection, mapped from the `database.tls` key: `off` and `require` map to their postures, and any
     /// other value falls back to `prefer`.
     var tls: TLS {
         switch string(
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index 9e4a82e..b44f742 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -23,9 +23,9 @@ extension AbsoluteConfigKey {
         public static let migrate: AbsoluteConfigKey = .init(.Database.migrate)
         /// The absolute configuration key for the persistence driver.
         public static let driver: AbsoluteConfigKey = .init(.Database.driver)
-        /// The absolute configuration key for the MySQL/MariaDB host.
+        /// The absolute configuration key for the PostgreSQL host.
         public static let host: AbsoluteConfigKey = .init(.Database.host)
-        /// The absolute configuration key for the MySQL/MariaDB port.
+        /// The absolute configuration key for the PostgreSQL port.
         public static let port: AbsoluteConfigKey = .init(.Database.port)
         /// The absolute configuration key for the database name.
         public static let name: AbsoluteConfigKey = .init(.Database.name)
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index 289641c..a6a6492 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -21,11 +21,11 @@ extension ConfigKey {
     public enum Database {
         /// The configuration key selecting migrate-and-exit mode (run migrations, then exit) instead of serving.
         public static let migrate: ConfigKey = "database.migrate"
-        /// The configuration key for the persistence driver (`inMemory` or `mysql`).
+        /// The configuration key for the persistence driver (`inMemory` or `postgres`).
         public static let driver: ConfigKey = "database.driver"
-        /// The configuration key for the MySQL/MariaDB host.
+        /// The configuration key for the PostgreSQL host.
         public static let host: ConfigKey = "database.host"
-        /// The configuration key for the MySQL/MariaDB port.
+        /// The configuration key for the PostgreSQL port.
         public static let port: ConfigKey = "database.port"
         /// The configuration key for the database name.
         public static let name: ConfigKey = "database.name"
diff --git a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
index f1adf3f..a7eeda8 100644
--- a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
@@ -17,8 +17,8 @@ extension Int {
     }
     /// A namespace for the persistence's default configuration values.
     public enum Database {
-        /// The default MySQL/MariaDB port.
-        public static let port = 3_306
+        /// The default PostgreSQL port.
+        public static let port = 5_432
         /// The default maximum pooled connections per event loop.
         public static let poolMaxPerEventLoop = 4
     }
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index a70db40..66940f5 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -3,9 +3,9 @@ extension String {
     public enum Database {
         /// The default persistence driver: in-memory SQLite, which needs no external infrastructure.
         public static let driver = "inMemory"
-        /// The driver token selecting the MySQL/MariaDB backend.
-        public static let driverMySQL = "mysql"
-        /// The default MySQL/MariaDB host.
+        /// The driver token selecting the PostgreSQL backend.
+        public static let driverPostgres = "postgres"
+        /// The default PostgreSQL host.
         public static let host = "localhost"
         /// The default database name.
         public static let name = "loud"
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 846ccf2..e8b425c 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -395,8 +395,8 @@ private extension AppTests {
     func app(
         staticFilesPath: String,
         strictTransportSecurity: String? = nil
-    ) async -> some ApplicationProtocol {
-        await application(
+    ) async throws -> some ApplicationProtocol {
+        try await application(
             reader: reader(
                 staticFilesPath: staticFilesPath,
                 strictTransportSecurity: strictTransportSecurity
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
index dcf3654..5c9d190 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -39,7 +39,7 @@ struct HealthControllerTests {
             driver: .inMemory,
             logger: Logger(label: "test")
         )
-        let fluent = service()
+        let fluent = try service()
 
         do {
             try await app(
@@ -70,7 +70,7 @@ struct HealthControllerTests {
         // Port 1 on the loopback interface has nothing listening, so the probe's connection is refused
         // immediately instead of timing out.
         let service = Service(
-            driver: .mysql(
+            driver: .postgres(
                 .init(
                     host: "127.0.0.1",
                     port: 1,
@@ -83,7 +83,7 @@ struct HealthControllerTests {
             ),
             logger: Logger(label: "test")
         )
-        let fluent = service()
+        let fluent = try service()
 
         do {
             try await app(
-- 
2.54.0


From 6156cf5b0de604c2b6f0b1897c9e54aed3858318 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 16:19:04 +0200
Subject: [PATCH 053/117] Migrated the Website service tooling to use
 PostgreSQL instead.

---
 Services/Website/.env.local                  | 14 +++++------
 Services/Website/Makefile                    | 19 ++++++++-------
 Services/Website/docker-compose.override.yml | 25 +++++++++-----------
 Services/Website/docker-compose.yml          | 10 ++++----
 4 files changed, 33 insertions(+), 35 deletions(-)

diff --git a/Services/Website/.env.local b/Services/Website/.env.local
index 865548e..64d9a99 100644
--- a/Services/Website/.env.local
+++ b/Services/Website/.env.local
@@ -37,25 +37,25 @@ LOG_LEVEL=debug
 
 # --- Persistence ----------------------------------------------------------------
 
-# Persistence driver: inMemory (default, no infrastructure) or mysql.
+# Persistence driver: inMemory (default, no infrastructure) or postgres.
 DATABASE_DRIVER=inMemory
 
-# MySQL/MariaDB connection, used when DATABASE_DRIVER=mysql.
-# `mariadb` is the local database's Compose service name; use 127.0.0.1 when
+# PostgreSQL connection, used when DATABASE_DRIVER=postgres.
+# `postgres` is the local database's Compose service name; use 127.0.0.1 when
 # running the app directly with `swift run`.
 DATABASE_HOST=localhost
 
 # Port of the database to connect to.
-DATABASE_PORT=3306
+DATABASE_PORT=5432
 
 # Name of the database to connect to.
-DATABASE_NAME=loud-ams
+DATABASE_NAME=loud
 
 # Username of the database to connect as.
-DATABASE_USERNAME=loud-ams
+DATABASE_USERNAME=loud
 
 # Provide the real password via the environment or a secret — never commit it.
-DATABASE_PASSWORD=loud-ams
+DATABASE_PASSWORD=loud
 
 # TLS posture when connecting: off | prefer | require (use `require` in production).
 DATABASE_TLS=off
diff --git a/Services/Website/Makefile b/Services/Website/Makefile
index 2ed486e..a81fb8a 100644
--- a/Services/Website/Makefile
+++ b/Services/Website/Makefile
@@ -73,11 +73,11 @@ db-mount: ## Start the local database instance
 	@docker compose \
 		--profile database up \
 		--detach \
-		--wait mariadb
+		--wait postgres
 
 .PHONY: db-migrate
 db-migrate: ## Run the migrations against the local database instance
-	@DATABASE_DRIVER=mysql \
+	@DATABASE_DRIVER=postgres \
 	DATABASE_HOST=127.0.0.1 \
 	DATABASE_TLS=off \
 	swift run \
@@ -88,21 +88,22 @@ db-migrate: ## Run the migrations against the local database instance
 db-shell: ## Open a SQL shell on the local database instance
 	@docker compose \
 		--profile database \
-		exec mariadb \
-		mariadb \
-			--user=$(or $(DATABASE_USERNAME),loud) \
-			--password=$(or $(DATABASE_PASSWORD),loud) \
-			$(or $(DATABASE_NAME),loud)
+		exec \
+		--env PGPASSWORD=$(or $(DATABASE_PASSWORD),loud) \
+		postgres \
+		psql \
+			--username=$(or $(DATABASE_USERNAME),loud) \
+			--dbname=$(or $(DATABASE_NAME),loud)
 
 .PHONY: db-unmount
 db-unmount: ## Stop and remove the local database instance (keeps the data volume)
 	@docker compose \
-		--profile database down mariadb
+		--profile database down postgres
 
 .PHONY: db-reset
 db-reset: ## Stop and remove the local database instance and delete its data volume
 	@docker compose \
-		--profile database down mariadb \
+		--profile database down postgres \
 		--volumes
 
 # --- Assets minification ------------------------------------------------------
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
index 4ca579d..e3101da 100644
--- a/Services/Website/docker-compose.override.yml
+++ b/Services/Website/docker-compose.override.yml
@@ -23,31 +23,28 @@ services:
   # Local development database, started only with the `database` profile so a plain `docker compose up` still runs the
   # in-memory backend:
   #
-  #   docker compose --profile database up mariadb
-  mariadb:
-    image: mariadb:11
+  #   docker compose --profile database up postgres
+  postgres:
+    image: postgres:18
     container_name: ${HOST_OWNER:-loud}-db
     restart: unless-stopped
     profiles:
       - database
     ports:
-      - "127.0.0.1:${DATABASE_PORT:-3306}:3306"
+      - "127.0.0.1:${DATABASE_PORT:-5432}:5432"
     environment:
-      MARIADB_RANDOM_ROOT_PASSWORD: "yes"
-      MARIADB_DATABASE: ${DATABASE_NAME:-loud-ams}
-      MARIADB_USER: ${DATABASE_USERNAME:-loud-ams}
-      MARIADB_PASSWORD: ${DATABASE_PASSWORD:-loud-ams}
-      MARIADB_AUTO_UPGRADE: "1"
-    command:
-      - "--character-set-server=utf8mb4"
-      - "--collation-server=utf8mb4_unicode_ci"
+      POSTGRES_DB: ${DATABASE_NAME:-loud}
+      POSTGRES_USER: ${DATABASE_USERNAME:-loud}
+      POSTGRES_PASSWORD: ${DATABASE_PASSWORD:-loud}
     security_opt:
       - no-new-privileges:true
     healthcheck:
-      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+      test: ["CMD-SHELL", "pg_isready --username=$${POSTGRES_USER} --dbname=$${POSTGRES_DB}"]
       interval: 5s
       timeout: 5s
       retries: 10
       start_period: 30s
     volumes:
-      - ./Tests/DB:/var/lib/mysql
+      # postgres:18 keeps its data directory under /var/lib/postgresql/<major>/docker, so the whole
+      # /var/lib/postgresql tree is mounted — not the pre-18 /var/lib/postgresql/data path.
+      - ./Tests/DB:/var/lib/postgresql
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index 06c973c..17c03e1 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -20,13 +20,13 @@ services:
       LOG_LEVEL: ${LOG_LEVEL:-info}
       HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-LoudWebsite}
       SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
-      # Persistence: in-memory by default; set DATABASE_DRIVER=mysql to run against a managed MySQL/MariaDB database.
+      # Persistence: in-memory by default; set DATABASE_DRIVER=postgres to run against a managed PostgreSQL database.
       # Provide the password via the environment or a secret — never commit it.
-      DATABASE_DRIVER: ${DATABASE_DRIVER:-mysql}
+      DATABASE_DRIVER: ${DATABASE_DRIVER:-postgres}
       DATABASE_HOST: ${DATABASE_HOST:-localhost}
-      DATABASE_PORT: ${DATABASE_PORT:-3306}
-      DATABASE_NAME: ${DATABASE_NAME:-loud-ams}
-      DATABASE_USERNAME: ${DATABASE_USERNAME:-loud-ams}
+      DATABASE_PORT: ${DATABASE_PORT:-5432}
+      DATABASE_NAME: ${DATABASE_NAME:-loud}
+      DATABASE_USERNAME: ${DATABASE_USERNAME:-loud}
       DATABASE_PASSWORD: ${DATABASE_PASSWORD:-}
       DATABASE_TLS: ${DATABASE_TLS:-prefer}
     healthcheck:
-- 
2.54.0


From f8a263168ec936bdd2f85548078af83fb0c2e3f4 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 16:42:28 +0200
Subject: [PATCH 054/117] Updated the documentation for the Website service
 target to name/reference PostgreSQL instead.

---
 Services/Website/README.md | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/Services/Website/README.md b/Services/Website/README.md
index f2325ac..dd240ae 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -10,7 +10,7 @@ The service:
 - Returns a custom not-found (404) HTML page, localized like the landing page, for any request that matches neither a route nor a static file.
 - Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
 - Stamps a hardened set of security headers on every response.
-- Persists data through [Fluent](https://github.com/hummingbird-project/hummingbird-fluent), against either an ephemeral in-memory SQLite database (the default — no external infrastructure) or a MySQL/MariaDB server, selected by a single configuration key.
+- Persists data through [Fluent](https://github.com/hummingbird-project/hummingbird-fluent), against either an ephemeral in-memory SQLite database (the default — no external infrastructure) or a PostgreSQL server, selected by a single configuration key.
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
@@ -55,7 +55,7 @@ the following sources, **highest precedence first**:
 5. Built-in defaults
 
 The two files play different roles:
-- **`.env`** (git-ignored) holds your deployment values — it is the file the Makefile and Compose read for the `${VAR}` placeholders, and typically selects the MySQL/MariaDB backend.
+- **`.env`** (git-ignored) holds your deployment values — it is the file the Makefile and Compose read for the `${VAR}` placeholders, and typically selects the PostgreSQL backend.
 - **`.env.local`** (tracked) holds the local development values — the in-memory database and `debug` logging, plus the image/deployment placeholders the Makefile falls back to when no `.env` exists. Because it sits *above* `.env`, a direct launch (`swift run` or a debugger) runs against the local values even when `.env` points at a deployment, the same way `docker-compose.override.yml` overrides the base Compose file. Compose itself never reads it, and the production image does not ship it — only the executable, its resources, and the static files are staged into the final stage.
 
 ### Environment variable naming
@@ -92,10 +92,10 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 ### Persistence
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `database.driver` | `DATABASE_DRIVER` | `inMemory` | Backend: `inMemory` (ephemeral SQLite, no infrastructure) or `mysql` (MySQL/MariaDB). |
+| `database.driver` | `DATABASE_DRIVER` | `inMemory` | Backend: `inMemory` (ephemeral SQLite, no infrastructure) or `postgres` (PostgreSQL). |
 | `database.migrate` | `DATABASE_MIGRATE` (flag `--database-migrate`) | `false` | When set, run the migrations and exit instead of serving. |
-| `database.host` | `DATABASE_HOST` | `localhost` | MySQL/MariaDB host. Ignored for `inMemory`. |
-| `database.port` | `DATABASE_PORT` | `3306` | MySQL/MariaDB port. Ignored for `inMemory`. |
+| `database.host` | `DATABASE_HOST` | `localhost` | PostgreSQL host. Ignored for `inMemory`. |
+| `database.port` | `DATABASE_PORT` | `5432` | PostgreSQL port. Ignored for `inMemory`. |
 | `database.name` | `DATABASE_NAME` | `loud` | Database name. Ignored for `inMemory`. |
 | `database.username` | `DATABASE_USERNAME` | `loud` | Database username. Ignored for `inMemory`. |
 | `database.password` | `DATABASE_PASSWORD` | _(empty)_ | Database password. Provide via the environment/a secret — never commit it. |
@@ -136,7 +136,7 @@ swift run Website # binds to Hummingbird's default 127.0.0.1:8080
 swift run Website --http-host 0.0.0.0 --http-port 9000 --log-level debug
 ```
 
-A direct run picks up the local development overrides from `.env.local` (in-memory database, `debug` logging) over whatever `.env` configures. To run against another backend, override per launch — e.g. `DATABASE_DRIVER=mysql swift run Website` — since process environment variables outrank both files.
+A direct run picks up the local development overrides from `.env.local` (in-memory database, `debug` logging) over whatever `.env` configures. To run against another backend, override per launch — e.g. `DATABASE_DRIVER=postgres swift run Website` — since process environment variables outrank both files.
 
 Or via the Makefile / Docker (uses `docker-compose.override.yml`, which builds from source and sets `LOG_LEVEL=debug`):
 ```sh
@@ -154,8 +154,8 @@ The service persists data through Fluent and selects its backend at runtime with
 ### In-memory (default)
 With no configuration, the service uses an ephemeral in-memory SQLite database. It is created and **migrated on startup** every launch, so `swift run Website` and `docker compose up` work with no external database — ideal for local development and tests.
 
-### MySQL / MariaDB
-Set `DATABASE_DRIVER=mysql` and the connection values (`DATABASE_HOST`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, …). Unlike the in-memory backend, a MySQL/MariaDB database is **not** migrated on boot — a shared database is migrated out of band so multiple instances never race:
+### PostgreSQL
+Set `DATABASE_DRIVER=postgres` and the connection values (`DATABASE_HOST`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, …). Unlike the in-memory backend, a PostgreSQL database is **not** migrated on boot — a shared database is migrated out of band so multiple instances never race:
 ```sh
 # Run the registered migrations against the configured database, then exit.
 swift run Website --database-migrate
@@ -163,14 +163,14 @@ swift run Website --database-migrate
 docker compose -f docker-compose.yml run --rm website --database-migrate
 ```
 
-A local MariaDB for development lives behind the `database` Compose profile (so a plain `docker compose up` still runs in-memory). Its data directory is bind-mounted to `Tests/DB` (git-ignored), so the database survives `db-unmount` and container restarts:
+A local PostgreSQL for development lives behind the `database` Compose profile (so a plain `docker compose up` still runs in-memory). Its data directory is bind-mounted to `Tests/DB` (git-ignored), so the database survives `db-unmount` and container restarts:
 ```sh
-make db-mount     # start MariaDB (docker compose --profile database up --wait mariadb)
+make db-mount     # start PostgreSQL (docker compose --profile database up --wait postgres)
 make db-migrate   # run migrations against it
-make db-shell     # open a SQL shell on it
+make db-shell     # open a SQL shell on it (psql)
 make db-unmount   # stop and remove the container (data kept in Tests/DB)
 make db-reset     # stop and remove the container
-DATABASE_DRIVER=mysql make site-mount   # run the site against MariaDB
+DATABASE_DRIVER=postgres make site-mount   # run the site against PostgreSQL
 ```
 > **Note:** because the data lives in the bind-mounted `Tests/DB` folder rather than a named volume, `db-reset`'s `--volumes` flag does **not** clear it. To start from an empty database, delete `Tests/DB` by hand.
 
@@ -187,11 +187,11 @@ make pkg-test
 
 Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Tests/Website.xctestplan` covers the service's two targets — `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests) — plus the local packages' suites: `InfrastructureTests`, `PersistenceTests`, `LocalizationTests`, and `UtilityTests`.
 
-The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the MySQL integration test is skipped unless a database is pointed at via `MYSQL_TEST_HOST` (with optional `MYSQL_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
+The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the PostgreSQL integration test is skipped unless a database is pointed at via `POSTGRES_TEST_HOST` (with optional `POSTGRES_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
 ```sh
 cd ../../Packages/Persistence && swift test                      # in-memory only
-# With the local MariaDB up (make db-mount):
-cd ../../Packages/Persistence && MYSQL_TEST_HOST=127.0.0.1 swift test
+# With the local PostgreSQL up (make db-mount):
+cd ../../Packages/Persistence && POSTGRES_TEST_HOST=127.0.0.1 swift test
 ```
 
 ## Deployment
@@ -262,8 +262,8 @@ The Makefile and Compose files read these from a `.env` file (or the environment
 | `LOG_LEVEL` | Runtime log level (default `info`). |
 | `HTTP_SERVER_NAME` | Runtime server name (default `LoudWebsite`). |
 | `SECURITY_STRICT_TRANSPORT_SECURITY` | HSTS header value (default `max-age=31536000; includeSubDomains`). |
-| `DATABASE_DRIVER` | `inMemory` or `mysql`. The production Compose file defaults it to `mysql`; the local override defaults back to the in-memory backend. |
-| `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` | MySQL/MariaDB connection (when `DATABASE_DRIVER=mysql`). Provide the password via a secret. |
+| `DATABASE_DRIVER` | `inMemory` or `postgres`. The production Compose file defaults it to `postgres`; the local override defaults back to the in-memory backend. |
+| `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` | PostgreSQL connection (when `DATABASE_DRIVER=postgres`). Provide the password via a secret. |
 | `DATABASE_TLS` | TLS posture when connecting: `off`, `prefer`, or `require` (default `prefer` in production — set `require` when the database enforces TLS, so a stripped connection fails instead of silently downgrading to plaintext). |
 
 Run the migrations against the production database once before (or during) rollout: `docker compose -f docker-compose.yml run --rm website --database-migrate`.
-- 
2.54.0


From 52f092a4d77196049eb2aa684e320ba9e862cdc5 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 16:49:54 +0200
Subject: [PATCH 055/117] Refactored the startup reply in the fake PostgreSQL
 server in the Persistence tests target.

---
 .../Utils/Fakes/PlaintextPostgresServer.swift | 27 +++++++++----------
 1 file changed, 13 insertions(+), 14 deletions(-)

diff --git a/Packages/Persistence/Tests/Utils/Fakes/PlaintextPostgresServer.swift b/Packages/Persistence/Tests/Utils/Fakes/PlaintextPostgresServer.swift
index d19762a..0df114d 100644
--- a/Packages/Persistence/Tests/Utils/Fakes/PlaintextPostgresServer.swift
+++ b/Packages/Persistence/Tests/Utils/Fakes/PlaintextPostgresServer.swift
@@ -99,7 +99,7 @@ private extension PlaintextPostgresServer {
             context: ChannelHandlerContext,
             data: NIOAny
         ) {
-            var buffer = unwrapInboundIn(data)
+            let buffer = unwrapInboundIn(data)
 
             switch state {
             case .awaitingSSLRequest:
@@ -107,13 +107,7 @@ private extension PlaintextPostgresServer {
                 // 'N', while a direct startup message (a client connecting with TLS disabled) is
                 // answered straight away.
                 guard buffer.getInteger(at: buffer.readerIndex + 4, as: Int32.self) == Self.sslRequestCode else {
-                    state = .established
-
-                    context.writeAndFlush(
-                        wrapOutboundOut(Self.startupResponse(allocator: context.channel.allocator)),
-                        promise: nil
-                    )
-
+                    completeStartup(context: context)
                     return
                 }
 
@@ -128,17 +122,22 @@ private extension PlaintextPostgresServer {
                     promise: nil
                 )
             case .awaitingStartup:
-                state = .established
-
-                context.writeAndFlush(
-                    wrapOutboundOut(Self.startupResponse(allocator: context.channel.allocator)),
-                    promise: nil
-                )
+                completeStartup(context: context)
             case .established:
                 context.close(promise: nil)
             }
         }
 
+        /// Answers a startup message and marks the connection established.
+        private func completeStartup(context: ChannelHandlerContext) {
+            state = .established
+
+            context.writeAndFlush(
+                wrapOutboundOut(Self.startupResponse(allocator: context.channel.allocator)),
+                promise: nil
+            )
+        }
+
         // MARK: Helpers
 
         /// The reply completing a plaintext startup: `AuthenticationOk`, `BackendKeyData`, and
-- 
2.54.0


From e51f09c66fddaab27e8e0b08794301a9c2d873e6 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 16:58:32 +0200
Subject: [PATCH 056/117] Added PostgresNIO and NIOSSL to the Persistence
 library target.

---
 Packages/Persistence/Package.swift | 12 ++++++++----
 Packages/Persistence/README.md     |  2 +-
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/Packages/Persistence/Package.swift b/Packages/Persistence/Package.swift
index 8317309..85dba7c 100644
--- a/Packages/Persistence/Package.swift
+++ b/Packages/Persistence/Package.swift
@@ -65,6 +65,14 @@ let package = Package(
                     name: "SQLKit",
                     package: "sql-kit"
                 ),
+                .product(
+                    name: "PostgresNIO",
+                    package: "postgres-nio"
+                ),
+                .product(
+                    name: "NIOSSL",
+                    package: "swift-nio-ssl"
+                ),
             ],
             path: "Sources"
         ),
@@ -84,10 +92,6 @@ let package = Package(
                     name: "NIOPosix",
                     package: "swift-nio"
                 ),
-                .product(
-                    name: "NIOSSL",
-                    package: "swift-nio-ssl"
-                ),
             ],
             path: "Tests"
         ),
diff --git a/Packages/Persistence/README.md b/Packages/Persistence/README.md
index f0ddddb..278c173 100644
--- a/Packages/Persistence/README.md
+++ b/Packages/Persistence/README.md
@@ -57,4 +57,4 @@ Every suite carries a tag naming the kind of API it exercises — `.enumeration`
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
 - macOS 15, matching the sibling `Infrastructure` and `Localization` packages (the services deploy to Linux containers; the packages carry no UI platforms).
-- Package dependencies: `hummingbird-fluent`, `fluent-postgres-driver`, `fluent-sqlite-driver`, and `sql-kit`; the test target additionally depends on `postgres-nio`, `swift-nio`, and `swift-nio-ssl` for the TLS fallback tests.
+- Package dependencies: `hummingbird-fluent`, `fluent-postgres-driver`, `fluent-sqlite-driver`, `sql-kit`, `postgres-nio`, and `swift-nio-ssl`; the test target additionally depends on `swift-nio` for the TLS fallback tests' fake server.
-- 
2.54.0


From 0796aa314e647c3670c308c95d76b7559ce9d1d6 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 4 Aug 2026 16:59:43 +0200
Subject: [PATCH 057/117] Moved the PostgreSQL TLS context building to the
 Service initialiser in the Persistence package.

---
 .../Sources/Public/Methods/Service.swift      | 39 ++++++++++++++-----
 .../Cases/Public/Methods/ProbeTests.swift     |  8 ++--
 .../Cases/Public/Methods/ServiceTests.swift   | 16 ++++----
 .../Sources/App/Extensions/App+Build.swift    |  8 ++--
 .../Controllers/HealthControllerTests.swift   |  8 ++--
 5 files changed, 50 insertions(+), 29 deletions(-)

diff --git a/Packages/Persistence/Sources/Public/Methods/Service.swift b/Packages/Persistence/Sources/Public/Methods/Service.swift
index 67bf4de..bf2dec2 100644
--- a/Packages/Persistence/Sources/Public/Methods/Service.swift
+++ b/Packages/Persistence/Sources/Public/Methods/Service.swift
@@ -2,16 +2,25 @@ import FluentPostgresDriver
 import FluentSQLiteDriver
 import HummingbirdFluent
 import Logging
+import PostgresNIO
 
 /// A factory building the `Fluent` service the application persists through.
 ///
 /// Built once around the driver the executable picks at startup and called as a function to produce the configured service: `let fluent = service()`.
 public struct Service: Sendable {
 
+    // MARK: Enumerations
+
+    /// The persistence backend resolved at construction, with the PostgreSQL TLS mode already built.
+    private enum Backend {
+        case postgres(Configuration, PostgresConnection.Configuration.TLS)
+        case inMemory
+    }
+
     // MARK: Properties
 
-    /// The persistence backend to register.
-    private let driver: Driver
+    /// The resolved persistence backend to register.
+    private let backend: Backend
 
     /// The logger the database emits through.
     private let logger: Logger
@@ -19,14 +28,27 @@ public struct Service: Sendable {
     // MARK: Initializers
 
     /// Creates a factory for a `Fluent` service backed by the given driver.
+    ///
+    /// The TLS context for the PostgreSQL backend is built here, once — the factory holds only resolved configuration, so producing the
+    /// service afterwards cannot fail.
     /// - Parameters:
     ///   - driver: the persistence backend to register.
     ///   - logger: the logger the database emits through.
+    /// - Throws: an error when the TLS context for the PostgreSQL backend cannot be built.
     public init(
         driver: Driver,
         logger: Logger
-    ) {
-        self.driver = driver
+    ) throws {
+        switch driver {
+        case .postgres(let configuration):
+            self.backend = .postgres(
+                configuration,
+                try configuration.tls.postgresTLS()
+            )
+        case .inMemory:
+            self.backend = .inMemory
+        }
+
         self.logger = logger
     }
 
@@ -37,15 +59,14 @@ public struct Service: Sendable {
     /// The selected backend is registered as the *default* database, so repositories resolve it with a plain `fluent.db()` and stay agnostic of which
     /// driver is in use. The returned service is not yet running; add it to the application's service group (`app.addServices(_:)`) so it starts and shuts
     /// its connection pool down alongside the server.
-    /// - Throws: an error when the TLS context for the PostgreSQL backend cannot be built.
     /// - Returns: the configured `Fluent` service, ready to be added to the service group.
-    public func callAsFunction() throws -> Fluent {
+    public func callAsFunction() -> Fluent {
         let fluent = Fluent(
             logger: logger
         )
 
-        switch driver {
-        case .postgres(let configuration):
+        switch backend {
+        case .postgres(let configuration, let tls):
             fluent.databases.use(
                 .postgres(
                     configuration: .init(
@@ -54,7 +75,7 @@ public struct Service: Sendable {
                         username: configuration.username,
                         password: configuration.password,
                         database: configuration.name,
-                        tls: try configuration.tls.postgresTLS()
+                        tls: tls
                     ),
                     maxConnectionsPerEventLoop: configuration.maxConnectionsPerEventLoop
                 ),
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
index 64971b6..9029fcd 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
@@ -15,11 +15,11 @@ struct ProbeTests {
 
     @Test
     func `reports a reachable database`() async throws {
-        let service = Service(
+        let service = try Service(
             driver: .inMemory,
             logger: Logger(label: "test")
         )
-        let fluent = try service()
+        let fluent = service()
         let probe = Probe(fluent: fluent)
 
         let isReachable = await probe()
@@ -33,7 +33,7 @@ struct ProbeTests {
     func `reports an unreachable database`() async throws {
         // Port 1 on the loopback interface has nothing listening, so the connection is refused
         // immediately instead of timing out.
-        let service = Service(
+        let service = try Service(
             driver: .postgres(
                 .init(
                     host: "127.0.0.1",
@@ -47,7 +47,7 @@ struct ProbeTests {
             ),
             logger: Logger(label: "test")
         )
-        let fluent = try service()
+        let fluent = service()
         let probe = Probe(fluent: fluent)
 
         let isReachable = await probe()
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
index 6b84904..8c7afd7 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
@@ -15,12 +15,12 @@ struct ServiceTests {
 
     @Test
     func `registers an SQLite database as the default for the in-memory driver`() async throws {
-        let service = Service(
+        let service = try Service(
             driver: .inMemory,
             logger: Logger(label: "test")
         )
 
-        let fluent = try service()
+        let fluent = service()
         let database = fluent.db() as? any SQLDatabase
 
         try await fluent.shutdown()
@@ -34,7 +34,7 @@ struct ServiceTests {
     func `registers a PostgreSQL database as the default for the postgres driver`() async throws {
         // Resolving the default database opens no connection — pooling is lazy — so no server
         // needs to be listening on the configured host and port.
-        let service = Service(
+        let service = try Service(
             driver: .postgres(
                 .init(
                     host: "127.0.0.1",
@@ -49,7 +49,7 @@ struct ServiceTests {
             logger: Logger(label: "test")
         )
 
-        let fluent = try service()
+        let fluent = service()
         let database = fluent.db() as? any SQLDatabase
 
         try await fluent.shutdown()
@@ -61,12 +61,12 @@ struct ServiceTests {
 
     @Test
     func `builds a usable in-memory database`() async throws {
-        let service = Service(
+        let service = try Service(
             driver: .inMemory,
             logger: Logger(label: "test")
         )
 
-        let fluent = try service()
+        let fluent = service()
 
         do {
             let database = try #require(fluent.db() as? any SQLDatabase)
@@ -116,12 +116,12 @@ private extension ServiceTests {
         revertAfter: Bool = false
     ) async throws {
         let prepareDB = PrepareDB()
-        let service = Service(
+        let service = try Service(
             driver: driver,
             logger: Logger(label: "test")
         )
 
-        let fluent = try service()
+        let fluent = service()
 
         do {
             await prepareDB(for: fluent)
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 61c5894..56b5caa 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -34,11 +34,11 @@ func application(
         logger.warning("String Catalog is \(isCatalogMissing ? "missing" : "undecodable"); pages will serve raw localization keys")
     }
 
-    let persistence = Service(
+    let persistence = try Service(
         driver: reader.driver,
         logger: logger
     )
-    let fluent = try persistence()
+    let fluent = persistence()
 
     let fingerprintAssets = FingerprintAssets(logger: logger)
     let prepareDB = PrepareDB()
@@ -88,12 +88,12 @@ func migration(
         serverName: reader.serverName,
         logLevel: reader.logLevel
     )
-    let service = Service(
+    let service = try Service(
         driver: reader.driver,
         logger: logger
     )
 
-    let fluent = try service()
+    let fluent = service()
     let prepareDB = PrepareDB()
 
     await prepareDB(for: fluent)
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
index 5c9d190..3a89f10 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -35,11 +35,11 @@ struct HealthControllerTests {
 
     @Test
     func `serves ready at the readiness path when the database is reachable`() async throws {
-        let service = Service(
+        let service = try Service(
             driver: .inMemory,
             logger: Logger(label: "test")
         )
-        let fluent = try service()
+        let fluent = service()
 
         do {
             try await app(
@@ -69,7 +69,7 @@ struct HealthControllerTests {
     func `serves unavailable at the readiness path when the database is unreachable`() async throws {
         // Port 1 on the loopback interface has nothing listening, so the probe's connection is refused
         // immediately instead of timing out.
-        let service = Service(
+        let service = try Service(
             driver: .postgres(
                 .init(
                     host: "127.0.0.1",
@@ -83,7 +83,7 @@ struct HealthControllerTests {
             ),
             logger: Logger(label: "test")
         )
-        let fluent = try service()
+        let fluent = service()
 
         do {
             try await app(
-- 
2.54.0


From 98cfbdd105351212b2d9bda8612e873c146621f9 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 10 Aug 2026 16:05:55 +0200
Subject: [PATCH 058/117] Updated the "db-reset" task in the Makefile in the
 Website service to actually delete the local data.

---
 Services/Website/Makefile | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Services/Website/Makefile b/Services/Website/Makefile
index a81fb8a..35fd8b7 100644
--- a/Services/Website/Makefile
+++ b/Services/Website/Makefile
@@ -96,15 +96,19 @@ db-shell: ## Open a SQL shell on the local database instance
 			--dbname=$(or $(DATABASE_NAME),loud)
 
 .PHONY: db-unmount
-db-unmount: ## Stop and remove the local database instance (keeps the data volume)
+db-unmount: ## Stop and remove the local database instance while keeping its data
 	@docker compose \
 		--profile database down postgres
 
 .PHONY: db-reset
-db-reset: ## Stop and remove the local database instance and delete its data volume
+db-reset: ## Stop and remove the local database instance, then delete its data
 	@docker compose \
 		--profile database down postgres \
 		--volumes
+	@if [ -d Tests/DB ]; then \
+		rm -rf Tests/DB; \
+		mkdir -p Tests/DB; \
+	fi
 
 # --- Assets minification ------------------------------------------------------
 
-- 
2.54.0


From a88569ad4c721c2941360c8bab53ea4181358af1 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 10 Aug 2026 16:33:31 +0200
Subject: [PATCH 059/117] Improved the verbosity of the documentation for the
 README file in the packages.

---
 Packages/Infrastructure/README.md | 13 ++++++-------
 Packages/Localization/README.md   | 11 +++++------
 Packages/Persistence/README.md    | 26 +++++++++++---------------
 Packages/Utility/README.md        |  5 ++---
 4 files changed, 24 insertions(+), 31 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index dfc8bd7..9297df6 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -2,7 +2,6 @@
 The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) toolkit the **Loud** services build on: declarative routing, hardened HTTP middlewares, pre-rendered localized HTML responses, and the page and asset scaffolding.
 
 ## Overview
-The package provides, grouped by role:
 | Role | Types |
 | --- | --- |
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
@@ -17,9 +16,9 @@ The package provides, grouped by role:
 
 ## Design rules
 The package holds only what every service can reuse; anything a service owns is injected, never referenced:
-- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and the `metadata` requirement through which a `Page` conformer supplies its icon links and theme colors — as are the `summary`, `canonicalURL`, `socialCard`, `structuredData`, and `analytics` values its other head tags render, each omitted unless the page provides it. A `SocialCard` and a `StructuredData` node take their URLs fully formed and absolute, as does an `Analytics` its script URL; composing them from an origin and a versioned asset path stays with the page providing them.
-- **Types own their format; `Page` renders generically.** Each optional head concern derives its own render-ready representation — the `SocialCard.tags` meta tags, the `StructuredData.payload` JSON-LD, the `Analytics.attributes` script attributes — and the `Page` scaffolding applies it without knowing the vocabulary (Open Graph, schema.org, or the Umami tracker convention). The page ``scripts`` and the analytics tracker render as `defer`red head tags, with a `preconnect` hint for the tracker's cross-origin host.
-- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern to follow. The open schema.org vocabularies extend the same way: the package declares only the `Property.Name` and `Node.Kind` constants every service shares, and a service adds the ones its own node shapes need.
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and a `Page` conformer's `metadata` — along with the `summary`, `canonicalURL`, `socialCard`, `structuredData`, and `analytics` its other head tags render, each omitted unless the page provides it. URLs arrive fully formed and absolute: composing them from an origin and a versioned asset path stays with the page.
+- **Types own their format; `Page` renders generically.** Each optional head concern derives its own render-ready representation — `SocialCard.tags`, `StructuredData.payload`, `Analytics.attributes` — and the `Page` scaffolding applies it without knowing the vocabulary (Open Graph, schema.org, or the Umami convention). Page ``scripts`` and the tracker render as `defer`red head tags, with a `preconnect` hint for the tracker's cross-origin host.
+- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern. The open schema.org vocabularies extend the same way: the package declares only the `Property.Name` and `Node.Kind` constants every service shares, and a service adds what its own node shapes need.
 - **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
 ## Layout
@@ -34,7 +33,7 @@ Sources/
 │   ├── Middlewares/       the five HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
 │   ├── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
-│   └── Types/             Analytics, SocialCard, and StructuredData, the latter two with their nested types in SocialCard/ and StructuredData/
+│   └── Types/             Analytics, SocialCard, StructuredData (the latter two nesting their own types in SocialCard/ and StructuredData/)
 └── Internal/
     ├── Extensions/        implementation details (the String separators)
     └── Types/             implementation details (FNV1aHash)
@@ -45,8 +44,8 @@ Tests/
 ```
 
 ## Testing
-Every suite carries a tag naming the kind of API it exercises — `.asset`, `.extension`, `.middleware`, `.protocol`, or `.type`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
+Every suite carries a tag for the kind of API it exercises — `.asset`, `.extension`, `.middleware`, `.protocol`, or `.type`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and summaries can slice a run by kind. A new suite adopts the tag matching its subject, or adds one when none fits.
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
-- macOS 15, matching the sibling `Localization`, `Persistence`, and `Utility` packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- macOS 15, matching the sibling packages (the services deploy to Linux containers; the packages carry no UI platforms).
diff --git a/Packages/Localization/README.md b/Packages/Localization/README.md
index e0a1c40..db9263a 100644
--- a/Packages/Localization/README.md
+++ b/Packages/Localization/README.md
@@ -2,7 +2,6 @@
 The server-side localization toolkit the **Loud** services build on: locale-explicit String Catalog lookups, `Accept-Language` negotiation, and the catalog-derived language list — with no dependencies beyond Foundation.
 
 ## Overview
-The package provides, grouped by role:
 | Role | Types |
 | --- | --- |
 | Lookup | `Localize`, a bundle-bound localizer that resolves a catalog key for an explicit locale |
@@ -11,10 +10,10 @@ The package provides, grouped by role:
 | Diagnostics | `CatalogState`, the outcome of reading the catalog (`loaded`, `missing`, or `undecodable`) |
 
 ## Design rules
-- **The String Catalog is the single source of truth.** Supported languages, the default language, and every string come from the bundle's `Localizable.xcstrings`. Adding a language is a translation-only change — once a locale exists in the catalog, `LanguageList` and `Negotiate` pick it up with no code change.
+- **The String Catalog is the single source of truth.** Supported languages, the default language, and every string come from the bundle's `Localizable.xcstrings`, so adding a language is a translation-only change — `LanguageList` and `Negotiate` pick up a new locale with no code change.
 - **The locale is always explicit.** A server has no single "current" locale, so every lookup names the locale to resolve in; nothing reads process-wide locale state.
-- **Raw `.xcstrings` parsing, for Linux parity.** The catalog is decoded from its JSON rather than through Foundation's compiled-catalog APIs, which are unavailable or non-functional on Linux. Consumers must `.copy` the catalog resource verbatim (not `.process` it) so it ships as raw JSON on every platform. Only simple `stringUnit` values are decoded; plural and device variations are not represented.
-- **Resolution never fails.** A missing entry falls back to the source-language string, then to the key itself; a missing or undecodable catalog degrades the language list to the default. Check `catalogState` once at startup and warn when it is not `.loaded`, before visitors ever see raw keys.
+- **Raw `.xcstrings` parsing, for Linux parity.** The catalog is decoded from its JSON rather than through Foundation's compiled-catalog APIs, which are unavailable or non-functional on Linux. Consumers must `.copy` the resource verbatim (never `.process` it) so it ships as raw JSON everywhere. Only simple `stringUnit` values are decoded — plural and device variations are not.
+- **Resolution never fails.** A missing entry falls back to the source-language string, then to the key itself; a missing or undecodable catalog degrades the language list to the default. Check `catalogState` once at startup and warn when it is not `.loaded`, before visitors see raw keys.
 - **Method structs.** `Localize` and `Negotiate` hold their lifetime-fixed configuration (the bundle) in `init` and take only per-call inputs in `callAsFunction`.
 - **One decoded catalog per bundle.** Catalogs are immutable at runtime, so every `Localize`, `Negotiate`, and `LanguageList` bound to the same bundle and table shares one cached `StringCatalog`.
 
@@ -36,9 +35,9 @@ Tests/
 ```
 
 ## Testing
-Every suite carries a tag naming the kind of API it exercises — `.method` or `.type`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
+Every suite carries a tag for the kind of API it exercises — `.method` or `.type`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and summaries can slice a run by kind. A new suite adopts the tag matching its subject, or adds one when none fits.
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
-- macOS 15, matching the sibling `Infrastructure` and `Persistence` packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- macOS 15, matching the sibling packages (the services deploy to Linux containers; the packages carry no UI platforms).
 - No package dependencies — Foundation and Synchronization only.
diff --git a/Packages/Persistence/README.md b/Packages/Persistence/README.md
index 278c173..c881d74 100644
--- a/Packages/Persistence/README.md
+++ b/Packages/Persistence/README.md
@@ -2,7 +2,6 @@
 The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based data layer the **Loud** services build on: runtime selection between a PostgreSQL backend and an ephemeral in-memory SQLite one, single-place migration registration, and a database readiness probe.
 
 ## Overview
-The package provides, grouped by role:
 | Role | Types |
 | --- | --- |
 | Backend selection | `Driver` (`postgres` or `inMemory`), `Configuration` (the PostgreSQL connection parameters), `TLS` (the connection's TLS posture) |
@@ -12,15 +11,15 @@ The package provides, grouped by role:
 | Scaffolding (internal) | `ExampleRecord`, `CreateExampleRecord`, and `ExampleRepository` — the model → migration → repository pattern, to be replaced by the first real domain model |
 
 ## Design rules
-- **The package reads no configuration.** The executable maps its `database.*` keys onto a `Driver` and hands it over; connection values arrive as plain data. See the Website service's `ConfigReader+Properties` for the mapping.
+- **The package reads no configuration.** The executable maps its `database.*` keys onto a `Driver` and hands it over; connection values arrive as plain data. The Website service's `ConfigReader+Properties` has the mapping.
 - **One default database.** `Service` registers the selected backend as the *default* database, so repositories resolve it with a plain `fluent.db()` and stay agnostic of which driver is in use.
-- **Migrations are declared once, and append-only.** `PrepareDB` is the single place migrations are registered, in the order they must run; alter the schema by adding a new migration, never by editing one that has already run. Registering does not apply them — the in-memory backend is migrated on startup, while a shared PostgreSQL database is migrated out of band (the executable's migrate-and-exit mode), so multiple booting instances never race.
-- **Models never cross a concurrency boundary.** FluentKit models are mutable reference types; repositories map them to `Sendable` value-type snapshots (e.g. `Example`) before returning, and the models themselves stay internal to the package.
+- **Migrations are declared once, and append-only.** `PrepareDB` registers every migration in the order it must run; alter the schema by adding a migration, never by editing one that has already run. Registering does not apply them: the in-memory backend migrates on startup, while a shared PostgreSQL database is migrated out of band (the executable's migrate-and-exit mode), so booting instances never race.
+- **Models never cross a concurrency boundary.** FluentKit models are mutable reference types, so they stay internal to the package and repositories return `Sendable` value-type snapshots (e.g. `Example`) instead.
 - **Readiness never throws.** `Probe` runs a `SELECT 1` — the cheapest statement both backends understand, independent of any schema — and maps every failure to `false`, so callers translate it straight into a readiness response.
-- **A single connection for the in-memory store.** The SQLite backend is capped at one connection per event loop so every query reaches the same in-memory database, rather than each pooled connection getting its own private one.
+- **A single connection for the in-memory store.** The SQLite backend is capped at one connection per event loop, so every query reaches the same in-memory database instead of each pooled connection getting a private one.
 - **Method structs.** `Service`, `PrepareDB`, and `Probe` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
-> **Note:** both TLS postures are enforced by the driver itself: `prefer` upgrades the connection only when the server advertises TLS and continues in plaintext otherwise, while `require` refuses the connection when the server offers none. Both behaviors are pinned by tests against a fake server that offers no TLS.
+> **Note:** the driver itself enforces both TLS postures — `prefer` upgrades only when the server advertises TLS and continues in plaintext otherwise, `require` refuses a server that offers none. Tests pin both against a fake plaintext-only server.
 
 ## Layout
 Sources are split by visibility, then by kind, one type per file:
@@ -41,20 +40,17 @@ Tests/
 ```
 
 ## Testing
-The suite runs against the in-memory backend by default, so `swift test` needs no database. The PostgreSQL integration test is skipped unless a database is pointed at via `POSTGRES_TEST_HOST` (with optional `POSTGRES_TEST_PORT`, `POSTGRES_TEST_NAME`, `POSTGRES_TEST_USERNAME`, and `POSTGRES_TEST_PASSWORD`); it reverts its migrations afterwards, so the shared database is left as it was found:
+The suite runs against the in-memory backend by default, so `swift test` needs no database. The PostgreSQL integration test is skipped unless `POSTGRES_TEST_HOST` points at one (with optional `POSTGRES_TEST_PORT`, `POSTGRES_TEST_NAME`, `POSTGRES_TEST_USERNAME`, and `POSTGRES_TEST_PASSWORD`); it reverts its migrations afterwards, leaving a shared database as it was found:
 ```sh
-# in-memory only
-swift test                                
-# or
-# with the local PostgreSQL up (make db-mount):
-POSTGRES_TEST_HOST=127.0.0.1 swift test
+swift test                               # in-memory only
+POSTGRES_TEST_HOST=127.0.0.1 swift test  # against the local PostgreSQL (make db-mount)
 ```
 
-Outside the application's service group, a built `Fluent` service must be shut down explicitly — even on failure — or its connection pool asserts on `deinit`; the suites' `do`/`catch` pattern around `fluent.shutdown()` is the shape to follow.
+Outside the application's service group, a built `Fluent` service must be shut down explicitly — even on failure — or its connection pool asserts on `deinit`; the suites' `do`/`catch` around `fluent.shutdown()` is the shape to follow.
 
-Every suite carries a tag naming the kind of API it exercises — `.enumeration` or `.method`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
+Every suite carries a tag for the kind of API it exercises — `.enumeration` or `.method`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and summaries can slice a run by kind. A new suite adopts the tag matching its subject, or adds one when none fits.
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
-- macOS 15, matching the sibling `Infrastructure` and `Localization` packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- macOS 15, matching the sibling packages (the services deploy to Linux containers; the packages carry no UI platforms).
 - Package dependencies: `hummingbird-fluent`, `fluent-postgres-driver`, `fluent-sqlite-driver`, `sql-kit`, `postgres-nio`, and `swift-nio-ssl`; the test target additionally depends on `swift-nio` for the TLS fallback tests' fake server.
diff --git a/Packages/Utility/README.md b/Packages/Utility/README.md
index 168ee32..5f62ff0 100644
--- a/Packages/Utility/README.md
+++ b/Packages/Utility/README.md
@@ -2,7 +2,6 @@
 The general-purpose helpers the **Loud** services share: small, single-purpose methods with no dependencies beyond Foundation and no ties to any web framework.
 
 ## Overview
-The package provides, grouped by role:
 | Role | Types |
 | --- | --- |
 | Validation | `NormalizeEmail`, which reduces a submitted email address to its canonical form |
@@ -23,9 +22,9 @@ Tests/
 ```
 
 ## Testing
-Every suite carries a tag naming the kind of API it exercises — `.method`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and result summaries can slice the run by kind. A new suite must adopt the tag matching its subject (or add a tag there if none fits).
+Every suite carries a tag for the kind of API it exercises — `.method`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and summaries can slice a run by kind. A new suite adopts the tag matching its subject, or adds one when none fits.
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
-- macOS 15, matching the sibling `Infrastructure`, `Localization`, and `Persistence` packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- macOS 15, matching the sibling packages (the services deploy to Linux containers; the packages carry no UI platforms).
 - No package dependencies — Foundation only.
-- 
2.54.0


From 19fa9d8d8cc7041c109a58c4f7ba1c092a52f1ea Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 10 Aug 2026 23:40:15 +0200
Subject: [PATCH 060/117] Hardened the database configuration in the Website
 service target.

---
 Services/Website/.env.local                  |  14 +-
 Services/Website/README.md                   | 161 +++++++++++--------
 Services/Website/docker-compose.override.yml |   8 +-
 Services/Website/docker-compose.yml          |   8 +-
 4 files changed, 107 insertions(+), 84 deletions(-)

diff --git a/Services/Website/.env.local b/Services/Website/.env.local
index 64d9a99..92d31f5 100644
--- a/Services/Website/.env.local
+++ b/Services/Website/.env.local
@@ -41,21 +41,19 @@ LOG_LEVEL=debug
 DATABASE_DRIVER=inMemory
 
 # PostgreSQL connection, used when DATABASE_DRIVER=postgres.
-# `postgres` is the local database's Compose service name; use 127.0.0.1 when
-# running the app directly with `swift run`.
 DATABASE_HOST=localhost
 
-# Port of the database to connect to.
-DATABASE_PORT=5432
-
 # Name of the database to connect to.
 DATABASE_NAME=loud
 
-# Username of the database to connect as.
-DATABASE_USERNAME=loud
-
 # Provide the real password via the environment or a secret — never commit it.
 DATABASE_PASSWORD=loud
 
+# Port of the database to connect to.
+DATABASE_PORT=5432
+
 # TLS posture when connecting: off | prefer | require (use `require` in production).
 DATABASE_TLS=off
+
+# Username of the database to connect as.
+DATABASE_USERNAME=loud
\ No newline at end of file
diff --git a/Services/Website/README.md b/Services/Website/README.md
index dd240ae..6346a19 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -1,16 +1,17 @@
 # Loud Website
-The **Loud** public website service — a [Hummingbird](https://github.com/hummingbird-project/hummingbird) server that renders a static landing page and serves the site's static assets.
+The **Loud** public website service — a [Hummingbird](https://github.com/hummingbird-project/hummingbird) server that renders a static landing page, registers newsletter subscriptions, and serves the site's static assets.
 
 ## Overview
 The service:
-- Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
-- Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
-- Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
-- Serves static files (CSS, JS, icons, manifest, `robots.txt`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`; the production image ships minified copies (see [Static assets](#static-assets)).
-- Returns a custom not-found (404) HTML page, localized like the landing page, for any request that matches neither a route nor a static file.
-- Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
-- Stamps a hardened set of security headers on every response.
-- Persists data through [Fluent](https://github.com/hummingbird-project/hummingbird-fluent), against either an ephemeral in-memory SQLite database (the default — no external infrastructure) or a PostgreSQL server, selected by a single configuration key.
+- Renders the landing page at `GET /` with [Elementary](https://github.com/elementary-swift/elementary), cached once per supported language; its canonical URL, Open Graph/Twitter card, and JSON-LD structured data all derive from the configured site origin.
+- Negotiates each request's language from `Accept-Language` against the `WebsiteLibrary` String Catalog (falling back to `en`), serving from the per-language cache with `Content-Language` and `Vary: Accept-Language`.
+- Registers newsletter subscriptions at `POST /subscribe`: form-encoded, validated and normalized, honeypot-guarded, and stored tagged with the negotiated language.
+- Answers `GET /health` (liveness, static JSON) and `GET /health/ready` (readiness — `200`/`503` on database reachability).
+- Serves static files from `Resources/Static` via Hummingbird's `FileMiddleware` with media-type-specific `Cache-Control`; the production image ships optimized copies (see [Static assets](#static-assets)).
+- Returns a custom 404 page, localized like the landing page, for anything matching neither a route nor a static file.
+- Embeds a cookieless [Umami](https://umami.is) tracker on both pages when configured — pageviews plus subscription, outbound Instagram, and 404 recovery events (see [Analytics](#analytics)).
+- Compresses responses (gzip/deflate) above a configurable size, and stamps a hardened set of security headers on every response.
+- Persists through [Fluent](https://github.com/hummingbird-project/hummingbird-fluent), against either an ephemeral in-memory SQLite database (the default — no external infrastructure) or PostgreSQL, selected by a single configuration key.
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
@@ -22,13 +23,13 @@ Two SwiftPM targets:
 | Target | Kind | Path | Role |
 | --- | --- | --- | --- |
 | `Website` | executable | `Sources/App` | Entry point: reads configuration, builds the persistence service, and either serves the website or runs the migrate-and-exit mode. |
-| `WebsiteLibrary` | library | `Sources/Library` | Controllers, the pages, the `StaticFile` asset catalog, the request context, and the `*+Defaults` extensions and configuration-key constants that supply the site's specifics to `Infrastructure`. |
+| `WebsiteLibrary` | library | `Sources/Library` | Controllers, the pages and their shared chrome fragments, the `StaticFile` asset catalog, the request context, the subscription form model, and the `*+Defaults` extensions and configuration-key constants that supply the site's specifics to `Infrastructure`. |
 
-The `Website` executable depends on four local packages:
-- `Localization` (`Packages/Localization`) — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteLibrary`).
-- `Infrastructure` (`Packages/Infrastructure`) — the shared Hummingbird toolkit: the `RouterController` protocol and `addController` result-builder extension for declarative routing, the security/vary/rate-limit/localization/not-found middlewares, the `Page` and `Asset` scaffolding, the pre-rendered localized HTML responses, and the `FingerprintAssets` version-token derivation. The service supplies its specifics (String Catalog bundle, pages, icon metadata) through the `*+Defaults` extensions in `WebsiteLibrary`.
-- `Persistence` (`Packages/Persistence`) — the Fluent-based data layer: the `Driver` selector, the `Service` factory that builds the `Fluent` service, the `PrepareDB` registrar that declares the migrations, and the `Probe` consulted by the readiness check; the models, migrations, and repositories stay internal to the package. It has no dependency on `swift-configuration`; the executable maps the `database.*` keys onto the driver.
-- `Utility` (`Packages/Utility`) — small shared helpers with no server dependencies, currently the `NormalizeEmail` method.
+The `Website` executable depends on four local packages, each under `Packages/`:
+- `Localization` — the `Localize` and `Negotiate` helpers and the `LanguageList` of catalog languages (used by `WebsiteLibrary`).
+- `Infrastructure` — the shared Hummingbird toolkit: declarative routing (`RouterController`, `addController`), the security/vary/rate-limit/localization/not-found middlewares, the `Page` and `Asset` scaffolding, the `SocialCard`/`StructuredData`/`Analytics` metadata types, the pre-rendered localized HTML responses, and `FingerprintAssets`. The service supplies its own specifics (String Catalog, pages, icons, analytics) through the `*+Defaults` extensions and `ConfigReader` properties in `WebsiteLibrary` and the executable.
+- `Persistence` — the Fluent data layer: the `Driver` selector, the `Service` factory, the `PrepareDB` migration registrar, and the `Probe` behind the readiness check. `Subscriber` and the repository types are public; record models and migrations stay internal. It has no `swift-configuration` dependency — the executable maps the `database.*` keys onto the driver.
+- `Utility` — shared helpers with no server dependencies, such as the `NormalizeEmail` the subscription flow canonicalizes addresses with.
 
 The persistence backend runs as a `Fluent` service inside the application's ServiceLifecycle group, so it starts and stops alongside the HTTP server (which owns its connection-pool shutdown on graceful termination).
 
@@ -42,12 +43,19 @@ LogRequestsMiddleware
           → NotFoundMiddleware        (renders the localized not-found page on .notFound)
             → FileMiddleware          (serves Resources/Static)
 RootController                        (GET / → landing page)
+SubscriptionController                (POST /subscribe → newsletter subscription)
 HealthController                      (GET /health → liveness, GET /health/ready → readiness)
 ```
 
+## Pages
+Both pages are rendered with Elementary and share the site chrome — the sticky top bar, the mobile drawer, and the footer — through the `Chrome` fragment, styled by `/css/shared.css` and driven by `/js/shared.js`. Every script is a progressive enhancement, loaded `defer`red from the document head: the pages stay fully usable without JavaScript.
+- **Landing page** (`IndexPage`): the site's sections plus the newsletter subscription forms, which validate inline and post with `fetch`, falling back to a plain form submission without JavaScript.
+- **Not-found page** (`NotFoundPage`): a "dead channel" stage — animated canvas static, CRT scanlines, a vignette, and a glitching 404 — with a Web Audio white-noise toggle that appears only when the script and the API are available. The decoration layers are pinned to the page, not the viewport, so nothing paints past its edges; the toggle's play/stop icons are inline vectors (the `▶`/`◼` glyphs render as emoji on iOS); and the loops stop under `prefers-reduced-motion` and disappear under forced colors. The chrome keeps only the brand, the theme toggles, and the "back to home" link here — with no section links to navigate, its top bar, drawer, and footer render as plain containers rather than `nav` landmarks.
+- **Shared behaviors**: a "Skip to content" link, visually hidden until focused, is each page's first focusable element, jumping keyboard and screen-reader users past the chrome; the theme toggle follows the system appearance until a choice is made, then stores it for the session; the footer's back-to-top link hides itself when the page has nothing to scroll; and the page wrapper bleeds the chrome's base color past both ends of the document, so rubber-band overscroll reads as the top bar or footer stretching rather than a seam.
+- **Analytics events**: beyond pageviews — `subscribe` and `subscribe_error` (tagged with which form, and the failure reason, never the address), `instagram` clicks (tagged with the profile, via declarative `data-umami-event` attributes), and `notfound_recover`. Every JavaScript call is guarded, so the pages behave identically when the tracker is absent, blocked, or suppressed by Do Not Track.
+
 ## Configuration
-Configuration is read through [swift-configuration](https://github.com/apple/swift-configuration) from
-the following sources, **highest precedence first**:
+Configuration is read through [swift-configuration](https://github.com/apple/swift-configuration), **highest precedence first**:
 1. Command-line arguments (e.g. `--http-host 0.0.0.0`)
 2. Process environment variables
 3. A `.env.local` file in the working directory (optional)
@@ -55,8 +63,10 @@ the following sources, **highest precedence first**:
 5. Built-in defaults
 
 The two files play different roles:
-- **`.env`** (git-ignored) holds your deployment values — it is the file the Makefile and Compose read for the `${VAR}` placeholders, and typically selects the PostgreSQL backend.
-- **`.env.local`** (tracked) holds the local development values — the in-memory database and `debug` logging, plus the image/deployment placeholders the Makefile falls back to when no `.env` exists. Because it sits *above* `.env`, a direct launch (`swift run` or a debugger) runs against the local values even when `.env` points at a deployment, the same way `docker-compose.override.yml` overrides the base Compose file. Compose itself never reads it, and the production image does not ship it — only the executable, its resources, and the static files are staged into the final stage.
+- **`.env`** (git-ignored) holds your deployment values, and is the file the Makefile and Compose read for their `${VAR}` placeholders — it typically selects the PostgreSQL backend.
+- **`.env.local`** (tracked) holds the local development overrides: in-memory database, `debug` logging. Sitting *above* `.env`, it keeps a direct launch (`swift run` or a debugger) on the local values even when `.env` points at a deployment. Compose never reads it, and the production image does not ship it.
+
+The Makefile `include`s `.env` and exports every value, so a target launched through `make` runs with the deployment configuration rather than the `.env.local` one: `make site-run` uses the backend `.env` selects, a bare `swift run Website` the in-memory one. And because a makefile assignment outranks an inherited environment variable, overriding a value for a single invocation takes a command-line variable *after* the target (`make site-mount DATABASE_DRIVER=postgres`) — an environment prefix is silently discarded.
 
 ### Environment variable naming
 A dotted config key maps to an environment variable by upper-casing, splitting camelCase, and replacing separators with `_`. For example `http.serverName` → `HTTP_SERVER_NAME`,
@@ -67,9 +77,9 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 ### Static file caching
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `cache.maxAge.asset` | `CACHE_MAX_AGE_ASSET` | `31536000` (1 year) | `max-age` for fingerprinted assets (CSS, JS) and fonts; also marked `immutable`. The pages reference CSS/JS through content-versioned URLs (`?v=<token>`), so a deploy busts them by changing the URL. |
+| `cache.maxAge.asset` | `CACHE_MAX_AGE_ASSET` | `31536000` (1 year) | `max-age` for fingerprinted assets (CSS, JS, MP4 video) and fonts; also marked `immutable`. The pages reference these through content-versioned URLs (`?v=<token>`), so a deploy busts them by changing the URL. |
 | `cache.maxAge.text` | `CACHE_MAX_AGE_TEXT` | `3600` (1 hour) | `max-age` for unversioned text assets (e.g. `robots.txt`); also marked `must-revalidate`. |
-| `cache.maxAge.image` | `CACHE_MAX_AGE_IMAGE` | `604800` (1 week) | `max-age` for images (ICO, PNG, SVG). |
+| `cache.maxAge.image` | `CACHE_MAX_AGE_IMAGE` | `604800` (1 week) | `max-age` for images (ICO, PNG, JPEG, SVG). |
 | `cache.maxAge.default` | `CACHE_MAX_AGE_DEFAULT` | `86400` (1 day) | `max-age` for everything else (e.g. the web manifest). |
 
 ### Response compression
@@ -110,24 +120,38 @@ See [Persistence](#persistence-1) below for the workflow.
 | `path.staticFiles` | `PATH_STATIC_FILES` | `Resources/Static` | Directory, relative to the working directory, that static files are served from. |
 
 ### Rate limiting
-These keys configure the `RateLimitMiddleware` budget for the upcoming newsletter subscription endpoint. They are read at startup, but the middleware is **not yet attached to any route** — the values have no effect until the subscription endpoint ships.
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
 | `rateLimit.limit` | `RATELIMIT_LIMIT` | `5` | Requests admitted per client per window on the subscribe endpoint; the excess is answered with `429 Too Many Requests` and a `Retry-After` header. |
 | `rateLimit.window` | `RATELIMIT_WINDOW` | `60` | Window length, in seconds, the limit applies to. |
-| `rateLimit.trustForwardedFor` | `RATELIMIT_TRUST_FORWARDED_FOR` | `false` | Key clients by the first `X-Forwarded-For` entry instead of the connection's address. Enable only behind a reverse proxy that sets the header — otherwise clients can forge it; leave it off when the server is directly reachable. |
+| `rateLimit.trustForwardedFor` | `RATELIMIT_TRUST_FORWARDED_FOR` | `false` | Key clients by the first `X-Forwarded-For` entry instead of the connection's address. Enable **only** behind a reverse proxy that sets the header — when the server is directly reachable, clients can forge it. |
+
+### Site
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `site.origin` | `SITE_ORIGIN` | `https://loud.amsterdam` | Public origin the site is served at (scheme and host, no trailing slash). The pages derive their canonical URL and other absolute links (social card image, structured data) from it, so a staging deployment can point it at itself instead of leaking the production origin into its markup. |
+
+### Analytics
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `analytics.websiteID` | `ANALYTICS_WEBSITE_ID` | `f28681d6-20e8-43f3-9c3b-5d6a0f8e0591` | The analytics website identifier the tracker on both pages reports as. **Set it to an empty string to disable analytics entirely** — the tracker script is then omitted from the pages. |
+| `analytics.domains` | `ANALYTICS_DOMAINS` | `loud.amsterdam` | Comma-delimited domains the tracker reports from; visits from any other host (development, staging) are ignored. |
+
+The tracker's origin (`https://analytics.rock-n-code.com`) is not configurable: it is single-sourced in code so the tracker tag and the `Content-Security-Policy` that must allow it (`security.contentSecurityPolicy` below) always agree. The pages also emit a `preconnect` hint for it, so the cross-origin handshake starts before the parser reaches the deferred tracker script.
+
+> **Keep `analytics.domains` in sync with `site.origin`.** Both encode the deployment's public host — the hosts the tracker reports from, and the host the pages are served at. Override one without the other (say, pointing a staging deployment at itself) and the domain filter stops matching: every visit is dropped silently, with no error. To disable analytics on a deployment instead, clear `analytics.websiteID` (see above).
 
 ### Security headers
 | Config key | Environment variable | Default |
 | --- | --- | --- |
-| `security.contentSecurityPolicy` | `SECURITY_CONTENT_SECURITY_POLICY` | `default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'` |
+| `security.contentSecurityPolicy` | `SECURITY_CONTENT_SECURITY_POLICY` | `default-src 'self'; script-src 'self' https://analytics.rock-n-code.com; connect-src 'self' https://analytics.rock-n-code.com; object-src 'none'; base-uri 'self'; frame-ancestors 'none'` |
 | `security.contentTypeOptions` | `SECURITY_CONTENT_TYPE_OPTIONS` | `nosniff` |
 | `security.frameOptions` | `SECURITY_FRAME_OPTIONS` | `DENY` |
 | `security.referrerPolicy` | `SECURITY_REFERRER_POLICY` | `strict-origin-when-cross-origin` |
 | `security.permissionsPolicy` | `SECURITY_PERMISSIONS_POLICY` | `accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()` |
 | `security.strictTransportSecurity` | `SECURITY_STRICT_TRANSPORT_SECURITY` | _none (omitted)_ |
 
-`Strict-Transport-Security` has **no default** and is omitted unless explicitly configured: it only takes effect over HTTPS (browsers ignore it on plain HTTP) and is "sticky" in browsers, so it must stay off in local HTTP development. It is enabled for production in `docker-compose.yml`, where it only has an effect once traffic is served over HTTPS behind a TLS-terminating proxy.
+`Strict-Transport-Security` has **no default** and is omitted unless explicitly configured: browsers ignore it on plain HTTP but remember it stickily once seen, so it must stay off in local HTTP development. `docker-compose.yml` enables it for production, where it takes effect once traffic is served over HTTPS behind a TLS-terminating proxy.
 
 ## Running locally
 Directly with Swift:
@@ -136,7 +160,7 @@ swift run Website # binds to Hummingbird's default 127.0.0.1:8080
 swift run Website --http-host 0.0.0.0 --http-port 9000 --log-level debug
 ```
 
-A direct run picks up the local development overrides from `.env.local` (in-memory database, `debug` logging) over whatever `.env` configures. To run against another backend, override per launch — e.g. `DATABASE_DRIVER=postgres swift run Website` — since process environment variables outrank both files.
+A direct run picks up the `.env.local` development overrides (in-memory database, `debug` logging) over whatever `.env` configures. To run against another backend, override per launch — `DATABASE_DRIVER=postgres swift run Website` — since process environment variables outrank both files.
 
 Or via the Makefile / Docker (uses `docker-compose.override.yml`, which builds from source and sets `LOG_LEVEL=debug`):
 ```sh
@@ -145,8 +169,7 @@ make site-run         # run locally with hot reload (hb watch)
 make site-mount       # docker compose up --build --detach
 make site-unmount     # docker compose down + remove the local image
 ```
-
-`make help` lists every available target.
+Unlike a direct `swift run`, these targets inherit the exported `.env` values (see [Configuration](#configuration)), so they run against whichever backend `.env` selects. `make help` lists every available target.
 
 ## Persistence
 The service persists data through Fluent and selects its backend at runtime with `database.driver`.
@@ -155,56 +178,57 @@ The service persists data through Fluent and selects its backend at runtime with
 With no configuration, the service uses an ephemeral in-memory SQLite database. It is created and **migrated on startup** every launch, so `swift run Website` and `docker compose up` work with no external database — ideal for local development and tests.
 
 ### PostgreSQL
-Set `DATABASE_DRIVER=postgres` and the connection values (`DATABASE_HOST`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, …). Unlike the in-memory backend, a PostgreSQL database is **not** migrated on boot — a shared database is migrated out of band so multiple instances never race:
+Set `DATABASE_DRIVER=postgres` and the connection values (`DATABASE_HOST`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD`, …). Unlike the in-memory backend, PostgreSQL is **not** migrated on boot — a shared database is migrated out of band so multiple instances never race:
 ```sh
-# Run the registered migrations against the configured database, then exit.
+# Run the registered migrations, then exit.
 swift run Website --database-migrate
-# In a container (production), against the managed database:
+# The same, in a container against the managed database.
 docker compose -f docker-compose.yml run --rm website --database-migrate
 ```
 
-A local PostgreSQL for development lives behind the `database` Compose profile (so a plain `docker compose up` still runs in-memory). Its data directory is bind-mounted to `Tests/DB` (git-ignored), so the database survives `db-unmount` and container restarts:
+A local PostgreSQL for development lives behind the `database` Compose profile, so a plain `docker compose up` still runs in-memory. Its data directory is bind-mounted to `Tests/DB` (git-ignored) and initialised once from the `DATABASE_NAME`/`DATABASE_USERNAME`/`DATABASE_PASSWORD` values in `.env`:
 ```sh
-make db-mount     # start PostgreSQL (docker compose --profile database up --wait postgres)
-make db-migrate   # run migrations against it
+make db-mount     # start PostgreSQL
+make db-migrate   # migrate it, from the host (forced to 127.0.0.1 with TLS off)
 make db-shell     # open a SQL shell on it (psql)
-make db-unmount   # stop and remove the container (data kept in Tests/DB)
-make db-reset     # stop and remove the container
-DATABASE_DRIVER=postgres make site-mount   # run the site against PostgreSQL
+make db-unmount   # stop and remove the container, keeping the data
+make db-reset     # stop and remove the container, and delete the data
 ```
-> **Note:** because the data lives in the bind-mounted `Tests/DB` folder rather than a named volume, `db-reset`'s `--volumes` flag does **not** clear it. To start from an empty database, delete `Tests/DB` by hand.
+Then run the site against it, on the host or in its container:
+```sh
+make site-run                              # hot reload on the host, via localhost:5432
+make site-mount                            # containerised, via the Compose service name
+curl -i localhost:8080/health/ready        # 200 once the database is reachable
+```
+The containerised run needs no `DATABASE_HOST`: `docker-compose.override.yml` pins it to `postgres`, the Compose service name, which is the only address that resolves from inside the network. The `.env` value is the *host machine's* view (`localhost`) and is left to `make site-run`, which does run on the host. The override also `depends_on` the database, so with the `database` profile enabled the website waits for PostgreSQL to pass its healthcheck; without the profile it still starts alone on the in-memory backend.
+
+> **Note:** every other `DATABASE_*` override must be passed *after* the target — `DATABASE_TLS=off make site-mount` is silently discarded (see [Configuration](#configuration)), `make site-mount DATABASE_TLS=off` is not.
+
+> **Note:** `db-reset` deletes `Tests/DB` itself, because Compose's `--volumes` flag cannot clear a bind mount. Use it to start from an empty database — for instance after changing `DATABASE_PASSWORD`, which is only read when the cluster is first initialised.
 
 ### Health checks
-`GET /health` is a liveness check (process is up, no dependency check). `GET /health/ready` is a readiness check that runs `SELECT 1` against the database and returns `200` when reachable or `503` otherwise — so an orchestrator restarts on liveness failure but only withholds traffic on readiness failure.
-
-`docker-compose.yml` configures the `website` container healthcheck against `GET /health`, so Compose reports process liveness without coupling container health to database reachability.
+`GET /health` is a liveness check (process is up, no dependency check). `GET /health/ready` runs `SELECT 1` against the database and returns `200` when reachable or `503` otherwise — so an orchestrator restarts on liveness failure but only withholds traffic on readiness failure. `docker-compose.yml` points the `website` container healthcheck at `/health`, keeping container health decoupled from database reachability.
 
 ## Testing
 ```sh
-make pkg-test
-# = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
+make pkg-test   # = swift test --disable-xctest --enable-code-coverage --enable-swift-testing --parallel
 ```
 
-Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. The `Tests/Website.xctestplan` covers the service's two targets — `WebsiteTests` (the executable/integration tests) and `WebsiteLibraryTests` (the library unit tests) — plus the local packages' suites: `InfrastructureTests`, `PersistenceTests`, `LocalizationTests`, and `UtilityTests`.
+Tests use the [Swift Testing](https://developer.apple.com/documentation/testing/) framework. `Tests/Website.xctestplan` covers the service's two targets — `WebsiteTests` (executable/integration) and `WebsiteLibraryTests` (library units) — plus the local packages' suites: `InfrastructureTests`, `PersistenceTests`, `LocalizationTests`, and `UtilityTests`.
 
-The `Persistence` package has its own suite (run it from `Packages/Persistence`). Its tests run against the in-memory backend by default; the PostgreSQL integration test is skipped unless a database is pointed at via `POSTGRES_TEST_HOST` (with optional `POSTGRES_TEST_PORT`/`NAME`/`USERNAME`/`PASSWORD`), so `swift test` stays runnable with no database:
+The `Persistence` package also has its own suite, run from `Packages/Persistence`. It uses the in-memory backend by default; the PostgreSQL integration test is skipped unless `POSTGRES_TEST_HOST` points at a database, so `swift test` stays runnable without one:
 ```sh
-cd ../../Packages/Persistence && swift test                      # in-memory only
-# With the local PostgreSQL up (make db-mount):
-cd ../../Packages/Persistence && POSTGRES_TEST_HOST=127.0.0.1 swift test
+cd ../../Packages/Persistence && swift test                              # in-memory only
+cd ../../Packages/Persistence && POSTGRES_TEST_HOST=127.0.0.1 swift test # against make db-mount
 ```
+`POSTGRES_TEST_NAME`/`USERNAME`/`PASSWORD` each default to `loud` (and `POSTGRES_TEST_PORT` is optional), so pass the password explicitly when the local container was initialised with a different `DATABASE_PASSWORD`.
 
 ## Deployment
 The production image is built for `linux/amd64` in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080` (`ENTRYPOINT ./Website --http-host 0.0.0.0 --http-port 8080`).
 
-Verify the image builds for its `linux/amd64` target without tagging or publishing:
 ```sh
-make img-check
-```
-
-Build, tag, and push a release to the registry (an explicit version is required):
-```sh
-make img-release version=1.2.3
+make img-check                  # verify it builds for linux/amd64, without tagging or publishing
+make img-release version=1.2.3  # build, tag, and push a release (an explicit version is required)
 ```
 
 Pull and run the prebuilt image in production — the `-f docker-compose.yml` flag is important, as it skips the local-development override:
@@ -214,22 +238,22 @@ docker compose -f docker-compose.yml up -d
 ```
 
 ### Static assets
-The image build optimizes the files under `Resources/Static` in its `assets` stage, in place, with pinned optimizer versions so asset output is reproducible for a given Dockerfile commit:
-- CSS and JS are minified with [esbuild](https://esbuild.github.io).
-- PNG images are losslessly recompressed with [oxipng](https://github.com/oxipng/oxipng) — the output is pixel-identical, only encoded smaller.
-- The SVG icon is minified with [svgo](https://github.com/svg/svgo).
+The image build optimizes the files under `Resources/Static` in place, in its `assets` stage, with pinned optimizer versions so asset output is reproducible for a given Dockerfile commit:
+- CSS and JS minified with [esbuild](https://esbuild.github.io).
+- PNGs losslessly recompressed with [oxipng](https://github.com/oxipng/oxipng) — pixel-identical, only encoded smaller.
+- The SVG icon minified with [svgo](https://github.com/svg/svgo).
+- JPEG metadata stripped with [jpegoptim](https://github.com/tjko/jpegoptim) — pixel data untouched.
+- MP4s remuxed with [ffmpeg](https://ffmpeg.org) so the `moov` index atom leads the file (faststart) and playback can start before the download finishes; streams are copied, not re-encoded.
 
-Files keep their names and paths, so the URLs derived from the `StaticFile` enumeration are unaffected. The sources in the repository stay readable and unminified: a direct `swift run` serves them as-is, while any image build — including the local `make site-mount` one, which builds the same Dockerfile — serves the optimized copies.
+Files keep their names and paths, so the URLs derived from the `StaticFile` enumeration are unaffected. The repository sources stay readable and unminified: a direct `swift run` serves them as-is, while any image build — including the local `make site-mount` one — serves the optimized copies. Assets are copied from the `assets` stage *after* the binary is built, so editing a CSS/JS/image file does not invalidate the release build cache.
 
-The Dockerfile copies only package manifests and Swift source inputs into the release build stage. Static assets are copied from the separate `assets` stage after the binary is built, so editing a CSS/JS/image file does not invalidate the release binary build cache.
-
-Preview the optimized output locally — requires only Docker and writes to the git-ignored `.build/minified`:
+Preview the optimized output locally (Docker only, writes to the git-ignored `.build/minified`):
 ```sh
 make ast-minify
 ```
 
 ### Icons
-All icons are renditions of the star mark in `icon.svg`, which is the canonical source — there is no external design file to regenerate from.
+All icons are renditions of the star mark in `icon.svg`, the canonical source — there is no external design file to regenerate from.
 
 | File | Size | Used by | Dark mode |
 | --- | --- | --- | --- |
@@ -240,7 +264,7 @@ All icons are renditions of the star mark in `icon.svg`, which is the canonical
 
 The landing page pairs the icons with two `theme-color` metas: `#0c0710` (media-qualified for dark, listed first — the first matching entry wins) and `#fafafa` as the fallback.
 
-The raster icons are committed binaries, regenerated from `icon.svg` on demand via a throwaway container (no local toolchain needed) — e.g. for the 512px rendition:
+The raster icons are committed binaries, regenerated from `icon.svg` on demand via a throwaway container (no local toolchain needed) — e.g. the 512px rendition:
 ```sh
 docker run --rm -v "$PWD/Resources/Static:/work" alpine sh -c '
   apk add --no-cache imagemagick librsvg oxipng &&
@@ -250,7 +274,7 @@ docker run --rm -v "$PWD/Resources/Static:/work" alpine sh -c '
 (`-density` scales the 192px viewBox: `96 × target ÷ 192`. For `favicon.ico`, rasterize a star-only copy of the SVG at 32px and pack it with `icotool -c --raw`.)
 
 ### Required variables
-The Makefile and Compose files read these from a `.env` file (or the environment). Provide your own values — do **not** commit secrets.
+The Makefile and Compose files read these from `.env` (or the environment). Provide your own values — do **not** commit secrets.
 | Variable | Used for |
 | --- | --- |
 | `HOST_CONTAINER` | Container registry host (e.g. `registry.example.com`). |
@@ -263,7 +287,8 @@ The Makefile and Compose files read these from a `.env` file (or the environment
 | `HTTP_SERVER_NAME` | Runtime server name (default `LoudWebsite`). |
 | `SECURITY_STRICT_TRANSPORT_SECURITY` | HSTS header value (default `max-age=31536000; includeSubDomains`). |
 | `DATABASE_DRIVER` | `inMemory` or `postgres`. The production Compose file defaults it to `postgres`; the local override defaults back to the in-memory backend. |
-| `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` | PostgreSQL connection (when `DATABASE_DRIVER=postgres`). Provide the password via a secret. |
-| `DATABASE_TLS` | TLS posture when connecting: `off`, `prefer`, or `require` (default `prefer` in production — set `require` when the database enforces TLS, so a stripped connection fails instead of silently downgrading to plaintext). |
+| `DATABASE_HOST`, `DATABASE_PASSWORD` | **Mandatory** — the Compose files carry no default for either, since none can be correct: `localhost` inside the container is the container itself, and a blank password authenticates as nobody. Compose refuses to start without them rather than booting a website that serves 503s. Provide the password via a secret. |
+| `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USERNAME` | The rest of the PostgreSQL connection (when `DATABASE_DRIVER=postgres`); these do default (`5432`, `loud`, `loud`). |
+| `DATABASE_TLS` | TLS posture: `off`, `prefer`, or `require`. The production Compose file defaults it to `require`, which refuses a server offering no TLS; the local override defaults it to `off` for the plaintext development container. `prefer` continues in plaintext when the upgrade is stripped, handing over the password — so it is not a safe production posture. |
 
 Run the migrations against the production database once before (or during) rollout: `docker compose -f docker-compose.yml run --rm website --database-migrate`.
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
index e3101da..f4d3484 100644
--- a/Services/Website/docker-compose.override.yml
+++ b/Services/Website/docker-compose.override.yml
@@ -17,8 +17,12 @@ services:
     environment:
       LOG_LEVEL: debug
       DATABASE_DRIVER: ${DATABASE_DRIVER:-inMemory}
-      DATABASE_HOST: ${DATABASE_HOST:-localhost}
+      DATABASE_HOST: postgres
       DATABASE_TLS: ${DATABASE_TLS:-off}
+    depends_on:
+      postgres:
+        condition: service_healthy
+        required: false
 
   # Local development database, started only with the `database` profile so a plain `docker compose up` still runs the
   # in-memory backend:
@@ -45,6 +49,4 @@ services:
       retries: 10
       start_period: 30s
     volumes:
-      # postgres:18 keeps its data directory under /var/lib/postgresql/<major>/docker, so the whole
-      # /var/lib/postgresql tree is mounted — not the pre-18 /var/lib/postgresql/data path.
       - ./Tests/DB:/var/lib/postgresql
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index 17c03e1..98765aa 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -20,15 +20,13 @@ services:
       LOG_LEVEL: ${LOG_LEVEL:-info}
       HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-LoudWebsite}
       SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
-      # Persistence: in-memory by default; set DATABASE_DRIVER=postgres to run against a managed PostgreSQL database.
-      # Provide the password via the environment or a secret — never commit it.
       DATABASE_DRIVER: ${DATABASE_DRIVER:-postgres}
-      DATABASE_HOST: ${DATABASE_HOST:-localhost}
+      DATABASE_HOST: ${DATABASE_HOST:?DATABASE_HOST is required}
       DATABASE_PORT: ${DATABASE_PORT:-5432}
       DATABASE_NAME: ${DATABASE_NAME:-loud}
       DATABASE_USERNAME: ${DATABASE_USERNAME:-loud}
-      DATABASE_PASSWORD: ${DATABASE_PASSWORD:-}
-      DATABASE_TLS: ${DATABASE_TLS:-prefer}
+      DATABASE_PASSWORD: ${DATABASE_PASSWORD:?DATABASE_PASSWORD is required}
+      DATABASE_TLS: ${DATABASE_TLS:-require}
     healthcheck:
       test: ["CMD", "curl", "--fail", "--silent", "--show-error", "http://127.0.0.1:8080/health"]
       interval: 30s
-- 
2.54.0


From 83035982448b693151599f21c15acac002577525 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 11 Aug 2026 01:35:17 +0200
Subject: [PATCH 061/117] Documented the database connection pooling in the
 Website service.

---
 Services/Website/.env.local         | 7 ++++++-
 Services/Website/README.md          | 9 ++++++---
 Services/Website/docker-compose.yml | 1 +
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/Services/Website/.env.local b/Services/Website/.env.local
index 92d31f5..750ae9d 100644
--- a/Services/Website/.env.local
+++ b/Services/Website/.env.local
@@ -49,10 +49,15 @@ DATABASE_NAME=loud
 # Provide the real password via the environment or a secret — never commit it.
 DATABASE_PASSWORD=loud
 
+# Maximum pooled connections per event loop, one loop per core — an 8-core host
+# can open 8 times this, and every replica that many again.
+DATABASE_POOL_MAX_PER_EVENT_LOOP=4
+
 # Port of the database to connect to.
 DATABASE_PORT=5432
 
-# TLS posture when connecting: off | prefer | require (use `require` in production).
+# TLS posture when connecting: off | prefer | require. Plaintext is the usual
+# choice over a private container network; use `require` across one you share.
 DATABASE_TLS=off
 
 # Username of the database to connect as.
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 6346a19..8c99460 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -63,7 +63,7 @@ Configuration is read through [swift-configuration](https://github.com/apple/swi
 5. Built-in defaults
 
 The two files play different roles:
-- **`.env`** (git-ignored) holds your deployment values, and is the file the Makefile and Compose read for their `${VAR}` placeholders — it typically selects the PostgreSQL backend.
+- **`.env`** (git-ignored) holds your deployment values — including the database password — and is the file the Makefile and Compose read for their `${VAR}` placeholders; it typically selects the PostgreSQL backend. Keep it out of version control and off shared machines: Compose passes its values to the container as environment variables, so anything in it is readable through `docker inspect` and by every process in the container.
 - **`.env.local`** (tracked) holds the local development overrides: in-memory database, `debug` logging. Sitting *above* `.env`, it keeps a direct launch (`swift run` or a debugger) on the local values even when `.env` points at a deployment. Compose never reads it, and the production image does not ship it.
 
 The Makefile `include`s `.env` and exports every value, so a target launched through `make` runs with the deployment configuration rather than the `.env.local` one: `make site-run` uses the backend `.env` selects, a bare `swift run Website` the in-memory one. And because a makefile assignment outranks an inherited environment variable, overriding a value for a single invocation takes a command-line variable *after* the target (`make site-mount DATABASE_DRIVER=postgres`) — an environment prefix is silently discarded.
@@ -112,6 +112,8 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 | `database.tls` | `DATABASE_TLS` | `prefer` | TLS posture when connecting: `off`, `prefer`, or `require`. Ignored for `inMemory`. |
 | `database.pool.maxPerEventLoop` | `DATABASE_POOL_MAX_PER_EVENT_LOOP` | `4` | Maximum pooled connections per event loop. Ignored for `inMemory`. |
 
+> **Connection budget:** the pool holds `database.pool.maxPerEventLoop` connections *per event loop*, and the event loop group runs one loop per core. An 8-core instance can therefore open 32, and each replica that many again — three replicas exhaust PostgreSQL's default `max_connections` of 100. Size this against the server's limit, not against the number alone.
+
 See [Persistence](#persistence-1) below for the workflow.
 
 ### Paths
@@ -169,7 +171,7 @@ make site-run         # run locally with hot reload (hb watch)
 make site-mount       # docker compose up --build --detach
 make site-unmount     # docker compose down + remove the local image
 ```
-Unlike a direct `swift run`, these targets inherit the exported `.env` values (see [Configuration](#configuration)), so they run against whichever backend `.env` selects. `make help` lists every available target.
+Unlike a direct `swift run`, these targets inherit the exported `.env` values (see [Configuration](#configuration)), so they run against whichever backend `.env` selects. The one exception is `DATABASE_HOST` under `make site-mount`: the local Compose override pins it to the `postgres` service name, since the `.env` value addresses the database from the host rather than from inside the container. `make help` lists every available target.
 
 ## Persistence
 The service persists data through Fluent and selects its backend at runtime with `database.driver`.
@@ -287,8 +289,9 @@ The Makefile and Compose files read these from `.env` (or the environment). Prov
 | `HTTP_SERVER_NAME` | Runtime server name (default `LoudWebsite`). |
 | `SECURITY_STRICT_TRANSPORT_SECURITY` | HSTS header value (default `max-age=31536000; includeSubDomains`). |
 | `DATABASE_DRIVER` | `inMemory` or `postgres`. The production Compose file defaults it to `postgres`; the local override defaults back to the in-memory backend. |
-| `DATABASE_HOST`, `DATABASE_PASSWORD` | **Mandatory** — the Compose files carry no default for either, since none can be correct: `localhost` inside the container is the container itself, and a blank password authenticates as nobody. Compose refuses to start without them rather than booting a website that serves 503s. Provide the password via a secret. |
+| `DATABASE_HOST`, `DATABASE_PASSWORD` | **Mandatory** — the production Compose file carries no default for either, since none can be correct: `localhost` inside the container is the container itself, and a blank password authenticates as nobody. It refuses to start without them rather than booting a website that serves 503s. Both come from `.env`, which is git-ignored — never commit the password. Compose interpolates each file before merging, so both must be set for a local `docker compose up` too, even though the override pins the host. |
 | `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USERNAME` | The rest of the PostgreSQL connection (when `DATABASE_DRIVER=postgres`); these do default (`5432`, `loud`, `loud`). |
+| `DATABASE_POOL_MAX_PER_EVENT_LOOP` | Pooled connections per event loop (default `4`) — see the [connection budget](#persistence) before scaling out. |
 | `DATABASE_TLS` | TLS posture: `off`, `prefer`, or `require`. The production Compose file defaults it to `require`, which refuses a server offering no TLS; the local override defaults it to `off` for the plaintext development container. `prefer` continues in plaintext when the upgrade is stripped, handing over the password — so it is not a safe production posture. |
 
 Run the migrations against the production database once before (or during) rollout: `docker compose -f docker-compose.yml run --rm website --database-migrate`.
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index 98765aa..a1e8981 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -27,6 +27,7 @@ services:
       DATABASE_USERNAME: ${DATABASE_USERNAME:-loud}
       DATABASE_PASSWORD: ${DATABASE_PASSWORD:?DATABASE_PASSWORD is required}
       DATABASE_TLS: ${DATABASE_TLS:-require}
+      DATABASE_POOL_MAX_PER_EVENT_LOOP: ${DATABASE_POOL_MAX_PER_EVENT_LOOP:-4}
     healthcheck:
       test: ["CMD", "curl", "--fail", "--silent", "--show-error", "http://127.0.0.1:8080/health"]
       interval: 30s
-- 
2.54.0


From d7465d03ccc0bc6a31907dd471e73c941ce5be4a Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Wed, 12 Aug 2026 23:57:08 +0200
Subject: [PATCH 062/117] Updated the Probe method in the Persistence package
 with a query deadline.

---
 Packages/Persistence/README.md                |  6 +--
 .../Sources/Public/Methods/Probe.swift        | 53 +++++++++++++-----
 .../Cases/Public/Methods/ProbeTests.swift     | 40 ++++++++++++++
 .../Utils/Fakes/SilentPostgresServer.swift    | 54 +++++++++++++++++++
 4 files changed, 138 insertions(+), 15 deletions(-)
 create mode 100644 Packages/Persistence/Tests/Utils/Fakes/SilentPostgresServer.swift

diff --git a/Packages/Persistence/README.md b/Packages/Persistence/README.md
index c881d74..a8b7f71 100644
--- a/Packages/Persistence/README.md
+++ b/Packages/Persistence/README.md
@@ -7,7 +7,7 @@ The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based da
 | Backend selection | `Driver` (`postgres` or `inMemory`), `Configuration` (the PostgreSQL connection parameters), `TLS` (the connection's TLS posture) |
 | Service | `Service`, which builds the `Fluent` service configured for the chosen driver |
 | Migrations | `PrepareDB`, the single registrar declaring every migration, in order |
-| Readiness | `Probe`, which reports whether the default database answers a `SELECT 1` |
+| Readiness | `Probe`, which reports whether the default database answers a `SELECT 1` within a deadline |
 | Scaffolding (internal) | `ExampleRecord`, `CreateExampleRecord`, and `ExampleRepository` — the model → migration → repository pattern, to be replaced by the first real domain model |
 
 ## Design rules
@@ -15,7 +15,7 @@ The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based da
 - **One default database.** `Service` registers the selected backend as the *default* database, so repositories resolve it with a plain `fluent.db()` and stay agnostic of which driver is in use.
 - **Migrations are declared once, and append-only.** `PrepareDB` registers every migration in the order it must run; alter the schema by adding a migration, never by editing one that has already run. Registering does not apply them: the in-memory backend migrates on startup, while a shared PostgreSQL database is migrated out of band (the executable's migrate-and-exit mode), so booting instances never race.
 - **Models never cross a concurrency boundary.** FluentKit models are mutable reference types, so they stay internal to the package and repositories return `Sendable` value-type snapshots (e.g. `Example`) instead.
-- **Readiness never throws.** `Probe` runs a `SELECT 1` — the cheapest statement both backends understand, independent of any schema — and maps every failure to `false`, so callers translate it straight into a readiness response.
+- **Readiness never throws, and never hangs.** `Probe` runs a `SELECT 1` — the cheapest statement both backends understand, independent of any schema — and maps every failure to `false`, so callers translate it straight into a readiness response. The query is raced against a deadline (2 seconds unless the probe is built with another), so a database that hangs rather than refuses yields a prompt "not ready" instead of a hanging readiness endpoint.
 - **A single connection for the in-memory store.** The SQLite backend is capped at one connection per event loop, so every query reaches the same in-memory database instead of each pooled connection getting a private one.
 - **Method structs.** `Service`, `PrepareDB`, and `Probe` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
@@ -36,7 +36,7 @@ Sources/
 Tests/
 ├── Cases/                 the test suites, mirroring the Sources/ layout
 └── Utils/                 the NotSQL* fakes backing the probe's non-SQL-database case, the
-                           plaintext-only fake PostgreSQL server, and the suite Tag constants
+                           plaintext-only and silent fake PostgreSQL servers, and the suite Tag constants
 ```
 
 ## Testing
diff --git a/Packages/Persistence/Sources/Public/Methods/Probe.swift b/Packages/Persistence/Sources/Public/Methods/Probe.swift
index 78a096d..9282a5f 100644
--- a/Packages/Persistence/Sources/Public/Methods/Probe.swift
+++ b/Packages/Persistence/Sources/Public/Methods/Probe.swift
@@ -12,14 +12,21 @@ public struct Probe: Sendable {
     /// The `Fluent` service whose default database is probed.
     private let fluent: Fluent
 
+    /// The longest the probe waits for the database's answer before reporting it as not reachable.
+    private let timeout: Duration
+
     // MARK: Initializers
 
     /// Creates a probe for the default database of the given `Fluent` service.
-    /// - Parameter fluent: the `Fluent` service whose default database is probed.
+    /// - Parameters:
+    ///   - fluent: the `Fluent` service whose default database is probed.
+    ///   - timeout: the longest the probe waits for the database's answer before reporting it as not reachable.
     public init(
-        fluent: Fluent
+        fluent: Fluent,
+        timeout: Duration = .seconds(2)
     ) {
         self.fluent = fluent
+        self.timeout = timeout
     }
 
     // MARK: Methods
@@ -28,21 +35,43 @@ public struct Probe: Sendable {
     ///
     /// Runs a trivial `SELECT 1` against the default database — the cheapest statement both the PostgreSQL and SQLite backends understand — so
     /// a readiness check does not depend on any particular schema or model. Any failure (connection refused, authentication error, pool exhausted) is
-    /// reported as not reachable rather than thrown, so callers can map it straight onto a readiness response. A default database that is not an SQL
-    /// database is likewise reported as not reachable.
-    /// - Returns: `true` when the database answers the probe, `false` otherwise.
+    /// reported as not reachable rather than thrown, and an answer that does not arrive within the timeout is likewise reported as not reachable — so
+    /// a database that hangs yields a prompt "not ready" instead of a hanging readiness endpoint. A default database that is not an SQL database is
+    /// also reported as not reachable.
+    /// - Returns: `true` when the database answers the probe in time, `false` otherwise.
     public func callAsFunction() async -> Bool {
         guard let database = fluent.db() as? any SQLDatabase else {
             return false
         }
-        
-        do {
-            try await database.raw("SELECT 1").run()
-            
-            return true
-        } catch {
-            return false
+
+        // The query is raced against the deadline from unstructured tasks whose first answer wins: a structured group
+        // would await the query child before returning, so a database that hangs mid-query — the very failure the
+        // deadline exists for — would hang the probe with it. The loser is cancelled and abandoned; a late answer lands
+        // in a finished stream and is dropped.
+        let (answers, continuation) = AsyncStream.makeStream(of: Bool.self)
+        let query = Task {
+            do {
+                try await database
+                    .raw("SELECT 1")
+                    .run()
+
+                continuation.yield(true)
+            } catch {
+                continuation.yield(false)
+            }
+        }
+        let deadline = Task {
+            try? await Task.sleep(for: timeout)
+
+            continuation.yield(false)
         }
 
+        var answer = answers.makeAsyncIterator()
+        let isReachable = await answer.next() ?? false
+
+        query.cancel()
+        deadline.cancel()
+
+        return isReachable
     }
 }
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
index 9029fcd..72875c8 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
@@ -57,6 +57,46 @@ struct ProbeTests {
         #expect(!isReachable)
     }
 
+    @Test
+    func `reports a hanging database as unreachable within its timeout`() async throws {
+        // The silent server accepts the TCP connection and never answers, so the probe's query can only
+        // ever be resolved by its deadline — without one, it would wait out the driver's own connect
+        // timeout (10 seconds) instead.
+        let server = try await SilentPostgresServer.start()
+        let service = try Service(
+            driver: .postgres(
+                .init(
+                    host: "127.0.0.1",
+                    port: server.port,
+                    name: "hanging",
+                    username: "nobody",
+                    password: "nothing",
+                    tls: .off,
+                    maxConnectionsPerEventLoop: 1
+                )
+            ),
+            logger: Logger(label: "test")
+        )
+        let fluent = service()
+        let probe = Probe(
+            fluent: fluent,
+            timeout: .milliseconds(100)
+        )
+
+        let clock = ContinuousClock()
+        let start = clock.now
+        let isReachable = await probe()
+        let elapsed = clock.now - start
+
+        try await fluent.shutdown()
+        try await server.stop()
+
+        #expect(!isReachable)
+        // Well past the 100-millisecond deadline to absorb scheduling noise, yet far below the driver's
+        // 10-second connect timeout — only the deadline can answer this fast.
+        #expect(elapsed < .seconds(5))
+    }
+
     @Test
     func `reports a default database that is not an SQL database`() async throws {
         let fluent = Fluent(logger: Logger(label: "test"))
diff --git a/Packages/Persistence/Tests/Utils/Fakes/SilentPostgresServer.swift b/Packages/Persistence/Tests/Utils/Fakes/SilentPostgresServer.swift
new file mode 100644
index 0000000..d1498c1
--- /dev/null
+++ b/Packages/Persistence/Tests/Utils/Fakes/SilentPostgresServer.swift
@@ -0,0 +1,54 @@
+import NIOCore
+import NIOPosix
+
+/// A fake server accepting connections and never answering.
+///
+/// A client connecting to it completes the TCP handshake and then waits forever for the first protocol byte — the shape of a database that hangs rather
+/// than refuses. This is what the probe's deadline test connects to, proving the probe answers within its timeout instead of hanging alongside the server.
+final class SilentPostgresServer {
+
+    // MARK: Properties
+
+    /// The port the server listens on, assigned by the system at bind time.
+    let port: Int
+
+    /// The listening channel the server accepts connections through.
+    private let channel: Channel
+
+    // MARK: Initializers
+
+    private init(
+        channel: Channel,
+        port: Int
+    ) {
+        self.channel = channel
+        self.port = port
+    }
+
+    // MARK: Functions
+
+    /// Starts a server on the loopback interface, on a system-assigned port.
+    /// - Returns: the running server, ready to be connected to at ``port``.
+    static func start() async throws -> SilentPostgresServer {
+        let channel = try await ServerBootstrap(group: MultiThreadedEventLoopGroup.singleton)
+            .bind(host: "127.0.0.1", port: 0)
+            .get()
+
+        guard let port = channel.localAddress?.port else {
+            throw ChannelError.unknownLocalAddress
+        }
+
+        return .init(
+            channel: channel,
+            port: port
+        )
+    }
+
+    /// Stops the server, closing its listening channel.
+    func stop() async throws {
+        try await channel
+            .close()
+            .get()
+    }
+
+}
-- 
2.54.0


From 70c0cc53030807d86ba0bc7b552226fc73ed6362 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 13 Aug 2026 00:11:42 +0200
Subject: [PATCH 063/117] Added a connection pool timeout to the Configuration
 type in the Persistence package.

---
 .../Sources/Public/Methods/Service.swift       |  3 ++-
 .../Sources/Public/Types/Configuration.swift   | 18 ++++++++++++------
 .../Cases/Public/Methods/ProbeTests.swift      |  6 ++++--
 .../Cases/Public/Methods/ServiceTests.swift    |  6 ++++--
 Services/Website/README.md                     |  3 ++-
 .../Extensions/ConfigReader+Properties.swift   | 10 +++++++---
 .../AbsoluteConfigKey+Constants.swift          |  2 ++
 .../Extensions/ConfigKey+Constants.swift       |  2 ++
 .../Public/Extensions/Int+Constants.swift      |  2 ++
 .../Controllers/HealthControllerTests.swift    |  3 ++-
 10 files changed, 39 insertions(+), 16 deletions(-)

diff --git a/Packages/Persistence/Sources/Public/Methods/Service.swift b/Packages/Persistence/Sources/Public/Methods/Service.swift
index bf2dec2..51cad79 100644
--- a/Packages/Persistence/Sources/Public/Methods/Service.swift
+++ b/Packages/Persistence/Sources/Public/Methods/Service.swift
@@ -77,7 +77,8 @@ public struct Service: Sendable {
                         database: configuration.name,
                         tls: tls
                     ),
-                    maxConnectionsPerEventLoop: configuration.maxConnectionsPerEventLoop
+                    maxConnectionsPerEventLoop: configuration.maxConnectionsPerEventLoop,
+                    connectionPoolTimeout: .init(configuration.poolTimeout)
                 ),
                 as: .psql,
                 isDefault: true
diff --git a/Packages/Persistence/Sources/Public/Types/Configuration.swift b/Packages/Persistence/Sources/Public/Types/Configuration.swift
index 1cdfc2f..1a771f8 100644
--- a/Packages/Persistence/Sources/Public/Types/Configuration.swift
+++ b/Packages/Persistence/Sources/Public/Types/Configuration.swift
@@ -17,6 +17,9 @@ public struct Configuration: Sendable {
     /// The password the connection authenticates with.
     let password: String
 
+    /// The longest a query waits for a pooled connection to become available before failing.
+    let poolTimeout: Duration
+
     /// The port the database server listens on.
     let port: Int
 
@@ -37,6 +40,7 @@ public struct Configuration: Sendable {
     ///   - password: the password the connection authenticates with.
     ///   - tls: the TLS posture used when connecting.
     ///   - maxConnectionsPerEventLoop: the maximum number of pooled connections opened per event loop.
+    ///   - poolTimeout: the longest a query waits for a pooled connection to become available before failing.
     public init(
         host: String,
         port: Int,
@@ -44,15 +48,17 @@ public struct Configuration: Sendable {
         username: String,
         password: String,
         tls: TLS,
-        maxConnectionsPerEventLoop: Int
+        maxConnectionsPerEventLoop: Int,
+        poolTimeout: Duration
     ) {
         self.host = host
-        self.port = port
-        self.name = name
-        self.username = username
-        self.password = password
-        self.tls = tls
         self.maxConnectionsPerEventLoop = maxConnectionsPerEventLoop
+        self.name = name
+        self.password = password
+        self.poolTimeout = poolTimeout
+        self.port = port
+        self.tls = tls
+        self.username = username
     }
 
 }
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
index 72875c8..c01ab7e 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ProbeTests.swift
@@ -42,7 +42,8 @@ struct ProbeTests {
                     username: "nobody",
                     password: "nothing",
                     tls: .off,
-                    maxConnectionsPerEventLoop: 1
+                    maxConnectionsPerEventLoop: 1,
+                    poolTimeout: .seconds(10)
                 )
             ),
             logger: Logger(label: "test")
@@ -72,7 +73,8 @@ struct ProbeTests {
                     username: "nobody",
                     password: "nothing",
                     tls: .off,
-                    maxConnectionsPerEventLoop: 1
+                    maxConnectionsPerEventLoop: 1,
+                    poolTimeout: .seconds(10)
                 )
             ),
             logger: Logger(label: "test")
diff --git a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
index 8c7afd7..a374cd9 100644
--- a/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
+++ b/Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift
@@ -43,7 +43,8 @@ struct ServiceTests {
                     username: "loud",
                     password: "loud",
                     tls: .off,
-                    maxConnectionsPerEventLoop: 1
+                    maxConnectionsPerEventLoop: 1,
+                    poolTimeout: .seconds(10)
                 )
             ),
             logger: Logger(label: "test")
@@ -165,7 +166,8 @@ private let postgresDriver: Persistence.Driver? = {
             username: environment["POSTGRES_TEST_USERNAME"] ?? "loud",
             password: environment["POSTGRES_TEST_PASSWORD"] ?? "loud",
             tls: .off,
-            maxConnectionsPerEventLoop: 2
+            maxConnectionsPerEventLoop: 2,
+            poolTimeout: .seconds(10)
         )
     )
 }()
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 8c99460..266710b 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -111,8 +111,9 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 | `database.password` | `DATABASE_PASSWORD` | _(empty)_ | Database password. Provide via the environment/a secret — never commit it. |
 | `database.tls` | `DATABASE_TLS` | `prefer` | TLS posture when connecting: `off`, `prefer`, or `require`. Ignored for `inMemory`. |
 | `database.pool.maxPerEventLoop` | `DATABASE_POOL_MAX_PER_EVENT_LOOP` | `4` | Maximum pooled connections per event loop. Ignored for `inMemory`. |
+| `database.pool.timeout` | `DATABASE_POOL_TIMEOUT` | `10` | Longest wait, in seconds, for a pooled connection to become available before the query fails. Ignored for `inMemory`. |
 
-> **Connection budget:** the pool holds `database.pool.maxPerEventLoop` connections *per event loop*, and the event loop group runs one loop per core. An 8-core instance can therefore open 32, and each replica that many again — three replicas exhaust PostgreSQL's default `max_connections` of 100. Size this against the server's limit, not against the number alone.
+> **Connection budget:** the pool holds `database.pool.maxPerEventLoop` connections *per event loop*, and the event loop group runs one loop per core. An 8-core instance can therefore open 32, and each replica that many again — three replicas exhaust PostgreSQL's default `max_connections` of 100. Size this against the server's limit, not against the number alone. When every connection is busy, a query waits up to `database.pool.timeout` for one to free up and then fails — this bounds how long requests stall on an exhausted pool.
 
 See [Persistence](#persistence-1) below for the workflow.
 
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index 4f5bb32..bfadf67 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -60,8 +60,8 @@ package extension ConfigReader {
     /// The persistence backend the service runs against, derived from the `database.*` keys.
     ///
     /// When `database.driver` selects PostgreSQL, the connection parameters are assembled from the `database.host`, `database.port`,
-    /// `database.name`, `database.username`, `database.password` (empty when unset), `database.tls`, and
-    /// `database.pool.maxPerEventLoop` keys. Any other driver value falls back to the in-memory database.
+    /// `database.name`, `database.username`, `database.password` (empty when unset), `database.tls`,
+    /// `database.pool.maxPerEventLoop`, and `database.pool.timeout` keys. Any other driver value falls back to the in-memory database.
     var driver: Driver {
         switch string(
             forKey: .Database.driver,
@@ -94,7 +94,11 @@ package extension ConfigReader {
                     maxConnectionsPerEventLoop: int(
                         forKey: .Database.poolMaxPerEventLoop,
                         default: .Database.poolMaxPerEventLoop
-                    )
+                    ),
+                    poolTimeout: .seconds(int(
+                        forKey: .Database.poolTimeout,
+                        default: .Database.poolTimeout
+                    ))
                 )
             )
         default:
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index b44f742..8cd3628 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -37,6 +37,8 @@ extension AbsoluteConfigKey {
         public static let tls: AbsoluteConfigKey = .init(.Database.tls)
         /// The absolute configuration key for the maximum pooled connections per event loop.
         public static let poolMaxPerEventLoop: AbsoluteConfigKey = .init(.Database.poolMaxPerEventLoop)
+        /// The absolute configuration key for the longest wait, in seconds, for a pooled connection to become available.
+        public static let poolTimeout: AbsoluteConfigKey = .init(.Database.poolTimeout)
     }
     /// A namespace for the HTTP server configuration keys, as absolute keys.
     public enum HTTP {
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index a6a6492..646a9da 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -37,6 +37,8 @@ extension ConfigKey {
         public static let tls: ConfigKey = "database.tls"
         /// The configuration key for the maximum pooled connections per event loop.
         public static let poolMaxPerEventLoop: ConfigKey = "database.pool.maxPerEventLoop"
+        /// The configuration key for the longest wait, in seconds, for a pooled connection to become available.
+        public static let poolTimeout: ConfigKey = "database.pool.timeout"
     }
     /// A namespace for the HTTP server configuration keys.
     public enum HTTP {
diff --git a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
index a7eeda8..82f4772 100644
--- a/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/Int+Constants.swift
@@ -21,5 +21,7 @@ extension Int {
         public static let port = 5_432
         /// The default maximum pooled connections per event loop.
         public static let poolMaxPerEventLoop = 4
+        /// The default longest wait, in seconds, for a pooled connection to become available (the driver's own default).
+        public static let poolTimeout = 10
     }
 }
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
index 3a89f10..00480d5 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -78,7 +78,8 @@ struct HealthControllerTests {
                     username: "nobody",
                     password: "nothing",
                     tls: .off,
-                    maxConnectionsPerEventLoop: 1
+                    maxConnectionsPerEventLoop: 1,
+                    poolTimeout: .seconds(10)
                 )
             ),
             logger: Logger(label: "test")
-- 
2.54.0


From 964e7fa707f6b1325ba9e1abd80bc4a387dc869f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 13 Aug 2026 00:53:42 +0200
Subject: [PATCH 064/117] Update the documentation of the README files in the
 packages and in the Website service target.

---
 Packages/Infrastructure/README.md | 6 +++---
 Packages/Localization/README.md   | 4 ++--
 Packages/Persistence/README.md    | 2 +-
 Services/Website/README.md        | 6 +++---
 4 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 9297df6..36494f9 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -16,9 +16,9 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 
 ## Design rules
 The package holds only what every service can reuse; anything a service owns is injected, never referenced:
-- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages (`LocalizationMiddleware`, `LocalizedHTMLCollectionResponse`, `NotFoundMiddleware`), the `document:` closure that builds a page for a locale, and a `Page` conformer's `metadata` — along with the `summary`, `canonicalURL`, `socialCard`, `structuredData`, and `analytics` its other head tags render, each omitted unless the page provides it. URLs arrive fully formed and absolute: composing them from an origin and a versioned asset path stays with the page.
-- **Types own their format; `Page` renders generically.** Each optional head concern derives its own render-ready representation — `SocialCard.tags`, `StructuredData.payload`, `Analytics.attributes` — and the `Page` scaffolding applies it without knowing the vocabulary (Open Graph, schema.org, or the Umami convention). Page ``scripts`` and the tracker render as `defer`red head tags, with a `preconnect` hint for the tracker's cross-origin host.
-- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `Page+Defaults`, `LocalizationMiddleware+Defaults`, and `NotFoundMiddleware+Defaults` are the pattern. The open schema.org vocabularies extend the same way: the package declares only the `Property.Name` and `Node.Kind` constants every service shares, and a service adds what its own node shapes need.
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages, the `document:` closure building a page for a locale, and a `Page` conformer's `metadata` plus its optional head concerns (`summary`, `canonicalURL`, `socialCard`, `structuredData`, `analytics`). URLs arrive fully formed and absolute; composing them stays with the page.
+- **Types own their format; `Page` renders generically.** Each head concern derives its own render-ready representation — `SocialCard.tags`, `StructuredData.payload`, `Analytics.attributes` — and `Page` applies it without knowing the vocabulary. Page ``scripts`` and the tracker render as `defer`red head tags, with a `preconnect` hint for the tracker's cross-origin host.
+- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `*+Defaults` extensions are the pattern. The open schema.org vocabularies extend the same way: the package declares the shared `Property.Name` and `Node.Kind` constants, and a service adds its own.
 - **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
 ## Layout
diff --git a/Packages/Localization/README.md b/Packages/Localization/README.md
index db9263a..5128cc4 100644
--- a/Packages/Localization/README.md
+++ b/Packages/Localization/README.md
@@ -10,10 +10,10 @@ The server-side localization toolkit the **Loud** services build on: locale-expl
 | Diagnostics | `CatalogState`, the outcome of reading the catalog (`loaded`, `missing`, or `undecodable`) |
 
 ## Design rules
-- **The String Catalog is the single source of truth.** Supported languages, the default language, and every string come from the bundle's `Localizable.xcstrings`, so adding a language is a translation-only change — `LanguageList` and `Negotiate` pick up a new locale with no code change.
+- **The String Catalog is the single source of truth.** Supported languages, the default language, and every string come from the bundle's `Localizable.xcstrings`, so adding a language is a translation-only change.
 - **The locale is always explicit.** A server has no single "current" locale, so every lookup names the locale to resolve in; nothing reads process-wide locale state.
 - **Raw `.xcstrings` parsing, for Linux parity.** The catalog is decoded from its JSON rather than through Foundation's compiled-catalog APIs, which are unavailable or non-functional on Linux. Consumers must `.copy` the resource verbatim (never `.process` it) so it ships as raw JSON everywhere. Only simple `stringUnit` values are decoded — plural and device variations are not.
-- **Resolution never fails.** A missing entry falls back to the source-language string, then to the key itself; a missing or undecodable catalog degrades the language list to the default. Check `catalogState` once at startup and warn when it is not `.loaded`, before visitors see raw keys.
+- **Resolution never fails.** A missing entry falls back to the source-language string, then to the key itself; a missing or undecodable catalog degrades the language list to the default. Check `catalogState` at startup and warn when it is not `.loaded`.
 - **Method structs.** `Localize` and `Negotiate` hold their lifetime-fixed configuration (the bundle) in `init` and take only per-call inputs in `callAsFunction`.
 - **One decoded catalog per bundle.** Catalogs are immutable at runtime, so every `Localize`, `Negotiate`, and `LanguageList` bound to the same bundle and table shares one cached `StringCatalog`.
 
diff --git a/Packages/Persistence/README.md b/Packages/Persistence/README.md
index a8b7f71..c3cb5e8 100644
--- a/Packages/Persistence/README.md
+++ b/Packages/Persistence/README.md
@@ -15,7 +15,7 @@ The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based da
 - **One default database.** `Service` registers the selected backend as the *default* database, so repositories resolve it with a plain `fluent.db()` and stay agnostic of which driver is in use.
 - **Migrations are declared once, and append-only.** `PrepareDB` registers every migration in the order it must run; alter the schema by adding a migration, never by editing one that has already run. Registering does not apply them: the in-memory backend migrates on startup, while a shared PostgreSQL database is migrated out of band (the executable's migrate-and-exit mode), so booting instances never race.
 - **Models never cross a concurrency boundary.** FluentKit models are mutable reference types, so they stay internal to the package and repositories return `Sendable` value-type snapshots (e.g. `Example`) instead.
-- **Readiness never throws, and never hangs.** `Probe` runs a `SELECT 1` — the cheapest statement both backends understand, independent of any schema — and maps every failure to `false`, so callers translate it straight into a readiness response. The query is raced against a deadline (2 seconds unless the probe is built with another), so a database that hangs rather than refuses yields a prompt "not ready" instead of a hanging readiness endpoint.
+- **Readiness never throws, and never hangs.** `Probe` runs a schema-independent `SELECT 1`, maps every failure to `false`, and races the query against a deadline (2 seconds by default) — a hanging database yields a prompt "not ready" instead of a stalled endpoint.
 - **A single connection for the in-memory store.** The SQLite backend is capped at one connection per event loop, so every query reaches the same in-memory database instead of each pooled connection getting a private one.
 - **Method structs.** `Service`, `PrepareDB`, and `Probe` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
 
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 266710b..55b2151 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -111,9 +111,9 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 | `database.password` | `DATABASE_PASSWORD` | _(empty)_ | Database password. Provide via the environment/a secret — never commit it. |
 | `database.tls` | `DATABASE_TLS` | `prefer` | TLS posture when connecting: `off`, `prefer`, or `require`. Ignored for `inMemory`. |
 | `database.pool.maxPerEventLoop` | `DATABASE_POOL_MAX_PER_EVENT_LOOP` | `4` | Maximum pooled connections per event loop. Ignored for `inMemory`. |
-| `database.pool.timeout` | `DATABASE_POOL_TIMEOUT` | `10` | Longest wait, in seconds, for a pooled connection to become available before the query fails. Ignored for `inMemory`. |
+| `database.pool.timeout` | `DATABASE_POOL_TIMEOUT` | `10` | Seconds a query waits for a pooled connection before failing. Ignored for `inMemory`. |
 
-> **Connection budget:** the pool holds `database.pool.maxPerEventLoop` connections *per event loop*, and the event loop group runs one loop per core. An 8-core instance can therefore open 32, and each replica that many again — three replicas exhaust PostgreSQL's default `max_connections` of 100. Size this against the server's limit, not against the number alone. When every connection is busy, a query waits up to `database.pool.timeout` for one to free up and then fails — this bounds how long requests stall on an exhausted pool.
+> **Connection budget:** the pool holds `database.pool.maxPerEventLoop` connections *per event loop*, and the event loop group runs one loop per core. An 8-core instance can therefore open 32, and each replica that many again — three replicas exhaust PostgreSQL's default `max_connections` of 100. Size this against the server's limit, not against the number alone. On an exhausted pool, a query waits up to `database.pool.timeout` before failing.
 
 See [Persistence](#persistence-1) below for the workflow.
 
@@ -210,7 +210,7 @@ The containerised run needs no `DATABASE_HOST`: `docker-compose.override.yml` pi
 > **Note:** `db-reset` deletes `Tests/DB` itself, because Compose's `--volumes` flag cannot clear a bind mount. Use it to start from an empty database — for instance after changing `DATABASE_PASSWORD`, which is only read when the cluster is first initialised.
 
 ### Health checks
-`GET /health` is a liveness check (process is up, no dependency check). `GET /health/ready` runs `SELECT 1` against the database and returns `200` when reachable or `503` otherwise — so an orchestrator restarts on liveness failure but only withholds traffic on readiness failure. `docker-compose.yml` points the `website` container healthcheck at `/health`, keeping container health decoupled from database reachability.
+`GET /health` is a liveness check (process is up, no dependency check). `GET /health/ready` runs `SELECT 1` against the database and returns `200` when reachable or `503` otherwise — so an orchestrator restarts on liveness failure but only withholds traffic on readiness failure. A hanging database is reported as not ready within the probe's 2-second deadline, so the route itself never stalls. `docker-compose.yml` points the `website` container healthcheck at `/health`, keeping container health decoupled from database reachability.
 
 ## Testing
 ```sh
-- 
2.54.0


From 3bcae4d789cd444cc1025b90d32bd2414a116047 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 13 Aug 2026 01:16:34 +0200
Subject: [PATCH 065/117] Added the "recorder" flag to the Analytics type in
 the Infrastructure package.

---
 .../Sources/Public/Types/Analytics.swift      | 23 ++++++++++--
 .../Cases/Public/Types/AnalyticsTests.swift   | 35 +++++++++++++++++++
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
index 378df23..8839c63 100644
--- a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
@@ -4,7 +4,8 @@ import Foundation
 ///
 /// A page carries it as an optional value so the ``Page`` scaffolding renders the tracker's deferred `<script>` in the document head, or omits it
 /// when the page has none. The attribute names follow the Umami tracker convention. The three behavior flags default to on, and each renders its
-/// `data-` attribute only when enabled, since the tracker treats an absent attribute as off.
+/// `data-` attribute only when enabled, since the tracker treats an absent attribute as off. Recorder mode, by contrast, defaults to off; when
+/// activated, the page embeds a second deferred script that loads the session recorder from the tracker's origin.
 public struct Analytics: Sendable {
     
     // MARK: Type aliases
@@ -25,6 +26,9 @@ public struct Analytics: Sendable {
     /// Whether the tracker collects Core Web Vitals from visitors (requires an Umami instance at v3.1 or newer).
     public let performance: Bool
 
+    /// Whether the tracker also records visitor sessions, loading the session recorder script alongside the tracker.
+    public let recorder: Bool
+
     /// The URL the tracker script is loaded from.
     public let scriptURL: String
 
@@ -41,13 +45,15 @@ public struct Analytics: Sendable {
     ///   - excludeHash: whether the tracker drops the URL fragment from reported pageviews; defaults to `true`.
     ///   - doNotTrack: whether the tracker honors the visitor's browser Do Not Track preference; defaults to `true`.
     ///   - performance: whether the tracker collects Core Web Vitals (requires Umami v3.1 or newer); defaults to `true`.
+    ///   - recorder: whether the tracker also records visitor sessions, loading the session recorder script alongside the tracker; defaults to `false`.
     public init(
         scriptURL: String,
         websiteID: String,
         domains: String,
         excludeHash: Bool = true,
         doNotTrack: Bool = true,
-        performance: Bool = true
+        performance: Bool = true,
+        recorder: Bool = false
     ) {
         self.scriptURL = scriptURL
         self.websiteID = websiteID
@@ -55,6 +61,7 @@ public struct Analytics: Sendable {
         self.excludeHash = excludeHash
         self.doNotTrack = doNotTrack
         self.performance = performance
+        self.recorder = recorder
     }
 
     // MARK: Computed
@@ -114,4 +121,16 @@ public struct Analytics: Sendable {
         return "\(scheme)://\(host)\(port)"
     }
 
+    /// The URL the session recorder script is loaded from, derived from the tracker's ``origin``, or `nil` when ``recorder`` mode is off
+    /// or no origin can be derived from the ``scriptURL``.
+    ///
+    /// A page renders it as a second deferred script tag after the tracker script, carrying only the `data-website-id` attribute.
+    public var recorderScriptURL: String? {
+        guard recorder, let origin else {
+            return nil
+        }
+
+        return "\(origin)/recorder.js"
+    }
+
 }
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
index 6330f9f..6b14d1d 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
@@ -67,6 +67,41 @@ struct AnalyticsTests {
         #expect(analytics.origin == nil)
     }
 
+    @Test
+    func `carries no recorder script URL by default`() {
+        let analytics = Analytics(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "id-123",
+            domains: "example.com"
+        )
+
+        #expect(analytics.recorderScriptURL == nil)
+    }
+
+    @Test
+    func `derives its recorder script URL from the origin when recorder mode is on`() {
+        let analytics = Analytics(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "id-123",
+            domains: "example.com",
+            recorder: true
+        )
+
+        #expect(analytics.recorderScriptURL == "https://analytics.example.com/recorder.js")
+    }
+
+    @Test
+    func `carries no recorder script URL when no origin can be derived`() {
+        let analytics = Analytics(
+            scriptURL: "/script",
+            websiteID: "id-123",
+            domains: "example.com",
+            recorder: true
+        )
+
+        #expect(analytics.recorderScriptURL == nil)
+    }
+
     @Test
     func `omits the disabled behavior flags`() {
         let analytics = Analytics(
-- 
2.54.0


From 4bb3e9098cc58311ffe32a6004beb4d612f8958d Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 13 Aug 2026 01:17:13 +0200
Subject: [PATCH 066/117] Added the session recorder script to the Page
 protocol in the Infrastructure package.

---
 .../Sources/Public/Protocols/Page.swift       | 12 ++++++++
 .../Cases/Public/Protocols/PageTests.swift    | 28 +++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
index 952ea4c..a2f4d6a 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Page.swift
@@ -86,6 +86,7 @@ public extension Page {
     /// The structured data is an inert data block — browsers never execute it, so a site's `Content-Security-Policy` does not apply to it —
     /// that search engines read for the organization's name, logo, and profiles. The analytics tracker, by contrast, is an executable script the
     /// policy must allow, and it is `defer`red so it never delays the page render; each behavior flag renders its `data-` attribute only when enabled.
+    /// When recorder mode is on, the session recorder script follows the tracker script, deferred as well and carrying only the website id.
     @HTMLBuilder
     var head: some HTML {
         meta(
@@ -147,6 +148,17 @@ public extension Page {
                     value: $0.value
                 )
             })
+
+            if let recorderScriptURL = analytics.recorderScriptURL {
+                script(
+                    .defer,
+                    .src(recorderScriptURL),
+                    .custom(
+                        name: "data-website-id",
+                        value: analytics.websiteID
+                    )
+                ) {}
+            }
         }
 
         metadata
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
index 8e6f1fc..04c4a17 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/PageTests.swift
@@ -151,6 +151,34 @@ struct PageTests {
         #expect(preconnect.lowerBound < script.lowerBound)
     }
 
+    @Test
+    func `omits the session recorder script by default`() {
+        let html = StubPage(analytics: .init(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "0000-website-id",
+            domains: "example.com"
+        )).render()
+
+        #expect(!html.contains("recorder.js"))
+    }
+
+    @Test
+    func `renders the session recorder script when recorder mode is on`() throws {
+        let html = StubPage(analytics: .init(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "0000-website-id",
+            domains: "example.com",
+            recorder: true
+        )).render()
+
+        #expect(html.contains(#"<script defer src="https://analytics.example.com/recorder.js" data-website-id="0000-website-id"></script>"#))
+
+        let tracker = try #require(html.range(of: #"<script defer src="https://analytics.example.com/script""#))
+        let recorder = try #require(html.range(of: #"<script defer src="https://analytics.example.com/recorder.js""#))
+
+        #expect(tracker.lowerBound < recorder.lowerBound)
+    }
+
     @Test
     func `omits the analytics behavior flags that are disabled`() {
         let html = StubPage(analytics: .init(
-- 
2.54.0


From 397ad6b896d6fb33038d176beba20560c437dc51 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 13 Aug 2026 01:24:11 +0200
Subject: [PATCH 067/117] Added the "analytics.recorder" flag to the Website
 service.

---
 Services/Website/README.md                    |  1 +
 .../Extensions/ConfigReader+Properties.swift  | 37 ++++++++++
 .../AbsoluteConfigKey+Constants.swift         |  9 +++
 .../Extensions/ConfigKey+Constants.swift      |  9 +++
 .../Public/Extensions/String+Constants.swift  | 17 +++++
 .../App/ConfigReaderPropertiesTests.swift     | 70 +++++++++++++++++++
 6 files changed, 143 insertions(+)
 create mode 100644 Services/Website/Tests/App/ConfigReaderPropertiesTests.swift

diff --git a/Services/Website/README.md b/Services/Website/README.md
index 55b2151..d3d107d 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -139,6 +139,7 @@ See [Persistence](#persistence-1) below for the workflow.
 | --- | --- | --- | --- |
 | `analytics.websiteID` | `ANALYTICS_WEBSITE_ID` | `f28681d6-20e8-43f3-9c3b-5d6a0f8e0591` | The analytics website identifier the tracker on both pages reports as. **Set it to an empty string to disable analytics entirely** — the tracker script is then omitted from the pages. |
 | `analytics.domains` | `ANALYTICS_DOMAINS` | `loud.amsterdam` | Comma-delimited domains the tracker reports from; visits from any other host (development, staging) are ignored. |
+| `analytics.recorder` | `ANALYTICS_RECORDER` | `true` | Whether the pages also embed the session recorder script (`recorder.js`, loaded from the tracker's origin) alongside the tracker. Set it to `false` to disable session recording on a deployment. |
 
 The tracker's origin (`https://analytics.rock-n-code.com`) is not configurable: it is single-sourced in code so the tracker tag and the `Content-Security-Policy` that must allow it (`security.contentSecurityPolicy` below) always agree. The pages also emit a `preconnect` hint for it, so the cross-origin handshake starts before the parser reaches the deferred tracker script.
 
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index bfadf67..adef521 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -14,6 +14,43 @@ package extension ConfigReader {
 
     // MARK: Computed
 
+    /// The analytics tracker the landing page embeds, built from the `analytics.*` keys, or `nil` when `analytics.websiteID` resolves
+    /// empty — a deployment disables analytics entirely by clearing the identifier.
+    ///
+    /// The script URL is not configurable: its origin is single-sourced in `String.Analytics`, so the tracker tag and the
+    /// `Content-Security-Policy` that must allow it derive from one constant and cannot drift apart.
+    ///
+    /// The `analytics.domains` filter must name the host the pages are served from — i.e. the host of ``siteOrigin``. The two keys are
+    /// independent, so a deployment that overrides `site.origin` without matching `analytics.domains` reports from a host it no longer
+    /// serves and records nothing; change them together.
+    ///
+    /// Recorder mode is on by default — the pages embed the session recorder script alongside the tracker — and the `analytics.recorder`
+    /// flag turns it off for a deployment. The recorder loads from the same origin as the tracker, so the `Content-Security-Policy` needs
+    /// no extra allowance.
+    var analytics: Analytics? {
+        let websiteID = string(
+            forKey: .Analytics.websiteID,
+            default: .Analytics.websiteID
+        )
+
+        guard !websiteID.isEmpty else {
+            return nil
+        }
+
+        return .init(
+            scriptURL: .Analytics.scriptURL,
+            websiteID: websiteID,
+            domains: string(
+                forKey: .Analytics.domains,
+                default: .Analytics.domains
+            ),
+            recorder: bool(
+                forKey: .Analytics.recorder,
+                default: true
+            )
+        )
+    }
+
     /// The `Cache-Control` policy applied to static files, grouped by media type.
     ///
     /// The max-ages are read from the `cache.maxAge.asset`, `cache.maxAge.text`, `cache.maxAge.image`, and
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index 8cd3628..62dd206 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -1,6 +1,15 @@
 import Configuration
 
 extension AbsoluteConfigKey {
+    /// A namespace for the analytics configuration keys, as absolute keys.
+    public enum Analytics {
+        /// The absolute configuration key for the analytics website identifier.
+        public static let websiteID: AbsoluteConfigKey = .init(.Analytics.websiteID)
+        /// The absolute configuration key for the comma-delimited domains the tracker reports from.
+        public static let domains: AbsoluteConfigKey = .init(.Analytics.domains)
+        /// The absolute configuration key for recorder mode, loading the session recorder script alongside the tracker.
+        public static let recorder: AbsoluteConfigKey = .init(.Analytics.recorder)
+    }
     /// A namespace for the static files cache configuration keys, as absolute keys.
     public enum Cache {
         /// The absolute configuration key for the max-age, in seconds, applied to fingerprinted assets and fonts.
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index 646a9da..9fcddaa 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -1,6 +1,15 @@
 import Configuration
 
 extension ConfigKey {
+    /// A namespace for the analytics configuration keys.
+    public enum Analytics {
+        /// The configuration key for the analytics website identifier (cleared to disable analytics).
+        public static let websiteID: ConfigKey = "analytics.websiteID"
+        /// The configuration key for the comma-delimited domains the tracker reports from.
+        public static let domains: ConfigKey = "analytics.domains"
+        /// The configuration key for recorder mode, loading the session recorder script alongside the tracker (set to `false` to disable).
+        public static let recorder: ConfigKey = "analytics.recorder"
+    }
     /// A namespace for the static files cache configuration keys.
     public enum Cache {
         /// The configuration key for the max-age, in seconds, applied to fingerprinted assets (CSS, JavaScript) and fonts.
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 66940f5..5da47ee 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -1,4 +1,21 @@
 extension String {
+    /// A namespace for the analytics default configuration values.
+    public enum Analytics {
+        /// The origin the analytics scripts are loaded from and their beacons are sent to (scheme and host, no trailing slash).
+        ///
+        /// Single-sourced here: both ``scriptURL`` and the session recorder script the pages embed in recorder mode derive from this
+        /// constant, and the site's `Content-Security-Policy` must allow it.
+        public static let origin = "https://analytics.rock-n-code.com"
+        /// The URL the analytics tracker script is loaded from.
+        public static let scriptURL = "\(origin)/script"
+        /// The default analytics website identifier the tracker reports as.
+        public static let websiteID = "f28681d6-20e8-43f3-9c3b-5d6a0f8e0591"
+        /// The default comma-delimited domains the tracker reports from; visits from any other host are ignored.
+        ///
+        /// Keep it paired with the host the pages are served at: a deployment that serves from another host without overriding
+        /// `analytics.domains` to match reports from a host it no longer serves, so analytics silently records nothing.
+        public static let domains = "loud.amsterdam"
+    }
     /// A namespace for the persistence's default configuration values and recognized tokens.
     public enum Database {
         /// The default persistence driver: in-memory SQLite, which needs no external infrastructure.
diff --git a/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift b/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
new file mode 100644
index 0000000..6698938
--- /dev/null
+++ b/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
@@ -0,0 +1,70 @@
+import Configuration
+import Infrastructure
+import Persistence
+import Testing
+
+@testable import Website
+@testable import WebsiteLibrary
+
+@Suite("ConfigReader properties")
+struct ConfigReaderPropertiesTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `analytics to default to the production tracker`() throws {
+        let analytics = try #require(reader().analytics)
+
+        #expect(analytics.scriptURL == .Analytics.scriptURL)
+        #expect(analytics.websiteID == .Analytics.websiteID)
+        #expect(analytics.domains == .Analytics.domains)
+        #expect(analytics.excludeHash)
+        #expect(analytics.doNotTrack)
+        #expect(analytics.performance)
+        #expect(analytics.recorder)
+    }
+
+    @Test
+    func `analytics to switch recorder mode off when configured`() throws {
+        let analytics = try #require(reader(values: [
+            .Analytics.recorder: false
+        ]).analytics)
+
+        #expect(!analytics.recorder)
+    }
+
+    @Test
+    func `analytics to override the website id and domains when configured`() throws {
+        let analytics = try #require(reader(values: [
+            .Analytics.websiteID: "custom-website-id",
+            .Analytics.domains: "staging.loud.amsterdam"
+        ]).analytics)
+
+        #expect(analytics.websiteID == "custom-website-id")
+        #expect(analytics.domains == "staging.loud.amsterdam")
+        #expect(analytics.scriptURL == .Analytics.scriptURL)
+    }
+
+    @Test
+    func `analytics to be omitted when the website id is cleared`() {
+        #expect(reader(values: [.Analytics.websiteID: ""]).analytics == nil)
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension ConfigReaderPropertiesTests {
+
+    // MARK: Methods
+
+    /// Builds a configuration reader over the given in-memory values alone.
+    func reader(
+        values: [AbsoluteConfigKey: ConfigValue] = [:]
+    ) -> ConfigReader {
+        ConfigReader(providers: [
+            InMemoryProvider(values: values)
+        ])
+    }
+
+}
-- 
2.54.0


From 2206d7199720c6267c7c64f1ada2139d57e5a839 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 13 Aug 2026 02:57:47 +0200
Subject: [PATCH 068/117] Turned the analytics tracker off by default in the
 template.

---
 .../Sources/Public/Types/Analytics.swift      | 22 +++++----
 .../Cases/Public/Types/AnalyticsTests.swift   | 12 +++++
 Scripts/bootstrap                             |  8 +++-
 Services/Website/README.md                    | 30 ++++++------
 .../Sources/App/Extensions/App+Build.swift    | 11 +++--
 .../Extensions/ConfigReader+Properties.swift  | 22 +++++----
 .../Library/Internal/Pages/IndexPage.swift    |  8 +++-
 .../Library/Internal/Pages/NotFoundPage.swift |  8 +++-
 .../Public/Controllers/RootController.swift   | 10 ++--
 .../NotFoundMiddleware+Defaults.swift         | 10 ++--
 .../Public/Extensions/String+Constants.swift  | 21 ++++----
 .../App/ConfigReaderPropertiesTests.swift     | 39 +++++++++------
 .../Controllers/RootControllerTests.swift     | 48 +++++++++++++++++--
 13 files changed, 178 insertions(+), 71 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
index 8839c63..8a368cf 100644
--- a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
@@ -20,7 +20,7 @@ public struct Analytics: Sendable {
     /// Whether the tracker honors the visitor's browser Do Not Track preference.
     public let doNotTrack: Bool
 
-    /// The comma-delimited domains the tracker reports from; visits from any other host are ignored.
+    /// The comma-delimited domains the tracker reports from; visits from any other host are ignored. Empty to report from every host.
     public let domains: String
 
     /// Whether the tracker collects Core Web Vitals from visitors (requires an Umami instance at v3.1 or newer).
@@ -41,7 +41,7 @@ public struct Analytics: Sendable {
     /// - Parameters:
     ///   - scriptURL: the URL the tracker script is loaded from.
     ///   - websiteID: the analytics website identifier the tracker reports as.
-    ///   - domains: the comma-delimited domains the tracker reports from; visits from any other host are ignored.
+    ///   - domains: the comma-delimited domains the tracker reports from; visits from any other host are ignored. Empty to report from every host.
     ///   - excludeHash: whether the tracker drops the URL fragment from reported pageviews; defaults to `true`.
     ///   - doNotTrack: whether the tracker honors the visitor's browser Do Not Track preference; defaults to `true`.
     ///   - performance: whether the tracker collects Core Web Vitals (requires Umami v3.1 or newer); defaults to `true`.
@@ -66,19 +66,25 @@ public struct Analytics: Sendable {
 
     // MARK: Computed
 
-    /// The tracker script's attributes, in a stable order: the website id and the reporting domains, then each enabled behavior flag.
+    /// The tracker script's attributes, in a stable order: the website id, the reporting domains when filtered, then each enabled behavior flag.
     ///
-    /// A disabled flag is left out entirely, since the tracker treats an absent attribute as off. Each `name` is a full attribute name following the
-    /// Umami `data-` convention, which a page applies to the deferred script verbatim — so the page renders the tracker without knowing its shape.
+    /// A disabled flag is left out entirely, since the tracker treats an absent attribute as off. An empty ``domains`` is left out for the same reason:
+    /// the tracker reads the attribute as an allowlist, so rendering it empty would filter out every host rather than none. Each `name` is a full
+    /// attribute name following the Umami `data-` convention, which a page applies to the deferred script verbatim — so the page renders the
+    /// tracker without knowing its shape.
     public var attributes: [Attribute] {
         var attributes = [(
             name: "data-website-id",
             value: websiteID
-        ), (
-            name: "data-domains",
-            value: domains
         )]
 
+        if !domains.isEmpty {
+            attributes.append((
+                name: "data-domains",
+                value: domains
+            ))
+        }
+
         if excludeHash {
             attributes.append((
                 name: "data-exclude-hash",
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
index 6b14d1d..39e297c 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/AnalyticsTests.swift
@@ -120,4 +120,16 @@ struct AnalyticsTests {
         ])
     }
 
+    @Test
+    func `omits the domains filter when it is empty`() {
+        // The tracker reads the attribute as an allowlist, so rendering it empty would filter out every host rather than none.
+        let analytics = Analytics(
+            scriptURL: "https://analytics.example.com/script",
+            websiteID: "id-123",
+            domains: ""
+        )
+
+        #expect(!analytics.attributes.map(\.name).contains("data-domains"))
+    }
+
 }
diff --git a/Scripts/bootstrap b/Scripts/bootstrap
index 9660f1e..b6c7b11 100755
--- a/Scripts/bootstrap
+++ b/Scripts/bootstrap
@@ -194,9 +194,13 @@ Next steps:
        - $W/Resources/Static/site.webmanifest                 (name / short_name)
   2. Set a real database password in a git-ignored $W/.env
      (the committed .env.local defaults the password to the slug — do NOT ship that).
-  3. Point the git remote at your new repository:
+  3. Analytics ships OFF, and stays off until you opt in. To enable it: point
+     String.Analytics.origin at your own Umami instance (it defaults to the
+     reserved https://analytics.example.com), allow that origin in
+     security.contentSecurityPolicy, then set ANALYTICS_WEBSITE_ID.
+  4. Point the git remote at your new repository:
        git remote set-url origin <new-repo-url>     # or 'git remote add origin ...'
-  4. Build and run:
+  5. Build and run:
        cd $W && make site-run
 
 The Persistence package still ships an ExampleRecord / ExampleRepository sample
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 922ca9a..c8c3314 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -10,7 +10,7 @@ The service:
 - Answers `HEAD` on every `GET` route: the router is built with `.autoGenerateHeadEndpoints`, so uptime monitors and crawlers probing with `HEAD` get the route's status and headers instead of a `404`.
 - Serves static files (CSS, JS, icons, manifest, `robots.txt`, `sitemap.xml`) from `Resources/Static` via Hummingbird's `FileMiddleware`, tagged with media-type-specific `Cache-Control`; the production image ships minified copies (see [Static assets](#static-assets)).
 - Returns a custom not-found (404) HTML page, localized like the landing page, for any request that matches neither a route nor a static file.
-- Embeds a cookieless [Umami](https://umami.is) tracker on the pages that provide one, configured through the `analytics.*` keys (see [Analytics](#analytics)).
+- Embeds a cookieless [Umami](https://umami.is) tracker on both pages once a deployment configures one; it ships **off**, so an unconfigured copy requests no third-party script (see [Analytics](#analytics)).
 - Compresses responses (gzip/deflate) above a configurable size when the client advertises support.
 - Stamps a hardened set of security headers on every response.
 - Persists data through [Fluent](https://github.com/hummingbird-project/hummingbird-fluent), against either an ephemeral in-memory SQLite database (the default — no external infrastructure) or a PostgreSQL server, selected by a single configuration key.
@@ -53,14 +53,15 @@ The router is created with `.autoGenerateHeadEndpoints`, so each of those `GET`
 ### Page metadata
 Each page conforms to `Infrastructure`'s `Page` protocol and supplies only its `title`, `content`, `stylesheets`, and `scripts`; the protocol assembles the document around them and renders the head in a fixed order: the viewport declaration, the `analytics` origin preconnect hint, the `summary`, the `canonicalURL` link, the `socialCard` tags, the `structuredData` script, the `analytics` tracker script, then the page `metadata` and the stylesheet links. The body is the content followed by the script tags.
 
-Five of those are optional and **omitted by default** — the reference site leaves them unset, so a generated site fills in what it needs by overriding them on `IndexPage` (or on the shared `Page+Defaults` extension, for site-wide values):
+Four of those are page-authored, optional, and **omitted by default** — the reference site leaves them unset, so a generated site fills in what it needs by overriding them on `IndexPage` (or on the shared `Page+Defaults` extension, for site-wide values):
 | Property | Renders as | Notes |
 | --- | --- | --- |
 | `summary` | `<meta name="description">` | The page's one-line description. |
 | `canonicalURL` | `<link rel="canonical">` | Absolute URL. |
 | `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, share image. Scrapers require absolute URLs, so the page composes them from its own origin. |
 | `structuredData` | `<script type="application/ld+json">` | A `StructuredData` graph of schema.org nodes; `StructuredData(name:url:logo:profiles:)` builds the site-wide `Organization` + `WebSite` pair. The payload is an inert data block, so the `Content-Security-Policy` does not apply to it. |
-| `analytics` | `<link rel="preconnect">` + a deferred `<script>` | An `Analytics` tracker — script URL, website identifier, reported domains, and the behavior flags, following the [Umami](https://umami.is) `data-` attribute convention. Unlike the structured data it *is* executable, so the `Content-Security-Policy` must allow its origin; with recorder mode on, a second deferred script follows it. The executable builds one from the `analytics.*` keys (see [Analytics](#analytics)). |
+
+The fifth, `analytics`, is *configuration*-authored rather than page-authored: the executable builds an `Analytics` from the `analytics.*` keys and hands it to `RootController` and `NotFoundMiddleware`, which pass it to both pages. It renders as a `<link rel="preconnect">` plus a deferred `<script>` carrying the [Umami](https://umami.is) `data-` attributes, and — unlike the structured data — it *is* executable, so the `Content-Security-Policy` must allow its origin. It is empty by default; see [Analytics](#analytics) for how to turn it on.
 
 What the pages *do* ship is in `Page+Defaults` (`Sources/Library/Internal/Extensions`), shared by every page: the document `lang`, the favicon / SVG icon / apple-touch-icon / web-manifest links, and the two `theme-color` metas.
 
@@ -141,26 +142,27 @@ See [Persistence](#persistence-1) below for the workflow.
 | `rateLimit.window` | `RATELIMIT_WINDOW` | `60` | Window length, in seconds, the limit applies to. |
 | `rateLimit.trustForwardedFor` | `RATELIMIT_TRUST_FORWARDED_FOR` | `false` | Key clients by the first `X-Forwarded-For` entry instead of the connection's address. Enable **only** behind a reverse proxy that sets the header — when the server is directly reachable, clients can forge it. |
 
-### Site
-| Config key | Environment variable | Default | Description |
-| --- | --- | --- | --- |
-| `site.origin` | `SITE_ORIGIN` | `https://loud.amsterdam` | Public origin the site is served at (scheme and host, no trailing slash). The pages derive their canonical URL and other absolute links (social card image, structured data) from it, so a staging deployment can point it at itself instead of leaking the production origin into its markup. |
-
 ### Analytics
+The template ships analytics **off**: `analytics.websiteID` is empty, so both pages embed no tracker at all and no third-party script is requested. Enabling it takes three steps, in this order:
+
+1. Point `String.Analytics.origin` (`Sources/Library/Public/Extensions/String+Constants.swift`) at your own [Umami](https://umami.is) instance. It ships as `https://analytics.example.com`, an [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606) reserved domain, so an unconfigured copy can never report to somebody else's server.
+2. Extend `security.contentSecurityPolicy` to allow that origin in `script-src` and `connect-src` — the default policy is `'self'`-only, so the tracker is blocked until you do.
+3. Set `ANALYTICS_WEBSITE_ID` on the deployment.
+
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `analytics.websiteID` | `ANALYTICS_WEBSITE_ID` | `f28681d6-20e8-43f3-9c3b-5d6a0f8e0591` | The analytics website identifier the tracker on both pages reports as. **Set it to an empty string to disable analytics entirely** — the tracker script is then omitted from the pages. |
-| `analytics.domains` | `ANALYTICS_DOMAINS` | `loud.amsterdam` | Comma-delimited domains the tracker reports from; visits from any other host (development, staging) are ignored. |
-| `analytics.recorder` | `ANALYTICS_RECORDER` | `true` | Whether the pages also embed the session recorder script (`recorder.js`, loaded from the tracker's origin) alongside the tracker. Set it to `false` to disable session recording on a deployment. |
+| `analytics.websiteID` | `ANALYTICS_WEBSITE_ID` | _(empty — analytics off)_ | The analytics website identifier the tracker on both pages reports as. While it is empty the tracker script is omitted entirely; clearing it again disables analytics on a deployment. |
+| `analytics.domains` | `ANALYTICS_DOMAINS` | _(empty — every host reports)_ | Comma-delimited domains the tracker reports from; visits from any other host (development, staging) are ignored. Left empty, the attribute is omitted and no host is filtered out. |
+| `analytics.recorder` | `ANALYTICS_RECORDER` | `false` | Whether the pages also embed the session recorder script (`recorder.js`, loaded from the tracker's origin) alongside the tracker. Session recording is the most invasive thing the tracker does, so it is opted into: set it to `true` to enable it on a deployment. |
 
-The tracker's origin (`https://analytics.rock-n-code.com`) is not configurable: it is single-sourced in code so the tracker tag and the `Content-Security-Policy` that must allow it (`security.contentSecurityPolicy` below) always agree. The pages also emit a `preconnect` hint for it, so the cross-origin handshake starts before the parser reaches the deferred tracker script.
+The tracker's origin is not a configuration key: it is single-sourced in code so the tracker tag and the `Content-Security-Policy` that must allow it (`security.contentSecurityPolicy` below) cannot drift apart at runtime. The pages emit a `preconnect` hint for it, so the cross-origin handshake starts before the parser reaches the deferred tracker script.
 
-> **Keep `analytics.domains` in sync with `site.origin`.** Both encode the deployment's public host — the hosts the tracker reports from, and the host the pages are served at. Override one without the other (say, pointing a staging deployment at itself) and the domain filter stops matching: every visit is dropped silently, with no error. To disable analytics on a deployment instead, clear `analytics.websiteID` (see above).
+> **Set `analytics.domains` to the host the deployment actually serves, or leave it empty.** It is an allowlist: name a host the deployment does not serve (say, pointing a staging box at the production domain) and every visit is dropped silently, with no error. To turn analytics off instead, clear `analytics.websiteID`.
 
 ### Security headers
 | Config key | Environment variable | Default |
 | --- | --- | --- |
-| `security.contentSecurityPolicy` | `SECURITY_CONTENT_SECURITY_POLICY` | `default-src 'self'; script-src 'self' https://analytics.rock-n-code.com; connect-src 'self' https://analytics.rock-n-code.com; object-src 'none'; base-uri 'self'; frame-ancestors 'none'` |
+| `security.contentSecurityPolicy` | `SECURITY_CONTENT_SECURITY_POLICY` | `default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'` |
 | `security.contentTypeOptions` | `SECURITY_CONTENT_TYPE_OPTIONS` | `nosniff` |
 | `security.frameOptions` | `SECURITY_FRAME_OPTIONS` | `DENY` |
 | `security.referrerPolicy` | `SECURITY_REFERRER_POLICY` | `strict-origin-when-cross-origin` |
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 56b5caa..aa93d86 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -49,6 +49,7 @@ func application(
         router: router(
             staticFilesPath: reader.staticFilesPath,
             assetVersion: fingerprintAssets(reader.staticFilesPath),
+            analytics: reader.analytics,
             cacheControl: reader.cacheControl,
             compressionMinResponseSize: reader.compressionMinResponseSize,
             rateLimit: reader.rateLimit,
@@ -145,9 +146,10 @@ private func logger(
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
 ///   - assetVersion: the version token the pages append to their asset URLs, or `nil` to leave them unversioned.
+///   - analytics: the analytics tracker both pages embed, or `nil` to omit it.
 ///   - cacheControl: the cache-control directives applied to the served static files.
 ///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
-///   - rateLimit: the rate limit applied to the subscription endpoint.
+///   - rateLimit: the rate limit applied to the rate-limited routes.
 ///   - securityHeaders: the security headers applied to every response.
 ///   - logLevel: the level the request-logging middleware logs at.
 ///   - probe: the probe consulted by the `HealthController` readiness route.
@@ -155,6 +157,7 @@ private func logger(
 private func router(
     staticFilesPath: String,
     assetVersion: String?,
+    analytics: Analytics?,
     cacheControl: CacheControl,
     compressionMinResponseSize: Int,
     rateLimit: RateLimitMiddleware<AppRequestContext>.Configuration,
@@ -180,7 +183,8 @@ private func router(
         )
         LocalizationMiddleware()
         NotFoundMiddleware(
-            assetVersion: assetVersion
+            assetVersion: assetVersion,
+            analytics: analytics
         )
         FileMiddleware(
             staticFilesPath,
@@ -190,7 +194,8 @@ private func router(
 
     router.addController {
         RootController<AppRequestContext>(
-            assetVersion: assetVersion
+            assetVersion: assetVersion,
+            analytics: analytics
         )
         HealthController<AppRequestContext>(
             probe: probe
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index adef521..b317f45 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -14,19 +14,21 @@ package extension ConfigReader {
 
     // MARK: Computed
 
-    /// The analytics tracker the landing page embeds, built from the `analytics.*` keys, or `nil` when `analytics.websiteID` resolves
-    /// empty — a deployment disables analytics entirely by clearing the identifier.
+    /// The analytics tracker both pages embed, built from the `analytics.*` keys, or `nil` when `analytics.websiteID` resolves empty.
+    ///
+    /// The identifier is empty by default, so the template serves no tracker at all until a deployment sets `analytics.websiteID` — and
+    /// clearing it again disables analytics entirely.
     ///
     /// The script URL is not configurable: its origin is single-sourced in `String.Analytics`, so the tracker tag and the
-    /// `Content-Security-Policy` that must allow it derive from one constant and cannot drift apart.
+    /// `Content-Security-Policy` that must allow it derive from one constant and cannot drift apart. Point that constant at your own
+    /// instance, and extend `security.contentSecurityPolicy` to allow it, before enabling analytics.
     ///
-    /// The `analytics.domains` filter must name the host the pages are served from — i.e. the host of ``siteOrigin``. The two keys are
-    /// independent, so a deployment that overrides `site.origin` without matching `analytics.domains` reports from a host it no longer
-    /// serves and records nothing; change them together.
+    /// The `analytics.domains` filter must name the host the pages are served from; it is empty by default, which reports from every host.
+    /// Set it to a host the deployment does not serve and the tracker silently records nothing.
     ///
-    /// Recorder mode is on by default — the pages embed the session recorder script alongside the tracker — and the `analytics.recorder`
-    /// flag turns it off for a deployment. The recorder loads from the same origin as the tracker, so the `Content-Security-Policy` needs
-    /// no extra allowance.
+    /// Recorder mode is off by default — session recording is the most invasive thing the tracker does, so a deployment opts into it
+    /// deliberately with the `analytics.recorder` flag. When on, the pages embed the session recorder script alongside the tracker; it loads
+    /// from the same origin, so the `Content-Security-Policy` needs no extra allowance.
     var analytics: Analytics? {
         let websiteID = string(
             forKey: .Analytics.websiteID,
@@ -46,7 +48,7 @@ package extension ConfigReader {
             ),
             recorder: bool(
                 forKey: .Analytics.recorder,
-                default: true
+                default: false
             )
         )
     }
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index 843d85a..920167c 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -8,6 +8,9 @@ struct IndexPage {
 
     // MARK: Properties
 
+    /// The analytics tracker embedded as a deferred script in the document head, or `nil` to omit it.
+    let analytics: Analytics?
+
     /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
     let assetVersion: String?
 
@@ -23,10 +26,13 @@ struct IndexPage {
     /// - Parameters:
     ///   - locale: the locale the page content is localized to.
     ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
+    ///   - analytics: the analytics tracker embedded in the document head, or `nil` (the default) to omit it.
     init(
         locale: Locale,
-        assetVersion: String? = nil
+        assetVersion: String? = nil,
+        analytics: Analytics? = nil
     ) {
+        self.analytics = analytics
         self.assetVersion = assetVersion
         self.locale = locale
         self.localize = .init(bundle: .module)
diff --git a/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift b/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
index f49730c..0052186 100644
--- a/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
@@ -8,6 +8,9 @@ struct NotFoundPage {
 
     // MARK: Properties
 
+    /// The analytics tracker embedded as a deferred script in the document head, or `nil` to omit it.
+    let analytics: Analytics?
+
     /// The version token appended to the page's asset URLs, or `nil` to leave them unversioned.
     let assetVersion: String?
 
@@ -24,10 +27,13 @@ struct NotFoundPage {
     ///   - locale: the locale the page content is localized to.
     ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
     ///     default) to leave them unversioned.
+    ///   - analytics: the analytics tracker embedded in the document head, or `nil` (the default) to omit it.
     init(
         locale: Locale,
-        assetVersion: String? = nil
+        assetVersion: String? = nil,
+        analytics: Analytics? = nil
     ) {
+        self.analytics = analytics
         self.assetVersion = assetVersion
         self.locale = locale
         self.localize = .init(bundle: .module)
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index b1a440f..98b0559 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -23,14 +23,18 @@ public struct RootController<Context: LocalizedRequestContext> {
     // MARK: Initializers
 
     /// Creates a root controller.
-    /// - Parameter assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
+    /// - Parameters:
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
+    ///   - analytics: the analytics tracker the landing page embeds, or `nil` (the default) to omit it.
     public init(
-        assetVersion: String? = nil
+        assetVersion: String? = nil,
+        analytics: Analytics? = nil
     ) {
         self.responses = .init(bundle: .module) {
             IndexPage(
                 locale: $0,
-                assetVersion: assetVersion
+                assetVersion: assetVersion,
+                analytics: analytics
             )
         }
     }
diff --git a/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift b/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
index 5c850f9..a4a6c11 100644
--- a/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
@@ -6,14 +6,18 @@ public extension NotFoundMiddleware {
     // MARK: Initializers
 
     /// Creates a not-found middleware that renders the website's error page, localized to the module's String Catalog languages.
-    /// - Parameter assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
+    /// - Parameters:
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
+    ///   - analytics: the analytics tracker the error page embeds, or `nil` (the default) to omit it.
     init(
-        assetVersion: String? = nil
+        assetVersion: String? = nil,
+        analytics: Analytics? = nil
     ) {
         self.init(bundle: .module) {
             NotFoundPage(
                 locale: $0,
-                assetVersion: assetVersion
+                assetVersion: assetVersion,
+                analytics: analytics
             )
         }
     }
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 8f7470b..fcea01a 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -1,20 +1,25 @@
 extension String {
     /// A namespace for the analytics default configuration values.
+    ///
+    /// Analytics ships **off**: ``websiteID`` is empty, so the pages embed no tracker until a deployment sets `analytics.websiteID`. Point
+    /// ``origin`` at your own instance before enabling it — the placeholder is an [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606)
+    /// reserved domain, so an unconfigured copy can never report to someone else's server.
     public enum Analytics {
         /// The origin the analytics scripts are loaded from and their beacons are sent to (scheme and host, no trailing slash).
         ///
         /// Single-sourced here: both ``scriptURL`` and the session recorder script the pages embed in recorder mode derive from this
-        /// constant, and the site's `Content-Security-Policy` must allow it.
-        public static let origin = "https://analytics.rock-n-code.com"
+        /// constant. It is deliberately not a configuration key — the `Content-Security-Policy` must allow the same origin, and a value that
+        /// can drift at runtime would silently break the tracker it is supposed to permit.
+        public static let origin = "https://analytics.example.com"
         /// The URL the analytics tracker script is loaded from.
         public static let scriptURL = "\(origin)/script"
-        /// The default analytics website identifier the tracker reports as.
-        public static let websiteID = "f28681d6-20e8-43f3-9c3b-5d6a0f8e0591"
-        /// The default comma-delimited domains the tracker reports from; visits from any other host are ignored.
+        /// The default analytics website identifier the tracker reports as: empty, which omits the tracker entirely.
+        public static let websiteID = ""
+        /// The default comma-delimited domains the tracker reports from: empty, which reports from every host.
         ///
-        /// Keep it paired with the host the pages are served at: a deployment that serves from another host without overriding
-        /// `analytics.domains` to match reports from a host it no longer serves, so analytics silently records nothing.
-        public static let domains = "loud.amsterdam"
+        /// Once set, keep it paired with the host the pages are served at — a deployment that serves from another host without matching
+        /// `analytics.domains` reports from a host it no longer serves, so analytics silently records nothing.
+        public static let domains = ""
     }
     /// A namespace for the persistence's default configuration values and recognized tokens.
     public enum Database {
diff --git a/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift b/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
index 6698938..3558d39 100644
--- a/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
+++ b/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
@@ -12,36 +12,47 @@ struct ConfigReaderPropertiesTests {
     // MARK: Functional tests
 
     @Test
-    func `analytics to default to the production tracker`() throws {
-        let analytics = try #require(reader().analytics)
-
-        #expect(analytics.scriptURL == .Analytics.scriptURL)
-        #expect(analytics.websiteID == .Analytics.websiteID)
-        #expect(analytics.domains == .Analytics.domains)
-        #expect(analytics.excludeHash)
-        #expect(analytics.doNotTrack)
-        #expect(analytics.performance)
-        #expect(analytics.recorder)
+    func `analytics to be omitted by default`() {
+        // The template ships no website identifier, so an unconfigured deployment embeds no tracker at all.
+        #expect(.Analytics.websiteID == "")
+        #expect(reader().analytics == nil)
     }
 
     @Test
-    func `analytics to switch recorder mode off when configured`() throws {
+    func `analytics to be enabled by setting the website id alone`() throws {
         let analytics = try #require(reader(values: [
-            .Analytics.recorder: false
+            .Analytics.websiteID: "0000-website-id"
         ]).analytics)
 
+        #expect(analytics.scriptURL == .Analytics.scriptURL)
+        #expect(analytics.websiteID == "0000-website-id")
+        #expect(analytics.domains.isEmpty)
+        #expect(analytics.excludeHash)
+        #expect(analytics.doNotTrack)
+        #expect(analytics.performance)
         #expect(!analytics.recorder)
     }
 
+    @Test
+    func `analytics to switch recorder mode on when configured`() throws {
+        // Session recording is the most invasive thing the tracker does, so it is opted into rather than out of.
+        let analytics = try #require(reader(values: [
+            .Analytics.websiteID: "0000-website-id",
+            .Analytics.recorder: true
+        ]).analytics)
+
+        #expect(analytics.recorder)
+    }
+
     @Test
     func `analytics to override the website id and domains when configured`() throws {
         let analytics = try #require(reader(values: [
             .Analytics.websiteID: "custom-website-id",
-            .Analytics.domains: "staging.loud.amsterdam"
+            .Analytics.domains: "staging.example.com"
         ]).analytics)
 
         #expect(analytics.websiteID == "custom-website-id")
-        #expect(analytics.domains == "staging.loud.amsterdam")
+        #expect(analytics.domains == "staging.example.com")
         #expect(analytics.scriptURL == .Analytics.scriptURL)
     }
 
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
index a211e9b..1d0752f 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
@@ -131,6 +131,42 @@ struct RootControllerTests {
         }
     }
 
+    @Test
+    func `embeds no analytics tracker by default`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(!body.contains("data-website-id"))
+                #expect(!body.contains("analytics"))
+            }
+        }
+    }
+
+    @Test
+    func `embeds the analytics tracker when one is configured`() async throws {
+        try await app(
+            analytics: .init(
+                scriptURL: "https://analytics.example.com/script",
+                websiteID: "0000-website-id",
+                domains: "example.com"
+            )
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                let body = String(buffer: response.body)
+
+                #expect(body.contains(#"<link rel="preconnect" href="https://analytics.example.com">"#))
+                #expect(body.contains(#"<script defer src="https://analytics.example.com/script" data-website-id="0000-website-id" data-domains="example.com""#))
+            }
+        }
+    }
+
 }
 
 // MARK: - Helpers
@@ -140,11 +176,14 @@ private extension RootControllerTests {
     // MARK: Methods
 
     /// Builds an application whose root controller appends the given version token to the landing
-    /// page's asset URLs.
-    /// - Parameter assetVersion: the version token appended to the page's asset URLs.
+    /// page's asset URLs and embeds the given analytics tracker.
+    /// - Parameters:
+    ///   - assetVersion: the version token appended to the page's asset URLs.
+    ///   - analytics: the analytics tracker the landing page embeds, or `nil` (the default) to omit it.
     /// - Returns: the configured application.
     func app(
-        assetVersion: String?
+        assetVersion: String? = nil,
+        analytics: Analytics? = nil
     ) -> some ApplicationProtocol {
         let router = Router(context: WebsiteRequestContext.self)
 
@@ -153,7 +192,8 @@ private extension RootControllerTests {
         }
 
         router.addRoutes(RootController<WebsiteRequestContext>(
-            assetVersion: assetVersion
+            assetVersion: assetVersion,
+            analytics: analytics
         ).routes)
 
         return Application(router: router)
-- 
2.54.0


From c075adad8475971522a09c6a49e131ed71058a2b Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 13 Aug 2026 03:19:10 +0200
Subject: [PATCH 069/117] Hardened the Docker build of the Website service
 target.

---
 .dockerignore                                |  3 +++
 Services/Website/.env.local                  |  7 +++++--
 Services/Website/Dockerfile                  | 17 +++++++++------
 Services/Website/Makefile                    |  2 +-
 Services/Website/README.md                   | 22 ++++++++++++++++----
 Services/Website/docker-compose.override.yml |  4 +++-
 Services/Website/docker-compose.yml          |  2 +-
 7 files changed, 42 insertions(+), 15 deletions(-)

diff --git a/.dockerignore b/.dockerignore
index b84d7f9..fe1482a 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -10,6 +10,9 @@
 **/.build
 **/.swiftpm
 
+# Test sources
+**/Tests
+
 # Xcode project (not used by the Linux build)
 *.xcodeproj
 
diff --git a/Services/Website/.env.local b/Services/Website/.env.local
index 3835e3e..ff393c8 100644
--- a/Services/Website/.env.local
+++ b/Services/Website/.env.local
@@ -20,8 +20,11 @@ HOST_USER=
 # Name of the Docker image to pull/run.
 IMAGE_NAME=website
 
-# Platform of the Docker image to pull/run.
-IMAGE_PLATFORM=linux/arm64
+# Platform of the deployment image
+IMAGE_PLATFORM=linux/amd64
+
+# Platform of the *local* build only (docker-compose.override.yml)
+BUILD_PLATFORM=linux/arm64
 
 # Tag of the image to pull/run. 
 # Use a semver in production; avoid `latest` so rollbacks are unambiguous.
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index c1c6879..f1230c6 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -1,7 +1,7 @@
 # ================================
 # Asset image
 # ================================
-FROM node:22-alpine AS assets
+FROM node:22-alpine@sha256:c610fcdfb1d5b4740dd70c284ed3cb16bb857e0f7166196e36a5501df7a3aa32 AS assets
 
 ARG ESBUILD_VERSION=0.28.1
 ARG OXIPNG_VERSION=9.1.5
@@ -30,7 +30,7 @@ COPY --from=assets /static /
 # ================================
 # Build image
 # ================================
-FROM swift:6.3-noble AS build
+FROM swift:6.3-noble@sha256:69bf1f0281e13d82c9e49d67c2dd1dcc8c00bad738c860f4323d7078787ec8ea AS build
 
 # Install OS updates
 RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
@@ -59,10 +59,15 @@ COPY ./Packages/Localization/Sources ./Packages/Localization/Sources
 COPY ./Packages/Persistence/Sources ./Packages/Persistence/Sources
 COPY ./Packages/Utility/Sources ./Packages/Utility/Sources
 COPY ./Services/Website/Sources ./Services/Website/Sources
-COPY ./Services/Website/Tests ./Services/Website/Tests
 
-# Build the application, with optimizations, with static linking, and using jemalloc
-RUN swift build --package-path ./Services/Website -c release \
+# Build the application, with optimizations, with static linking, and using jemalloc.
+#
+# SPM validates the path of every target in the root package — including the test targets — even when only the
+# executable product is built, so those directories have to exist. They are created empty instead of copied: the test
+# sources are not needed to compile the product, keeping them out means editing a test never invalidates this layer,
+# and it keeps the local database bind mount under Tests/DB out of the image entirely.
+RUN mkdir -p ./Services/Website/Tests/App ./Services/Website/Tests/Library \
+    && swift build --package-path ./Services/Website -c release \
     --product "Website" \
     --static-swift-stdlib \
     -Xlinker -ljemalloc
@@ -89,7 +94,7 @@ RUN chmod -R a-w ./Resources
 # ================================
 # Run image
 # ================================
-FROM ubuntu:noble
+FROM ubuntu:noble@sha256:561618e2c15bf2397621dd04f96926663a3b5616c189cf7e38db7e82f5c538ea
 
 # Make sure all system packages are up to date, and install only essential packages.
 RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
diff --git a/Services/Website/Makefile b/Services/Website/Makefile
index 7caf706..a5b63fd 100644
--- a/Services/Website/Makefile
+++ b/Services/Website/Makefile
@@ -126,7 +126,7 @@ ast-minify: ## Preview the minified JS/CSS assets in .build/minified
 .PHONY: img-check
 img-check: ## Check the production image builds
 	@docker build \
-		--platform linux/amd64 \
+		--platform $(IMAGE_PLATFORM) \
 		--file Dockerfile \
 		../..
 
diff --git a/Services/Website/README.md b/Services/Website/README.md
index c8c3314..5355f6f 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -246,7 +246,20 @@ cd ../../Packages/Persistence && POSTGRES_TEST_HOST=127.0.0.1 swift test # again
 `POSTGRES_TEST_NAME`/`USERNAME`/`PASSWORD` each default to `site` (and `POSTGRES_TEST_PORT` is optional), so pass the password explicitly when the local container was initialised with a different `DATABASE_PASSWORD`.
 
 ## Deployment
-The production image is built in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080`. `make img-check` pins the build to `linux/amd64`; `make img-release` builds for `IMAGE_PLATFORM`.
+The production image is built in release mode with a statically linked Swift runtime and jemalloc, runs as a non-root `hummingbird` user, and exposes port `8080`.
+
+`IMAGE_PLATFORM` is the single source of truth for the deployment architecture: `make img-check` and `make img-release` both build for it, and `docker-compose.yml` runs the pulled image with it. Keep it matched to the deployment host — the three have to agree, or a release builds for one architecture and the production Compose file refuses to run it. Local development builds are separate and follow `BUILD_PLATFORM` (see `docker-compose.override.yml`), since they target your machine rather than the deployment.
+
+The test sources are deliberately absent from the image. SPM validates the path of every target in the root package — including the test targets — even when only the executable product is built, so the Dockerfile creates those two directories empty rather than copying them. That keeps test edits from invalidating the release-build layer, and keeps the local database bind mount under `Tests/DB` out of the build context entirely (`.dockerignore` excludes `**/Tests` for the same reason).
+
+### Base images
+All three stages pin their base by digest as well as tag, so a rebuild of an old commit resolves the same bases it originally used. The trade-off is that they no longer pick up upstream rebuilds on their own: **refresh the digests deliberately**, on whatever cadence you patch on, with
+
+```sh
+docker buildx imagetools inspect swift:6.3-noble --format '{{.Manifest.Digest}}'
+```
+
+Both build stages are discarded — only `ubuntu:noble` ships — and the build and run stages each `apt-get dist-upgrade`, so OS packages are patched at build time regardless of the pin's age. What a stale pin holds back is the base layer itself.
 
 The executable is the `ENTRYPOINT` and its serving flags are the `CMD`:
 ```dockerfile
@@ -256,7 +269,7 @@ CMD ["--http-host", "0.0.0.0", "--http-port", "8080"]
 The split is what makes the migrate-and-exit invocation below work: `docker compose run --rm website --database-migrate` replaces the `CMD` flags without having to override the entrypoint.
 
 ```sh
-make img-check                  # verify it builds for linux/amd64, without tagging or publishing
+make img-check                  # verify it builds for IMAGE_PLATFORM, without tagging or publishing
 make img-release version=1.2.3  # build, tag, and push a release (an explicit version is required)
 ```
 
@@ -269,7 +282,7 @@ docker compose -f docker-compose.yml up -d
 ### Static assets
 `Resources/Static` holds the site's stylesheets and scripts under `css/` and `js/`, paired by name: `shared.*` is loaded by every page, alongside a per-page `index.*` and `not-found.*`. The remaining files — the icons, `site.webmanifest`, `robots.txt`, and `sitemap.xml` — sit at the root. Every one of them is a case of the `StaticFile` enumeration, which is what the pages derive their URLs from.
 
-The image build optimizes the files under `Resources/Static` in its `assets` stage, in place, with pinned optimizer versions so asset output is reproducible for a given Dockerfile commit:
+The image build optimizes the files under `Resources/Static` in its `assets` stage, in place, with pinned optimizer versions — and on a base image pinned by digest, not just by tag — so asset output is reproducible for a given Dockerfile commit:
 - CSS and JS are minified with [esbuild](https://esbuild.github.io) (every file in `css/` and `js/`).
 - PNG images are losslessly recompressed with [oxipng](https://github.com/oxipng/oxipng), recursively — the output is pixel-identical, only encoded smaller.
 - SVGs are minified with [svgo](https://github.com/svg/svgo), recursively.
@@ -321,7 +334,8 @@ The Makefile and Compose files read these from `.env` (or the environment). Prov
 | `HOST_OWNER` | Registry namespace / owner. |
 | `HOST_USER`, `HOST_PASSWORD` | Registry credentials for `make img-release`. |
 | `IMAGE_NAME`, `IMAGE_TAG` | Image name and tag. `IMAGE_TAG` is the fallback for `make img-release`'s `version=` argument. |
-| `IMAGE_PLATFORM` | Build platform for `make img-release` (e.g. `linux/amd64`). `make img-check` pins `linux/amd64` regardless. |
+| `IMAGE_PLATFORM` | Deployment architecture (default `linux/amd64`). Drives `make img-check`, `make img-release`, and the `platform:` the production Compose file runs the pulled image with — keep it matched to the deployment host. |
+| `BUILD_PLATFORM` | Architecture of the *local* development build only (default `linux/arm64`); set it to `linux/amd64` on an Intel Mac or an amd64 Linux box. Never used by the production Compose file. |
 | `HOST_PORT` | Host port mapped to the container's `8080` (default `8080`). |
 | `LOG_LEVEL` | Runtime log level (default `info`). |
 | `HTTP_SERVER_NAME` | Runtime server name (default `SiteWebsite`). |
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
index 0ece36c..80389f0 100644
--- a/Services/Website/docker-compose.override.yml
+++ b/Services/Website/docker-compose.override.yml
@@ -10,7 +10,9 @@
 services:
   website:
     image: ${IMAGE_NAME}:${IMAGE_TAG:-latest}
-    platform: linux/arm64
+    # The local build targets the development machine, not the deployment: this cancels the base file's
+    # ${IMAGE_PLATFORM}. Set BUILD_PLATFORM=linux/amd64 in .env when developing on an Intel Mac or an amd64 Linux box.
+    platform: ${BUILD_PLATFORM:-linux/arm64}
     build:
       context: ../..
       dockerfile: Services/Website/Dockerfile
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index f9a965d..d7de7b1 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -11,7 +11,7 @@ name: site-platform
 services:
   website:
     image: ${HOST_CONTAINER}/${HOST_OWNER}/${IMAGE_NAME}:${IMAGE_TAG:-latest}
-    platform: linux/amd64
+    platform: ${IMAGE_PLATFORM:-linux/amd64}
     container_name: ${HOST_OWNER}-${IMAGE_NAME}
     restart: unless-stopped
     ports:
-- 
2.54.0


From a5305c6044c7a3b2eb6910b4c5a9ff2006398db1 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 13 Aug 2026 15:56:25 +0200
Subject: [PATCH 070/117] Improved the Docker image and build context for the
 Website service target.

---
 .dockerignore               | 3 +++
 Services/Website/Dockerfile | 5 +++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/.dockerignore b/.dockerignore
index b84d7f9..4d8f56b 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -10,6 +10,9 @@
 **/.build
 **/.swiftpm
 
+# The test database's data directory.
+**/Tests/DB
+
 # Xcode project (not used by the Linux build)
 *.xcodeproj
 
diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index c1c6879..89df2b4 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -70,8 +70,9 @@ RUN swift build --package-path ./Services/Website -c release \
 # Switch to the staging area
 WORKDIR /staging
 
-# Copy main executable to staging area
-RUN cp "$(swift build --package-path /build/Services/Website -c release --show-bin-path)/Website" ./
+# Copy main executable to staging area, without its debug sections
+RUN cp "$(swift build --package-path /build/Services/Website -c release --show-bin-path)/Website" ./ \
+    && strip --strip-debug ./Website
 
 # Copy static swift backtracer binary to staging area
 RUN cp "/usr/libexec/swift/linux/swift-backtrace-static" ./
-- 
2.54.0


From 844a85f88c0827fd13160e8e006ca2f49592729c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 14 Aug 2026 08:33:32 +0200
Subject: [PATCH 071/117] Added the Event type to the Analytics type in the
 Infrastructure package.

---
 .../Sources/Public/Types/Analytics.swift      |  55 +++------
 .../Types/Analytics/AnalyticsAttribute.swift  |  31 ++++++
 .../Types/Analytics/AnalyticsEvent.swift      |  55 +++++++++
 .../Types/Analytics/AnalyticsEventTests.swift | 105 ++++++++++++++++++
 4 files changed, 206 insertions(+), 40 deletions(-)
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsAttribute.swift
 create mode 100644 Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsEvent.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Types/Analytics/AnalyticsEventTests.swift

diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
index 8839c63..9d127d9 100644
--- a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
@@ -1,16 +1,10 @@
 import Foundation
 
-/// The analytics tracker a page embeds: where the script loads from, which site it reports as, which domains it reports from, and how it behaves.
+/// The Umami analytics tracker a page embeds as a deferred `<script>` in its document head.
 ///
-/// A page carries it as an optional value so the ``Page`` scaffolding renders the tracker's deferred `<script>` in the document head, or omits it
-/// when the page has none. The attribute names follow the Umami tracker convention. The three behavior flags default to on, and each renders its
-/// `data-` attribute only when enabled, since the tracker treats an absent attribute as off. Recorder mode, by contrast, defaults to off; when
-/// activated, the page embeds a second deferred script that loads the session recorder from the tracker's origin.
+/// The behavior flags default to on and render their `data-` attributes only when enabled, since the tracker treats an absent attribute as off.
+/// Recorder mode defaults to off; when on, the page embeds a second deferred script loading the session recorder from the tracker's origin.
 public struct Analytics: Sendable {
-    
-    // MARK: Type aliases
-    
-    public typealias Attribute = (name: String, value: String)
 
     // MARK: Properties
 
@@ -66,47 +60,30 @@ public struct Analytics: Sendable {
 
     // MARK: Computed
 
-    /// The tracker script's attributes, in a stable order: the website id and the reporting domains, then each enabled behavior flag.
-    ///
-    /// A disabled flag is left out entirely, since the tracker treats an absent attribute as off. Each `name` is a full attribute name following the
-    /// Umami `data-` convention, which a page applies to the deferred script verbatim — so the page renders the tracker without knowing its shape.
+    /// The tracker script's attributes: the website id and reporting domains, then each enabled behavior flag; disabled flags are omitted.
     public var attributes: [Attribute] {
-        var attributes = [(
-            name: "data-website-id",
-            value: websiteID
-        ), (
-            name: "data-domains",
-            value: domains
-        )]
+        var attributes: [Attribute] = [
+            .init("data-website-id", value: websiteID),
+            .init("data-domains", value: domains)
+        ]
 
         if excludeHash {
-            attributes.append((
-                name: "data-exclude-hash",
-                value: "true"
-            ))
+            attributes.append(.init("data-exclude-hash", value: "true"))
         }
 
         if doNotTrack {
-            attributes.append((
-                name: "data-do-not-track",
-                value: "true"
-            ))
+            attributes.append(.init("data-do-not-track", value: "true"))
         }
 
         if performance {
-            attributes.append((
-                name: "data-performance",
-                value: "true"
-            ))
+            attributes.append(.init("data-performance", value: "true"))
         }
 
         return attributes
     }
 
-    /// The origin the tracker is served from (scheme and host, plus any explicit port), derived from the ``scriptURL``, or `nil` when the
-    /// URL carries no scheme or host.
-    ///
-    /// A page renders it as a `preconnect` hint before the tracker script, so the connection handshake starts as early as possible.
+    /// The origin the tracker is served from (scheme, host, and any explicit port), derived from the ``scriptURL``; `nil` when the URL
+    /// carries no scheme or host. Rendered as a `preconnect` hint before the tracker script.
     public var origin: String? {
         guard
             let url = URL(string: scriptURL),
@@ -121,10 +98,8 @@ public struct Analytics: Sendable {
         return "\(scheme)://\(host)\(port)"
     }
 
-    /// The URL the session recorder script is loaded from, derived from the tracker's ``origin``, or `nil` when ``recorder`` mode is off
-    /// or no origin can be derived from the ``scriptURL``.
-    ///
-    /// A page renders it as a second deferred script tag after the tracker script, carrying only the `data-website-id` attribute.
+    /// The URL the session recorder script is loaded from; `nil` when ``recorder`` mode is off or no ``origin`` can be derived.
+    /// Rendered as a second deferred script carrying only the `data-website-id` attribute.
     public var recorderScriptURL: String? {
         guard recorder, let origin else {
             return nil
diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsAttribute.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsAttribute.swift
new file mode 100644
index 0000000..370329d
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsAttribute.swift
@@ -0,0 +1,31 @@
+extension Analytics {
+    /// A name-value pair rendered as an HTML attribute.
+    ///
+    /// The ``name`` is a full `data-` attribute name applied verbatim — except inside ``Analytics/Event/properties``, where it is the bare
+    /// key the event prefixes on render.
+    public struct Attribute: Equatable, Sendable {
+
+        // MARK: Properties
+
+        /// The attribute's name.
+        public let name: String
+
+        /// The attribute's value.
+        public let value: String
+
+        // MARK: Initializers
+
+        /// Creates a tracker attribute.
+        /// - Parameters:
+        ///   - name: the attribute's name.
+        ///   - value: the attribute's value.
+        public init(
+            _ name: String,
+            value: String
+        ) {
+            self.name = name
+            self.value = value
+        }
+
+    }
+}
diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsEvent.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsEvent.swift
new file mode 100644
index 0000000..c552cfa
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics/AnalyticsEvent.swift
@@ -0,0 +1,55 @@
+extension Analytics {
+    /// An interaction a page reports to the tracker, rendered as `data-` attributes on the element that carries it.
+    ///
+    /// The tracker records a click on any element carrying `data-umami-event`; each `data-umami-event-<name>` beside it becomes a property
+    /// the report can be broken down by. Reports group by ``name``, so related interactions should share one name and differ by a property.
+    public struct Event: Equatable, Sendable {
+
+        // MARK: Properties
+
+        /// The event's name, which is what a report groups by.
+        public let name: String
+
+        /// The event's properties, in declaration order, which is the order they render.
+        ///
+        /// Each ``Attribute/name`` is the bare key — `set`, not `data-umami-event-set`; ``attributes`` adds the prefix.
+        public let properties: [Attribute]
+
+        // MARK: Initializers
+
+        /// Creates an event.
+        /// - Parameters:
+        ///   - name: the event's name, which is what a report groups by.
+        ///   - properties: the event's properties as bare keys — `set`, not `data-umami-event-set` — rendered in the order written.
+        ///     Empty by default.
+        public init(
+            name: String,
+            properties: KeyValuePairs<String, String> = [:]
+        ) {
+            self.name = name
+            self.properties = properties.map {
+                .init($0.key, value: $0.value)
+            }
+        }
+
+        // MARK: Computed
+
+        /// The event's attributes — the event name, then each property — as full `data-` attribute names an element applies verbatim.
+        public var attributes: [Attribute] {
+            [.init(Constant.Name.prefix, value: name)]
+            + properties.map {
+                .init("\(Constant.Name.prefix)-\($0.name)", value: $0.value)
+            }
+        }
+
+    }
+}
+
+// MARK: - Constants
+
+private enum Constant {
+    enum Name {
+        /// The attribute name the tracker watches for, and the prefix each property renders under.
+        static let prefix = "data-umami-event"
+    }
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/Analytics/AnalyticsEventTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/Analytics/AnalyticsEventTests.swift
new file mode 100644
index 0000000..6256ac6
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/Analytics/AnalyticsEventTests.swift
@@ -0,0 +1,105 @@
+import Testing
+
+@testable import Infrastructure
+
+@Suite(
+    "Analytics.Event type",
+    .tags(.type)
+)
+struct AnalyticsEventTests {
+
+    // MARK: Computed tests
+
+    @Test
+    func `renders the event name alone when it carries no properties`() {
+        let event = Analytics.Event(name: "instagram")
+
+        #expect(event.attributes.count == 1)
+        #expect(event.attributes[0] == Analytics.Attribute(
+            "data-umami-event",
+            value: "instagram"
+        ))
+    }
+
+    @Test
+    func `renders each property as an attribute suffixed by its key`() {
+        let event = Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        )
+
+        #expect(event.attributes.count == 2)
+        #expect(event.attributes[1] == Analytics.Attribute(
+            "data-umami-event-set",
+            value: "avc-xi"
+        ))
+    }
+
+    @Test
+    func `renders the name first, then the properties in the order given`() {
+        let event = Analytics.Event(
+            name: "interview",
+            properties: [
+                "placement": "credit",
+                "locale": "en",
+            ]
+        )
+
+        // The order is the rendered attribute order, which a dictionary would leave to churn between builds.
+        #expect(event.attributes.map(\.name) == [
+            "data-umami-event",
+            "data-umami-event-placement",
+            "data-umami-event-locale",
+        ])
+        #expect(event.attributes.map(\.value) == ["interview", "credit", "en"])
+    }
+
+    // MARK: Equatable tests
+
+    @Test
+    func `matches an event rendering the same attributes`() {
+        let event = Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        )
+
+        #expect(event == Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        ))
+    }
+
+    @Test(arguments: [
+        Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-ix"]
+        ),
+        Analytics.Event(
+            name: "playlist",
+            properties: ["show": "avc-xi"]
+        ),
+        Analytics.Event(
+            name: "apple_music",
+            properties: ["set": "avc-xi"]
+        ),
+        Analytics.Event(name: "playlist"),
+        Analytics.Event(
+            name: "playlist",
+            properties: [
+                "set": "avc-xi",
+                "placement": "strip",
+            ]
+        ),
+    ])
+    func `differs from an event rendering anything else`(
+        from other: Analytics.Event
+    ) {
+        let event = Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        )
+
+        #expect(event != other)
+    }
+
+}
-- 
2.54.0


From 7d53be539e9998273902ffc6d5c65d91e4dfc4b7 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 14 Aug 2026 12:44:31 +0200
Subject: [PATCH 072/117] Bundled the static files into the App test target.

---
 Services/Website/Package.swift            |  7 ++++++-
 Services/Website/Tests/App/AppTests.swift | 20 ++++++++++++--------
 Services/Website/Tests/App/Static         |  1 +
 3 files changed, 19 insertions(+), 9 deletions(-)
 create mode 120000 Services/Website/Tests/App/Static

diff --git a/Services/Website/Package.swift b/Services/Website/Package.swift
index f3539f9..f21be13 100644
--- a/Services/Website/Package.swift
+++ b/Services/Website/Package.swift
@@ -120,7 +120,12 @@ let package = Package(
                     package: "hummingbird"
                 ),
             ],
-            path: "Tests/App"
+            path: "Tests/App",
+            resources: [
+                // `Static` links to the service's `Resources/Static`, copying it into the test bundle at build
+                // time — the tests must not read the repository tree, which Xcode's test runner is denied.
+                .copy("Static")
+            ]
         ),
         .testTarget(
             name: "WebsiteLibraryTests",
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index e8b425c..a455a32 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -20,14 +20,18 @@ struct AppTests {
         .js
     ]
 
-    // Absolute path to the package's "Resources/Static" folder, derived from this
-    // file's location so the static files resolve regardless of the working directory.
-    private let staticFilesPath = URL(fileURLWithPath: #filePath)
-        .deletingLastPathComponent()  // Tests/App
-        .deletingLastPathComponent()  // Tests
-        .deletingLastPathComponent()  // package root
-        .appendingPathComponent(.Path.staticResources)
-        .path
+    // Absolute path to the copy of the package's "Resources/Static" folder made into the test bundle
+    // at build time — the repository tree itself is off limits to Xcode's test runner.
+    private let staticFilesPath: String = {
+        guard let url = Bundle.module.url(
+            forResource: "Static",
+            withExtension: nil
+        ) else {
+            preconditionFailure("The static files are missing from the test bundle.")
+        }
+
+        return url.path
+    }()
 
     // MARK: Functional tests
 
diff --git a/Services/Website/Tests/App/Static b/Services/Website/Tests/App/Static
new file mode 120000
index 0000000..dcadd44
--- /dev/null
+++ b/Services/Website/Tests/App/Static
@@ -0,0 +1 @@
+../../Resources/Static
\ No newline at end of file
-- 
2.54.0


From 091c0f06869ff3dd2070504159c58db1abf01080 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 15 Aug 2026 23:41:53 +0200
Subject: [PATCH 073/117] Added an optional per-asset folder to the Asset
 protocol and the AssetExtension extension in the Infrastructure package.

---
 .../Public/Enumerations/AssetExtension.swift       |  4 ++--
 .../Sources/Public/Protocols/Asset.swift           | 13 +++++++++++--
 .../Public/Enumerations/AssetExtensionTests.swift  | 10 +++++-----
 .../Tests/Cases/Public/Protocols/AssetTests.swift  | 14 ++++++++++++--
 .../Tests/Utils/Assets/StubAsset.swift             |  3 ++-
 5 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
index 9d1ae00..bdcd25e 100644
--- a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
+++ b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
@@ -40,8 +40,8 @@ public extension AssetExtension {
         }
     }
 
-    /// The sub-directory within the static root that holds files with this extension, if any.
-    var subdirectory: String? {
+    /// The folder within the static root that holds files with this extension, if any.
+    var folder: String? {
         switch self {
         case .css: "css"
         case .js: "js"
diff --git a/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift b/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
index be5506d..32173a9 100644
--- a/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
+++ b/Packages/Infrastructure/Sources/Public/Protocols/Asset.swift
@@ -1,11 +1,15 @@
 /// An asset shipped with a website: a file stored under the static files root and served by Hummingbird's `FileMiddleware` middleware.
 ///
 /// A conforming asset supplies its file name and the extensions it is available with, each resolving to its own file; the protocol derives the paths from them:
-/// the file's path within the static files root and the URL path it is served at, optionally versioned to bust caches.
+/// the file's path within the static files root and the URL path it is served at, optionally versioned to bust caches. Each file lands in its extension's own
+/// folder unless the asset names a ``folder`` of its own.
 public protocol Asset: Sendable {
 
     // MARK: Properties
 
+    /// The folder within the static files root that holds the asset's files, or `nil` (the default) to use each extension's own folder.
+    var folder: String? { get }
+
     /// The file extensions the asset is available with.
     var fileExtensions: [AssetExtension] { get }
 
@@ -18,6 +22,11 @@ public protocol Asset: Sendable {
 
 public extension Asset {
 
+    // MARK: Computed
+
+    /// The asset's files live in each extension's own folder by default.
+    var folder: String? { nil }
+
     // MARK: Methods
 
     /// Resolves the asset's path against the given base directory.
@@ -50,7 +59,7 @@ public extension Asset {
     ) -> String {
         let file = "\(fileName).\(fileExtension.rawValue)"
 
-        return fileExtension.subdirectory
+        return (folder ?? fileExtension.folder)
             .map { "\($0)/\(file)" } ?? file
     }
 
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
index f49dbea..f1fff74 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
@@ -23,13 +23,13 @@ struct AssetExtensionTests {
 
     @Test(arguments: zip(
         Self.extensions,
-        Self.subdirectories
+        Self.folders
     ))
-    func `subdirectory`(
+    func `folder`(
         for fileExtension: AssetExtension,
-        expects subdirectory: String?
+        expects folder: String?
     ) {
-        #expect(fileExtension.subdirectory == subdirectory)
+        #expect(fileExtension.folder == folder)
     }
 
 }
@@ -60,7 +60,7 @@ private extension AssetExtensionTests {
         "application/manifest+json",
         "application/xml"
     ]
-    static let subdirectories: [String?] = [
+    static let folders: [String?] = [
         "css",
         "js",
         nil,
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
index 08b392b..013e2eb 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Protocols/AssetTests.swift
@@ -14,6 +14,11 @@ struct AssetTests {
         fileExtensions: [.png],
         fileName: "icon"
     )
+    private let portrait = StubAsset(
+        folder: "img/organizer",
+        fileExtensions: [.jpg],
+        fileName: "portrait"
+    )
     private let shared = StubAsset(
         fileExtensions: [.css, .js],
         fileName: "shared"
@@ -22,13 +27,18 @@ struct AssetTests {
     // MARK: Method tests
 
     @Test
-    func `relative path nests the file inside its extension's sub-directory`() {
+    func `relative path nests the file inside its extension's folder`() {
         #expect(shared.relativePath(for: .css) == "css/shared.css")
         #expect(shared.relativePath(for: .js) == "js/shared.js")
     }
 
     @Test
-    func `relative path keeps the file at the root without a sub-directory`() {
+    func `relative path prefers the asset's own folder over the extension's`() {
+        #expect(portrait.relativePath(for: .jpg) == "img/organizer/portrait.jpg")
+    }
+
+    @Test
+    func `relative path keeps the file at the root without a folder`() {
         #expect(image.relativePath(for: .png) == "icon.png")
     }
 
diff --git a/Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift b/Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift
index c508008..9000a1c 100644
--- a/Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift
+++ b/Packages/Infrastructure/Tests/Utils/Assets/StubAsset.swift
@@ -1,10 +1,11 @@
 import Infrastructure
 
-/// An ``Asset`` with a fixed file name and set of extensions.
+/// An ``Asset`` with a fixed file name and set of extensions, optionally held in a folder of its own.
 struct StubAsset: Asset {
 
     // MARK: Properties
 
+    var folder: String? = nil
     let fileExtensions: [AssetExtension]
     let fileName: String
 
-- 
2.54.0


From b6ad9ff497a2fed78a73744c5a14cea6f89ae433 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 20 Aug 2026 00:54:29 +0200
Subject: [PATCH 074/117] Fixed the analytics and security headers for the
 Website service target.

---
 Services/Website/.env.local                   | 41 +++++++++++++++++--
 .../Public/Extensions/String+Constants.swift  |  2 +-
 Services/Website/docker-compose.yml           |  3 ++
 3 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/Services/Website/.env.local b/Services/Website/.env.local
index ff393c8..31ed678 100644
--- a/Services/Website/.env.local
+++ b/Services/Website/.env.local
@@ -1,6 +1,6 @@
 # Local `.env` file used solely for Development purposes.
 
-# --- Image / deployment -------------------------------------------------------
+# --- Image / deployment ------------------------------------------------------
 
 # Host name of the container running the Website service.
 HOST_CONTAINER=containers.rock-n-code.com
@@ -30,7 +30,7 @@ BUILD_PLATFORM=linux/arm64
 # Use a semver in production; avoid `latest` so rollbacks are unambiguous.
 IMAGE_TAG=latest
 
-# --- Application config -------------------------------------------------------
+# --- Application config ------------------------------------------------------
 
 # Server name reported by the HTTP service.
 HTTP_SERVER_NAME=SiteWebsite
@@ -38,7 +38,42 @@ HTTP_SERVER_NAME=SiteWebsite
 # Log verbosity: trace | debug | info | notice | warning | error | critical
 LOG_LEVEL=debug
 
-# --- Persistence ----------------------------------------------------------------
+# --- Analytics ---------------------------------------------------------------
+
+# Umami website identifier; empty omits the tracker. Set `String.Analytics.origin`
+# and allow it in `security.contentSecurityPolicy` first, or the tracker is blocked.
+ANALYTICS_WEBSITE_ID=
+
+# Comma-delimited hosts the tracker reports from; empty reports from every host.
+# A host the deployment does not serve drops every visit silently.
+ANALYTICS_DOMAINS=
+
+# Whether the pages also embed the session recorder script: true | false
+ANALYTICS_RECORDER=false
+
+# --- Security ----------------------------------------------------------------
+
+# `Content-Security-Policy`. Must allow `String.Analytics.origin` in `script-src` and
+# `connect-src`, or the tracker is blocked; drop those two once analytics is off.
+SECURITY_CONTENT_SECURITY_POLICY=default-src 'self'; script-src 'self' https://analytics.rock-n-code.com; connect-src 'self' https://analytics.rock-n-code.com; object-src 'none'; base-uri 'self'; frame-ancestors 'none'
+
+# `X-Content-Type-Options`: disables MIME sniffing.
+SECURITY_CONTENT_TYPE_OPTIONS=nosniff
+
+# `X-Frame-Options`: DENY | SAMEORIGIN
+SECURITY_FRAME_OPTIONS=DENY
+
+# `Referrer-Policy`.
+SECURITY_REFERRER_POLICY=strict-origin-when-cross-origin
+
+# `Permissions-Policy`: denies browser features the site does not use.
+SECURITY_PERMISSIONS_POLICY=accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()
+
+# `Strict-Transport-Security`. Left unset: browsers ignore it over plain HTTP but
+# remember it stickily once seen, so it stays off in local development.
+# SECURITY_STRICT_TRANSPORT_SECURITY=max-age=31536000; includeSubDomains
+
+# --- Persistence -------------------------------------------------------------
 
 # Persistence driver: inMemory (default, no infrastructure) or postgres.
 DATABASE_DRIVER=inMemory
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index fcea01a..3c35954 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -10,7 +10,7 @@ extension String {
         /// Single-sourced here: both ``scriptURL`` and the session recorder script the pages embed in recorder mode derive from this
         /// constant. It is deliberately not a configuration key — the `Content-Security-Policy` must allow the same origin, and a value that
         /// can drift at runtime would silently break the tracker it is supposed to permit.
-        public static let origin = "https://analytics.example.com"
+        public static let origin = "https://analytics.rock-n-code.com"
         /// The URL the analytics tracker script is loaded from.
         public static let scriptURL = "\(origin)/script"
         /// The default analytics website identifier the tracker reports as: empty, which omits the tracker entirely.
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index d7de7b1..25773e3 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -20,6 +20,9 @@ services:
       LOG_LEVEL: ${LOG_LEVEL:-info}
       HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-SiteWebsite}
       SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
+      # Falls back to the policy the app ships with; set it in `.env` to allow the analytics origin,
+      # which must match `String.Analytics.origin`.
+      SECURITY_CONTENT_SECURITY_POLICY: "${SECURITY_CONTENT_SECURITY_POLICY:-default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'}"
       # Persistence: a managed PostgreSQL database. Provide the password via the environment or a secret — never
       # commit it.
       DATABASE_DRIVER: ${DATABASE_DRIVER:-postgres}
-- 
2.54.0


From 6ecc20987fde2c933594ec56f6805b3feeddfad1 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 20 Aug 2026 01:10:37 +0200
Subject: [PATCH 075/117] Updated the README file in the repository root.

---
 README.md | 126 +++++++++++++++++++++++++++++-------------------------
 1 file changed, 68 insertions(+), 58 deletions(-)

diff --git a/README.md b/README.md
index a415db4..1790d21 100644
--- a/README.md
+++ b/README.md
@@ -1,97 +1,97 @@
 # Website Template
 
-This repository is a **template** for the platform's websites. It ships as a
-complete, buildable reference site whose identity is the neutral placeholder
-**`Site`** / **`site`**. You generate a real site from it in two steps: create
-a fresh repository, then run the bootstrap script to stamp in your site's
-display name, slug, and canonical URL.
+A **template** for the platform's websites, shipping as a complete, buildable
+reference site under the placeholder identity **`Site`** / **`site`**. Generating
+a real site takes two steps: create a fresh repository, then run the bootstrap
+script to stamp in the display name, slug, and canonical URL.
 
 ## What's in here
 
 | Path | Role |
 | --- | --- |
-| [`Services/Website`](Services/Website/README.md) | The Hummingbird website service — the executable, the pages, the static assets, and the Docker/Compose deployment. Its README is the operational reference. |
-| [`Packages/Infrastructure`](Packages/Infrastructure/README.md) | Shared Hummingbird toolkit: declarative routing, the hardened middlewares, the `Page`/`Asset` scaffolding, and the pre-rendered localized responses. |
+| [`Services/Website`](Services/Website/README.md) | The Hummingbird website service — executable, pages, static assets, Docker/Compose deployment. Its README is the operational reference. |
+| [`Packages/Infrastructure`](Packages/Infrastructure/README.md) | Shared Hummingbird toolkit: declarative routing, the hardened middlewares, the `Page`/`Asset` scaffolding, the head-metadata types (`SocialCard`, `StructuredData`, `Analytics`), and the pre-rendered localized responses. |
 | [`Packages/Localization`](Packages/Localization/README.md) | String Catalog lookups, `Accept-Language` negotiation, and the catalog-derived language list. |
-| [`Packages/Persistence`](Packages/Persistence/README.md) | The Fluent data layer: driver selection, migration registration, and the readiness probe. |
+| [`Packages/Persistence`](Packages/Persistence/README.md) | The Fluent data layer: driver selection (in-memory SQLite or PostgreSQL), migration registration, and the readiness probe. |
 | [`Packages/Utility`](Packages/Utility/README.md) | Dependency-free helpers shared across the services. |
 | `Site.xcodeproj` | The umbrella Xcode project (renamed to your site by bootstrap). |
 | `Scripts/bootstrap` | The generator. Rewrites placeholders, then deletes itself. |
 | `Makefile` | Bootstrap convenience only (`make bootstrap`); removed by the script. |
 
 All four packages are **vendored**, not fetched: the service depends on them by
-relative path, so each generated repository owns its own copy. That is
-deliberate — a generated site is fully self-contained and can diverge freely.
-The trade-off is that engine fixes are propagated to existing sites by hand (or
-by re-generating and porting content).
+relative path, so every generated repository owns its copy and can diverge
+freely. The trade-off is that engine fixes reach existing sites only by hand.
 
 ## Requirements
 
 - Swift 6.3 toolchain (every manifest is `swift-tools-version:6.3`).
-- Docker — optional, for the containerized run/deploy workflow.
-- The Hummingbird CLI (`hb`) — optional, only for `make site-run`.
+- Docker — optional: the containerized run/deploy workflow, the local PostgreSQL
+  instance (`make db-mount`), and the asset-optimization preview.
+- Hummingbird CLI (`hb`) — optional, only for `make site-run`.
 
-See [the service README](Services/Website/README.md) for configuration keys,
-persistence, testing, and deployment.
+Configuration keys, persistence, testing, and deployment are documented in
+[the service README](Services/Website/README.md).
 
 ## Generating a new site
 
 ### 1. Create a repository from this template
 
-On Gitea, mark this repository as a template once (repository **Settings →
-Template → “Template” checkbox**). New sites are then created with the
-**“Use this template”** button, which produces a fresh repository with its own
-history — no template commits carried over.
+On Gitea, mark this repository as a template once (**Settings → Template →
+“Template”**); new sites then come from the **“Use this template”** button, each
+with its own history.
 
-> No Gitea button? Just clone this repo, `rm -rf .git`, and continue — the
-> bootstrap script offers to re-initialise git for you.
+> No Gitea button? Clone this repo, `rm -rf .git`, and continue — bootstrap
+> offers to re-initialise git.
 
 ### 2. Bootstrap
 
-Clone the new repository, then from its root run:
+From the new repository's root:
 
 ```sh
 make bootstrap        # or: ./Scripts/bootstrap
 ```
 
-You'll be asked for:
-
 | Prompt | Example | Rewrites |
 | --- | --- | --- |
 | **Site display name** (PascalCase) | `Loud` | Server name (`LoudWebsite`), `Loud.xcodeproj`, README title. |
 | **Project slug** (lowercase) | `loud-ams` | Container owner, database name/user, Compose project name. |
 | **Canonical site URL** (scheme + host) | `https://loud.amsterdam` | The `Sitemap:` reference in `robots.txt` and the `<loc>` entry in `sitemap.xml`. |
 
-The canonical URL defaults to the reserved placeholder `https://site.example.com`;
-leaving it there is allowed (the script warns), so you can bootstrap before the
-domain is decided and set it later in the two crawler files.
-
-The script rewrites the placeholder occurrences in place, renames
-`Site.xcodeproj`, optionally starts a fresh git history, and then removes
-itself along with this file and the root `Makefile`. It refuses to run outside
-the repository root, and validates the URL before touching anything — a
-rejected value leaves the tree untouched, so it is safe to re-run.
-
-Accepting the default display name (`Site`) is supported: the rename is skipped
-and the placeholders simply stay in place.
+- The URL defaults to the reserved `https://site.example.com`; leaving it is
+  allowed (the script warns) and can be corrected later in the two crawler files.
+- Keeping the default display name `Site` is allowed too: the Xcode rename is
+  skipped and the placeholders stay in place.
+- The script refuses to run outside the repository root and validates the URL
+  before writing, so a rejected value leaves the tree untouched.
+- It rewrites in place, renames `Site.xcodeproj`, optionally starts a fresh git
+  history, then deletes itself, this file, and the root `Makefile`.
 
 ### 3. Fill in the content
 
-Bootstrap leaves reminders, but in short:
-
 1. **Copy & localization** — `Services/Website/Sources/Library/Catalogs/Localizable.xcstrings`
    (English only out of the box) and the landing / 404 pages under
    `Services/Website/Sources/Library`.
 2. **Static assets** — `Services/Website/Resources/Static` (CSS, JS, favicon, icons).
    The manifest's `name` / `short_name` are empty and are not rewritten by bootstrap.
 3. **Head metadata** — the pages ship no `summary`, `canonicalURL`, `socialCard`, or
-   `structuredData`, so there is no meta description, no link preview, and no JSON-LD
-   until you supply them. See
-   [Page metadata](Services/Website/README.md#page-metadata).
-4. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
-   `Services/Website/.env` (the committed `.env.local` is an example only).
-5. **Domain models** — the `Persistence` package ships a sample
-   `ExampleRecord` / `ExampleRepository`; replace it when you add real data.
+   `structuredData`: no meta description, no link preview, no JSON-LD until you
+   supply them. See [Page metadata](Services/Website/README.md#page-metadata).
+4. **Analytics** — the cookieless [Umami](https://umami.is) tracker ships **off**
+   (`analytics.websiteID` is empty, so no third-party script is requested).
+   Enabling it, in order: point `String.Analytics.origin` at the instance you
+   report to, allow that origin in `security.contentSecurityPolicy` (`.env.local`
+   already does; `docker-compose.yml` falls back to a `'self'`-only policy), then
+   set `ANALYTICS_WEBSITE_ID`. `ANALYTICS_DOMAINS` limits which hosts report;
+   `ANALYTICS_RECORDER` opts into the session recorder. See
+   [Analytics](Services/Website/README.md#analytics).
+5. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
+   `Services/Website/.env`; the committed `.env.local` is an example and defaults
+   the password to the slug.
+6. **Domain models** — replace the `Persistence` package's sample `ExampleRecord`
+   / `ExampleRepository`. The default driver is in-memory SQLite, migrated on
+   every boot; a real site sets `DATABASE_DRIVER=postgres` and migrates out of
+   band (`swift run Website --database-migrate`). See
+   [Persistence](Services/Website/README.md#persistence).
 
 ### 4. Build & run
 
@@ -105,31 +105,41 @@ make site-mount        # docker compose up --build
 ## What bootstrap does NOT change
 
 - Organisation (`Röck+Cöde VoF`) and Xcode `DEVELOPMENT_TEAM` — shared across all sites.
-- The package architecture, middleware, security headers, and persistence layer.
-- The generic `website` image name and `Makefile` command names (`site-run`, `site-mount`, …).
-- The four `Packages/*/README.md` files — no rewrite line covers them, so whatever
-  site name they mention ships as-is into every generated repository.
+- The package architecture, middlewares, security headers, and persistence layer
+  (PostgreSQL, behind the in-memory SQLite default).
+- The analytics origin: `String.Analytics.origin` and the `Content-Security-Policy`
+  in `.env.local` that allows it both name the platform's shared Umami instance.
+  Tracking stays off until a site sets `ANALYTICS_WEBSITE_ID`.
+- The generic `website` image name and the `Makefile` target names (`site-run`,
+  `site-mount`, …).
+- The four `Packages/*/README.md` files and the package sources — no rewrite line
+  covers them, so whatever site name they carry ships as-is. `Packages/Persistence`'s
+  PostgreSQL integration test defaults its `POSTGRES_TEST_*` credentials to `site`.
 
 ## Maintaining the template itself
 
-Edit and test the reference site directly — it builds and its tests pass with
-the `Site` / `site` placeholders in place:
+Edit and test the reference site directly — it builds and its tests pass with the
+`Site` / `site` placeholders in place:
 
 ```sh
 (cd Services/Website && make pkg-test)      # the service's own two test targets
 (cd Packages/Infrastructure && swift test)  # and likewise for each vendored package
 ```
 
-Keep the placeholders intact so the bootstrap script's targeted replacements
-keep matching. They are:
+No external infrastructure is needed: `Packages/Persistence`'s PostgreSQL
+integration test skips itself unless `POSTGRES_TEST_HOST` is set. To run it,
+start the database (`cd Services/Website && make db-mount`), then
+`POSTGRES_TEST_HOST=127.0.0.1 swift test`.
+
+Keep the placeholders intact so the bootstrap rewrites keep matching:
 
 | Placeholder | Appears in |
 | --- | --- |
 | `Site` | Xcode project name and `project.pbxproj`, the service README title |
 | `SiteWebsite` | `String+Constants.swift`, `.env.local`, `docker-compose.yml`, the service README |
-| `site` | `String+Constants.swift` defaults, `HOST_OWNER` / `DATABASE_*` in `.env.local` and Compose, the `site-platform` Compose project, the `Makefile` `db-shell` fallbacks |
+| `site` | `String+Constants.swift` defaults, `HOST_OWNER` / `DATABASE_*` in `.env.local` and both Compose files, the `site-platform` Compose project, the `Makefile` `db-shell` fallbacks |
 | `https://site.example.com` | `Resources/Static/robots.txt`, `Resources/Static/sitemap.xml` |
 
-If you introduce a new site-specific value, give it a placeholder from this set
-and add a matching rewrite line in `Scripts/bootstrap` — a value that no rewrite
-covers ships verbatim into every generated site.
+A new site-specific value needs a placeholder from this set and a matching
+rewrite line in `Scripts/bootstrap`; anything else ships verbatim into every
+generated site.
-- 
2.54.0


From 6c014525bf41f10103e3171ed640b5b532e7cee2 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 20 Aug 2026 01:14:49 +0200
Subject: [PATCH 076/117] Updated the analytics origin documentation for the
 Website service target.

---
 Scripts/bootstrap                                         | 6 +++---
 Services/Website/README.md                                | 2 +-
 .../Library/Public/Extensions/String+Constants.swift      | 8 ++++----
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Scripts/bootstrap b/Scripts/bootstrap
index b6c7b11..e5cfd71 100755
--- a/Scripts/bootstrap
+++ b/Scripts/bootstrap
@@ -194,9 +194,9 @@ Next steps:
        - $W/Resources/Static/site.webmanifest                 (name / short_name)
   2. Set a real database password in a git-ignored $W/.env
      (the committed .env.local defaults the password to the slug — do NOT ship that).
-  3. Analytics ships OFF, and stays off until you opt in. To enable it: point
-     String.Analytics.origin at your own Umami instance (it defaults to the
-     reserved https://analytics.example.com), allow that origin in
+  3. Analytics ships OFF, and stays off until you opt in. To enable it: check
+     String.Analytics.origin (it defaults to the platform instance at
+     https://analytics.rock-n-code.com), allow that origin in
      security.contentSecurityPolicy, then set ANALYTICS_WEBSITE_ID.
   4. Point the git remote at your new repository:
        git remote set-url origin <new-repo-url>     # or 'git remote add origin ...'
diff --git a/Services/Website/README.md b/Services/Website/README.md
index 5355f6f..ca0d288 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -145,7 +145,7 @@ See [Persistence](#persistence-1) below for the workflow.
 ### Analytics
 The template ships analytics **off**: `analytics.websiteID` is empty, so both pages embed no tracker at all and no third-party script is requested. Enabling it takes three steps, in this order:
 
-1. Point `String.Analytics.origin` (`Sources/Library/Public/Extensions/String+Constants.swift`) at your own [Umami](https://umami.is) instance. It ships as `https://analytics.example.com`, an [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606) reserved domain, so an unconfigured copy can never report to somebody else's server.
+1. Check `String.Analytics.origin` (`Sources/Library/Public/Extensions/String+Constants.swift`). It ships as `https://analytics.rock-n-code.com`, the platform's shared [Umami](https://umami.is) instance; point it elsewhere if this site reports to another one. The origin alone tracks nothing — the tracker is omitted entirely while `analytics.websiteID` is empty.
 2. Extend `security.contentSecurityPolicy` to allow that origin in `script-src` and `connect-src` — the default policy is `'self'`-only, so the tracker is blocked until you do.
 3. Set `ANALYTICS_WEBSITE_ID` on the deployment.
 
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 3c35954..e95e120 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -1,15 +1,15 @@
 extension String {
     /// A namespace for the analytics default configuration values.
     ///
-    /// Analytics ships **off**: ``websiteID`` is empty, so the pages embed no tracker until a deployment sets `analytics.websiteID`. Point
-    /// ``origin`` at your own instance before enabling it — the placeholder is an [RFC 2606](https://www.rfc-editor.org/rfc/rfc2606)
-    /// reserved domain, so an unconfigured copy can never report to someone else's server.
+    /// Analytics ships **off**: ``websiteID`` is empty, so the pages embed no tracker until a deployment sets `analytics.websiteID`. Until
+    /// then ``origin`` is inert — it names the platform's shared instance, which a site reporting to another one repoints before enabling
+    /// analytics.
     public enum Analytics {
         /// The origin the analytics scripts are loaded from and their beacons are sent to (scheme and host, no trailing slash).
         ///
         /// Single-sourced here: both ``scriptURL`` and the session recorder script the pages embed in recorder mode derive from this
         /// constant. It is deliberately not a configuration key — the `Content-Security-Policy` must allow the same origin, and a value that
-        /// can drift at runtime would silently break the tracker it is supposed to permit.
+        /// can drift at runtime would silently break the tracker it is supposed to permit. Defaults to the platform's shared Umami instance.
         public static let origin = "https://analytics.rock-n-code.com"
         /// The URL the analytics tracker script is loaded from.
         public static let scriptURL = "\(origin)/script"
-- 
2.54.0


From fcfb3f21d5373b3e8178b527238a7e7e23e34eb1 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 02:55:04 +0200
Subject: [PATCH 077/117] Added the organization descriptors and a number value
 to the structured data types in the Infrastructure package.

---
 .../Sources/Public/Types/StructuredData.swift  | 18 ++++++++++++++++++
 .../StructuredDataProperty.swift               |  6 ++++++
 .../StructuredData/StructuredDataValue.swift   |  6 +++++-
 .../Public/Types/StructuredDataTests.swift     | 18 ++++++++++++++++++
 4 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
index 5e5addb..fb38c4b 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
@@ -46,11 +46,17 @@ public extension StructuredData {
     /// - Parameters:
     ///   - name: the name of the organization and the site.
     ///   - url: the absolute URL the site is served at.
+    ///   - alternateName: the name the organization is also known by, or `nil` (the default) to omit its property.
+    ///   - description: what the organization does, or `nil` (the default) to omit its property.
+    ///   - areaServed: the area the organization serves, or `nil` (the default) to omit its property.
     ///   - logo: the absolute URL of the organization's logo, or `nil` (the default) to omit its property.
     ///   - profiles: the absolute URLs of the organization's public profiles, or empty (the default) to omit their property.
     init(
         name: String,
         url: String,
+        alternateName: String? = nil,
+        description: String? = nil,
+        areaServed: String? = nil,
         logo: String? = nil,
         profiles: [String] = []
     ) {
@@ -61,6 +67,18 @@ public extension StructuredData {
             .init(.url, value: .string(url)),
         ]
 
+        if let alternateName {
+            organization.append(.init(.alternateName, value: .string(alternateName)))
+        }
+
+        if let description {
+            organization.append(.init(.description, value: .string(description)))
+        }
+
+        if let areaServed {
+            organization.append(.init(.areaServed, value: .string(areaServed)))
+        }
+
         if let logo {
             organization.append(.init(.logo, value:.string(logo)))
         }
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
index fb52cb0..2fd7044 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
@@ -69,6 +69,12 @@ extension StructuredData.Property {
 // MARK: - Constants
 
 public extension StructuredData.Property.Name {
+    /// The name the thing a node describes is also known by.
+    static let alternateName: Self = "alternateName"
+    /// The area an organization serves.
+    static let areaServed: Self = "areaServed"
+    /// What the thing a node describes is or does.
+    static let description: Self = "description"
     /// The absolute URL of an organization's logo.
     static let logo: Self = "logo"
     /// The name of the thing a node describes.
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataValue.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataValue.swift
index 4ee5324..06b8a31 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataValue.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataValue.swift
@@ -1,5 +1,5 @@
 extension StructuredData {
-    /// A value of a ``Property``: a string, a list, a nested node, or a reference to another node.
+    /// A value of a ``Property``: a string, a number, a list, a nested node, or a reference to another node.
     ///
     /// Every string a value renders is escaped as a JSON literal with `<` escaped as well, so a value can never close the `script`
     /// tag embedding the payload it renders into.
@@ -8,6 +8,8 @@ extension StructuredData {
         case array([Value])
         /// A nested node, e.g. the place a schema.org event is located at.
         case node(Node)
+        /// A whole number, e.g. a list item's position, rendered unquoted so it reads as a number rather than as text.
+        case number(Int)
         /// A reference to the ``Node/id`` of another node in the graph, rendered as an `@id` object.
         case reference(String)
         /// A string value.
@@ -28,6 +30,8 @@ extension StructuredData.Value {
             "[\(values.map(\.fragment).joined(separator: .Separator.comma))]"
         case .node(let node):
             node.fragment
+        case .number(let number):
+            String(number)
         case .reference(let id):
             #"{"@id":\#(Self.literal(id))}"#
         case .string(let string):
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
index f0bfcb3..131ead0 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
@@ -30,6 +30,21 @@ struct StructuredDataTests {
         )
     }
 
+    @Test
+    func `carries the organization's alternate name, description, and area in that order`() {
+        let data = StructuredData(
+            name: "A Site",
+            url: "https://site.example/",
+            alternateName: "The Site",
+            description: "What the site is.",
+            areaServed: "A City"
+        )
+
+        #expect(data.payload.contains(
+            #""name":"A Site","url":"https://site.example/","alternateName":"The Site","description":"What the site is.","areaServed":"A City""#
+        ))
+    }
+
     @Test
     func `omits the properties of the facts minimal data does not carry`() {
         let data = StructuredData(
@@ -120,6 +135,9 @@ struct StructuredDataTests {
         #expect(StructuredData.Value.array([.string("A"), .string("B")]).fragment == #"["A","B"]"#)
         #expect(StructuredData.Value.reference("https://site.example/#organization").fragment == #"{"@id":"https://site.example/#organization"}"#)
         #expect(StructuredData.Value.node(.init(type: "Place", properties: [])).fragment == #"{"@type":"Place"}"#)
+        // Unquoted, or a consumer reads the position of a list item as text and cannot order by it.
+        #expect(StructuredData.Value.number(1).fragment == "1")
+        #expect(StructuredData.Value.number(-3).fragment == "-3")
     }
 
     @Test
-- 
2.54.0


From 1520c44b1663f5b1732e83e22ce169a6b04d4be9 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 22 Aug 2026 23:00:23 +0000
Subject: [PATCH 078/117] HTTPS redirect middleware for the Infrastructure
 package (#52)

---
 Packages/Infrastructure/README.md             |   4 +-
 .../Extensions/HTTPFieldName+Constants.swift  |   2 +
 .../Middlewares/HTTPSRedirectMiddleware.swift | 182 ++++++++++++++++++
 .../HTTPSRedirectMiddlewareTests.swift        | 179 +++++++++++++++++
 .../Sources/App/Extensions/App+Build.swift    |  13 +-
 .../Extensions/ConfigReader+Properties.swift  |  14 ++
 .../AbsoluteConfigKey+Constants.swift         |   5 +
 .../Extensions/ConfigKey+Constants.swift      |   6 +
 8 files changed, 400 insertions(+), 5 deletions(-)
 create mode 100644 Packages/Infrastructure/Sources/Public/Middlewares/HTTPSRedirectMiddleware.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Middlewares/HTTPSRedirectMiddlewareTests.swift

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 36494f9..f6545b8 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -5,7 +5,7 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Role | Types |
 | --- | --- |
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
-| Middlewares | `SecurityHeadersMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
+| Middlewares | `SecurityHeadersMiddleware`, `HTTPSRedirectMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
 | Link previews | `SocialCard`, its `Image`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, and the open `Name` and `Kind` vocabularies |
@@ -30,7 +30,7 @@ Sources/
 │   ├── Enumerations/      AssetExtension
 │   ├── Extensions/        addController, plus the default header names and values
 │   ├── Methods/           FingerprintAssets
-│   ├── Middlewares/       the five HTTP middlewares
+│   ├── Middlewares/       the six HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
 │   ├── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
 │   └── Types/             Analytics, SocialCard, StructuredData (the latter two nesting their own types in SocialCard/ and StructuredData/)
diff --git a/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift b/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
index 9f89f0a..365523e 100644
--- a/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
+++ b/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
@@ -9,4 +9,6 @@ public extension HTTPField.Name {
     static let frameOptions = Self("X-Frame-Options")!
     /// The `X-Forwarded-For` field name (not provided as a standard `HTTPField.Name`).
     static let xForwardedFor = Self("X-Forwarded-For")!
+    /// The `X-Forwarded-Proto` field name (not provided as a standard `HTTPField.Name`).
+    static let xForwardedProto = Self("X-Forwarded-Proto")!
 }
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/HTTPSRedirectMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/HTTPSRedirectMiddleware.swift
new file mode 100644
index 0000000..3d615f2
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/HTTPSRedirectMiddleware.swift
@@ -0,0 +1,182 @@
+import Foundation
+import HTTPTypes
+import Hummingbird
+
+/// Answers a request forwarded over plain HTTP with `301 Moved Permanently` to the same path on the site's HTTPS origin.
+///
+/// Behind a TLS-terminating proxy the server only sees plain HTTP, so the visitor's scheme survives only in the `X-Forwarded-Proto` header the proxy
+/// sets. Redirecting collapses the `http://` and `https://` copies of every page onto one address — what a search engine consolidates a site's signals
+/// against.
+///
+/// Three deliberate choices:
+/// - **`301`, not `302`.** A temporary redirect tells a crawler the HTTP address is the canonical one, so the HTTP URLs stay indexed. Browsers cache a
+///   `301` for a long time, so the target must be settled before enabling this.
+/// - **The target comes from ``Configuration/origin``, not the request's `Host` header.** A client cannot steer a configured origin, so it can neither
+///   aim the redirect elsewhere nor poison a shared cache with the result.
+/// - **`/.well-known/` is exempt.** A certificate authority looks there for an ACME challenge over plain HTTP; redirecting it away breaks renewal, and
+///   the breakage surfaces only when the certificate expires.
+///
+/// - Note: `Context` is the request context the middleware is resolved against.
+public struct HTTPSRedirectMiddleware<Context: RequestContext>: Sendable {
+
+    // MARK: Properties
+
+    /// The origin the redirects point at, and whether the forwarded-protocol header is trusted.
+    private let configuration: Configuration
+
+    /// Whether the middleware redirects at all, resolved once at initialization.
+    ///
+    /// An untrusted header disables it, and so does an origin that is not itself HTTPS: redirecting to a plain-HTTP origin would loop.
+    private let isEnabled: Bool
+
+    // MARK: Initializers
+
+    /// Creates an HTTPS-redirect middleware.
+    /// - Parameter configuration: the origin the redirects point at, and whether the forwarded-protocol header is trusted.
+    public init(
+        configuration: Configuration
+    ) {
+        self.configuration = configuration
+        self.isEnabled = configuration.trustForwardedProto
+            && configuration.origin.hasPrefix(.httpsPrefix)
+    }
+
+}
+
+// MARK: - RouterMiddleware
+
+extension HTTPSRedirectMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Redirects a request forwarded over plain HTTP, and passes every other request down the chain.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the redirect, or the downstream response.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        guard
+            isEnabled,
+            isForwardedOverHTTP(request),
+            !isWellKnown(request)
+        else {
+            return try await next(
+                request,
+                context
+            )
+        }
+
+        var response = Response(status: .movedPermanently)
+
+        response.headers[.location] = configuration.origin + target(of: request)
+
+        return response
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension HTTPSRedirectMiddleware {
+
+    // MARK: Methods
+
+    /// Whether the proxy reported the visitor's request as plain HTTP.
+    ///
+    /// Only the leftmost entry is read: a chain of proxies appends to the header, so that entry is the scheme the visitor used. The comparison is
+    /// case-insensitive, the header carrying a scheme name rather than a fixed-case token.
+    /// - Parameter request: the incoming request.
+    /// - Returns: `true` when the header's first entry names plain HTTP.
+    func isForwardedOverHTTP(
+        _ request: Request
+    ) -> Bool {
+        request.headers[.xForwardedProto]?
+            .split(separator: ",")
+            .first?
+            .trimmingCharacters(in: .whitespaces)
+            .lowercased() == .httpScheme
+    }
+
+    /// Whether the request addresses the reserved well-known space, which is left on plain HTTP so an ACME challenge stays reachable.
+    /// - Parameter request: the incoming request.
+    /// - Returns: `true` when the path falls inside the well-known space.
+    func isWellKnown(
+        _ request: Request
+    ) -> Bool {
+        request.uri.path.hasPrefix(.wellKnownPrefix)
+    }
+
+    /// The path and query the redirect preserves, so a visitor lands on the address they asked for.
+    ///
+    /// Rebuilt from the parsed components rather than the raw request target: a target in absolute form would append a second origin to the first.
+    /// - Parameter request: the incoming request.
+    /// - Returns: the path, followed by the query when the request carries one.
+    func target(
+        of request: Request
+    ) -> String {
+        guard
+            let query = request.uri.query,
+            !query.isEmpty
+        else {
+            return request.uri.path
+        }
+
+        return request.uri.path + .querySeparator + query
+    }
+
+}
+
+// MARK: - Configuration
+
+extension HTTPSRedirectMiddleware {
+    /// The origin an ``HTTPSRedirectMiddleware`` redirects to, and whether it trusts the header telling it to.
+    public struct Configuration: Sendable {
+
+        // MARK: Properties
+
+        /// The public origin the redirects point at (scheme and host, no trailing slash).
+        ///
+        /// An origin that is not itself HTTPS disables the middleware rather than redirecting into a loop.
+        public let origin: String
+
+        /// Whether the visitor's scheme is read from the `X-Forwarded-Proto` header.
+        ///
+        /// This is the middleware's only trigger. Enable it solely behind a reverse proxy that sets the header: on a directly reachable server the header
+        /// is client-supplied, so it stays off by default.
+        public let trustForwardedProto: Bool
+
+        // MARK: Initializers
+
+        /// Creates an HTTPS-redirect configuration.
+        /// - Parameters:
+        ///   - origin: the public origin the redirects point at (scheme and host, no trailing slash).
+        ///   - trustForwardedProto: whether the visitor's scheme is read from the `X-Forwarded-Proto` header. Defaults to `false`.
+        public init(
+            origin: String,
+            trustForwardedProto: Bool = false
+        ) {
+            self.origin = origin
+            self.trustForwardedProto = trustForwardedProto
+        }
+
+    }
+}
+
+// MARK: - String+Constants
+
+private extension String {
+    /// The forwarded-protocol value naming a request made over plain HTTP.
+    static let httpScheme = "http"
+    /// The scheme prefix a redirect target must carry for the redirect to terminate.
+    static let httpsPrefix = "https://"
+    /// The delimiter placed between a redirect target's path and its query.
+    static let querySeparator = "?"
+    /// The reserved path prefix left on plain HTTP, so an ACME challenge stays reachable.
+    static let wellKnownPrefix = "/.well-known/"
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/HTTPSRedirectMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/HTTPSRedirectMiddlewareTests.swift
new file mode 100644
index 0000000..5296a98
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/HTTPSRedirectMiddlewareTests.swift
@@ -0,0 +1,179 @@
+import HTTPTypes
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import Infrastructure
+
+@Suite(
+    "HTTPSRedirectMiddleware middleware",
+    .tags(.middleware)
+)
+struct HTTPSRedirectMiddlewareTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `redirects a request forwarded over plain http`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedProto: "http"]
+            ) { response in
+                #expect(response.status == .movedPermanently)
+                #expect(response.headers[.location] == "https://example.com/hello")
+            }
+        }
+    }
+
+    @Test
+    func `preserves the path and the query of the redirected request`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello?utm_source=test&utm_medium=email",
+                method: .get,
+                headers: [.xForwardedProto: "http"]
+            ) { response in
+                #expect(response.headers[.location] == "https://example.com/hello?utm_source=test&utm_medium=email")
+            }
+        }
+    }
+
+    @Test
+    func `matches the forwarded scheme regardless of its casing`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedProto: "HTTP"]
+            ) { response in
+                #expect(response.status == .movedPermanently)
+            }
+        }
+    }
+
+    @Test
+    func `reads the leftmost entry of a proxy chain`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedProto: "http, https"]
+            ) { response in
+                #expect(response.status == .movedPermanently)
+            }
+        }
+    }
+
+    @Test
+    func `passes a request forwarded over https through`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedProto: "https"]
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.location] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `passes a request without the forwarded header through`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+            }
+        }
+    }
+
+    @Test
+    func `passes every request through when the header is not trusted`() async throws {
+        try await app(
+            configuration: .init(
+                origin: "https://example.com",
+                trustForwardedProto: false
+            )
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedProto: "http"]
+            ) { response in
+                #expect(response.status == .ok)
+            }
+        }
+    }
+
+    @Test
+    func `leaves the well-known space on plain http`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/.well-known/acme-challenge/token",
+                method: .get,
+                headers: [.xForwardedProto: "http"]
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.location] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `passes every request through when the origin is not itself https`() async throws {
+        try await app(
+            configuration: .init(
+                origin: "http://example.com",
+                trustForwardedProto: true
+            )
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get,
+                headers: [.xForwardedProto: "http"]
+            ) { response in
+                #expect(response.status == .ok)
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension HTTPSRedirectMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose router applies the HTTPS-redirect middleware ahead of a `/hello`
+    /// route returning a plain body and a `/.well-known/acme-challenge/token` route standing in for
+    /// a certificate authority's challenge file.
+    func app(
+        configuration: HTTPSRedirectMiddleware<BasicRequestContext>.Configuration = .init(
+            origin: "https://example.com",
+            trustForwardedProto: true
+        )
+    ) -> some ApplicationProtocol {
+        let router = Router()
+
+        router.addMiddleware {
+            HTTPSRedirectMiddleware(configuration: configuration)
+        }
+
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        router.get(".well-known/acme-challenge/token") { _, _ in
+            "token"
+        }
+
+        return Application(router: router)
+    }
+
+}
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index aa93d86..a46ce9f 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -52,6 +52,7 @@ func application(
             analytics: reader.analytics,
             cacheControl: reader.cacheControl,
             compressionMinResponseSize: reader.compressionMinResponseSize,
+            httpsRedirect: reader.httpsRedirect,
             rateLimit: reader.rateLimit,
             securityHeaders: reader.securityHeaders,
             logLevel: reader.logLevel,
@@ -135,21 +136,23 @@ private func logger(
 /// Builds the application's router.
 ///
 /// Registers the request-logging middleware, the security-headers middleware that stamps the given `securityHeaders` onto every response, the
-/// vary middleware that marks every response as varying on `Accept-Encoding`, the response-compression middleware that compresses responses
+/// HTTPS-redirect middleware that bounces requests forwarded over plain HTTP to the canonical origin, the vary middleware that marks every response as varying on `Accept-Encoding`, the response-compression middleware that compresses responses
 /// larger than `minimumResponseSizeToCompress` when the client advertises support, the localization middleware that negotiates the request's
 /// language from its `Accept-Language` header, the not-found middleware that serves the error page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then adds the `RootController` routes that
 /// render the landing page, and the `HealthController` routes that serve the health check.
 ///
 /// The security-headers middleware sits just inside request logging so it covers every response that reaches a client — the landing page, the compressed
-/// responses, the rendered error page, and the served static files.
+/// responses, the rendered not-found page, and the served static files. The HTTPS redirect sits directly beneath it, so a redirect carries the security
+/// headers but skips the negotiation, compression, and file lookup it would otherwise pay for.
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
 ///   - assetVersion: the version token the pages append to their asset URLs, or `nil` to leave them unversioned.
 ///   - analytics: the analytics tracker both pages embed, or `nil` to omit it.
 ///   - cacheControl: the cache-control directives applied to the served static files.
 ///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
-///   - rateLimit: the rate limit applied to the rate-limited routes.
+///   - httpsRedirect: the origin plain-HTTP requests are redirected to, and whether the forwarded-protocol header is trusted.
+///   - rateLimit: the rate limit applied to the subscription endpoint.
 ///   - securityHeaders: the security headers applied to every response.
 ///   - logLevel: the level the request-logging middleware logs at.
 ///   - probe: the probe consulted by the `HealthController` readiness route.
@@ -160,6 +163,7 @@ private func router(
     analytics: Analytics?,
     cacheControl: CacheControl,
     compressionMinResponseSize: Int,
+    httpsRedirect: HTTPSRedirectMiddleware<AppRequestContext>.Configuration,
     rateLimit: RateLimitMiddleware<AppRequestContext>.Configuration,
     securityHeaders: SecurityHeadersMiddleware<AppRequestContext>.Configuration,
     logLevel: Logger.Level,
@@ -177,6 +181,9 @@ private func router(
         SecurityHeadersMiddleware(
             configuration: securityHeaders
         )
+        HTTPSRedirectMiddleware(
+            configuration: httpsRedirect
+        )
         VaryMiddleware()
         ResponseCompressionMiddleware(
             minimumResponseSizeToCompress: compressionMinResponseSize
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index b317f45..7f115f4 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -145,6 +145,20 @@ package extension ConfigReader {
         }
     }
 
+    /// The HTTPS redirect middleware configuration, built from the `https.trustForwardedProto` key and ``siteOrigin``.
+    ///
+    /// Off by default, so a deployment without a proxy in front never redirects on a header its clients could have written themselves. The redirects
+    /// point at ``siteOrigin`` — the same value the pages build their canonical URLs from, so the two cannot disagree.
+    var httpsRedirect: HTTPSRedirectMiddleware<AppRequestContext>.Configuration {
+        .init(
+            origin: siteOrigin,
+            trustForwardedProto: bool(
+                forKey: .HTTPS.trustForwardedProto,
+                default: false
+            )
+        )
+    }
+
     /// The minimum log level the application emits at, read from the `log.level` key.
     ///
     /// Falls back to `.info` when the key is unset or its value names no `Logger.Level` case.
diff --git a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
index 62dd206..216af97 100644
--- a/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/AbsoluteConfigKey+Constants.swift
@@ -58,6 +58,11 @@ extension AbsoluteConfigKey {
         /// The absolute configuration key for the server's name.
         public static let serverName: AbsoluteConfigKey = .init(.HTTP.serverName)
     }
+    /// A namespace for the HTTPS redirect configuration keys, as absolute keys.
+    public enum HTTPS {
+        /// The absolute configuration key for reading the visitor's original scheme from the `X-Forwarded-Proto` header.
+        public static let trustForwardedProto: AbsoluteConfigKey = .init(.HTTPS.trustForwardedProto)
+    }
     /// A namespace for the logging configuration keys, as absolute keys.
     public enum Log {
         /// The absolute configuration key for the minimum log level.
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index 9fcddaa..5199d99 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -58,6 +58,12 @@ extension ConfigKey {
         /// The configuration key for the server's name.
         public static let serverName: ConfigKey = "http.serverName"
     }
+    /// A namespace for the HTTPS redirect configuration keys.
+    public enum HTTPS {
+        /// The configuration key for reading the visitor's original scheme from the `X-Forwarded-Proto` header, redirecting the plain-HTTP
+        /// ones to the site origin (enable only behind a trusted proxy that sets the header).
+        public static let trustForwardedProto: ConfigKey = "https.trustForwardedProto"
+    }
     /// A namespace for the logging configuration keys.
     public enum Log {
         /// The configuration key for the minimum log level.
-- 
2.54.0


From f6a77305ac4c881f66c459a5ff1dca9b8f018fa7 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 00:06:13 +0000
Subject: [PATCH 079/117] Trailing slash middleware for the Infrastructure
 package (#53)

---
 Packages/Infrastructure/README.md             |   4 +-
 .../TrailingSlashRedirectMiddleware.swift     | 114 +++++++++++++
 ...TrailingSlashRedirectMiddlewareTests.swift | 150 ++++++++++++++++++
 Services/Website/README.md                    |  20 ++-
 .../Sources/App/Extensions/App+Build.swift    |   7 +-
 Services/Website/docker-compose.override.yml  |   1 +
 Services/Website/docker-compose.yml           |   7 +-
 7 files changed, 293 insertions(+), 10 deletions(-)
 create mode 100644 Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Middlewares/TrailingSlashRedirectMiddlewareTests.swift

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index f6545b8..0cd6239 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -5,7 +5,7 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Role | Types |
 | --- | --- |
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
-| Middlewares | `SecurityHeadersMiddleware`, `HTTPSRedirectMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
+| Middlewares | `SecurityHeadersMiddleware`, `HTTPSRedirectMiddleware`, `TrailingSlashRedirectMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
 | Link previews | `SocialCard`, its `Image`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, and the open `Name` and `Kind` vocabularies |
@@ -30,7 +30,7 @@ Sources/
 │   ├── Enumerations/      AssetExtension
 │   ├── Extensions/        addController, plus the default header names and values
 │   ├── Methods/           FingerprintAssets
-│   ├── Middlewares/       the six HTTP middlewares
+│   ├── Middlewares/       the seven HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
 │   ├── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
 │   └── Types/             Analytics, SocialCard, StructuredData (the latter two nesting their own types in SocialCard/ and StructuredData/)
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
new file mode 100644
index 0000000..39344ab
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
@@ -0,0 +1,114 @@
+import HTTPTypes
+import Hummingbird
+
+/// Answers a request whose path carries a trailing slash with `301 Moved Permanently` to the same path without one.
+///
+/// The router matches `/mr-rock` and `/mr-rock/` alike, and `FileMiddleware` serves `/robots.txt/` as readily as `/robots.txt`, so without this
+/// every address on the site answers under at least two URLs. A search engine treats those as separate pages competing with each other, and any link
+/// earned by one is not credited to the other. Redirecting collapses them onto the form the pages already name as canonical.
+///
+/// Two deliberate choices:
+/// - **The `Location` is relative.** A relative target resolves against the request's own scheme and host, so the middleware needs no configured
+///   origin and cannot be aimed elsewhere by a forged `Host` header.
+/// - **Only `GET` and `HEAD` are redirected.** A client answering a `301` to a `POST` may repeat it as a `GET` and drop the body, so a form
+///   submission is left to the route that already matches it.
+///
+/// - Note: `Context` is the request context the middleware is resolved against.
+public struct TrailingSlashRedirectMiddleware<Context: RequestContext>: Sendable {
+
+    // MARK: Initializers
+
+    /// Creates a trailing-slash redirect middleware.
+    public init() {}
+
+}
+
+// MARK: - RouterMiddleware
+
+extension TrailingSlashRedirectMiddleware: RouterMiddleware {
+
+    // MARK: Functions
+
+    /// Redirects a `GET` or `HEAD` whose path carries a trailing slash, and passes every other request down the chain.
+    /// - Parameters:
+    ///   - request: the incoming request.
+    ///   - context: the context the request is resolved against.
+    ///   - next: the next responder in the middleware chain.
+    /// - Returns: the redirect, or the downstream response.
+    /// - Throws: any error thrown downstream.
+    public func handle(
+        _ request: Request,
+        context: Context,
+        next: (Request, Context) async throws -> Response
+    ) async throws -> Response {
+        let path = request.uri.path
+        let canonical = canonicalPath(of: path)
+
+        guard
+            request.method == .get || request.method == .head,
+            canonical != path
+        else {
+            return try await next(
+                request,
+                context
+            )
+        }
+
+        var response = Response(status: .movedPermanently)
+
+        response.headers[.location] = canonical + query(of: request)
+
+        return response
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension TrailingSlashRedirectMiddleware {
+
+    // MARK: Methods
+
+    /// The path with its trailing slashes removed, which is the form the pages name as their canonical URL.
+    ///
+    /// A path of nothing but slashes collapses to the root, so `//` redirects to `/` while `/` itself is left alone.
+    /// - Parameter path: the requested path.
+    /// - Returns: the canonical form of the path.
+    func canonicalPath(
+        of path: String
+    ) -> String {
+        var canonical = path
+
+        while canonical.hasSuffix(.pathSeparator), canonical != .pathSeparator {
+            canonical.removeLast()
+        }
+
+        return canonical
+    }
+
+    /// The query the redirect preserves, so a campaign-tagged link survives the canonicalization.
+    /// - Parameter request: the incoming request.
+    /// - Returns: the query prefixed with its delimiter, or an empty string when the request carries none.
+    func query(
+        of request: Request
+    ) -> String {
+        guard
+            let query = request.uri.query,
+            !query.isEmpty
+        else {
+            return ""
+        }
+
+        return .querySeparator + query
+    }
+
+}
+
+// MARK: - String+Constants
+
+private extension String {
+    /// The separator a canonical path never ends on, and the root path it collapses to.
+    static let pathSeparator = "/"
+    /// The delimiter placed between a redirect target's path and its query.
+    static let querySeparator = "?"
+}
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/TrailingSlashRedirectMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/TrailingSlashRedirectMiddlewareTests.swift
new file mode 100644
index 0000000..7b053bf
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/TrailingSlashRedirectMiddlewareTests.swift
@@ -0,0 +1,150 @@
+import HTTPTypes
+import Hummingbird
+import HummingbirdTesting
+import Testing
+
+@testable import Infrastructure
+
+@Suite(
+    "TrailingSlashRedirectMiddleware middleware",
+    .tags(.middleware)
+)
+struct TrailingSlashRedirectMiddlewareTests {
+
+    // MARK: Functional tests
+
+    @Test
+    func `redirects a path carrying a trailing slash`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello/",
+                method: .get
+            ) { response in
+                #expect(response.status == .movedPermanently)
+                #expect(response.headers[.location] == "/hello")
+            }
+        }
+    }
+
+    @Test
+    func `preserves the query of the redirected request`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello/?utm_source=test&utm_medium=email",
+                method: .get
+            ) { response in
+                #expect(response.headers[.location] == "/hello?utm_source=test&utm_medium=email")
+            }
+        }
+    }
+
+    @Test
+    func `collapses a path of nothing but slashes onto the root`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "//",
+                method: .get
+            ) { response in
+                #expect(response.status == .movedPermanently)
+                #expect(response.headers[.location] == "/")
+            }
+        }
+    }
+
+    @Test
+    func `strips every trailing slash at once`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello///",
+                method: .get
+            ) { response in
+                #expect(response.headers[.location] == "/hello")
+            }
+        }
+    }
+
+    @Test
+    func `passes the canonical path through`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.location] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `leaves the root path alone`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.location] == nil)
+            }
+        }
+    }
+
+    @Test
+    func `redirects a head request as it does a get`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello/",
+                method: .head
+            ) { response in
+                #expect(response.status == .movedPermanently)
+                #expect(response.headers[.location] == "/hello")
+            }
+        }
+    }
+
+    @Test
+    func `passes a post through so its body survives`() async throws {
+        try await app().test(.router) { client in
+            try await client.execute(
+                uri: "/hello/",
+                method: .post
+            ) { response in
+                #expect(response.status == .ok)
+                #expect(response.headers[.location] == nil)
+            }
+        }
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension TrailingSlashRedirectMiddlewareTests {
+
+    // MARK: Methods
+
+    /// Builds an application whose router applies the trailing-slash middleware ahead of a `/hello`
+    /// route answering both `GET` and `POST`, and a root route standing in for the landing page.
+    func app() -> some ApplicationProtocol {
+        let router = Router()
+
+        router.addMiddleware {
+            TrailingSlashRedirectMiddleware()
+        }
+
+        router.get("hello") { _, _ in
+            "Hello!"
+        }
+
+        router.post("hello") { _, _ in
+            "Posted!"
+        }
+
+        router.get("/") { _, _ in
+            "Root!"
+        }
+
+        return Application(router: router)
+    }
+
+}
diff --git a/Services/Website/README.md b/Services/Website/README.md
index ca0d288..3382af1 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -107,6 +107,24 @@ The groups are matched in order, so the specific media types (`text/css`, `text/
 | `http.port` | `HTTP_PORT` | _none_ | Port the server listens on. Supplied via the `--http-port` CLI flag (the Docker image passes `8080`). |
 | `http.serverName` | `HTTP_SERVER_NAME` | `SiteWebsite` | Server name and logger label. |
 
+### HTTPS redirect
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `https.trustForwardedProto` | `HTTPS_TRUST_FORWARDED_PROTO` | `false` | Read the visitor's scheme from the `X-Forwarded-Proto` header and answer the plain-HTTP ones with `301 Moved Permanently` to the same path on `site.origin`. Enable **only** behind a reverse proxy that sets the header — it is the sole trigger. |
+
+Redirecting collapses the `http://` and `https://` copies of every page onto one address, which is what a search engine consolidates a site's signals against. Three details:
+
+- **`301`, not `302`** — a temporary redirect keeps the HTTP URLs indexed. Browsers cache it for a long time, so settle the target first.
+- **Target built from `site.origin`, not the `Host` header** — a client cannot steer it. An origin that is not itself HTTPS disables the middleware instead of looping.
+- **`/.well-known/` is exempt** — redirecting the ACME challenge path breaks certificate renewal.
+
+`docker-compose.yml` enables it for production; `docker-compose.override.yml` pins it off for local development.
+
+Trailing slashes are canonicalized separately and unconditionally, with no configuration key: the router matches `/mr-rock` and `/mr-rock/` alike, so
+every `GET`/`HEAD` whose path ends in a slash is answered with a `301` to the form without one (`//` collapses to `/`; `/` is left alone). The
+`Location` is relative, so it keeps the request's own scheme and host. Other methods pass through, since a client may repeat a redirected `POST` as a
+`GET` and drop the body.
+
 ### Logging
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
@@ -169,7 +187,7 @@ The tracker's origin is not a configuration key: it is single-sourced in code so
 | `security.permissionsPolicy` | `SECURITY_PERMISSIONS_POLICY` | `accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()` |
 | `security.strictTransportSecurity` | `SECURITY_STRICT_TRANSPORT_SECURITY` | _none (omitted)_ |
 
-`Strict-Transport-Security` has **no default** and is omitted unless explicitly configured: browsers ignore it on plain HTTP but remember it stickily once seen, so it must stay off in local HTTP development. `docker-compose.yml` enables it for production, where it takes effect once traffic is served over HTTPS behind a TLS-terminating proxy.
+`Strict-Transport-Security` has **no default** and is omitted unless explicitly configured: browsers ignore it on plain HTTP but remember it stickily once seen, so it must stay off in local HTTP development. `docker-compose.yml` enables it for production, where it takes effect once traffic is served over HTTPS behind a TLS-terminating proxy. [`https.trustForwardedProto`](#https-redirect) carries the same caveat: a cached `301` is as sticky as an HSTS commitment.
 
 ## Running locally
 Directly with Swift:
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index a46ce9f..e75d04f 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -136,7 +136,8 @@ private func logger(
 /// Builds the application's router.
 ///
 /// Registers the request-logging middleware, the security-headers middleware that stamps the given `securityHeaders` onto every response, the
-/// HTTPS-redirect middleware that bounces requests forwarded over plain HTTP to the canonical origin, the vary middleware that marks every response as varying on `Accept-Encoding`, the response-compression middleware that compresses responses
+/// HTTPS-redirect middleware that bounces requests forwarded over plain HTTP to the canonical origin, the trailing-slash redirect middleware that
+/// collapses each path onto its canonical form, the vary middleware that marks every response as varying on `Accept-Encoding`, the response-compression middleware that compresses responses
 /// larger than `minimumResponseSizeToCompress` when the client advertises support, the localization middleware that negotiates the request's
 /// language from its `Accept-Language` header, the not-found middleware that serves the error page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then adds the `RootController` routes that
@@ -144,7 +145,8 @@ private func logger(
 ///
 /// The security-headers middleware sits just inside request logging so it covers every response that reaches a client — the landing page, the compressed
 /// responses, the rendered not-found page, and the served static files. The HTTPS redirect sits directly beneath it, so a redirect carries the security
-/// headers but skips the negotiation, compression, and file lookup it would otherwise pay for.
+/// headers but skips the negotiation, compression, and file lookup it would otherwise pay for. The trailing-slash redirect follows it, ahead of the
+/// routes and `FileMiddleware` that would otherwise answer both spellings of every path.
 /// - Parameters:
 ///   - staticFilesPath: the folder, relative to the working directory, the static files are served from.
 ///   - assetVersion: the version token the pages append to their asset URLs, or `nil` to leave them unversioned.
@@ -184,6 +186,7 @@ private func router(
         HTTPSRedirectMiddleware(
             configuration: httpsRedirect
         )
+        TrailingSlashRedirectMiddleware()
         VaryMiddleware()
         ResponseCompressionMiddleware(
             minimumResponseSizeToCompress: compressionMinResponseSize
diff --git a/Services/Website/docker-compose.override.yml b/Services/Website/docker-compose.override.yml
index 80389f0..2d69ace 100644
--- a/Services/Website/docker-compose.override.yml
+++ b/Services/Website/docker-compose.override.yml
@@ -18,6 +18,7 @@ services:
       dockerfile: Services/Website/Dockerfile
     environment:
       LOG_LEVEL: debug
+      HTTPS_TRUST_FORWARDED_PROTO: "false"
       DATABASE_DRIVER: ${DATABASE_DRIVER:-inMemory}
       DATABASE_HOST: postgres
       DATABASE_TLS: ${DATABASE_TLS:-off}
diff --git a/Services/Website/docker-compose.yml b/Services/Website/docker-compose.yml
index 25773e3..31d4721 100644
--- a/Services/Website/docker-compose.yml
+++ b/Services/Website/docker-compose.yml
@@ -19,12 +19,9 @@ services:
     environment:
       LOG_LEVEL: ${LOG_LEVEL:-info}
       HTTP_SERVER_NAME: ${HTTP_SERVER_NAME:-SiteWebsite}
-      SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
-      # Falls back to the policy the app ships with; set it in `.env` to allow the analytics origin,
-      # which must match `String.Analytics.origin`.
       SECURITY_CONTENT_SECURITY_POLICY: "${SECURITY_CONTENT_SECURITY_POLICY:-default-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'}"
-      # Persistence: a managed PostgreSQL database. Provide the password via the environment or a secret — never
-      # commit it.
+      SECURITY_STRICT_TRANSPORT_SECURITY: "${SECURITY_STRICT_TRANSPORT_SECURITY:-max-age=31536000; includeSubDomains}"
+      HTTPS_TRUST_FORWARDED_PROTO: "${HTTPS_TRUST_FORWARDED_PROTO:-true}"
       DATABASE_DRIVER: ${DATABASE_DRIVER:-postgres}
       DATABASE_HOST: ${DATABASE_HOST:?DATABASE_HOST is required}
       DATABASE_PORT: ${DATABASE_PORT:-5432}
-- 
2.54.0


From 5996a78ff31613f2530f0847a934175e47fe724a Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 00:12:27 +0200
Subject: [PATCH 080/117] Documented and enabled the HTTPS redirect in the
 Website service.

---
 Services/Website/README.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Services/Website/README.md b/Services/Website/README.md
index 3382af1..5e356a7 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -125,6 +125,19 @@ every `GET`/`HEAD` whose path ends in a slash is answered with a `301` to the fo
 `Location` is relative, so it keeps the request's own scheme and host. Other methods pass through, since a client may repeat a redirected `POST` as a
 `GET` and drop the body.
 
+### HTTPS redirect
+| Config key | Environment variable | Default | Description |
+| --- | --- | --- | --- |
+| `https.trustForwardedProto` | `HTTPS_TRUST_FORWARDED_PROTO` | `false` | Read the visitor's scheme from the `X-Forwarded-Proto` header and answer the plain-HTTP ones with `301 Moved Permanently` to the same path on `site.origin`. Enable **only** behind a reverse proxy that sets the header — it is the sole trigger. |
+
+Redirecting collapses the `http://` and `https://` copies of every page onto one address, which is what a search engine consolidates a site's signals against. Three details:
+
+- **`301`, not `302`** — a temporary redirect keeps the HTTP URLs indexed. Browsers cache it for a long time, so settle the target first.
+- **Target built from `site.origin`, not the `Host` header** — a client cannot steer it. An origin that is not itself HTTPS disables the middleware instead of looping.
+- **`/.well-known/` is exempt** — redirecting the ACME challenge path breaks certificate renewal.
+
+`docker-compose.yml` enables it for production; `docker-compose.override.yml` pins it off for local development.
+
 ### Logging
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-- 
2.54.0


From c0f56a48973a647e74cc1b4a35c53ae205f83c71 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 00:32:11 +0200
Subject: [PATCH 081/117] Wired the trailing-slash redirect into the App router
 in the Website service target.

---
 Services/Website/README.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Services/Website/README.md b/Services/Website/README.md
index 5e356a7..9255e62 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -138,6 +138,11 @@ Redirecting collapses the `http://` and `https://` copies of every page onto one
 
 `docker-compose.yml` enables it for production; `docker-compose.override.yml` pins it off for local development.
 
+Trailing slashes are canonicalized separately and unconditionally, with no configuration key: the router matches `/mr-rock` and `/mr-rock/` alike, so
+every `GET`/`HEAD` whose path ends in a slash is answered with a `301` to the form without one (`//` collapses to `/`; `/` is left alone). The
+`Location` is relative, so it keeps the request's own scheme and host. Other methods pass through, since a client may repeat a redirected `POST` as a
+`GET` and drop the body.
+
 ### Logging
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-- 
2.54.0


From 88bcae9dc9f4ffb4e0b8b7b91e1285172601f4f2 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 09:03:13 +0200
Subject: [PATCH 082/117] Added the WebP case to the Asset extensions in the
 Infrastructure package.

---
 .../Public/Enumerations/AssetExtension.swift    | 17 +++++++++++++----
 .../Enumerations/AssetExtensionTests.swift      | 17 +++++++++++++++++
 2 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
index bdcd25e..be7af89 100644
--- a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
+++ b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
@@ -1,21 +1,25 @@
 /// A file extension used by an ``Asset``.
 ///
 /// Each case's raw value is the extension itself (e.g. `"css"`), which an asset appends to its file name when resolving paths.
-public enum AssetExtension: String, Sendable {
+public enum AssetExtension: String, CaseIterable, Sendable {
     /// A Cascading Style Sheets file.
     case css
+    /// A Windows icon image.
+    case ico
+    /// A JPEG image.
+    case jpg
     /// A JavaScript file.
     case js
     /// A Portable Network Graphics image.
     case png
-    /// A Windows icon image.
-    case ico
     /// A Scalable Vector Graphics image.
     case svg
     /// A plain text file.
     case txt
     /// A web application manifest file.
     case webmanifest
+    /// A WebP image.
+    case webp
     /// An Extensible Markup Language file.
     case xml
 }
@@ -30,12 +34,14 @@ public extension AssetExtension {
     var contentType: String {
         switch self {
         case .css: "text/css"
+        case .ico: "image/vnd.microsoft.icon"
+        case .jpg: "image/jpeg"
         case .js: "text/javascript"
         case .png: "image/png"
-        case .ico: "image/vnd.microsoft.icon"
         case .svg: "image/svg+xml"
         case .txt: "text/plain"
         case .webmanifest: "application/manifest+json"
+        case .webp: "image/webp"
         case .xml: "application/xml"
         }
     }
@@ -45,6 +51,9 @@ public extension AssetExtension {
         switch self {
         case .css: "css"
         case .js: "js"
+        case .jpg,
+             .mp4,
+             .webp: "media"
         default: nil
         }
     }
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
index f1fff74..d5f8c80 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
@@ -32,6 +32,17 @@ struct AssetExtensionTests {
         #expect(fileExtension.folder == folder)
     }
 
+    // MARK: CaseIterable tests
+
+    @Test
+    func `covers every case in the parameterised tests`() {
+        // `zip` stops at the shorter sequence, so a case missing from the arrays below is silently untested rather
+        // than failing — this is what catches that.
+        #expect(Self.extensions == AssetExtension.allCases)
+        #expect(Self.contentTypes.count == AssetExtension.allCases.count)
+        #expect(Self.folders.count == AssetExtension.allCases.count)
+    }
+
 }
 
 // MARK: - Helpers
@@ -44,6 +55,8 @@ private extension AssetExtensionTests {
         .css,
         .js,
         .png,
+        .jpg,
+        .webp,
         .ico,
         .svg,
         .txt,
@@ -54,6 +67,8 @@ private extension AssetExtensionTests {
         "text/css",
         "text/javascript",
         "image/png",
+        "image/jpeg",
+        "image/webp",
         "image/vnd.microsoft.icon",
         "image/svg+xml",
         "text/plain",
@@ -64,6 +79,8 @@ private extension AssetExtensionTests {
         "css",
         "js",
         nil,
+        "media",
+        "media",
         nil,
         nil,
         nil,
-- 
2.54.0


From fec52b7942eb87e2b530955b3503b7c9db652a30 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 11:07:17 +0200
Subject: [PATCH 083/117] Added the noindex robots tag to the responses on the
 Health controller in the Website library target.

---
 .../Public/Extensions/HTTPFieldName+Constants.swift    |  2 ++
 .../Library/Public/Controllers/HealthController.swift  | 10 +++++++++-
 .../Public/Controllers/HealthControllerTests.swift     |  4 ++++
 3 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift b/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
index 365523e..71b5fc1 100644
--- a/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
+++ b/Packages/Infrastructure/Sources/Public/Extensions/HTTPFieldName+Constants.swift
@@ -5,6 +5,8 @@ public extension HTTPField.Name {
     static let permissionsPolicy = Self("Permissions-Policy")!
     /// The `Referrer-Policy` field name (not provided as a standard `HTTPField.Name`).
     static let referrerPolicy = Self("Referrer-Policy")!
+    /// The `X-Robots-Tag` field name (not provided as a standard `HTTPField.Name`).
+    static let robotsTag = Self("X-Robots-Tag")!
     /// The `X-Frame-Options` field name (not provided as a standard `HTTPField.Name`).
     static let frameOptions = Self("X-Frame-Options")!
     /// The `X-Forwarded-For` field name (not provided as a standard `HTTPField.Name`).
diff --git a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
index b6043a0..4a35757 100644
--- a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
@@ -116,6 +116,11 @@ private extension HealthController {
     }
 
     /// Builds a JSON response carrying the given status and payload.
+    ///
+    /// Every response is marked `noindex`. The checks answer `200 OK` to anyone who asks and nothing on the site links to them, so they are
+    /// unlikely to be found — but `robots.txt` allows the whole site, and a path that leaks into a log, a monitor, or an inbound link is crawlable
+    /// on discovery. The header keeps them out of the index even once they are fetched, which a `Disallow` rule would not: that stops the crawl, not
+    /// the indexing, and publishes the paths to everyone reading the file.
     /// - Parameters:
     ///   - status: the HTTP status of the response.
     ///   - payload: the JSON body of the response.
@@ -126,7 +131,10 @@ private extension HealthController {
     ) -> Response {
         Response(
             status: status,
-            headers: [.contentType: "application/json"],
+            headers: [
+                .contentType: "application/json",
+                .robotsTag: "noindex",
+            ],
             body: .init(byteBuffer: .init(string: payload))
         )
     }
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
index 00480d5..84048da 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/HealthControllerTests.swift
@@ -1,5 +1,6 @@
 import Hummingbird
 import HummingbirdTesting
+import Infrastructure
 import Logging
 import NIOCore
 import Persistence
@@ -29,6 +30,7 @@ struct HealthControllerTests {
                 #expect(response.status == .ok)
                 #expect(response.headers[.contentType] == "application/json")
                 #expect(body == #"{"status":"ok"}"#)
+                #expect(response.headers[.robotsTag] == "noindex")
             }
         }
     }
@@ -54,6 +56,7 @@ struct HealthControllerTests {
                     #expect(response.status == .ok)
                     #expect(response.headers[.contentType] == "application/json")
                     #expect(body == #"{"status":"ready"}"#)
+                    #expect(response.headers[.robotsTag] == "noindex")
                 }
             }
         } catch {
@@ -99,6 +102,7 @@ struct HealthControllerTests {
                     #expect(response.status == .serviceUnavailable)
                     #expect(response.headers[.contentType] == "application/json")
                     #expect(body == #"{"status":"unavailable"}"#)
+                    #expect(response.headers[.robotsTag] == "noindex")
                 }
             }
         } catch {
-- 
2.54.0


From c64c8b726da89f176b6fadebe657178cc2725374 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 11:36:22 +0200
Subject: [PATCH 084/117] Added the email property to the organization
 structured data in the Infrastructure package target.

---
 .../Sources/Public/Types/StructuredData.swift              | 6 ++++++
 .../Types/StructuredData/StructuredDataProperty.swift      | 2 ++
 .../Tests/Cases/Public/Types/StructuredDataTests.swift     | 7 ++++---
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
index fb38c4b..d86fbcb 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
@@ -49,6 +49,7 @@ public extension StructuredData {
     ///   - alternateName: the name the organization is also known by, or `nil` (the default) to omit its property.
     ///   - description: what the organization does, or `nil` (the default) to omit its property.
     ///   - areaServed: the area the organization serves, or `nil` (the default) to omit its property.
+    ///   - email: the address the organization is written to, or `nil` (the default) to omit its property.
     ///   - logo: the absolute URL of the organization's logo, or `nil` (the default) to omit its property.
     ///   - profiles: the absolute URLs of the organization's public profiles, or empty (the default) to omit their property.
     init(
@@ -57,6 +58,7 @@ public extension StructuredData {
         alternateName: String? = nil,
         description: String? = nil,
         areaServed: String? = nil,
+        email: String? = nil,
         logo: String? = nil,
         profiles: [String] = []
     ) {
@@ -79,6 +81,10 @@ public extension StructuredData {
             organization.append(.init(.areaServed, value: .string(areaServed)))
         }
 
+        if let email {
+            organization.append(.init(.email, value: .string(email)))
+        }
+
         if let logo {
             organization.append(.init(.logo, value:.string(logo)))
         }
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
index 2fd7044..6600667 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
@@ -75,6 +75,8 @@ public extension StructuredData.Property.Name {
     static let areaServed: Self = "areaServed"
     /// What the thing a node describes is or does.
     static let description: Self = "description"
+    /// The address the thing a node describes is written to.
+    static let email: Self = "email"
     /// The absolute URL of an organization's logo.
     static let logo: Self = "logo"
     /// The name of the thing a node describes.
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
index 131ead0..74be9d3 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
@@ -31,17 +31,18 @@ struct StructuredDataTests {
     }
 
     @Test
-    func `carries the organization's alternate name, description, and area in that order`() {
+    func `carries the organization's alternate name, description, area, and address in that order`() {
         let data = StructuredData(
             name: "A Site",
             url: "https://site.example/",
             alternateName: "The Site",
             description: "What the site is.",
-            areaServed: "A City"
+            areaServed: "A City",
+            email: "hello@site.example"
         )
 
         #expect(data.payload.contains(
-            #""name":"A Site","url":"https://site.example/","alternateName":"The Site","description":"What the site is.","areaServed":"A City""#
+            #""name":"A Site","url":"https://site.example/","alternateName":"The Site","description":"What the site is.","areaServed":"A City","email":"hello@site.example""#
         ))
     }
 
-- 
2.54.0


From ecafb146086d7c7488d986e336d1d6d7768ebb02 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 12:31:51 +0200
Subject: [PATCH 085/117] Reworded the README documentation in the
 Infrastructure package target.

---
 Packages/Infrastructure/README.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 0cd6239..6be42fc 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -1,5 +1,5 @@
 # Infrastructure
-The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) toolkit the **Loud** services build on: declarative routing, hardened HTTP middlewares, pre-rendered localized HTML responses, and the page and asset scaffolding.
+The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) toolkit the **Loud** services build on: declarative routing, hardened HTTP middlewares, pre-rendered localized responses, and page and asset scaffolding.
 
 ## Overview
 | Role | Types |
@@ -15,11 +15,11 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
 
 ## Design rules
-The package holds only what every service can reuse; anything a service owns is injected, never referenced:
-- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. A type that needs a service's content takes it as a parameter: the `bundle:` whose String Catalog names the supported languages, the `document:` closure building a page for a locale, and a `Page` conformer's `metadata` plus its optional head concerns (`summary`, `canonicalURL`, `socialCard`, `structuredData`, `analytics`). URLs arrive fully formed and absolute; composing them stays with the page.
-- **Types own their format; `Page` renders generically.** Each head concern derives its own render-ready representation — `SocialCard.tags`, `StructuredData.payload`, `Analytics.attributes` — and `Page` applies it without knowing the vocabulary. Page ``scripts`` and the tracker render as `defer`red head tags, with a `preconnect` hint for the tracker's cross-origin host.
-- **Services fill the gaps once, via extensions.** A service restores its convenient call sites with retroactive extensions — the Website's `*+Defaults` extensions are the pattern. The open schema.org vocabularies extend the same way: the package declares the shared `Property.Name` and `Node.Kind` constants, and a service adds its own.
-- **Method structs.** Single-operation types such as `FingerprintAssets` hold their lifetime-fixed configuration in `init` and take only per-call inputs in `callAsFunction`.
+The package holds only what every service can reuse. Anything a service owns is injected, never referenced.
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. What a type needs, it takes as a parameter: the `bundle:` whose String Catalog names the supported languages, the `document:` closure that builds a page for a locale, a `Page` conformer's `metadata` and its optional head concerns (`summary`, `canonicalURL`, `socialCard`, `structuredData`, `analytics`). URLs arrive absolute and fully formed — composing them stays with the page.
+- **Types own their format; `Page` renders generically.** Each head concern derives its own render-ready form — `SocialCard.tags`, `StructuredData.payload`, `Analytics.attributes` — which `Page` applies without knowing the vocabulary. A page's `scripts` and the tracker render as `defer`red head tags, the tracker preceded by a `preconnect` to its cross-origin host.
+- **Services fill the gaps once, via extensions.** A service restores its convenient call sites retroactively — the Website's `*+Defaults` are the pattern. The open schema.org vocabularies work the same way: the package declares the shared `Property.Name` and `Node.Kind` constants, a service adds its own.
+- **Method structs.** Single-operation types such as `FingerprintAssets` take lifetime-fixed configuration in `init` and per-call inputs in `callAsFunction`.
 
 ## Layout
 Sources are split by visibility, then by kind, one type per file:
@@ -33,7 +33,7 @@ Sources/
 │   ├── Middlewares/       the seven HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
 │   ├── Responses/         CachedHTMLResponse, LocalizedHTMLCollectionResponse
-│   └── Types/             Analytics, SocialCard, StructuredData (the latter two nesting their own types in SocialCard/ and StructuredData/)
+│   └── Types/             Analytics, SocialCard, StructuredData — each nesting its own types in a folder of that name
 └── Internal/
     ├── Extensions/        implementation details (the String separators)
     └── Types/             implementation details (FNV1aHash)
@@ -44,8 +44,8 @@ Tests/
 ```
 
 ## Testing
-Every suite carries a tag for the kind of API it exercises — `.asset`, `.extension`, `.middleware`, `.protocol`, or `.type`, declared in `Tests/Utils/Extensions/Tag+Constants.swift` — so test plans and summaries can slice a run by kind. A new suite adopts the tag matching its subject, or adds one when none fits.
+Every suite carries a tag for the kind of API it exercises — `.asset`, `.extension`, `.middleware`, `.protocol`, `.type` — declared in `Tests/Utils/Extensions/Tag+Constants.swift`, so a run can be sliced by kind. A new suite takes the tag matching its subject, or adds one when none fits.
 
 ## Requirements
 - Swift 6.3 toolchain (`swift-tools-version:6.3`).
-- macOS 15, matching the sibling packages (the services deploy to Linux containers; the packages carry no UI platforms).
+- macOS 15, matching the sibling packages. The services deploy to Linux containers; the packages declare no UI platforms.
-- 
2.54.0


From 0ee8368e1ab0f27d71db5fc4981fd2950979f6da Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 12:48:24 +0200
Subject: [PATCH 086/117] Added the organization identifier helper to the
 StructuredData type in the Infrastructure package target.

---
 .../Sources/Public/Types/StructuredData.swift    | 16 +++++++++++++++-
 .../Cases/Public/Types/StructuredDataTests.swift | 13 +++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
index d86fbcb..9f5d219 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
@@ -23,6 +23,20 @@ public struct StructuredData: Equatable, Sendable {
         self.nodes = nodes
     }
 
+    // MARK: Methods
+
+    /// The `@id` of the `Organization` node ``init(name:url:alternateName:description:areaServed:email:logo:profiles:)`` builds.
+    ///
+    /// A page on another path that asserts a relationship to the organization — a `Person`'s `worksFor`, say — references this rather than
+    /// spelling the fragment a second time, so the two can never drift apart.
+    /// - Parameter url: the absolute URL the site is served at, as passed to that initializer.
+    /// - Returns: the organization node's `@id`.
+    public static func organizationID(
+        forSiteURL url: String
+    ) -> String {
+        url + "#organization"
+    }
+
     // MARK: Computed
 
     /// The minified JSON-LD payload: the schema.org `@context`, and the ``nodes`` in a `@graph`.
@@ -62,7 +76,7 @@ public extension StructuredData {
         logo: String? = nil,
         profiles: [String] = []
     ) {
-        let id = url + "#organization"
+        let id = Self.organizationID(forSiteURL: url)
 
         var organization: [Property] = [
             .init(.name, value: .string(name)),
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
index 74be9d3..26638ed 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
@@ -46,6 +46,19 @@ struct StructuredDataTests {
         ))
     }
 
+    @Test
+    func `derives the organization's identifier from the site URL`() {
+        let url = "https://site.example/"
+        let data = StructuredData(
+            name: "A Site",
+            url: url
+        )
+
+        // The helper is what another page references the organization by, so it has to name the node this actually builds.
+        #expect(StructuredData.organizationID(forSiteURL: url) == "https://site.example/#organization")
+        #expect(data.payload.contains(##""@id":"\##(StructuredData.organizationID(forSiteURL: url))""##))
+    }
+
     @Test
     func `omits the properties of the facts minimal data does not carry`() {
         let data = StructuredData(
-- 
2.54.0


From eb0a2127f66ce842dc150e74ef66a33b397879ab Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 23 Aug 2026 12:55:38 +0200
Subject: [PATCH 087/117] Reworded the documentation of the organization
 identifier helper in the Infrastructure package target.

---
 .../Sources/Public/Types/StructuredData.swift               | 6 +++---
 .../Tests/Cases/Public/Types/StructuredDataTests.swift      | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
index 9f5d219..813be3a 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
@@ -25,10 +25,10 @@ public struct StructuredData: Equatable, Sendable {
 
     // MARK: Methods
 
-    /// The `@id` of the `Organization` node ``init(name:url:alternateName:description:areaServed:email:logo:profiles:)`` builds.
+    /// The `@id` of the `Organization` node the site-wide initializer builds.
     ///
-    /// A page on another path that asserts a relationship to the organization — a `Person`'s `worksFor`, say — references this rather than
-    /// spelling the fragment a second time, so the two can never drift apart.
+    /// A page asserting a relationship to it — a `Person`'s `worksFor`, say — references this instead of spelling the fragment again, so the two
+    /// cannot drift.
     /// - Parameter url: the absolute URL the site is served at, as passed to that initializer.
     /// - Returns: the organization node's `@id`.
     public static func organizationID(
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
index 26638ed..0467739 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
@@ -54,7 +54,7 @@ struct StructuredDataTests {
             url: url
         )
 
-        // The helper is what another page references the organization by, so it has to name the node this actually builds.
+        // Another page references the organization by this, so it must name the node the initializer actually builds.
         #expect(StructuredData.organizationID(forSiteURL: url) == "https://site.example/#organization")
         #expect(data.payload.contains(##""@id":"\##(StructuredData.organizationID(forSiteURL: url))""##))
     }
-- 
2.54.0


From d8cf1abf6a9a233f8cdeacee254cca811f959d4c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 24 Aug 2026 00:06:05 +0200
Subject: [PATCH 088/117] Changed the default Open Graph locale in the Website
 library target from `en_US` to `en_NL`.

---
 Packages/Infrastructure/Sources/Public/Types/SocialCard.swift | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
index 0fe4a74..dd7926e 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
@@ -12,7 +12,7 @@ public struct SocialCard: Sendable {
 
     /// The locale of the card's text, or `nil` to omit its tag.
     ///
-    /// Open Graph specifies the `language_TERRITORY` form (e.g. `en_US`); scrapers also accept a bare language code (e.g. `en`).
+    /// Open Graph specifies the `language_TERRITORY` form (e.g. `en_NL`); scrapers also accept a bare language code (e.g. `en`).
     public let locale: String?
 
     /// The name of the site the card belongs to, or `nil` to omit its tag.
@@ -41,7 +41,7 @@ public struct SocialCard: Sendable {
     ///   - summary: the card's summary, or `nil` (the default) to omit its tag.
     ///   - url: the absolute URL the card's page is served at, or `nil` (the default) to omit its tag.
     ///   - siteName: the name of the site the card belongs to, or `nil` (the default) to omit its tag.
-    ///   - locale: the locale of the card's text, ideally in Open Graph's `language_TERRITORY` form (e.g. `en_US`), or `nil` (the default)
+    ///   - locale: the locale of the card's text, ideally in Open Graph's `language_TERRITORY` form (e.g. `en_NL`), or `nil` (the default)
     ///     to omit its tag.
     ///   - image: the card's share image, or `nil` (the default) to omit its tags.
     ///   - type: the Open Graph type of the object the card describes. Defaults to `website`.
-- 
2.54.0


From 74e81e1517da3b0355aeb28cff6ca1983edcf28e Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 24 Aug 2026 01:19:50 +0200
Subject: [PATCH 089/117] Refactored the StaticFile enumeration in the Website
 library target into a structure.

---
 .../Internal/Enumerations/StaticFile.swift    | 72 --------------
 .../Library/Internal/Types/StaticFile.swift   | 93 +++++++++++++++++++
 Services/Website/Tests/App/AppTests.swift     |  2 +-
 .../Enumerations/StaticFileTests.swift        | 82 ----------------
 .../Internal/Types/StaticFileTests.swift      | 57 ++++++++++++
 .../Utils/Extensions/Tag+Constants.swift      |  2 +
 6 files changed, 153 insertions(+), 155 deletions(-)
 delete mode 100644 Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
 create mode 100644 Services/Website/Sources/Library/Internal/Types/StaticFile.swift
 delete mode 100644 Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift

diff --git a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift b/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
deleted file mode 100644
index 945ca74..0000000
--- a/Services/Website/Sources/Library/Internal/Enumerations/StaticFile.swift
+++ /dev/null
@@ -1,72 +0,0 @@
-import Infrastructure
-
-/// A static file shipped with the website service.
-///
-/// Each case identifies a file name stored under the static files root (the `Resources/Static` directory) and served by Hummingbird's
-/// `FileMiddleware` middleware. A name can be available with more than one extension (see ``fileExtensions``), each resolving to its own file.
-enum StaticFile: Asset, CaseIterable {
-    /// The `apple-touch-icon.png` icon.
-    case appleTouchIcon
-    /// The `favicon.ico` icon.
-    case favicon
-    /// The `icon.svg` icon.
-    case icon
-    /// The `icon-192.png` icon for the web manifest.
-    case icon192
-    /// The `icon-512.png` icon for the web manifest.
-    case icon512
-    /// The `css/index.css` stylesheet and `js/index.js` script for the landing page.
-    case index
-    /// The `css/not-found.css` stylesheet and `js/not-found.js` script for the not-found page.
-    case notFound
-    /// The `robots.txt` crawler directives.
-    case robots
-    /// The `css/shared.css` stylesheet and `js/shared.js` script shared across pages.
-    case shared
-    /// The `site.webmanifest` web application manifest.
-    case site
-    /// The `sitemap.xml` crawler sitemap.
-    case sitemap
-}
-
-// MARK: - Extensions
-
-extension StaticFile {
-
-    // MARK: Computed
-    
-    /// The file extensions the file is available with.
-    var fileExtensions: [AssetExtension] {
-        switch self {
-        case .appleTouchIcon,
-             .icon192,
-             .icon512: [.png]
-        case .index,
-             .notFound,
-             .shared: [.css, .js]
-        case .favicon: [.ico]
-        case .icon: [.svg]
-        case .robots: [.txt]
-        case .site: [.webmanifest]
-        case .sitemap: [.xml]
-        }
-    }
-
-    /// The file's name, without extension.
-    var fileName: String {
-        switch self {
-        case .appleTouchIcon: "apple-touch-icon"
-        case .favicon: "favicon"
-        case .icon: "icon"
-        case .icon192: "icon-192"
-        case .icon512: "icon-512"
-        case .index: "index"
-        case .notFound: "not-found"
-        case .robots: "robots"
-        case .shared: "shared"
-        case .site: "site"
-        case .sitemap: "sitemap"
-        }
-    }
-
-}
diff --git a/Services/Website/Sources/Library/Internal/Types/StaticFile.swift b/Services/Website/Sources/Library/Internal/Types/StaticFile.swift
new file mode 100644
index 0000000..8a8a857
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Types/StaticFile.swift
@@ -0,0 +1,93 @@
+import Infrastructure
+
+/// A static file shipped with the website service.
+///
+/// Each constant declares one file stored under the static files root (the `Resources/Static` directory) and served by Hummingbird's
+/// `FileMiddleware` middleware. A file can be available with more than one extension (see ``fileExtensions``), each resolving to its own file.
+struct StaticFile: Asset {
+
+    // MARK: Properties
+
+    /// The file extensions the file is available with.
+    let fileExtensions: [AssetExtension]
+
+    /// The file's name, without extension.
+    let fileName: String
+
+    // MARK: Initializers
+
+    /// Declares a static file.
+    /// - Parameters:
+    ///   - fileName: the file's name, without extension.
+    ///   - fileExtensions: the extensions the file is available with, one file each.
+    init(
+        _ fileName: String,
+        as fileExtensions: AssetExtension...
+    ) {
+        self.fileExtensions = fileExtensions
+        self.fileName = fileName
+    }
+
+}
+
+// MARK: - Extensions
+
+extension StaticFile {
+
+    // MARK: - Constants
+
+    /// Every file the service ships.
+    ///
+    /// Spelled out because Swift cannot enumerate a type's own constants: a file missing here is still served, but goes untested.
+    static let all: [Self] = [
+        .appleTouchIcon,
+        .favicon,
+        .icon,
+        .icon192,
+        .icon512,
+        .index,
+        .notFound,
+        .robots,
+        .shared,
+        .site,
+        .sitemap,
+    ]
+
+}
+
+// MARK: - Constants
+
+extension StaticFile {
+    /// The `apple-touch-icon.png` icon.
+    static let appleTouchIcon = Self("apple-touch-icon", as: .png)
+
+    /// The `favicon.ico` icon.
+    static let favicon = Self("favicon", as: .ico)
+
+    /// The `icon.svg` icon.
+    static let icon = Self("icon", as: .svg)
+
+    /// The `icon-192.png` icon for the web manifest.
+    static let icon192 = Self("icon-192", as: .png)
+
+    /// The `icon-512.png` icon for the web manifest.
+    static let icon512 = Self("icon-512", as: .png)
+
+    /// The `css/index.css` stylesheet and `js/index.js` script for the landing page.
+    static let index = Self("index", as: .css, .js)
+
+    /// The `css/not-found.css` stylesheet and `js/not-found.js` script for the not-found page.
+    static let notFound = Self("not-found", as: .css, .js)
+
+    /// The `robots.txt` crawler directives.
+    static let robots = Self("robots", as: .txt)
+
+    /// The `css/shared.css` stylesheet and `js/shared.js` script shared across pages.
+    static let shared = Self("shared", as: .css, .js)
+
+    /// The `site.webmanifest` web application manifest.
+    static let site = Self("site", as: .webmanifest)
+
+    /// The `sitemap.xml` crawler sitemap.
+    static let sitemap = Self("sitemap", as: .xml)
+}
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index a455a32..372d6d5 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -107,7 +107,7 @@ struct AppTests {
         }
     }
 
-    @Test(arguments: StaticFile.allCases)
+    @Test(arguments: StaticFile.all)
     func `static files to be served`(
         staticFile file: StaticFile
     ) async throws {
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
deleted file mode 100644
index b675544..0000000
--- a/Services/Website/Tests/Library/Cases/Internal/Enumerations/StaticFileTests.swift
+++ /dev/null
@@ -1,82 +0,0 @@
-import Infrastructure
-import Testing
-
-@testable import WebsiteLibrary
-
-@Suite(
-    "StaticFile enumeration",
-    .tags(.enumeration)
-)
-struct StaticFileTests {
-
-    // MARK: Type aliases
-
-    typealias File = StaticFile
-
-    // MARK: Computed tests
-
-    @Test(arguments: zip(
-        File.allCases,
-        Self.fileExtensions
-    ))
-    func `file extensions`(
-        for file: File,
-        expects extensions: [AssetExtension]
-    ) {
-        #expect(file.fileExtensions == extensions)
-    }
-
-    @Test(arguments: zip(
-        File.allCases,
-        Self.fileNames
-    ))
-    func `file name`(
-        for file: File,
-        expects fileName: String
-    ) {
-        #expect(file.fileName == fileName)
-    }
-
-    // MARK: CaseIterable tests
-
-    @Test
-    func `all cases`() {
-        #expect(File.allCases.count == 11)
-    }
-
-}
-
-// MARK: - Helpers
-
-private extension StaticFileTests {
-
-    // MARK: Constants
-
-    static let fileExtensions: [[AssetExtension]] = [
-        [.png],
-        [.ico],
-        [.svg],
-        [.png],
-        [.png],
-        [.css, .js],
-        [.css, .js],
-        [.txt],
-        [.css, .js],
-        [.webmanifest],
-        [.xml]
-    ]
-    static let fileNames: [String] = [
-        "apple-touch-icon",
-        "favicon",
-        "icon",
-        "icon-192",
-        "icon-512",
-        "index",
-        "not-found",
-        "robots",
-        "shared",
-        "site",
-        "sitemap"
-    ]
-
-}
diff --git a/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift
new file mode 100644
index 0000000..726c34f
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift
@@ -0,0 +1,57 @@
+import Infrastructure
+import Testing
+
+@testable import WebsiteLibrary
+
+@Suite(
+    "StaticFile type",
+    .tags(.type)
+)
+struct StaticFileTests {
+
+    // MARK: Type aliases
+
+    typealias File = StaticFile
+
+    // MARK: Computed tests
+
+    /// The path is asserted rather than the three facts behind it: it is the only form the rest of the service sees.
+    @Test(arguments: Self.paths)
+    func `relative paths`(
+        for file: File,
+        expects paths: [String]
+    ) {
+        #expect(file.fileExtensions.map(file.relativePath) == paths)
+    }
+
+    // MARK: Constants tests
+
+    @Test
+    func `all files`() {
+        #expect(File.all.count == Self.paths.count)
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension StaticFileTests {
+
+    // MARK: Constants
+
+    /// Every file paired with the path it is served at, one per extension, in ``StaticFile/all`` order.
+    static let paths: [(File, [String])] = [
+        (.appleTouchIcon, ["apple-touch-icon.png"]),
+        (.favicon, ["favicon.ico"]),
+        (.icon, ["icon.svg"]),
+        (.icon192, ["icon-192.png"]),
+        (.icon512, ["icon-512.png"]),
+        (.index, ["css/index.css", "js/index.js"]),
+        (.notFound, ["css/not-found.css", "js/not-found.js"]),
+        (.robots, ["robots.txt"]),
+        (.shared, ["css/shared.css", "js/shared.js"]),
+        (.site, ["site.webmanifest"]),
+        (.sitemap, ["sitemap.xml"]),
+    ]
+
+}
diff --git a/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift b/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
index 63cb88f..7fe73f7 100644
--- a/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
+++ b/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
@@ -7,4 +7,6 @@ extension Tag {
     @Tag static var enumeration: Tag
     /// Tests exercising a page of the Website library.
     @Tag static var page: Tag
+    /// Tests exercising a type of the Website library.
+    @Tag static var type: Tag
 }
-- 
2.54.0


From 1033cab2afb1c5bc0eef8fd6b65b7043c3dbf474 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 24 Aug 2026 01:40:52 +0200
Subject: [PATCH 090/117] Added an optional `founder` reference to the
 Organization node in the Infrastructure package.

---
 Packages/Infrastructure/README.md             |  9 ++++---
 .../Sources/Public/Types/StructuredData.swift |  8 +++++-
 .../StructuredDataProperty.swift              |  2 ++
 .../Public/Types/StructuredDataTests.swift    | 25 +++++++++++++++++++
 4 files changed, 39 insertions(+), 5 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 6be42fc..0ad53b2 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -7,9 +7,9 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
 | Middlewares | `SecurityHeadersMiddleware`, `HTTPSRedirectMiddleware`, `TrailingSlashRedirectMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
-| Link previews | `SocialCard`, its `Image`, and the `Tag` meta tags it derives |
-| Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, and the open `Name` and `Kind` vocabularies |
-| Analytics | `Analytics`, the tracker script `Attribute`s it derives, and the `origin` its preconnect hint targets |
+| Link previews | `SocialCard`, its `Image` and `Style`, and the `Tag` meta tags it derives |
+| Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, the open `Name` and `Kind` vocabularies, and the site-wide initializer building the `Organization`/`WebSite` pair |
+| Analytics | `Analytics`, the `Event`s a page reports, the tracker script `Attribute`s it derives, and the `origin` its preconnect hint targets |
 | Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
@@ -18,6 +18,7 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 The package holds only what every service can reuse. Anything a service owns is injected, never referenced.
 - **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. What a type needs, it takes as a parameter: the `bundle:` whose String Catalog names the supported languages, the `document:` closure that builds a page for a locale, a `Page` conformer's `metadata` and its optional head concerns (`summary`, `canonicalURL`, `socialCard`, `structuredData`, `analytics`). URLs arrive absolute and fully formed — composing them stays with the page.
 - **Types own their format; `Page` renders generically.** Each head concern derives its own render-ready form — `SocialCard.tags`, `StructuredData.payload`, `Analytics.attributes` — which `Page` applies without knowing the vocabulary. A page's `scripts` and the tracker render as `defer`red head tags, the tracker preceded by a `preconnect` to its cross-origin host.
+- **Nodes are joined by `@id`, not repetition.** A node another page must point at gets its identifier from a helper rather than a hand-spelled fragment — `organizationID(forSiteURL:)` names the node the site-wide initializer builds, and that initializer's `founder` takes such an identifier back. A service adds the helper for any node it owns, so neither side can drift.
 - **Services fill the gaps once, via extensions.** A service restores its convenient call sites retroactively — the Website's `*+Defaults` are the pattern. The open schema.org vocabularies work the same way: the package declares the shared `Property.Name` and `Node.Kind` constants, a service adds its own.
 - **Method structs.** Single-operation types such as `FingerprintAssets` take lifetime-fixed configuration in `init` and per-call inputs in `callAsFunction`.
 
@@ -28,7 +29,7 @@ Sources/
 ├── Public/                public API
 │   ├── Builders/          RouteCollectionBuilder
 │   ├── Enumerations/      AssetExtension
-│   ├── Extensions/        addController, plus the default header names and values
+│   ├── Extensions/        addController, plus the default header names, rate limits, and header values
 │   ├── Methods/           FingerprintAssets
 │   ├── Middlewares/       the seven HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
index 813be3a..38d0acd 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
@@ -66,6 +66,7 @@ public extension StructuredData {
     ///   - email: the address the organization is written to, or `nil` (the default) to omit its property.
     ///   - logo: the absolute URL of the organization's logo, or `nil` (the default) to omit its property.
     ///   - profiles: the absolute URLs of the organization's public profiles, or empty (the default) to omit their property.
+    ///   - founder: the `@id` of the `Person` node founding the organization, or `nil` (the default) to omit its property.
     init(
         name: String,
         url: String,
@@ -74,7 +75,8 @@ public extension StructuredData {
         areaServed: String? = nil,
         email: String? = nil,
         logo: String? = nil,
-        profiles: [String] = []
+        profiles: [String] = [],
+        founder: String? = nil
     ) {
         let id = Self.organizationID(forSiteURL: url)
 
@@ -110,6 +112,10 @@ public extension StructuredData {
             ))
         }
 
+        if let founder {
+            organization.append(.init(.founder, value: .reference(founder)))
+        }
+
         self.init(nodes: [
             .init(
                 type: .organization,
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
index 6600667..b311bdb 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
@@ -77,6 +77,8 @@ public extension StructuredData.Property.Name {
     static let description: Self = "description"
     /// The address the thing a node describes is written to.
     static let email: Self = "email"
+    /// The person who founded an organization.
+    static let founder: Self = "founder"
     /// The absolute URL of an organization's logo.
     static let logo: Self = "logo"
     /// The name of the thing a node describes.
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
index 0467739..c2a8603 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
@@ -46,6 +46,31 @@ struct StructuredDataTests {
         ))
     }
 
+    @Test
+    func `references the organization's founder by identifier`() {
+        let data = StructuredData(
+            name: "A Site",
+            url: "https://site.example/",
+            profiles: ["https://social.example/a-site"],
+            founder: "https://site.example/who#person"
+        )
+
+        // Last of the organization's properties, after the profiles.
+        #expect(data.payload.contains(
+            #""sameAs":["https://social.example/a-site"],"founder":{"@id":"https://site.example/who#person"}}"#
+        ))
+    }
+
+    @Test
+    func `omits the founder when the data carries none`() {
+        let data = StructuredData(
+            name: "A Site",
+            url: "https://site.example/"
+        )
+
+        #expect(!data.payload.contains("founder"))
+    }
+
     @Test
     func `derives the organization's identifier from the site URL`() {
         let url = "https://site.example/"
-- 
2.54.0


From 5b2da4eb16b410c0aff2a7ea5900951adce42727 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 25 Aug 2026 16:06:05 +0200
Subject: [PATCH 091/117] Added the MP4 and WOFF2 cases to the AssetExtension
 enumeration.

---
 .../Public/Enumerations/AssetExtension.swift  | 11 ++++++--
 .../Enumerations/AssetExtensionTests.swift    | 28 +++++++++++--------
 2 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
index be7af89..81b5fb1 100644
--- a/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
+++ b/Packages/Infrastructure/Sources/Public/Enumerations/AssetExtension.swift
@@ -10,6 +10,8 @@ public enum AssetExtension: String, CaseIterable, Sendable {
     case jpg
     /// A JavaScript file.
     case js
+    /// An MPEG-4 video.
+    case mp4
     /// A Portable Network Graphics image.
     case png
     /// A Scalable Vector Graphics image.
@@ -20,6 +22,8 @@ public enum AssetExtension: String, CaseIterable, Sendable {
     case webmanifest
     /// A WebP image.
     case webp
+    /// A Web Open Font Format 2 font.
+    case woff2
     /// An Extensible Markup Language file.
     case xml
 }
@@ -37,11 +41,13 @@ public extension AssetExtension {
         case .ico: "image/vnd.microsoft.icon"
         case .jpg: "image/jpeg"
         case .js: "text/javascript"
+        case .mp4: "video/mp4"
         case .png: "image/png"
         case .svg: "image/svg+xml"
         case .txt: "text/plain"
         case .webmanifest: "application/manifest+json"
         case .webp: "image/webp"
+        case .woff2: "font/woff2"
         case .xml: "application/xml"
         }
     }
@@ -52,8 +58,9 @@ public extension AssetExtension {
         case .css: "css"
         case .js: "js"
         case .jpg,
-             .mp4,
-             .webp: "media"
+             .webp: "img"
+        case .mp4: "video"
+        case .woff2: "font"
         default: nil
         }
     }
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
index d5f8c80..c0fbbb4 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Enumerations/AssetExtensionTests.swift
@@ -53,38 +53,44 @@ private extension AssetExtensionTests {
 
     static let extensions: [AssetExtension] = [
         .css,
-        .js,
-        .png,
-        .jpg,
-        .webp,
         .ico,
+        .jpg,
+        .js,
+        .mp4,
+        .png,
         .svg,
         .txt,
         .webmanifest,
+        .webp,
+        .woff2,
         .xml
     ]
     static let contentTypes: [String] = [
         "text/css",
-        "text/javascript",
-        "image/png",
-        "image/jpeg",
-        "image/webp",
         "image/vnd.microsoft.icon",
+        "image/jpeg",
+        "text/javascript",
+        "video/mp4",
+        "image/png",
         "image/svg+xml",
         "text/plain",
         "application/manifest+json",
+        "image/webp",
+        "font/woff2",
         "application/xml"
     ]
     static let folders: [String?] = [
         "css",
+        nil,
+        "img",
         "js",
-        nil,
-        "media",
-        "media",
+        "video",
         nil,
         nil,
         nil,
         nil,
+        "img",
+        "font",
         nil
     ]
 
-- 
2.54.0


From 988090a511ebbcf6e5743e084d6bf79d099fe7be Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 25 Aug 2026 16:24:03 +0200
Subject: [PATCH 092/117] Added a configurable site origin to the
 ConfigReader+Properties extension in the Website library target.

---
 .../Sources/Public/Types/Analytics.swift              | 10 +++-------
 .../App/Extensions/ConfigReader+Properties.swift      | 11 +++++++++++
 .../Public/Extensions/ConfigKey+Constants.swift       |  5 +++++
 .../Library/Public/Extensions/String+Constants.swift  |  8 ++++++++
 4 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
index 4cccf66..2754ffb 100644
--- a/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/Analytics.swift
@@ -60,18 +60,14 @@ public struct Analytics: Sendable {
 
     // MARK: Computed
 
-    /// The tracker script's attributes: the website id and reporting domains, then each enabled behavior flag; disabled flags are omitted.
+    /// The tracker script's attributes: the website id, the reporting domains when set, then each enabled behavior flag; disabled flags are omitted.
     public var attributes: [Attribute] {
         var attributes: [Attribute] = [
-            .init("data-website-id", value: websiteID),
-            .init("data-domains", value: domains)
+            .init("data-website-id", value: websiteID)
         ]
 
         if !domains.isEmpty {
-            attributes.append((
-                name: "data-domains",
-                value: domains
-            ))
+            attributes.append(.init("data-domains", value: domains))
         }
 
         if excludeHash {
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index 7f115f4..f0b7399 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -240,6 +240,17 @@ package extension ConfigReader {
         )
     }
 
+    /// The public origin the site is served at (scheme and host, no trailing slash), read from the `site.origin` key.
+    ///
+    /// The redirects and any absolute links derive from it, so a staging deployment can point it at itself — or leave it unset — without the
+    /// production origin leaking into its markup.
+    var siteOrigin: String {
+        string(
+            forKey: .Site.origin,
+            default: .Site.origin
+        )
+    }
+
     /// The directory the static files are served from, read from the `path.staticFiles` key.
     var staticFilesPath: String {
         string(
diff --git a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
index 5199d99..d33245c 100644
--- a/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/ConfigKey+Constants.swift
@@ -98,4 +98,9 @@ extension ConfigKey {
         /// The configuration key for the `Strict-Transport-Security` header value (omitted when unset).
         public static let strictTransportSecurity: ConfigKey = "security.strictTransportSecurity"
     }
+    /// A namespace for the site configuration keys.
+    public enum Site {
+        /// The configuration key for the public origin the site is served at (scheme and host, no trailing slash).
+        public static let origin: ConfigKey = "site.origin"
+    }
 }
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index e95e120..3eda526 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -50,4 +50,12 @@ extension String {
         /// The website server's name.
         public static let name = "SiteWebsite"
     }
+    /// A namespace for the site string constants.
+    public enum Site {
+        /// The default public origin the site is served at (scheme and host, no trailing slash): empty, which leaves the HTTPS redirect off.
+        ///
+        /// A deployment that trusts the forwarded-protocol header without also setting `site.origin` would otherwise redirect at a host the
+        /// template guessed for it, and a `301` is cached for a long time.
+        public static let origin = ""
+    }
 }
-- 
2.54.0


From 7aee1cd949fd02e5eb1cc7bdb57a5157598c587f Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 25 Aug 2026 16:59:07 +0200
Subject: [PATCH 093/117] Added immutable caching to the fingerprinted media
 types for the ConfigReader+Properties extension in the Website service
 target.

---
 .../Extensions/ConfigReader+Properties.swift  | 16 ++++++--
 Services/Website/Tests/App/AppTests.swift     |  8 +++-
 .../App/ConfigReaderPropertiesTests.swift     | 38 +++++++++++++++++++
 3 files changed, 56 insertions(+), 6 deletions(-)

diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index f0b7399..d3acee0 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -56,10 +56,15 @@ package extension ConfigReader {
     /// The `Cache-Control` policy applied to static files, grouped by media type.
     ///
     /// The max-ages are read from the `cache.maxAge.asset`, `cache.maxAge.text`, `cache.maxAge.image`, and
-    /// `cache.maxAge.default` keys. Stylesheets and scripts are referenced through fingerprinted URLs (see `FingerprintAssets`) and
-    /// fonts are immutable subset files, so all three are served long-lived and `immutable` — a deploy busts them by changing the URL, never by
-    /// revalidation. The remaining text files (e.g. `robots.txt`) keep their unversioned URLs and require revalidation once stale; images and
-    /// everything else are served public with their max-age alone. The groups match in order, so the specific types precede the `text` category.
+    /// `cache.maxAge.default` keys. Stylesheets, scripts, videos, JPEGs, and WebPs are referenced through fingerprinted URLs (see
+    /// `FingerprintAssets`) and fonts are immutable subset files, so all of them are served long-lived and `immutable` — a deploy busts them by
+    /// changing the URL, never by revalidation. The remaining text files (e.g. `robots.txt`) keep their unversioned URLs and require revalidation
+    /// once stale; the remaining images cannot be `immutable` — the group covers the icons, and a browser fetches `/favicon.ico` unversioned
+    /// whatever the markup says — and everything else is served public with its max-age alone. The groups match in order, so the specific types
+    /// precede the `text` and `image` categories.
+    ///
+    /// - Important: an image the markup references without a `?v=` token must be in neither JPEG nor WebP, or it is served immutable for a year and
+    ///   a deploy cannot dislodge it.
     var cacheControl: CacheControl {
         let maxAgeAsset = int(
             forKey: .Cache.maxAgeAsset,
@@ -82,6 +87,9 @@ package extension ConfigReader {
             (.textCss, [.public, .maxAge(maxAgeAsset), .immutable]),
             (.textJavascript, [.public, .maxAge(maxAgeAsset), .immutable]),
             (.font, [.public, .maxAge(maxAgeAsset), .immutable]),
+            (.videoMp4, [.public, .maxAge(maxAgeAsset), .immutable]),
+            (.imageJpeg, [.public, .maxAge(maxAgeAsset), .immutable]),
+            (.imageWebp, [.public, .maxAge(maxAgeAsset), .immutable]),
             (.text, [.public, .maxAge(maxAgeText), .mustRevalidate]),
             (.image, [.public, .maxAge(maxAgeImage)]),
             (.init(type: .any), [.public, .maxAge(maxAgeDefault)]),
diff --git a/Services/Website/Tests/App/AppTests.swift b/Services/Website/Tests/App/AppTests.swift
index 372d6d5..37676d2 100644
--- a/Services/Website/Tests/App/AppTests.swift
+++ b/Services/Website/Tests/App/AppTests.swift
@@ -14,10 +14,14 @@ struct AppTests {
 
     // MARK: Constants
 
-    // Stylesheets and scripts are referenced through fingerprinted URLs, so they are served immutable.
+    // Referenced through fingerprinted URLs, or an immutable subset file in the case of a font, so all of these are served immutable.
     private let immutableExtensions: [AssetExtension] = [
         .css,
-        .js
+        .jpg,
+        .js,
+        .mp4,
+        .webp,
+        .woff2
     ]
 
     // Absolute path to the copy of the package's "Resources/Static" folder made into the test bundle
diff --git a/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift b/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
index 3558d39..0f89b72 100644
--- a/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
+++ b/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
@@ -61,6 +61,44 @@ struct ConfigReaderPropertiesTests {
         #expect(reader(values: [.Analytics.websiteID: ""]).analytics == nil)
     }
 
+    @Test(arguments: [
+        "shared.css",
+        "shared.js",
+        "milker-400.woff2",
+        "booth.mp4",
+        "portrait.jpg",
+        "portrait.webp"
+    ])
+    func `cache control to mark the fingerprinted media immutable`(
+        file: String
+    ) throws {
+        let header = try #require(reader().cacheControl.getCacheControlHeader(for: file))
+
+        #expect(header.contains("immutable"))
+    }
+
+    @Test(arguments: [
+        // The icons are exempt: a browser fetches `/favicon.ico` unversioned whatever the markup says, and the manifest names the PNGs.
+        "favicon.ico",
+        "icon-192.png",
+        "icon.svg"
+    ])
+    func `cache control to leave the unversioned images mutable`(
+        file: String
+    ) throws {
+        let header = try #require(reader().cacheControl.getCacheControlHeader(for: file))
+
+        #expect(!header.contains("immutable"))
+    }
+
+    @Test
+    func `cache control to have the unversioned text revalidate`() throws {
+        let header = try #require(reader().cacheControl.getCacheControlHeader(for: "robots.txt"))
+
+        #expect(header.contains("must-revalidate"))
+        #expect(!header.contains("immutable"))
+    }
+
 }
 
 // MARK: - Helpers
-- 
2.54.0


From c09ac657ab8fe6e7292471cc50dfaecbc722c899 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 25 Aug 2026 17:05:08 +0200
Subject: [PATCH 094/117] Added font preload links to the Page+Defaults
 extension in the Website library target.

---
 .../Internal/Extensions/Page+Defaults.swift   | 34 +++++++++++++++++--
 .../Cases/Internal/Pages/IndexPageTests.swift |  7 ++++
 .../Internal/Types/StaticFileTests.swift      |  9 +++++
 3 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift b/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
index f852a71..2b60080 100644
--- a/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
+++ b/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
@@ -6,6 +6,16 @@ import Localization
 /// The site-wide defaults shared by every page of the website.
 extension Page {
 
+    // MARK: Constants
+
+    /// The fonts preloaded on every page: one per face the stylesheets actually render.
+    ///
+    /// Listed rather than derived from every WOFF2 in ``StaticFile/all``: a subset gated by a `unicode-range` no page reaches would add a
+    /// download that never otherwise happens. Empty until the site ships fonts of its own.
+    static var preloadedFonts: [StaticFile] {
+        []
+    }
+
     // MARK: Computed
 
     /// The document language, derived from the page's locale and falling back to the default language.
@@ -14,9 +24,29 @@ extension Page {
             ?? LanguageList().default
     }
 
-    /// The icon, manifest, and theme colour metadata shared by every page of the website.
-    @HTMLBuilder
+    /// The site-wide head metadata; a page that adds tags of its own composes ``siteMetadata`` rather than replacing it.
     var metadata: some HTML {
+        siteMetadata
+    }
+
+    /// The ``preloadedFonts`` links, then the icon, manifest, and theme colour metadata shared by every page of the website.
+    ///
+    /// A preload URL must match the stylesheet's `@font-face` source exactly — unversioned, with `crossorigin` — or the browser fetches the
+    /// font twice.
+    @HTMLBuilder
+    var siteMetadata: some HTML {
+        for file in Self.preloadedFonts {
+            link(
+                .rel("preload"),
+                .href(file.urlPath(for: .woff2)),
+                .as(.font),
+                .custom(
+                    name: "type",
+                    value: AssetExtension.woff2.contentType
+                ),
+                .crossorigin(.anonymous)
+            )
+        }
         link(
             .rel(.icon),
             .href(StaticFile.favicon.urlPath(
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index d06606a..8f81109 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -32,6 +32,13 @@ struct IndexPageTests {
         #expect(html.contains("/js/index.js"))
     }
 
+    @Test
+    func `renders no font preloads until fonts are declared`() {
+        // The template ships no fonts, so a preload link here would point at a file the service does not serve.
+        #expect(IndexPage.preloadedFonts.isEmpty)
+        #expect(!IndexPage(locale: .init(identifier: "en")).render().contains(#"rel="preload""#))
+    }
+
     @Test
     func `renders versioned asset URLs when given a version`() {
         let html = IndexPage(
diff --git a/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift
index 726c34f..9c61e8f 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift
@@ -24,6 +24,15 @@ struct StaticFileTests {
         #expect(file.fileExtensions.map(file.relativePath) == paths)
     }
 
+    /// A preload URL must match the stylesheet's `@font-face` source exactly, so it carries the extension's folder and no version query.
+    @Test
+    func `unversioned font paths`() {
+        let font = File("a-font-400", as: .woff2)
+
+        #expect(font.relativePath(for: .woff2) == "font/a-font-400.woff2")
+        #expect(font.urlPath(for: .woff2) == "/font/a-font-400.woff2")
+    }
+
     // MARK: Constants tests
 
     @Test
-- 
2.54.0


From 3358946e3dd13b90a1cdb55b8c15354ed699e4b6 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Tue, 25 Aug 2026 17:23:20 +0200
Subject: [PATCH 095/117] Added the ImageWidth enumeration to the Website
 library target.

---
 .../Internal/Enumerations/ImageWidth.swift    | 29 +++++++++++++
 .../Library/Internal/Types/StaticFile.swift   | 39 +++++++++++++++++
 .../Enumerations/ImageWidthTests.swift        | 24 +++++++++++
 .../Internal/Types/StaticFileTests.swift      | 43 +++++++++++++++++++
 4 files changed, 135 insertions(+)
 create mode 100644 Services/Website/Sources/Library/Internal/Enumerations/ImageWidth.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Internal/Enumerations/ImageWidthTests.swift

diff --git a/Services/Website/Sources/Library/Internal/Enumerations/ImageWidth.swift b/Services/Website/Sources/Library/Internal/Enumerations/ImageWidth.swift
new file mode 100644
index 0000000..3aa8d1a
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Enumerations/ImageWidth.swift
@@ -0,0 +1,29 @@
+/// A rendition an image asset is available at, from the narrowest up to the full-size file.
+///
+/// ``StaticFile`` names one file per rendition, and a page's `srcset` offers them all so the browser picks by rendered width.
+/// The declaration order is the `srcset` order: narrowest first.
+enum ImageWidth: CaseIterable {
+    /// The small rendition, 480 pixels wide.
+    case small
+    /// The medium rendition, 800 pixels wide.
+    case medium
+    /// The large rendition: the full-size file, 1200 pixels wide.
+    case large
+}
+
+// MARK: - Extensions
+
+extension ImageWidth {
+
+    // MARK: Computed
+
+    /// The rendition's width in pixels: what the file is resampled to, and what its `srcset` descriptor states.
+    var width: Int {
+        switch self {
+        case .small: 480
+        case .medium: 800
+        case .large: 1200
+        }
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Internal/Types/StaticFile.swift b/Services/Website/Sources/Library/Internal/Types/StaticFile.swift
index 8a8a857..d28c4b1 100644
--- a/Services/Website/Sources/Library/Internal/Types/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Types/StaticFile.swift
@@ -14,18 +14,26 @@ struct StaticFile: Asset {
     /// The file's name, without extension.
     let fileName: String
 
+    /// The folder holding the file, or `nil` when it sits in its extensions' own folders.
+    ///
+    /// Imagery sits in a folder per page — `img/index`, `img/about` — rather than in its extension's own.
+    let folder: String?
+
     // MARK: Initializers
 
     /// Declares a static file.
     /// - Parameters:
     ///   - fileName: the file's name, without extension.
+    ///   - folder: the folder holding the file, or `nil` (the default) to use each extension's own folder.
     ///   - fileExtensions: the extensions the file is available with, one file each.
     init(
         _ fileName: String,
+        in folder: String? = nil,
         as fileExtensions: AssetExtension...
     ) {
         self.fileExtensions = fileExtensions
         self.fileName = fileName
+        self.folder = folder
     }
 
 }
@@ -55,6 +63,37 @@ extension StaticFile {
 
 }
 
+// MARK: - Methods
+
+extension StaticFile {
+
+    /// The `srcset` value offering every rendition of a responsive image, narrowest first, ending on the full-size file.
+    ///
+    /// The renditions are named by the given closure, which conventionally gives the `large` one the bare file name and the narrower ones their
+    /// width — as `srcset` files are usually named:
+    ///
+    /// ```swift
+    /// static func portrait(_ width: ImageWidth) -> Self {
+    ///     Self(width == .large ? "portrait" : "portrait-\(width.width)", in: "img/about", as: .jpg, .webp)
+    /// }
+    /// ```
+    /// - Parameters:
+    ///   - fileExtension: the format the renditions are named in.
+    ///   - version: the version token appended to each URL, or `nil` (the default) to leave them unversioned.
+    ///   - rendition: the file naming a given width.
+    /// - Returns: the `srcset` value for that format.
+    static func srcSet(
+        for fileExtension: AssetExtension,
+        version: String? = nil,
+        rendition: (ImageWidth) -> Self
+    ) -> String {
+        ImageWidth.allCases
+            .map { "\(rendition($0).urlPath(for: fileExtension, version: version)) \($0.width)w" }
+            .joined(separator: ", ")
+    }
+
+}
+
 // MARK: - Constants
 
 extension StaticFile {
diff --git a/Services/Website/Tests/Library/Cases/Internal/Enumerations/ImageWidthTests.swift b/Services/Website/Tests/Library/Cases/Internal/Enumerations/ImageWidthTests.swift
new file mode 100644
index 0000000..a635990
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Internal/Enumerations/ImageWidthTests.swift
@@ -0,0 +1,24 @@
+import Testing
+
+@testable import WebsiteLibrary
+
+@Suite(
+    "ImageWidth enumeration",
+    .tags(.enumeration)
+)
+struct ImageWidthTests {
+
+    // MARK: Computed tests
+
+    @Test(arguments: zip(
+        ImageWidth.allCases,
+        [480, 800, 1200]
+    ))
+    func `width`(
+        for imageWidth: ImageWidth,
+        expects width: Int
+    ) {
+        #expect(imageWidth.width == width)
+    }
+
+}
diff --git a/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift b/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift
index 9c61e8f..18d1163 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Types/StaticFileTests.swift
@@ -33,6 +33,49 @@ struct StaticFileTests {
         #expect(font.urlPath(for: .woff2) == "/font/a-font-400.woff2")
     }
 
+    /// Imagery sits in a folder per page, so a declared folder replaces the extension's own for every extension the file has.
+    @Test
+    func `declared folder paths`() {
+        let portrait = File("portrait", in: "img/about", as: .jpg, .webp)
+
+        #expect(portrait.relativePath(for: .jpg) == "img/about/portrait.jpg")
+        #expect(portrait.relativePath(for: .webp) == "img/about/portrait.webp")
+    }
+
+    // MARK: Methods tests
+
+    @Test(arguments: zip(
+        [AssetExtension.jpg, .webp],
+        ["jpg", "webp"]
+    ))
+    func `srcset offers every rendition narrowest first`(
+        for fileExtension: AssetExtension,
+        expects suffix: String
+    ) {
+        let srcSet = File.srcSet(for: fileExtension) { width in
+            File(
+                width == .large ? "portrait" : "portrait-\(width.width)",
+                in: "img/about",
+                as: .jpg, .webp
+            )
+        }
+
+        #expect(srcSet == [
+            "/img/about/portrait-480.\(suffix) 480w",
+            "/img/about/portrait-800.\(suffix) 800w",
+            "/img/about/portrait.\(suffix) 1200w"
+        ].joined(separator: ", "))
+    }
+
+    @Test
+    func `srcset versions every rendition when given a version`() {
+        let srcSet = File.srcSet(for: .jpg, version: "0123456789abcdef") { _ in
+            File("portrait", in: "img/about", as: .jpg)
+        }
+
+        #expect(srcSet.components(separatedBy: "?v=0123456789abcdef").count - 1 == ImageWidth.allCases.count)
+    }
+
     // MARK: Constants tests
 
     @Test
-- 
2.54.0


From 4ee1abbd679cf072472d4122ec77923065cb050c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 08:35:06 +0200
Subject: [PATCH 096/117] Improved the documentation of the README file in the
 Infrastructure package.

---
 Packages/Infrastructure/README.md                               | 2 +-
 .../Public/Middlewares/TrailingSlashRedirectMiddleware.swift    | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 0ad53b2..50a01f5 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -1,5 +1,5 @@
 # Infrastructure
-The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) toolkit the **Loud** services build on: declarative routing, hardened HTTP middlewares, pre-rendered localized responses, and page and asset scaffolding.
+The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) toolkit the platform's services build on: declarative routing, hardened HTTP middlewares, pre-rendered localized responses, and page and asset scaffolding.
 
 ## Overview
 | Role | Types |
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
index 39344ab..4a77fcd 100644
--- a/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
@@ -3,7 +3,7 @@ import Hummingbird
 
 /// Answers a request whose path carries a trailing slash with `301 Moved Permanently` to the same path without one.
 ///
-/// The router matches `/mr-rock` and `/mr-rock/` alike, and `FileMiddleware` serves `/robots.txt/` as readily as `/robots.txt`, so without this
+/// The router matches `/about` and `/about/` alike, and `FileMiddleware` serves `/robots.txt/` as readily as `/robots.txt`, so without this
 /// every address on the site answers under at least two URLs. A search engine treats those as separate pages competing with each other, and any link
 /// earned by one is not credited to the other. Redirecting collapses them onto the form the pages already name as canonical.
 ///
-- 
2.54.0


From d40f988877b65d36099c14566f7096addd79de8a Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 08:35:21 +0200
Subject: [PATCH 097/117] Improved the documentation of the README file in the
 Localization package.

---
 Packages/Localization/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Packages/Localization/README.md b/Packages/Localization/README.md
index 5128cc4..3f79dae 100644
--- a/Packages/Localization/README.md
+++ b/Packages/Localization/README.md
@@ -1,5 +1,5 @@
 # Localization
-The server-side localization toolkit the **Loud** services build on: locale-explicit String Catalog lookups, `Accept-Language` negotiation, and the catalog-derived language list — with no dependencies beyond Foundation.
+The server-side localization toolkit the platform's services build on: locale-explicit String Catalog lookups, `Accept-Language` negotiation, and the catalog-derived language list — with no dependencies beyond Foundation.
 
 ## Overview
 | Role | Types |
-- 
2.54.0


From c1ca6609e46d70b5bd63e77d2fa263f2854ec41d Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 08:35:35 +0200
Subject: [PATCH 098/117] Improved the documentation of the README file in the
 Persistence package.

---
 Packages/Persistence/README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Packages/Persistence/README.md b/Packages/Persistence/README.md
index c3cb5e8..977375c 100644
--- a/Packages/Persistence/README.md
+++ b/Packages/Persistence/README.md
@@ -1,5 +1,5 @@
 # Persistence
-The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based data layer the **Loud** services build on: runtime selection between a PostgreSQL backend and an ephemeral in-memory SQLite one, single-place migration registration, and a database readiness probe.
+The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based data layer the platform's services build on: runtime selection between a PostgreSQL backend and an ephemeral in-memory SQLite one, single-place migration registration, and a database readiness probe.
 
 ## Overview
 | Role | Types |
@@ -8,7 +8,7 @@ The [Fluent](https://github.com/hummingbird-project/hummingbird-fluent)-based da
 | Service | `Service`, which builds the `Fluent` service configured for the chosen driver |
 | Migrations | `PrepareDB`, the single registrar declaring every migration, in order |
 | Readiness | `Probe`, which reports whether the default database answers a `SELECT 1` within a deadline |
-| Scaffolding (internal) | `ExampleRecord`, `CreateExampleRecord`, and `ExampleRepository` — the model → migration → repository pattern, to be replaced by the first real domain model |
+| Scaffolding | The internal `ExampleRecord` and `CreateExampleRecord`, and the public `Example` snapshot and `ExampleRepository` — the model → migration → repository pattern, to be replaced by the first real domain model |
 
 ## Design rules
 - **The package reads no configuration.** The executable maps its `database.*` keys onto a `Driver` and hands it over; connection values arrive as plain data. The Website service's `ConfigReader+Properties` has the mapping.
@@ -39,6 +39,8 @@ Tests/
                            plaintext-only and silent fake PostgreSQL servers, and the suite Tag constants
 ```
 
+> **Exception:** `Example` and `ExampleRepository` are `public` despite sitting under `Internal/`, so they are API a service can call. Move them to `Public/Models` and `Public/Repositories` when the first real domain model replaces them.
+
 ## Testing
 The suite runs against the in-memory backend by default, so `swift test` needs no database. The PostgreSQL integration test is skipped unless `POSTGRES_TEST_HOST` points at one (with optional `POSTGRES_TEST_PORT`, `POSTGRES_TEST_NAME`, `POSTGRES_TEST_USERNAME`, and `POSTGRES_TEST_PASSWORD`); it reverts its migrations afterwards, leaving a shared database as it was found:
 ```sh
-- 
2.54.0


From 8a9402e8f12eab2bb055ad17d518448d44ff640d Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 08:35:44 +0200
Subject: [PATCH 099/117] Improved the documentation of the README file in the
 Utility package.

---
 Packages/Utility/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Packages/Utility/README.md b/Packages/Utility/README.md
index 5f62ff0..9e8b0f5 100644
--- a/Packages/Utility/README.md
+++ b/Packages/Utility/README.md
@@ -1,5 +1,5 @@
 # Utility
-The general-purpose helpers the **Loud** services share: small, single-purpose methods with no dependencies beyond Foundation and no ties to any web framework.
+The general-purpose helpers the platform's services share: small, single-purpose methods with no dependencies beyond Foundation and no ties to any web framework.
 
 ## Overview
 | Role | Types |
-- 
2.54.0


From 5a833be33d2eaa7922adde7d35c9c24219dd4d2d Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 08:37:19 +0200
Subject: [PATCH 100/117] Updated the documentations in the Website service
 target.

---
 Services/Website/README.md                    | 59 +++++++++----------
 .../Sources/App/Extensions/App+Build.swift    |  4 +-
 .../Extensions/ConfigReader+Properties.swift  |  2 +-
 .../Library/Internal/Pages/NotFoundPage.swift |  6 +-
 .../Library/Internal/Types/StaticFile.swift   |  3 +-
 .../Public/Controllers/HealthController.swift |  6 +-
 .../NotFoundMiddleware+Defaults.swift         |  4 +-
 7 files changed, 41 insertions(+), 43 deletions(-)

diff --git a/Services/Website/README.md b/Services/Website/README.md
index 9255e62..5d21b0a 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -38,14 +38,16 @@ The persistence backend runs as a `Fluent` service inside the application's Serv
 Requests pass through the middleware chain in this order (outermost first), then reach the routes:
 ```
 LogRequestsMiddleware
-  → SecurityHeadersMiddleware        (security headers on every response)
-    → VaryMiddleware                 (marks every response as varying on Accept-Encoding)
-      → ResponseCompressionMiddleware (gzip/deflate above the size threshold)
-        → LocalizationMiddleware      (negotiates the request's language)
-          → NotFoundMiddleware        (renders the localized not-found page on .notFound)
-            → FileMiddleware          (serves Resources/Static)
-RootController                        (GET / → landing page)
-HealthController                      (GET /health → liveness, GET /health/ready → readiness)
+  → SecurityHeadersMiddleware            (security headers on every response)
+    → HTTPSRedirectMiddleware            (301 to site.origin when forwarded over plain HTTP)
+      → TrailingSlashRedirectMiddleware  (301 to the path without a trailing slash)
+        → VaryMiddleware                 (marks every response as varying on Accept-Encoding)
+          → ResponseCompressionMiddleware (gzip/deflate above the size threshold)
+            → LocalizationMiddleware      (negotiates the request's language)
+              → NotFoundMiddleware        (renders the localized not-found page on .notFound)
+                → FileMiddleware          (serves Resources/Static)
+RootController                            (GET / → landing page)
+HealthController                          (GET /health → liveness, GET /health/ready → readiness)
 ```
 
 The router is created with `.autoGenerateHeadEndpoints`, so each of those `GET` routes gets a `HEAD` sibling for free.
@@ -63,7 +65,9 @@ Four of those are page-authored, optional, and **omitted by default** — the re
 
 The fifth, `analytics`, is *configuration*-authored rather than page-authored: the executable builds an `Analytics` from the `analytics.*` keys and hands it to `RootController` and `NotFoundMiddleware`, which pass it to both pages. It renders as a `<link rel="preconnect">` plus a deferred `<script>` carrying the [Umami](https://umami.is) `data-` attributes, and — unlike the structured data — it *is* executable, so the `Content-Security-Policy` must allow its origin. It is empty by default; see [Analytics](#analytics) for how to turn it on.
 
-What the pages *do* ship is in `Page+Defaults` (`Sources/Library/Internal/Extensions`), shared by every page: the document `lang`, the favicon / SVG icon / apple-touch-icon / web-manifest links, and the two `theme-color` metas.
+What the pages *do* ship is in `Page+Defaults` (`Sources/Library/Internal/Extensions`), shared by every page: the document `lang`, the `preloadedFonts` links, the favicon / SVG icon / apple-touch-icon / web-manifest links, and the two `theme-color` metas. Those live in `siteMetadata`, which `metadata` returns unchanged — a page that adds head tags of its own composes `siteMetadata` rather than replacing it.
+
+`preloadedFonts` is empty until the site ships fonts. Listing one emits `<link rel="preload" as="font" crossorigin>` at `/font/<name>.woff2`, deliberately unversioned: a preload URL must match the stylesheet's `@font-face` source exactly, or the browser fetches the font twice. List only the faces the stylesheets actually render — a subset gated by a `unicode-range` no page reaches would add a download that never otherwise happens.
 
 ## Configuration
 Configuration is read through [swift-configuration](https://github.com/apple/swift-configuration), **highest precedence first**:
@@ -88,12 +92,14 @@ A dotted config key maps to an environment variable by upper-casing, splitting c
 ### Static file caching
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `cache.maxAge.asset` | `CACHE_MAX_AGE_ASSET` | `31536000` (1 year) | `max-age` for fingerprinted assets (CSS, JS) and fonts; also marked `immutable`. The pages reference CSS/JS through content-versioned URLs (`?v=<token>`), so a deploy busts them by changing the URL. |
+| `cache.maxAge.asset` | `CACHE_MAX_AGE_ASSET` | `31536000` (1 year) | `max-age` for the fingerprinted assets (CSS, JS, MP4, JPEG, WebP) and fonts; also marked `immutable`. The pages reference them through content-versioned URLs (`?v=<token>`), so a deploy busts them by changing the URL. Fonts are immutable subset files, preloaded unversioned. |
 | `cache.maxAge.text` | `CACHE_MAX_AGE_TEXT` | `3600` (1 hour) | `max-age` for the remaining `text/*` assets (e.g. `robots.txt`), which keep unversioned URLs; also marked `must-revalidate`. |
-| `cache.maxAge.image` | `CACHE_MAX_AGE_IMAGE` | `604800` (1 week) | `max-age` for images (ICO, PNG, SVG). |
+| `cache.maxAge.image` | `CACHE_MAX_AGE_IMAGE` | `604800` (1 week) | `max-age` for the remaining images — the icons (ICO, PNG, SVG), which a browser fetches unversioned whatever the markup says, so they cannot be `immutable`. |
 | `cache.maxAge.default` | `CACHE_MAX_AGE_DEFAULT` | `86400` (1 day) | `max-age` for everything else — including `site.webmanifest` (`application/manifest+json`) and `sitemap.xml` (`application/xml`), neither of which is `text/*`. |
 
-The groups are matched in order, so the specific media types (`text/css`, `text/javascript`, `font/*`) are resolved before the general `text/*` category.
+The groups are matched in order, so the specific media types (`text/css`, `text/javascript`, `font/*`, `video/mp4`, `image/jpeg`, `image/webp`) resolve before the general `text/*` and `image/*` categories.
+
+> **An image the markup references without a `?v=` token must be neither JPEG nor WebP**, or it is served immutable for a year and no deploy can dislodge it.
 
 ### Response compression
 | Config key | Environment variable | Default | Description |
@@ -120,28 +126,17 @@ Redirecting collapses the `http://` and `https://` copies of every page onto one
 
 `docker-compose.yml` enables it for production; `docker-compose.override.yml` pins it off for local development.
 
-Trailing slashes are canonicalized separately and unconditionally, with no configuration key: the router matches `/mr-rock` and `/mr-rock/` alike, so
+Trailing slashes are canonicalized separately and unconditionally, with no configuration key: the router matches `/about` and `/about/` alike, so
 every `GET`/`HEAD` whose path ends in a slash is answered with a `301` to the form without one (`//` collapses to `/`; `/` is left alone). The
 `Location` is relative, so it keeps the request's own scheme and host. Other methods pass through, since a client may repeat a redirected `POST` as a
 `GET` and drop the body.
 
-### HTTPS redirect
+### Site
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `https.trustForwardedProto` | `HTTPS_TRUST_FORWARDED_PROTO` | `false` | Read the visitor's scheme from the `X-Forwarded-Proto` header and answer the plain-HTTP ones with `301 Moved Permanently` to the same path on `site.origin`. Enable **only** behind a reverse proxy that sets the header — it is the sole trigger. |
+| `site.origin` | `SITE_ORIGIN` | _(empty)_ | The public origin the site is served at (scheme and host, no trailing slash). The HTTPS redirect points at it, and absolute links derive from it. |
 
-Redirecting collapses the `http://` and `https://` copies of every page onto one address, which is what a search engine consolidates a site's signals against. Three details:
-
-- **`301`, not `302`** — a temporary redirect keeps the HTTP URLs indexed. Browsers cache it for a long time, so settle the target first.
-- **Target built from `site.origin`, not the `Host` header** — a client cannot steer it. An origin that is not itself HTTPS disables the middleware instead of looping.
-- **`/.well-known/` is exempt** — redirecting the ACME challenge path breaks certificate renewal.
-
-`docker-compose.yml` enables it for production; `docker-compose.override.yml` pins it off for local development.
-
-Trailing slashes are canonicalized separately and unconditionally, with no configuration key: the router matches `/mr-rock` and `/mr-rock/` alike, so
-every `GET`/`HEAD` whose path ends in a slash is answered with a `301` to the form without one (`//` collapses to `/`; `/` is left alone). The
-`Location` is relative, so it keeps the request's own scheme and host. Other methods pass through, since a client may repeat a redirected `POST` as a
-`GET` and drop the body.
+Empty by default, which leaves the [HTTPS redirect](#https-redirect) off: a deployment that trusts the forwarded-protocol header without setting this would otherwise redirect at a host the template guessed, and a `301` is cached for a long time. Bootstrap does **not** fill it in — it rewrites the crawler files only.
 
 ### Logging
 | Config key | Environment variable | Default | Description |
@@ -174,10 +169,12 @@ See [Persistence](#persistence-1) below for the workflow.
 ### Rate limiting
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `rateLimit.limit` | `RATELIMIT_LIMIT` | `5` | Requests admitted per client per window on the subscribe endpoint; the excess is answered with `429 Too Many Requests` and a `Retry-After` header. |
+| `rateLimit.limit` | `RATELIMIT_LIMIT` | `5` | Requests admitted per client per window; the excess is answered with `429 Too Many Requests` and a `Retry-After` header. |
 | `rateLimit.window` | `RATELIMIT_WINDOW` | `60` | Window length, in seconds, the limit applies to. |
 | `rateLimit.trustForwardedFor` | `RATELIMIT_TRUST_FORWARDED_FOR` | `false` | Key clients by the first `X-Forwarded-For` entry instead of the connection's address. Enable **only** behind a reverse proxy that sets the header — when the server is directly reachable, clients can forge it. |
 
+> **Configured but unapplied.** The template ships no endpoint worth limiting, so `RateLimitMiddleware` is built from these keys and never added to the chain. Wire it onto the route group that needs it — a form submission, say — when the site grows one.
+
 ### Analytics
 The template ships analytics **off**: `analytics.websiteID` is empty, so both pages embed no tracker at all and no third-party script is requested. Enabling it takes three steps, in this order:
 
@@ -316,7 +313,9 @@ docker compose -f docker-compose.yml up -d
 ```
 
 ### Static assets
-`Resources/Static` holds the site's stylesheets and scripts under `css/` and `js/`, paired by name: `shared.*` is loaded by every page, alongside a per-page `index.*` and `not-found.*`. The remaining files — the icons, `site.webmanifest`, `robots.txt`, and `sitemap.xml` — sit at the root. Every one of them is a case of the `StaticFile` enumeration, which is what the pages derive their URLs from.
+`Resources/Static` holds the site's stylesheets and scripts under `css/` and `js/`, paired by name: `shared.*` is loaded by every page, alongside a per-page `index.*` and `not-found.*`. The remaining files — the icons, `site.webmanifest`, `robots.txt`, and `sitemap.xml` — sit at the root.
+
+Each extension resolves to its own folder (`css/`, `js/`, `img/`, `font/`, `video/`), which a `StaticFile` overrides with `in:` when it needs one of its own — imagery conventionally sits in a folder per page (`img/index`). `img/` ships empty. Every one of them is a constant of the `StaticFile` structure, which is what the pages derive their URLs from.
 
 The image build optimizes the files under `Resources/Static` in its `assets` stage, in place, with pinned optimizer versions — and on a base image pinned by digest, not just by tag — so asset output is reproducible for a given Dockerfile commit:
 - CSS and JS are minified with [esbuild](https://esbuild.github.io) (every file in `css/` and `js/`).
@@ -325,7 +324,7 @@ The image build optimizes the files under `Resources/Static` in its `assets` sta
 
 The PNG and SVG passes walk the tree (`--recursive`), so images added in a subdirectory are optimized without touching the Dockerfile.
 
-Files keep their names and paths, so the URLs derived from the `StaticFile` enumeration are unaffected. The repository sources stay readable and unminified: a direct `swift run` serves them as-is, while any image build — including the local `make site-mount` one — serves the optimized copies. Assets are copied from the `assets` stage *after* the binary is built, so editing a CSS/JS/image file does not invalidate the release build cache.
+Files keep their names and paths, so the URLs derived from the `StaticFile` constants are unaffected. The repository sources stay readable and unminified: a direct `swift run` serves them as-is, while any image build — including the local `make site-mount` one — serves the optimized copies. Assets are copied from the `assets` stage *after* the binary is built, so editing a CSS/JS/image file does not invalidate the release build cache.
 
 Preview the optimized output locally (Docker only, writes to the git-ignored `.build/minified`):
 ```sh
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index e75d04f..616075a 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -139,7 +139,7 @@ private func logger(
 /// HTTPS-redirect middleware that bounces requests forwarded over plain HTTP to the canonical origin, the trailing-slash redirect middleware that
 /// collapses each path onto its canonical form, the vary middleware that marks every response as varying on `Accept-Encoding`, the response-compression middleware that compresses responses
 /// larger than `minimumResponseSizeToCompress` when the client advertises support, the localization middleware that negotiates the request's
-/// language from its `Accept-Language` header, the not-found middleware that serves the error page, and the static file middleware that serves the
+/// language from its `Accept-Language` header, the not-found middleware that serves the not-found page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then adds the `RootController` routes that
 /// render the landing page, and the `HealthController` routes that serve the health check.
 ///
@@ -154,7 +154,7 @@ private func logger(
 ///   - cacheControl: the cache-control directives applied to the served static files.
 ///   - compressionMinResponseSize: the minimum response body size, in bytes, before compression is applied.
 ///   - httpsRedirect: the origin plain-HTTP requests are redirected to, and whether the forwarded-protocol header is trusted.
-///   - rateLimit: the rate limit applied to the subscription endpoint.
+///   - rateLimit: the rate limit configuration, currently applied to no route.
 ///   - securityHeaders: the security headers applied to every response.
 ///   - logLevel: the level the request-logging middleware logs at.
 ///   - probe: the probe consulted by the `HealthController` readiness route.
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index d3acee0..767bbc7 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -186,7 +186,7 @@ package extension ConfigReader {
         )
     }
 
-    /// The rate limit applied to the subscription endpoint, built from the `rateLimit.*` keys.
+    /// The rate limit built from the `rateLimit.*` keys; the template applies it to no route yet.
     ///
     /// `rateLimit.limit` requests are admitted per client per `rateLimit.window` seconds. When `rateLimit.trustForwardedFor` is set,
     /// clients are keyed by the first `X-Forwarded-For` entry — enable it only behind a reverse proxy that sets the header, since clients can forge it
diff --git a/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift b/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
index 0052186..902f827 100644
--- a/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/NotFoundPage.swift
@@ -25,8 +25,7 @@ struct NotFoundPage {
     /// Creates a not-found page localized to the given locale.
     /// - Parameters:
     ///   - locale: the locale the page content is localized to.
-    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the
-    ///     default) to leave them unversioned.
+    ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
     ///   - analytics: the analytics tracker embedded in the document head, or `nil` (the default) to omit it.
     init(
         locale: Locale,
@@ -38,9 +37,10 @@ struct NotFoundPage {
         self.locale = locale
         self.localize = .init(bundle: .module)
     }
+
 }
 
-// MARK: Page
+// MARK: - Page
 
 extension NotFoundPage: Page {
 
diff --git a/Services/Website/Sources/Library/Internal/Types/StaticFile.swift b/Services/Website/Sources/Library/Internal/Types/StaticFile.swift
index d28c4b1..7925703 100644
--- a/Services/Website/Sources/Library/Internal/Types/StaticFile.swift
+++ b/Services/Website/Sources/Library/Internal/Types/StaticFile.swift
@@ -3,7 +3,8 @@ import Infrastructure
 /// A static file shipped with the website service.
 ///
 /// Each constant declares one file stored under the static files root (the `Resources/Static` directory) and served by Hummingbird's
-/// `FileMiddleware` middleware. A file can be available with more than one extension (see ``fileExtensions``), each resolving to its own file.
+/// `FileMiddleware` middleware. A file can be available with more than one extension (see ``fileExtensions``), each resolving to its own file, and
+/// sits in its extension's own folder unless it names a ``folder`` of its own.
 struct StaticFile: Asset {
 
     // MARK: Properties
diff --git a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
index 4a35757..36b0d4e 100644
--- a/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/HealthController.swift
@@ -117,10 +117,8 @@ private extension HealthController {
 
     /// Builds a JSON response carrying the given status and payload.
     ///
-    /// Every response is marked `noindex`. The checks answer `200 OK` to anyone who asks and nothing on the site links to them, so they are
-    /// unlikely to be found — but `robots.txt` allows the whole site, and a path that leaks into a log, a monitor, or an inbound link is crawlable
-    /// on discovery. The header keeps them out of the index even once they are fetched, which a `Disallow` rule would not: that stops the crawl, not
-    /// the indexing, and publishes the paths to everyone reading the file.
+    /// Every response is marked `noindex`: the checks answer `200 OK` to anyone, and `robots.txt` allows the whole site. A `Disallow` rule would
+    /// stop the crawl but not the indexing, and would publish the paths to everyone reading the file.
     /// - Parameters:
     ///   - status: the HTTP status of the response.
     ///   - payload: the JSON body of the response.
diff --git a/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift b/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
index a4a6c11..e00ec1d 100644
--- a/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/NotFoundMiddleware+Defaults.swift
@@ -5,10 +5,10 @@ public extension NotFoundMiddleware {
 
     // MARK: Initializers
 
-    /// Creates a not-found middleware that renders the website's error page, localized to the module's String Catalog languages.
+    /// Creates a not-found middleware that renders the website's not-found page, localized to the module's String Catalog languages.
     /// - Parameters:
     ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
-    ///   - analytics: the analytics tracker the error page embeds, or `nil` (the default) to omit it.
+    ///   - analytics: the analytics tracker the page embeds, or `nil` (the default) to omit the tracker script.
     init(
         assetVersion: String? = nil,
         analytics: Analytics? = nil
-- 
2.54.0


From cf58b97de14a36779bdf22b169de407d8f7597d6 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 09:03:50 +0200
Subject: [PATCH 101/117] Updated the ConfigReader+Properties extension in the
 Website service target to fail to the boot in case of unknown database
 tokens.

---
 Services/Website/README.md                    |   6 +-
 .../Sources/App/Extensions/App+Build.swift    |  10 +-
 .../Extensions/ConfigReader+Properties.swift  | 132 +++++++++++-------
 .../Public/Extensions/String+Constants.swift  |   8 +-
 .../App/ConfigReaderPropertiesTests.swift     |  52 +++++++
 5 files changed, 151 insertions(+), 57 deletions(-)

diff --git a/Services/Website/README.md b/Services/Website/README.md
index 5d21b0a..a5d5378 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -146,17 +146,19 @@ Empty by default, which leaves the [HTTPS redirect](#https-redirect) off: a depl
 ### Persistence
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `database.driver` | `DATABASE_DRIVER` | `inMemory` | Backend: `inMemory` (ephemeral SQLite, no infrastructure) or `postgres` (PostgreSQL). |
+| `database.driver` | `DATABASE_DRIVER` | `inMemory` | Backend: `inMemory` (ephemeral SQLite, no infrastructure) or `postgres` (PostgreSQL). Any other value fails the boot. |
 | `database.migrate` | `DATABASE_MIGRATE` (flag `--database-migrate`) | `false` | When set, run the migrations and exit instead of serving. |
 | `database.host` | `DATABASE_HOST` | `localhost` | PostgreSQL host. Ignored for `inMemory`. |
 | `database.port` | `DATABASE_PORT` | `5432` | PostgreSQL port. Ignored for `inMemory`. |
 | `database.name` | `DATABASE_NAME` | `site` | Database name. Ignored for `inMemory`. |
 | `database.username` | `DATABASE_USERNAME` | `site` | Database username. Ignored for `inMemory`. |
 | `database.password` | `DATABASE_PASSWORD` | _(empty)_ | Database password. Provide via the environment/a secret — never commit it. |
-| `database.tls` | `DATABASE_TLS` | `prefer` | TLS posture when connecting: `off`, `prefer`, or `require`. Ignored for `inMemory`. |
+| `database.tls` | `DATABASE_TLS` | `prefer` | TLS posture when connecting: `off`, `prefer`, or `require`. Any other value fails the boot. Ignored for `inMemory`. |
 | `database.pool.maxPerEventLoop` | `DATABASE_POOL_MAX_PER_EVENT_LOOP` | `4` | Maximum pooled connections per event loop. Ignored for `inMemory`. |
 | `database.pool.timeout` | `DATABASE_POOL_TIMEOUT` | `10` | Seconds a query waits for a pooled connection before failing. Ignored for `inMemory`. |
 
+> **Unrecognized tokens fail the boot.** Neither `database.driver` nor `database.tls` falls back, because both fallbacks are silent and costly: an unrecognized driver would run on the ephemeral in-memory database and discard every write on restart, and an unrecognized posture would land on `prefer`, which hands the password over in plaintext when the upgrade is stripped. The thrown `ConfigError` names the tokens the key accepts.
+
 > **Connection budget:** the pool holds `database.pool.maxPerEventLoop` connections *per event loop*, and the event loop group runs one loop per core. An 8-core instance can therefore open 32, and each replica that many again — three replicas exhaust PostgreSQL's default `max_connections` of 100. Size this against the server's limit, not against the number alone. On an exhausted pool, a query waits up to `database.pool.timeout` before failing.
 
 See [Persistence](#persistence-1) below for the workflow.
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 616075a..5659f00 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -16,7 +16,8 @@ import WebsiteLibrary
 /// band (so a shared database is never migrated on boot).
 /// - Parameter reader: the configuration reader the values are read from.
 /// - Returns: the configured application, ready to run as a service.
-/// - Throws: an error when the persistence service cannot be built (e.g. its TLS context fails to build).
+/// - Throws: a ``ConfigError`` when a `database.*` key holds an unrecognized token, or an error when the persistence service cannot be built
+///   (e.g. its TLS context fails to build).
 func application(
     reader: ConfigReader
 ) async throws -> some ApplicationProtocol {
@@ -34,8 +35,9 @@ func application(
         logger.warning("String Catalog is \(isCatalogMissing ? "missing" : "undecodable"); pages will serve raw localization keys")
     }
 
+    let driver = try reader.driver
     let persistence = try Service(
-        driver: reader.driver,
+        driver: driver,
         logger: logger
     )
     let fluent = persistence()
@@ -68,7 +70,7 @@ func application(
 
     // The in-memory backend is recreated on every launch, so it is migrated on startup. The PostgreSQL backend is
     // left untouched here: a shared database is migrated out of band to avoid multi-instance races.
-    if case .inMemory = reader.driver {
+    if case .inMemory = driver {
         app.beforeServerStarts {
             try await fluent.migrate()
         }
@@ -91,7 +93,7 @@ func migration(
         logLevel: reader.logLevel
     )
     let service = try Service(
-        driver: reader.driver,
+        driver: try reader.driver,
         logger: logger
     )
 
diff --git a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
index 767bbc7..338cd5f 100644
--- a/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
+++ b/Services/Website/Sources/App/Extensions/ConfigReader+Properties.swift
@@ -108,48 +108,53 @@ package extension ConfigReader {
     ///
     /// When `database.driver` selects PostgreSQL, the connection parameters are assembled from the `database.host`, `database.port`,
     /// `database.name`, `database.username`, `database.password` (empty when unset), `database.tls`,
-    /// `database.pool.maxPerEventLoop`, and `database.pool.timeout` keys. Any other driver value falls back to the in-memory database.
+    /// `database.pool.maxPerEventLoop`, and `database.pool.timeout` keys. Any token but `inMemory` and `postgres` throws a
+    /// ``ConfigError``: a mistyped driver fails the boot rather than running on the in-memory database and discarding every write on restart.
     var driver: Driver {
-        switch string(
-            forKey: .Database.driver,
-            default: .Database.driver
-        ) {
-        case .Database.driverPostgres:
-            return .postgres(
-                .init(
-                    host: string(
-                        forKey: .Database.host,
-                        default: .Database.host
-                    ),
-                    port: int(
-                        forKey: .Database.port,
-                        default: .Database.port
-                    ),
-                    name: string(
-                        forKey: .Database.name,
-                        default: .Database.name
-                    ),
-                    username: string(
-                        forKey: .Database.username,
-                        default: .Database.username
-                    ),
-                    password: string(
-                        forKey: .Database.password,
-                        default: ""
-                    ),
-                    tls: tls,
-                    maxConnectionsPerEventLoop: int(
-                        forKey: .Database.poolMaxPerEventLoop,
-                        default: .Database.poolMaxPerEventLoop
-                    ),
-                    poolTimeout: .seconds(int(
-                        forKey: .Database.poolTimeout,
-                        default: .Database.poolTimeout
-                    ))
+        get throws {
+            switch string(
+                forKey: .Database.driver,
+                default: .Database.driver
+            ) {
+            case .Database.driverInMemory:
+                return .inMemory
+            case .Database.driverPostgres:
+                return .postgres(
+                    .init(
+                        host: string(
+                            forKey: .Database.host,
+                            default: .Database.host
+                        ),
+                        port: int(
+                            forKey: .Database.port,
+                            default: .Database.port
+                        ),
+                        name: string(
+                            forKey: .Database.name,
+                            default: .Database.name
+                        ),
+                        username: string(
+                            forKey: .Database.username,
+                            default: .Database.username
+                        ),
+                        password: string(
+                            forKey: .Database.password,
+                            default: ""
+                        ),
+                        tls: try tls,
+                        maxConnectionsPerEventLoop: int(
+                            forKey: .Database.poolMaxPerEventLoop,
+                            default: .Database.poolMaxPerEventLoop
+                        ),
+                        poolTimeout: .seconds(int(
+                            forKey: .Database.poolTimeout,
+                            default: .Database.poolTimeout
+                        ))
+                    )
                 )
-            )
-        default:
-            return .inMemory
+            case let token:
+                throw ConfigError.unknownDatabaseDriver(token)
+            }
         }
     }
 
@@ -275,16 +280,45 @@ private extension ConfigReader {
 
     // MARK: Properties
 
-    /// The TLS posture for the PostgreSQL connection, mapped from the `database.tls` key: `off` and `require` map to their postures, and any
-    /// other value falls back to `prefer`.
+    /// The TLS posture for the PostgreSQL connection, mapped from the `database.tls` key.
+    ///
+    /// Any token but `off`, `prefer`, and `require` throws a ``ConfigError``: a mistyped posture (`required`, say) fails the boot rather than
+    /// falling back to `prefer`, which hands the password over in plaintext when the upgrade is stripped.
     var tls: TLS {
-        switch string(
-            forKey: .Database.tls,
-            default: .Database.tls
-        ) {
-        case .Database.tlsOff: .off
-        case .Database.tlsRequire: .require
-        default: .prefer
+        get throws {
+            switch string(
+                forKey: .Database.tls,
+                default: .Database.tls
+            ) {
+            case .Database.tlsOff: .off
+            case .Database.tlsPrefer: .prefer
+            case .Database.tlsRequire: .require
+            case let token: throw ConfigError.unknownDatabaseTLS(token)
+            }
+        }
+    }
+
+}
+
+// MARK: - ConfigError
+
+/// A configuration value the executable refuses to boot with; ``description`` names the tokens the key accepts.
+package enum ConfigError: Error, Equatable, CustomStringConvertible {
+
+    /// The `database.driver` key holds an unrecognized token.
+    case unknownDatabaseDriver(String)
+
+    /// The `database.tls` key holds an unrecognized token.
+    case unknownDatabaseTLS(String)
+
+    // MARK: Computed
+
+    package var description: String {
+        switch self {
+        case .unknownDatabaseDriver(let token):
+            "Unknown 'database.driver' value '\(token)': use '\(String.Database.driverInMemory)' or '\(String.Database.driverPostgres)'."
+        case .unknownDatabaseTLS(let token):
+            "Unknown 'database.tls' value '\(token)': use '\(String.Database.tlsOff)', '\(String.Database.tlsPrefer)', or '\(String.Database.tlsRequire)'."
         }
     }
 
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 3eda526..17ab005 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -24,7 +24,9 @@ extension String {
     /// A namespace for the persistence's default configuration values and recognized tokens.
     public enum Database {
         /// The default persistence driver: in-memory SQLite, which needs no external infrastructure.
-        public static let driver = "inMemory"
+        public static let driver = driverInMemory
+        /// The driver token selecting the in-memory SQLite backend.
+        public static let driverInMemory = "inMemory"
         /// The driver token selecting the PostgreSQL backend.
         public static let driverPostgres = "postgres"
         /// The default PostgreSQL host.
@@ -34,9 +36,11 @@ extension String {
         /// The default database username.
         public static let username = "site"
         /// The default TLS posture token.
-        public static let tls = "prefer"
+        public static let tls = tlsPrefer
         /// The TLS token disabling TLS.
         public static let tlsOff = "off"
+        /// The TLS token upgrading to TLS only when the server offers it.
+        public static let tlsPrefer = "prefer"
         /// The TLS token requiring TLS.
         public static let tlsRequire = "require"
     }
diff --git a/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift b/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
index 0f89b72..8f41914 100644
--- a/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
+++ b/Services/Website/Tests/App/ConfigReaderPropertiesTests.swift
@@ -99,6 +99,58 @@ struct ConfigReaderPropertiesTests {
         #expect(!header.contains("immutable"))
     }
 
+    @Test
+    func `driver to default to the in-memory database`() throws {
+        guard case .inMemory = try reader().driver else {
+            Issue.record("Expected the in-memory driver when 'database.driver' is unset.")
+            return
+        }
+    }
+
+    @Test
+    func `driver to select postgres when configured`() throws {
+        guard case .postgres = try reader(values: [.Database.driver: "postgres"]).driver else {
+            Issue.record("Expected the postgres driver when 'database.driver' selects it.")
+            return
+        }
+    }
+
+    @Test
+    func `driver to throw on an unknown token`() {
+        // A silent fallback would run the deployment on the ephemeral database and discard every write on restart.
+        #expect(throws: ConfigError.unknownDatabaseDriver("mariadb")) {
+            _ = try reader(values: [.Database.driver: "mariadb"]).driver
+        }
+    }
+
+    @Test(arguments: [
+        String.Database.tlsOff,
+        String.Database.tlsPrefer,
+        String.Database.tlsRequire
+    ])
+    func `driver to accept a recognized tls token`(token: String) throws {
+        let reader = reader(values: [
+            .Database.driver: .init(stringLiteral: .Database.driverPostgres),
+            .Database.tls: .init(stringLiteral: token)
+        ])
+
+        guard case .postgres = try reader.driver else {
+            Issue.record("Expected the postgres driver for the '\(token)' TLS token.")
+            return
+        }
+    }
+
+    @Test
+    func `driver to throw on an unknown tls token`() {
+        // A silent fallback to `prefer` hands the password over in plaintext when the upgrade is stripped.
+        #expect(throws: ConfigError.unknownDatabaseTLS("required")) {
+            _ = try reader(values: [
+                .Database.driver: .init(stringLiteral: .Database.driverPostgres),
+                .Database.tls: "required"
+            ]).driver
+        }
+    }
+
 }
 
 // MARK: - Helpers
-- 
2.54.0


From 8bf6e86ffb60b520cebc2a16b789e2c492854da8 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 09:15:59 +0200
Subject: [PATCH 102/117] Implemented the "tagging()" method for the the
 AnalyticsEvent+Tagging extension in the Infrastructure package.

---
 Packages/Infrastructure/README.md             |  4 +-
 .../Extensions/AnalyticsEvent+Tagging.swift   | 24 +++++++++
 .../TrailingSlashRedirectMiddleware.swift     |  2 +-
 .../AnalyticsEventTaggingTests.swift          | 49 +++++++++++++++++++
 4 files changed, 76 insertions(+), 3 deletions(-)
 create mode 100644 Packages/Infrastructure/Sources/Public/Extensions/AnalyticsEvent+Tagging.swift
 create mode 100644 Packages/Infrastructure/Tests/Cases/Public/Extensions/AnalyticsEventTaggingTests.swift

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 50a01f5..2181cf2 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -9,7 +9,7 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
 | Link previews | `SocialCard`, its `Image` and `Style`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, the open `Name` and `Kind` vocabularies, and the site-wide initializer building the `Organization`/`WebSite` pair |
-| Analytics | `Analytics`, the `Event`s a page reports, the tracker script `Attribute`s it derives, and the `origin` its preconnect hint targets |
+| Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to a tag), the tracker script `Attribute`s it derives, and the `origin` its preconnect hint targets |
 | Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
@@ -29,7 +29,7 @@ Sources/
 ├── Public/                public API
 │   ├── Builders/          RouteCollectionBuilder
 │   ├── Enumerations/      AssetExtension
-│   ├── Extensions/        addController, plus the default header names, rate limits, and header values
+│   ├── Extensions/        addController and Analytics.Event tagging, plus the default header names, rate limits, and header values
 │   ├── Methods/           FingerprintAssets
 │   ├── Middlewares/       the seven HTTP middlewares
 │   ├── Protocols/         Asset, LocalizedRequestContext, Page, RouterController
diff --git a/Packages/Infrastructure/Sources/Public/Extensions/AnalyticsEvent+Tagging.swift b/Packages/Infrastructure/Sources/Public/Extensions/AnalyticsEvent+Tagging.swift
new file mode 100644
index 0000000..2605648
--- /dev/null
+++ b/Packages/Infrastructure/Sources/Public/Extensions/AnalyticsEvent+Tagging.swift
@@ -0,0 +1,24 @@
+import Elementary
+
+public extension Analytics.Event {
+
+    // MARK: Methods
+
+    /// The event's ``attributes`` as attributes of the tag reporting it.
+    ///
+    /// ```swift
+    /// a(.href(url)) { "Listen" }
+    ///     .attributes(contentsOf: Analytics.Event(name: "playlist").tagging())
+    /// ```
+    ///
+    /// - Returns: one HTML attribute per event attribute, applied verbatim.
+    func tagging<Tag: HTMLTrait.Attributes.Global>() -> [HTMLAttribute<Tag>] {
+        attributes.map {
+            .custom(
+                name: $0.name,
+                value: $0.value
+            )
+        }
+    }
+
+}
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
index 4a77fcd..19b61e3 100644
--- a/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/TrailingSlashRedirectMiddleware.swift
@@ -3,7 +3,7 @@ import Hummingbird
 
 /// Answers a request whose path carries a trailing slash with `301 Moved Permanently` to the same path without one.
 ///
-/// The router matches `/about` and `/about/` alike, and `FileMiddleware` serves `/robots.txt/` as readily as `/robots.txt`, so without this
+/// The router matches `/page` and `/page/` alike, and `FileMiddleware` serves `/robots.txt/` as readily as `/robots.txt`, so without this
 /// every address on the site answers under at least two URLs. A search engine treats those as separate pages competing with each other, and any link
 /// earned by one is not credited to the other. Redirecting collapses them onto the form the pages already name as canonical.
 ///
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Extensions/AnalyticsEventTaggingTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Extensions/AnalyticsEventTaggingTests.swift
new file mode 100644
index 0000000..174225c
--- /dev/null
+++ b/Packages/Infrastructure/Tests/Cases/Public/Extensions/AnalyticsEventTaggingTests.swift
@@ -0,0 +1,49 @@
+import Elementary
+import Testing
+
+@testable import Infrastructure
+
+@Suite(
+    "Analytics.Event+Tagging extension",
+    .tags(.extension)
+)
+struct AnalyticsEventTaggingTests {
+
+    // MARK: Methods tests
+
+    @Test
+    func `applies the event name to the tag`() {
+        let markup = a(.href("/")) { "Listen" }
+            .attributes(contentsOf: Analytics.Event(name: "instagram").tagging())
+
+        #expect(markup.render().contains(#"data-umami-event="instagram""#))
+    }
+
+    @Test
+    func `applies every event attribute to the tag`() {
+        let event = Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        )
+
+        let markup = button {}
+            .attributes(contentsOf: event.tagging())
+        let rendered = markup.render()
+
+        #expect(rendered.contains(#"data-umami-event="playlist""#))
+        #expect(rendered.contains(#"data-umami-event-set="avc-xi""#))
+    }
+
+    @Test
+    func `returns one attribute per event attribute`() {
+        let event = Analytics.Event(
+            name: "playlist",
+            properties: ["set": "avc-xi"]
+        )
+
+        let attributes: [HTMLAttribute<HTMLTag.a>] = event.tagging()
+
+        #expect(attributes.count == event.attributes.count)
+    }
+
+}
-- 
2.54.0


From 1cae261dffb8fe927da3dd084446aa4d54ad7fce Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 09:22:10 +0200
Subject: [PATCH 103/117] Improved the .dockerignore definitions in the Website
 service target.

---
 Services/Website/.dockerignore | 13 +++++++++++--
 Services/Website/README.md     |  2 +-
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/Services/Website/.dockerignore b/Services/Website/.dockerignore
index 1f3233b..2a1db0d 100644
--- a/Services/Website/.dockerignore
+++ b/Services/Website/.dockerignore
@@ -1,7 +1,16 @@
+# Applies only when this directory is itself the build context. The Dockerfile
+# builds from the repository root (it copies the sibling Packages/), so today's
+# builds read the root .dockerignore instead — keep the two in step.
+
 .build
 .swiftpm
-.DS_Store
 .env.local
 docker-compose.*
 Makefile
-README.md
\ No newline at end of file
+README.md
+
+# The double star matches at every depth; a bare pattern only covers the context root.
+**/.DS_Store
+
+# Local database data directory (bind-mounted by Compose)
+Tests/DB
diff --git a/Services/Website/README.md b/Services/Website/README.md
index a5d5378..acdeba3 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -285,7 +285,7 @@ The production image is built in release mode with a statically linked Swift run
 
 `IMAGE_PLATFORM` is the single source of truth for the deployment architecture: `make img-check` and `make img-release` both build for it, and `docker-compose.yml` runs the pulled image with it. Keep it matched to the deployment host — the three have to agree, or a release builds for one architecture and the production Compose file refuses to run it. Local development builds are separate and follow `BUILD_PLATFORM` (see `docker-compose.override.yml`), since they target your machine rather than the deployment.
 
-The test sources are deliberately absent from the image. SPM validates the path of every target in the root package — including the test targets — even when only the executable product is built, so the Dockerfile creates those two directories empty rather than copying them. That keeps test edits from invalidating the release-build layer, and keeps the local database bind mount under `Tests/DB` out of the build context entirely (`.dockerignore` excludes `**/Tests` for the same reason).
+The test sources are deliberately absent from the image. SPM validates the path of every target in the root package — including the test targets — even when only the executable product is built, so the Dockerfile creates those two directories empty rather than copying them. That keeps test edits from invalidating the release-build layer, and keeps the local database bind mount under `Tests/DB` out of the build context entirely (the root `.dockerignore` excludes `**/Tests/DB` for the same reason).
 
 ### Base images
 All three stages pin their base by digest as well as tag, so a rebuild of an old commit resolves the same bases it originally used. The trade-off is that they no longer pick up upstream rebuilds on their own: **refresh the digests deliberately**, on whatever cadence you patch on, with
-- 
2.54.0


From a3d0bc75fd5963eda59a8e7d2dabd74dc63bcf4e Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 09:39:28 +0200
Subject: [PATCH 104/117] Implemented the validation for the name and slug
 inputs in the bootstrap script.

---
 Scripts/bootstrap | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/Scripts/bootstrap b/Scripts/bootstrap
index e5cfd71..eeb33fd 100755
--- a/Scripts/bootstrap
+++ b/Scripts/bootstrap
@@ -35,11 +35,46 @@ printf 'Site display name (PascalCase, e.g. Berlin) [Site]: '
 read -r NAME
 NAME="${NAME:-Site}"
 
+# The name is interpolated into sed replacements, a Swift string literal, the
+# Xcode project's directory name and the pbxproj. In a replacement `&` stands for
+# the whole match and `\` escapes, so either would corrupt the rewrites silently
+# rather than fail them — reject anything but letters and digits.
+case "$NAME" in
+	*[!A-Za-z0-9]*)
+		echo "error: the display name must be letters and digits only (got \"$NAME\")." >&2
+		exit 1
+		;;
+esac
+case "$NAME" in
+	[A-Za-z]*) ;;
+	*)
+		echo "error: the display name must start with a letter (got \"$NAME\")." >&2
+		exit 1
+		;;
+esac
+
 DEFAULT_SLUG="$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]')"
 printf 'Project slug (lowercase, used for owner/db/compose, e.g. loud-berlin) [%s]: ' "$DEFAULT_SLUG"
 read -r SLUG
 SLUG="${SLUG:-$DEFAULT_SLUG}"
 
+# The slug carries the same sed hazard as the name, and additionally becomes the
+# Compose project name and the PostgreSQL database name and role, which admit
+# lowercase alphanumerics, hyphens and underscores alone.
+case "$SLUG" in
+	*[!a-z0-9_-]*)
+		echo "error: the project slug must be lowercase letters, digits, hyphens or underscores (got \"$SLUG\")." >&2
+		exit 1
+		;;
+esac
+case "$SLUG" in
+	[a-z0-9]*) ;;
+	*)
+		echo "error: the project slug must start with a lowercase letter or digit (got \"$SLUG\")." >&2
+		exit 1
+		;;
+esac
+
 printf 'Canonical site URL (scheme + host, e.g. https://berlin.example.com) [%s]: ' "$PLACEHOLDER_URL"
 read -r URL
 URL="${URL:-$PLACEHOLDER_URL}"
@@ -84,7 +119,12 @@ rewrite() {
 	shift
 	[ -f "$file" ] || return 0
 	tmp="${file}.bootstrap.tmp"
-	sed "$@" "$file" >"$tmp" && mv "$tmp" "$file"
+	if sed "$@" "$file" >"$tmp"; then
+		mv "$tmp" "$file"
+	else
+		rm -f "$tmp"
+		return 1
+	fi
 }
 
 W="Services/Website"
-- 
2.54.0


From 6c75d5e7437b1c085cbf3a3ca1585da86d49f06c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 09:53:39 +0200
Subject: [PATCH 105/117] Improved the bootstrap script to write the canonical
 site origin and also, fixed some nasty bugs.

---
 .dockerignore                                 |  2 +-
 Makefile                                      |  2 +-
 README.md                                     | 14 +++++---
 Scripts/bootstrap                             | 33 +++++++++++++++----
 Services/Website/README.md                    |  4 +--
 .../Public/Extensions/String+Constants.swift  |  7 ++--
 6 files changed, 43 insertions(+), 19 deletions(-)

diff --git a/.dockerignore b/.dockerignore
index 5b74369..e4ba8fa 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -10,7 +10,7 @@
 **/.build
 **/.swiftpm
 
-# Test sources
+# Local database data directory.
 **/Tests/DB
 
 # Xcode project (not used by the Linux build)
diff --git a/Makefile b/Makefile
index 4f0b966..8076dd9 100644
--- a/Makefile
+++ b/Makefile
@@ -1,5 +1,5 @@
 # Template root Makefile — bootstrap convenience only.
-# This file is removed by `Tools/bootstrap` once the template is generated.
+# This file is removed by `Scripts/bootstrap` once the template is generated.
 
 .DEFAULT_GOAL := help
 
diff --git a/README.md b/README.md
index 1790d21..70134c9 100644
--- a/README.md
+++ b/README.md
@@ -53,9 +53,9 @@ make bootstrap        # or: ./Scripts/bootstrap
 
 | Prompt | Example | Rewrites |
 | --- | --- | --- |
-| **Site display name** (PascalCase) | `Loud` | Server name (`LoudWebsite`), `Loud.xcodeproj`, README title. |
-| **Project slug** (lowercase) | `loud-ams` | Container owner, database name/user, Compose project name. |
-| **Canonical site URL** (scheme + host) | `https://loud.amsterdam` | The `Sitemap:` reference in `robots.txt` and the `<loc>` entry in `sitemap.xml`. |
+| **Site display name** (PascalCase) | `Acme` | Server name (`AcmeWebsite`), `Acme.xcodeproj`, README title. |
+| **Project slug** (lowercase) | `acme-web` | Container owner, database name/user, Compose project name. |
+| **Canonical site URL** (scheme + host) | `https://acme.example.com` | The `Sitemap:` reference in `robots.txt`, the `<loc>` entry in `sitemap.xml`, and `String.Site.origin`. |
 
 - The URL defaults to the reserved `https://site.example.com`; leaving it is
   allowed (the script warns) and can be corrected later in the two crawler files.
@@ -84,10 +84,14 @@ make bootstrap        # or: ./Scripts/bootstrap
    set `ANALYTICS_WEBSITE_ID`. `ANALYTICS_DOMAINS` limits which hosts report;
    `ANALYTICS_RECORDER` opts into the session recorder. See
    [Analytics](Services/Website/README.md#analytics).
-5. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
+5. **Site origin** — bootstrap writes the canonical URL into `String.Site.origin`
+   (override with `SITE_ORIGIN`), leaving it empty for the placeholder. An empty
+   or non-HTTPS origin disables the HTTPS redirect, which
+   `HTTPS_TRUST_FORWARDED_PROTO` must enable besides.
+6. **Secrets** — set a real `DATABASE_PASSWORD` in a git-ignored
    `Services/Website/.env`; the committed `.env.local` is an example and defaults
    the password to the slug.
-6. **Domain models** — replace the `Persistence` package's sample `ExampleRecord`
+7. **Domain models** — replace the `Persistence` package's sample `ExampleRecord`
    / `ExampleRepository`. The default driver is in-memory SQLite, migrated on
    every boot; a real site sets `DATABASE_DRIVER=postgres` and migrates out of
    band (`swift run Website --database-migrate`). See
diff --git a/Scripts/bootstrap b/Scripts/bootstrap
index eeb33fd..746a31c 100755
--- a/Scripts/bootstrap
+++ b/Scripts/bootstrap
@@ -31,7 +31,7 @@ PLACEHOLDER_URL_PATTERN='https://site\.example\.com'
 
 # --- Prompts ------------------------------------------------------------------
 
-printf 'Site display name (PascalCase, e.g. Berlin) [Site]: '
+printf 'Site display name (PascalCase, e.g. Acme) [Site]: '
 read -r NAME
 NAME="${NAME:-Site}"
 
@@ -54,7 +54,7 @@ case "$NAME" in
 esac
 
 DEFAULT_SLUG="$(printf '%s' "$NAME" | tr '[:upper:]' '[:lower:]')"
-printf 'Project slug (lowercase, used for owner/db/compose, e.g. loud-berlin) [%s]: ' "$DEFAULT_SLUG"
+printf 'Project slug (lowercase, used for owner/db/compose, e.g. acme-web) [%s]: ' "$DEFAULT_SLUG"
 read -r SLUG
 SLUG="${SLUG:-$DEFAULT_SLUG}"
 
@@ -75,7 +75,7 @@ case "$SLUG" in
 		;;
 esac
 
-printf 'Canonical site URL (scheme + host, e.g. https://berlin.example.com) [%s]: ' "$PLACEHOLDER_URL"
+printf 'Canonical site URL (scheme + host, e.g. https://acme.example.com) [%s]: ' "$PLACEHOLDER_URL"
 read -r URL
 URL="${URL:-$PLACEHOLDER_URL}"
 URL="${URL%/}" # the rewrites append their own path, so drop a trailing slash
@@ -99,7 +99,7 @@ esac
 echo
 echo "  display name : $NAME       (server name \"${NAME}Website\", ${NAME}.xcodeproj)"
 echo "  slug         : $SLUG       (container owner, database name/user, compose project)"
-echo "  canonical URL: $URL       (robots.txt sitemap reference, sitemap.xml entry)"
+echo "  canonical URL: $URL       (robots.txt, sitemap.xml, String.Site.origin)"
 echo
 printf 'Apply these values? [y/N]: '
 read -r CONFIRM
@@ -136,6 +136,13 @@ rewrite "$W/Sources/Library/Public/Extensions/String+Constants.swift" \
 	-e "s/SiteWebsite/${NAME}Website/g" \
 	-e "s/= \"site\"/= \"${SLUG}\"/g"
 
+# Canonical origin. Left empty for the placeholder, which keeps the HTTPS
+# redirect off rather than aimed at a reserved example domain.
+if [ "$URL" != "$PLACEHOLDER_URL" ]; then
+	rewrite "$W/Sources/Library/Public/Extensions/String+Constants.swift" \
+		-e "s|^        public static let origin = \"\"\$|        public static let origin = \"${URL}\"|"
+fi
+
 # Local env example.
 rewrite "$W/.env.local" \
 	-e "s/SiteWebsite/${NAME}Website/g" \
@@ -162,6 +169,17 @@ rewrite "$W/docker-compose.override.yml" \
 rewrite "$W/Makefile" \
 	-e "s/),site)/),${SLUG})/g"
 
+# Web app manifest: the identity shown by an install prompt.
+rewrite "$W/Resources/Static/site.webmanifest" \
+	-e "s/^  \"short_name\": \"\"/  \"short_name\": \"${NAME}\"/" \
+	-e "s/^  \"name\": \"\"/  \"name\": \"${NAME}\"/"
+
+# Persistence integration test: its POSTGRES_TEST_* fallbacks address the local
+# container `make db-mount` creates, which is initialised from the slug.
+rewrite "Packages/Persistence/Tests/Cases/Public/Methods/ServiceTests.swift" \
+	-e "s/?? \"site\"/?? \"${SLUG}\"/g" \
+	-e "s/: \"site\",\$/: \"${SLUG}\",/"
+
 # Crawler files: the absolute origin they must carry. `|` is the sed delimiter,
 # since both the placeholder and the replacement contain slashes.
 rewrite "$W/Resources/Static/robots.txt" \
@@ -175,7 +193,9 @@ rewrite "$W/README.md" \
 	-e "s/^# Site Website\$/# ${NAME} Website/" \
 	-e "s/\*\*Site\*\*/**${NAME}**/" \
 	-e "s/SiteWebsite/${NAME}Website/g" \
-	-e "s/\`site\`/\`${SLUG}\`/g"
+	-e "s/\`site\`/\`${SLUG}\`/g" \
+	-e "s/\`Site\.xcodeproj\`/\`${NAME}.xcodeproj\`/g" \
+	-e "s|^\`robots.txt\` and \`sitemap.xml\` need an absolute origin.*\$|\`robots.txt\` and \`sitemap.xml\` carry the absolute origin bootstrap wrote into them: ${URL}. Update both if the canonical origin ever changes.|"
 
 # Xcode project: PBXProject name + directory.
 if [ -d "$XCODEPROJ" ]; then
@@ -218,7 +238,6 @@ rm -f Scripts/bootstrap
 rmdir Scripts 2>/dev/null || true
 rm -f Makefile          # root convenience Makefile (bootstrap only)
 rm -f README.md       # template usage docs
-rm -rf .gitea           # Gitea template metadata
 
 # --- Done ---------------------------------------------------------------------
 
@@ -231,7 +250,7 @@ Next steps:
        - $W/Sources/Library/Catalogs/Localizable.xcstrings   (copy)
        - $W/Sources/Library                                   (landing / 404 pages)
        - $W/Resources/Static                                  (css, js, favicon, icons)
-       - $W/Resources/Static/site.webmanifest                 (name / short_name)
+       - $W/Resources/Static/site.webmanifest                 (theme colours)
   2. Set a real database password in a git-ignored $W/.env
      (the committed .env.local defaults the password to the slug — do NOT ship that).
   3. Analytics ships OFF, and stays off until you opt in. To enable it: check
diff --git a/Services/Website/README.md b/Services/Website/README.md
index acdeba3..b7faa7c 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -134,9 +134,9 @@ every `GET`/`HEAD` whose path ends in a slash is answered with a `301` to the fo
 ### Site
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `site.origin` | `SITE_ORIGIN` | _(empty)_ | The public origin the site is served at (scheme and host, no trailing slash). The HTTPS redirect points at it, and absolute links derive from it. |
+| `site.origin` | `SITE_ORIGIN` | _(set by bootstrap)_ | The public origin the site is served at (scheme and host, no trailing slash). The HTTPS redirect points at it, and absolute links derive from it. |
 
-Empty by default, which leaves the [HTTPS redirect](#https-redirect) off: a deployment that trusts the forwarded-protocol header without setting this would otherwise redirect at a host the template guessed, and a `301` is cached for a long time. Bootstrap does **not** fill it in — it rewrites the crawler files only.
+Bootstrap writes the canonical URL it prompts for here, leaving it empty for the placeholder. An empty or non-HTTPS origin disables the [HTTPS redirect](#https-redirect), which `https.trustForwardedProto` must enable besides — a `301` is cached for a long time, so it is never issued at a host nobody named.
 
 ### Logging
 | Config key | Environment variable | Default | Description |
diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index 17ab005..ad103ec 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -56,10 +56,11 @@ extension String {
     }
     /// A namespace for the site string constants.
     public enum Site {
-        /// The default public origin the site is served at (scheme and host, no trailing slash): empty, which leaves the HTTPS redirect off.
+        /// The default public origin the site is served at (scheme and host, no trailing slash).
         ///
-        /// A deployment that trusts the forwarded-protocol header without also setting `site.origin` would otherwise redirect at a host the
-        /// template guessed for it, and a `301` is cached for a long time.
+        /// Bootstrap writes the canonical URL it prompts for here, leaving it empty for the placeholder. An empty or non-HTTPS origin disables
+        /// the HTTPS redirect, which `https.trustForwardedProto` must enable besides — a `301` is cached for a long time, so it is never issued
+        /// at a host nobody named.
         public static let origin = ""
     }
 }
-- 
2.54.0


From 79cfb42fbbadfe03886f78a95d8fb60b5c15b85c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 19:03:52 +0200
Subject: [PATCH 106/117] Updated the LocalizationMiddleware middleware in the
 Infrastructure package to read explicit language requests.

---
 .../Middlewares/LocalizationMiddleware.swift  | 26 +++++++++--
 .../Sources/Public/Types/SocialCard.swift     |  4 +-
 .../LocalizationMiddlewareTests.swift         | 43 +++++++++++++++++++
 3 files changed, 67 insertions(+), 6 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
index 964909c..c7adec7 100644
--- a/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
@@ -5,11 +5,13 @@ import Localization
 
 /// Resolves the visitor's preferred language and records it on the request context.
 ///
-/// Placed ahead of the localized responders in the middleware chain, it reads the request's `Accept-Language` header, negotiates the best supported
-/// match (falling back to the default language), and stores it on the context's ``LocalizedRequestContext/language``.
+/// Placed ahead of the localized responders in the middleware chain, it reads the request's `lang` query parameter, its path, and its
+/// `Accept-Language` header, negotiates the best supported match (falling back to the default language), and stores it on the context's
+/// ``LocalizedRequestContext/language``.
 ///
-/// The request is otherwise passed through untouched — the URL and routing are not affected — so each page is served at its existing path and varies its
-/// content by header.
+/// The query parameter is the deliberate override a language switcher links to; failing that, a leading path segment naming a supported language
+/// pins it, so an unrouted path under a language's prefix — its not-found page — answers in that language. Values naming no supported language
+/// are ignored, leaving the header. The request is passed through untouched — the path and routing are unaffected.
 public struct LocalizationMiddleware<Context: LocalizedRequestContext> {
 
     // MARK: Properties
@@ -49,7 +51,13 @@ extension LocalizationMiddleware: RouterMiddleware {
     ) async throws -> Response {
         var context = context
 
+        // The deliberate query override first; failing that, the leading path segment, so a language's whole URL
+        // prefix — routed or not — answers in its language.
+        let requested = request.uri.queryParameters[.Parameter.language].map(String.init)
+            ?? request.uri.path.split(separator: "/").first.map(String.init)
+
         context.language = negotiate(
+            requested: requested,
             acceptLanguage: request.headers[.acceptLanguage]
         )
 
@@ -57,3 +65,13 @@ extension LocalizationMiddleware: RouterMiddleware {
     }
 
 }
+
+// MARK: - Constants
+
+private extension Substring {
+    /// A namespace for the query parameters the middleware reads.
+    enum Parameter {
+        /// The query parameter carrying an explicit language choice; the site's language switcher appends it to the current path.
+        static let language: Substring = "lang"
+    }
+}
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
index dd7926e..0fe4a74 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
@@ -12,7 +12,7 @@ public struct SocialCard: Sendable {
 
     /// The locale of the card's text, or `nil` to omit its tag.
     ///
-    /// Open Graph specifies the `language_TERRITORY` form (e.g. `en_NL`); scrapers also accept a bare language code (e.g. `en`).
+    /// Open Graph specifies the `language_TERRITORY` form (e.g. `en_US`); scrapers also accept a bare language code (e.g. `en`).
     public let locale: String?
 
     /// The name of the site the card belongs to, or `nil` to omit its tag.
@@ -41,7 +41,7 @@ public struct SocialCard: Sendable {
     ///   - summary: the card's summary, or `nil` (the default) to omit its tag.
     ///   - url: the absolute URL the card's page is served at, or `nil` (the default) to omit its tag.
     ///   - siteName: the name of the site the card belongs to, or `nil` (the default) to omit its tag.
-    ///   - locale: the locale of the card's text, ideally in Open Graph's `language_TERRITORY` form (e.g. `en_NL`), or `nil` (the default)
+    ///   - locale: the locale of the card's text, ideally in Open Graph's `language_TERRITORY` form (e.g. `en_US`), or `nil` (the default)
     ///     to omit its tag.
     ///   - image: the card's share image, or `nil` (the default) to omit its tags.
     ///   - type: the Open Graph type of the object the card describes. Defaults to `website`.
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
index f246f5c..bb167a9 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Middlewares/LocalizationMiddlewareTests.swift
@@ -25,6 +25,9 @@ struct LocalizationMiddlewareTests {
         router.get("language") { _, context in
             context.language
         }
+        router.get("de/language") { _, context in
+            context.language
+        }
 
         return router
     }())
@@ -69,4 +72,44 @@ struct LocalizationMiddlewareTests {
         }
     }
 
+    @Test
+    func `honours a supported lang query parameter over the header`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language?lang=de",
+                method: .get,
+                headers: [.acceptLanguage: "en"]
+            ) { response in
+                #expect(String(buffer: response.body) == "de")
+            }
+        }
+    }
+
+    /// A language's whole URL prefix answers in its language, so its not-found page does too.
+    @Test
+    func `pins the language a leading path segment names over the header`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/de/language",
+                method: .get,
+                headers: [.acceptLanguage: "en"]
+            ) { response in
+                #expect(String(buffer: response.body) == "de")
+            }
+        }
+    }
+
+    @Test
+    func `negotiates the header when the lang query parameter is unsupported`() async throws {
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/language?lang=fr",
+                method: .get,
+                headers: [.acceptLanguage: "de"]
+            ) { response in
+                #expect(String(buffer: response.body) == "de")
+            }
+        }
+    }
+
 }
-- 
2.54.0


From 9b16ce3339dbeeff789bc2468b0bf207efa83b43 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 19:05:52 +0200
Subject: [PATCH 107/117] Updated the Negotiate method in the Localization
 package to add explicit language requests.

---
 Packages/Localization/README.md               |  2 +-
 .../Sources/Public/Methods/Negotiate.swift    | 18 ++++++++-
 .../Cases/Public/Methods/NegotiateTests.swift | 40 +++++++++++++++++++
 3 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/Packages/Localization/README.md b/Packages/Localization/README.md
index 3f79dae..7be3a52 100644
--- a/Packages/Localization/README.md
+++ b/Packages/Localization/README.md
@@ -5,7 +5,7 @@ The server-side localization toolkit the platform's services build on: locale-ex
 | Role | Types |
 | --- | --- |
 | Lookup | `Localize`, a bundle-bound localizer that resolves a catalog key for an explicit locale |
-| Negotiation | `Negotiate`, which picks the best supported language from an `Accept-Language` header per RFC 9110 |
+| Negotiation | `Negotiate`, which picks the best supported language from an explicit request or an `Accept-Language` header per RFC 9110 |
 | Languages | `LanguageList`, the supported and default languages a bundle's String Catalog defines |
 | Diagnostics | `CatalogState`, the outcome of reading the catalog (`loaded`, `missing`, or `undecodable`) |
 
diff --git a/Packages/Localization/Sources/Public/Methods/Negotiate.swift b/Packages/Localization/Sources/Public/Methods/Negotiate.swift
index ee41bed..c18694e 100644
--- a/Packages/Localization/Sources/Public/Methods/Negotiate.swift
+++ b/Packages/Localization/Sources/Public/Methods/Negotiate.swift
@@ -24,18 +24,32 @@ public struct Negotiate: Sendable {
 
     // MARK: Methods
 
-    /// Picks the best supported language for the given `Accept-Language` header value.
+    /// Picks the best supported language for the given explicit request and `Accept-Language` header value.
     ///
     /// Invoked by calling the instance directly, for example `negotiate(acceptLanguage: header)`.
+    /// A `requested` language — a deliberate choice, such as a language switcher's query parameter — wins over the header when it matches a
+    /// supported language, on the same terms a header tag matches; an unsupported value is ignored, so it cannot select a language the catalog
+    /// does not serve.
+    ///
     /// The header is parsed into its language ranges, which are ordered by descending `q` weight as RFC 9110 prescribes: an entry without a weight
     /// counts as 1, entries weighted 0 are "not acceptable" and dropped, and equal weights keep the header order. Each tag is then matched against the
     /// supported languages in turn — first by an exact match, then by its primary language subtag, so `de-AT` resolves to a supported `de` — while the
     /// `*` wildcard accepts the default language. When the header is absent or matches nothing, the default language is returned.
-    /// - Parameter acceptLanguage: the raw `Accept-Language` header value, if any.
+    /// - Parameters:
+    ///   - requested: an explicitly requested language identifier, if any; it overrides the header when supported.
+    ///   - acceptLanguage: the raw `Accept-Language` header value, if any.
     /// - Returns: the identifier of the supported language to serve.
     public func callAsFunction(
+        requested: String? = nil,
         acceptLanguage language: String?
     ) -> String {
+        if
+            let requested,
+            let match = match(requested, in: list.all)
+        {
+            return match
+        }
+
         guard let language else {
             return list.default
         }
diff --git a/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift b/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
index f7cb0bc..6adc16c 100644
--- a/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
+++ b/Packages/Localization/Tests/Cases/Public/Methods/NegotiateTests.swift
@@ -127,4 +127,44 @@ struct NegotiateTests {
         #expect(language == "en")
     }
 
+    @Test
+    func `honours a supported requested language over the header`() {
+        let language = negotiate(
+            requested: "de",
+            acceptLanguage: "en"
+        )
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `matches a regional requested language by its primary subtag`() {
+        let language = negotiate(
+            requested: "de-AT",
+            acceptLanguage: "en"
+        )
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `ignores an unsupported requested language`() {
+        let language = negotiate(
+            requested: "fr",
+            acceptLanguage: "de"
+        )
+
+        #expect(language == "de")
+    }
+
+    @Test
+    func `ignores an empty requested language`() {
+        let language = negotiate(
+            requested: "",
+            acceptLanguage: "de"
+        )
+
+        #expect(language == "de")
+    }
+
 }
-- 
2.54.0


From a3d9655766e2ae0c06c0dd7ca45a8f8326a64fe9 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 19:07:04 +0200
Subject: [PATCH 108/117] Added language support to the Website service target.

---
 Packages/Infrastructure/README.md             |   4 +-
 Services/Website/README.md                    |  38 ++++--
 .../Sources/App/Extensions/App+Build.swift    |  11 +-
 .../Internal/Extensions/Page+Defaults.swift   |  62 +++++++++
 .../Library/Internal/Pages/IndexPage.swift    |  36 +++++
 .../Library/Internal/Types/Language.swift     | 100 ++++++++++++++
 .../Public/Controllers/RootController.swift   |  33 ++++-
 .../Extensions/PageDefaultsTests.swift        | 128 ++++++++++++++++++
 .../Cases/Internal/Pages/IndexPageTests.swift |  26 ++++
 .../Cases/Internal/Types/LanguageTests.swift  | 109 +++++++++++++++
 .../Controllers/RootControllerTests.swift     |  36 ++++-
 .../Utils/Extensions/Tag+Constants.swift      |   2 +
 12 files changed, 568 insertions(+), 17 deletions(-)
 create mode 100644 Services/Website/Sources/Library/Internal/Types/Language.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Internal/Extensions/PageDefaultsTests.swift
 create mode 100644 Services/Website/Tests/Library/Cases/Internal/Types/LanguageTests.swift

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 2181cf2..8fd2d8d 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -5,11 +5,11 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Role | Types |
 | --- | --- |
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
-| Middlewares | `SecurityHeadersMiddleware`, `HTTPSRedirectMiddleware`, `TrailingSlashRedirectMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware`, `NotFoundMiddleware` |
+| Middlewares | `SecurityHeadersMiddleware`, `HTTPSRedirectMiddleware`, `TrailingSlashRedirectMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware` (negotiating from a `lang` query parameter, then a leading path segment, then `Accept-Language`), `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
 | Link previews | `SocialCard`, its `Image` and `Style`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, the open `Name` and `Kind` vocabularies, and the site-wide initializer building the `Organization`/`WebSite` pair |
-| Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to a tag), the tracker script `Attribute`s it derives, and the `origin` its preconnect hint targets |
+| Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to a tag), the tracker script `Attribute`s it derives, the optional session `recorder` script paired with it, and the `origin` its preconnect hint targets |
 | Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
diff --git a/Services/Website/README.md b/Services/Website/README.md
index b7faa7c..57c1076 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -3,8 +3,8 @@ The **Site** public website service — a [Hummingbird](https://github.com/hummi
 
 ## Overview
 The service:
-- Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached).
-- Negotiates each request's language from its `Accept-Language` header against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
+- Serves the landing page at `GET /` (rendered once per supported language with [Elementary](https://github.com/elementary-swift/elementary) and cached), plus one prefixed route per non-default catalog language — `GET /nl` and so on (see [Language editions](#language-editions)).
+- Negotiates each request's language from the `lang` query parameter, the leading path segment, then its `Accept-Language` header, against the languages in the `WebsiteLibrary` String Catalog, falling back to the default (`en`); pages are served from the per-language cache with `Content-Language` and `Vary: Accept-Language` headers.
 - Builds every page on the shared `Page` scaffolding from `Infrastructure`, which assembles the document head around the page's own markup: the viewport declaration, the optional `description` summary and `rel="canonical"` link, the Open Graph / Twitter link-preview tags, the JSON-LD structured-data script, and the optional analytics tracker (see [Page metadata](#page-metadata)).
 - Answers a liveness check at `GET /health` with a static JSON payload, and a readiness check at `GET /health/ready` that reports whether the database is reachable (`200` ready / `503` unavailable).
 - Answers `HEAD` on every `GET` route: the router is built with `.autoGenerateHeadEndpoints`, so uptime monitors and crawlers probing with `HEAD` get the route's status and headers instead of a `404`.
@@ -43,10 +43,10 @@ LogRequestsMiddleware
       → TrailingSlashRedirectMiddleware  (301 to the path without a trailing slash)
         → VaryMiddleware                 (marks every response as varying on Accept-Encoding)
           → ResponseCompressionMiddleware (gzip/deflate above the size threshold)
-            → LocalizationMiddleware      (negotiates the request's language)
+            → LocalizationMiddleware      (negotiates the language: ?lang=, path prefix, then Accept-Language)
               → NotFoundMiddleware        (renders the localized not-found page on .notFound)
                 → FileMiddleware          (serves Resources/Static)
-RootController                            (GET / → landing page)
+RootController                            (GET / → landing page; GET /<lang> → its other editions)
 HealthController                          (GET /health → liveness, GET /health/ready → readiness)
 ```
 
@@ -55,20 +55,38 @@ The router is created with `.autoGenerateHeadEndpoints`, so each of those `GET`
 ### Page metadata
 Each page conforms to `Infrastructure`'s `Page` protocol and supplies only its `title`, `content`, `stylesheets`, and `scripts`; the protocol assembles the document around them and renders the head in a fixed order: the viewport declaration, the `analytics` origin preconnect hint, the `summary`, the `canonicalURL` link, the `socialCard` tags, the `structuredData` script, the `analytics` tracker script, then the page `metadata` and the stylesheet links. The body is the content followed by the script tags.
 
-Four of those are page-authored, optional, and **omitted by default** — the reference site leaves them unset, so a generated site fills in what it needs by overriding them on `IndexPage` (or on the shared `Page+Defaults` extension, for site-wide values):
+Four of those are page-authored and optional. `IndexPage` supplies `canonicalURL`; the other three are **omitted by default** — the reference site leaves them unset, so a generated site fills in what it needs by overriding them on `IndexPage` (or on the shared `Page+Defaults` extension, for site-wide values):
 | Property | Renders as | Notes |
 | --- | --- | --- |
 | `summary` | `<meta name="description">` | The page's one-line description. |
-| `canonicalURL` | `<link rel="canonical">` | Absolute URL. |
-| `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, share image. Scrapers require absolute URLs, so the page composes them from its own origin. |
+| `canonicalURL` | `<link rel="canonical">` | Absolute URL. `IndexPage` derives it from `site.origin` and the page's own language; an unset origin omits it (see [Language editions](#language-editions)). |
+| `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, share image. Scrapers require absolute URLs, so the page composes them from its own origin; `Page+Defaults` supplies the locale as `ogLocale`. |
 | `structuredData` | `<script type="application/ld+json">` | A `StructuredData` graph of schema.org nodes; `StructuredData(name:url:logo:profiles:)` builds the site-wide `Organization` + `WebSite` pair. The payload is an inert data block, so the `Content-Security-Policy` does not apply to it. |
 
 The fifth, `analytics`, is *configuration*-authored rather than page-authored: the executable builds an `Analytics` from the `analytics.*` keys and hands it to `RootController` and `NotFoundMiddleware`, which pass it to both pages. It renders as a `<link rel="preconnect">` plus a deferred `<script>` carrying the [Umami](https://umami.is) `data-` attributes, and — unlike the structured data — it *is* executable, so the `Content-Security-Policy` must allow its origin. It is empty by default; see [Analytics](#analytics) for how to turn it on.
 
-What the pages *do* ship is in `Page+Defaults` (`Sources/Library/Internal/Extensions`), shared by every page: the document `lang`, the `preloadedFonts` links, the favicon / SVG icon / apple-touch-icon / web-manifest links, and the two `theme-color` metas. Those live in `siteMetadata`, which `metadata` returns unchanged — a page that adds head tags of its own composes `siteMetadata` rather than replacing it.
+What the pages *do* ship is in `Page+Defaults` (`Sources/Library/Internal/Extensions`), shared by every page: the document `lang`, the `ogLocale` a social card would carry, the `preloadedFonts` links, the favicon / SVG icon / apple-touch-icon / web-manifest links, and the two `theme-color` metas. The last group lives in `siteMetadata`, which `metadata` returns unchanged — a page that adds head tags of its own composes `siteMetadata` rather than replacing it.
+
+`ogLocale` renders Open Graph's `language_TERRITORY` form by looking the page's `lang` up in the `ogLocales` map, which ships one pairing: `en` → `en_US`. A site serving a language in a territory of its own repoints or extends the map (`en_NL`, `nl_NL`, …); a language with no entry stays a bare code, which scrapers also accept. Nothing reads it until a page supplies a `socialCard`.
 
 `preloadedFonts` is empty until the site ships fonts. Listing one emits `<link rel="preload" as="font" crossorigin>` at `/font/<name>.woff2`, deliberately unversioned: a preload URL must match the stylesheet's `@font-face` source exactly, or the browser fetches the font twice. List only the faces the stylesheets actually render — a subset gated by a `unicode-range` no page reaches would add a download that never otherwise happens.
 
+### Language editions
+The `WebsiteLibrary` String Catalog is the single source of truth for the languages the site serves: add a localization and it appears, with no code change. `Language` (`Sources/Library/Internal/Types`) reads that list and derives each language's URLs from it.
+
+The catalog's source language is the **default** and owns the site's bare paths; every other language answers under a prefix of its own. The root collapses onto the prefix alone, so a Dutch home is `/nl`, not `/nl/` — the spelling `TrailingSlashRedirectMiddleware` redirects away from anyway:
+
+| Language | Landing page | A page at `/privacy` |
+| --- | --- | --- |
+| `en` (default) | `/` | `/privacy` |
+| `nl` | `/nl` | `/nl/privacy` |
+
+`RootController` registers the bare route plus one per non-default language. A prefixed route answers in *its* language for every visitor and every crawler — the path is the language choice, so the negotiated context language is ignored, which is what lets a search engine index it as that edition. The template ships an English-only catalog, so it registers the bare route alone.
+
+Given a `site.origin`, each page then emits the `hreflang` alternates tying its editions together — one per language plus an `x-default` pointing at the default language's edition, whose bare URL negotiates the language and so is the right landing for everyone unmatched. A single-language site emits none: a set naming one edition tells a search engine nothing it cannot already see. `Page+Defaults`' `languageAlternates(origin:path:languages:)` takes the language set, so a page translated into only some of them narrows it rather than advertising an edition that does not exist.
+
+Visitors switch language two ways, both handled by `LocalizationMiddleware` ahead of the routes: a `?lang=` query parameter (what a language switcher links to) and the leading path segment. Either beats `Accept-Language`; a value naming no supported language is ignored. The path segment matters beyond the routed pages — it is what makes an *unrouted* path under a language's prefix answer its not-found page in that language.
+
 ## Configuration
 Configuration is read through [swift-configuration](https://github.com/apple/swift-configuration), **highest precedence first**:
 1. Command-line arguments (e.g. `--http-host 0.0.0.0`)
@@ -134,9 +152,9 @@ every `GET`/`HEAD` whose path ends in a slash is answered with a `301` to the fo
 ### Site
 | Config key | Environment variable | Default | Description |
 | --- | --- | --- | --- |
-| `site.origin` | `SITE_ORIGIN` | _(set by bootstrap)_ | The public origin the site is served at (scheme and host, no trailing slash). The HTTPS redirect points at it, and absolute links derive from it. |
+| `site.origin` | `SITE_ORIGIN` | _(set by bootstrap)_ | The public origin the site is served at (scheme and host, no trailing slash). The HTTPS redirect points at it, and the pages' `rel="canonical"` links and `hreflang` alternates derive from it. |
 
-Bootstrap writes the canonical URL it prompts for here, leaving it empty for the placeholder. An empty or non-HTTPS origin disables the [HTTPS redirect](#https-redirect), which `https.trustForwardedProto` must enable besides — a `301` is cached for a long time, so it is never issued at a host nobody named.
+Bootstrap writes the canonical URL it prompts for here, leaving it empty for the placeholder. An empty or non-HTTPS origin disables the [HTTPS redirect](#https-redirect), which `https.trustForwardedProto` must enable besides — a `301` is cached for a long time, so it is never issued at a host nobody named. An empty origin also leaves the pages without canonical URLs and language alternates, rather than building either against an empty host.
 
 ### Logging
 | Config key | Environment variable | Default | Description |
diff --git a/Services/Website/Sources/App/Extensions/App+Build.swift b/Services/Website/Sources/App/Extensions/App+Build.swift
index 5659f00..c60adef 100644
--- a/Services/Website/Sources/App/Extensions/App+Build.swift
+++ b/Services/Website/Sources/App/Extensions/App+Build.swift
@@ -57,6 +57,9 @@ func application(
             httpsRedirect: reader.httpsRedirect,
             rateLimit: reader.rateLimit,
             securityHeaders: reader.securityHeaders,
+            // An unset origin leaves the pages without canonical URLs and language alternates, rather than
+            // building both against an empty host.
+            siteOrigin: reader.siteOrigin.isEmpty ? nil : reader.siteOrigin,
             logLevel: reader.logLevel,
             probe: Probe(fluent: fluent)
         ),
@@ -141,9 +144,10 @@ private func logger(
 /// HTTPS-redirect middleware that bounces requests forwarded over plain HTTP to the canonical origin, the trailing-slash redirect middleware that
 /// collapses each path onto its canonical form, the vary middleware that marks every response as varying on `Accept-Encoding`, the response-compression middleware that compresses responses
 /// larger than `minimumResponseSizeToCompress` when the client advertises support, the localization middleware that negotiates the request's
-/// language from its `Accept-Language` header, the not-found middleware that serves the not-found page, and the static file middleware that serves the
+/// language from its `Accept-Language` header (honouring the `lang` query override and the language a leading path segment names), the
+/// not-found middleware that serves the not-found page, and the static file middleware that serves the
 /// contents of `staticFilesPath` (tagging responses with the given `cacheControl` directives), then adds the `RootController` routes that
-/// render the landing page, and the `HealthController` routes that serve the health check.
+/// render the landing page — one per language the String Catalog serves — and the `HealthController` routes that serve the health check.
 ///
 /// The security-headers middleware sits just inside request logging so it covers every response that reaches a client — the landing page, the compressed
 /// responses, the rendered not-found page, and the served static files. The HTTPS redirect sits directly beneath it, so a redirect carries the security
@@ -158,6 +162,7 @@ private func logger(
 ///   - httpsRedirect: the origin plain-HTTP requests are redirected to, and whether the forwarded-protocol header is trusted.
 ///   - rateLimit: the rate limit configuration, currently applied to no route.
 ///   - securityHeaders: the security headers applied to every response.
+///   - siteOrigin: the public origin the pages derive their canonical URLs and language alternates from, or `nil` to omit them.
 ///   - logLevel: the level the request-logging middleware logs at.
 ///   - probe: the probe consulted by the `HealthController` readiness route.
 /// - Returns: the configured router.
@@ -170,6 +175,7 @@ private func router(
     httpsRedirect: HTTPSRedirectMiddleware<AppRequestContext>.Configuration,
     rateLimit: RateLimitMiddleware<AppRequestContext>.Configuration,
     securityHeaders: SecurityHeadersMiddleware<AppRequestContext>.Configuration,
+    siteOrigin: String?,
     logLevel: Logger.Level,
     probe: Probe
 ) -> Router<AppRequestContext> {
@@ -207,6 +213,7 @@ private func router(
     router.addController {
         RootController<AppRequestContext>(
             assetVersion: assetVersion,
+            siteOrigin: siteOrigin,
             analytics: analytics
         )
         HealthController<AppRequestContext>(
diff --git a/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift b/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
index 2b60080..7ce8886 100644
--- a/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
+++ b/Services/Website/Sources/Library/Internal/Extensions/Page+Defaults.swift
@@ -16,6 +16,14 @@ extension Page {
         []
     }
 
+    /// The territories paired with the site's languages, in Open Graph's `language_TERRITORY` form.
+    ///
+    /// English ships as `en_US`, Open Graph's conventional default. A site serving a language in a territory of its own repoints or extends the
+    /// map (`en_NL`, `nl_NL`, …); a language with no entry stays a bare code, which scrapers also accept.
+    static var ogLocales: [String: String] {
+        ["en": "en_US"]
+    }
+
     // MARK: Computed
 
     /// The document language, derived from the page's locale and falling back to the default language.
@@ -24,11 +32,65 @@ extension Page {
             ?? LanguageList().default
     }
 
+    /// The locale of the page's social card, in Open Graph's `language_TERRITORY` form where ``ogLocales`` pairs the page's language with a
+    /// territory; a language it does not name stays a bare code, which scrapers also accept.
+    ///
+    /// Keyed off ``lang``, so the card's locale and the document's `lang` attribute never describe the document differently. Nothing reads it
+    /// until a page supplies a `socialCard` — like ``preloadedFonts``, it is a hook a generated site fills in.
+    var ogLocale: String {
+        Self.ogLocales[lang] ?? lang
+    }
+
     /// The site-wide head metadata; a page that adds tags of its own composes ``siteMetadata`` rather than replacing it.
     var metadata: some HTML {
         siteMetadata
     }
 
+    /// The `hreflang` alternates tying the page's language editions together, or nothing without an origin — the annotations require absolute URLs.
+    ///
+    /// Nothing is emitted for a single-language site either: a set naming one edition tells a search engine nothing it cannot already see.
+    /// `x-default` points at the catalog's default language, whose bare URL negotiates the language and so is the right landing for everyone
+    /// unmatched — it stays the catalog's default even when `languages` names a subset.
+    /// - Parameters:
+    ///   - origin: the site's public origin, or `nil` to emit nothing.
+    ///   - path: the page's bare (default-language) path.
+    ///   - languages: the languages the page is published in; every catalog language by default. A page translated into only some of them
+    ///     narrows the set, so it never advertises an edition that does not exist.
+    /// - Returns: one `alternate` link per language, followed by the `x-default` link.
+    @HTMLBuilder
+    func languageAlternates(
+        origin: String?,
+        path: String,
+        languages: [Language] = Language.all
+    ) -> some HTML {
+        if let origin, languages.count > 1 {
+            ForEach(languages) { language in
+                link(
+                    .rel("alternate"),
+                    .custom(
+                        name: "hreflang",
+                        value: language.identifier
+                    ),
+                    .href(language.url(
+                        origin: origin,
+                        path: path
+                    ))
+                )
+            }
+            link(
+                .rel("alternate"),
+                .custom(
+                    name: "hreflang",
+                    value: "x-default"
+                ),
+                .href(Language.default.url(
+                    origin: origin,
+                    path: path
+                ))
+            )
+        }
+    }
+
     /// The ``preloadedFonts`` links, then the icon, manifest, and theme colour metadata shared by every page of the website.
     ///
     /// A preload URL must match the stylesheet's `@font-face` source exactly — unversioned, with `crossorigin` — or the browser fetches the
diff --git a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
index 920167c..ee61949 100644
--- a/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
+++ b/Services/Website/Sources/Library/Internal/Pages/IndexPage.swift
@@ -17,6 +17,9 @@ struct IndexPage {
     /// The locale the page content is localized to.
     let locale: Locale
 
+    /// The public origin the page derives its canonical URL and language alternates from, or `nil` to omit them.
+    let siteOrigin: String?
+
     /// Resolves the page's text from the bundled String Catalog for the page's ``locale``.
     private let localize: Localize
 
@@ -26,15 +29,18 @@ struct IndexPage {
     /// - Parameters:
     ///   - locale: the locale the page content is localized to.
     ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
+    ///   - siteOrigin: the public origin the page derives its canonical URL and language alternates from, or `nil` (the default) to omit them.
     ///   - analytics: the analytics tracker embedded in the document head, or `nil` (the default) to omit it.
     init(
         locale: Locale,
         assetVersion: String? = nil,
+        siteOrigin: String? = nil,
         analytics: Analytics? = nil
     ) {
         self.analytics = analytics
         self.assetVersion = assetVersion
         self.locale = locale
+        self.siteOrigin = siteOrigin
         self.localize = .init(bundle: .module)
     }
 
@@ -44,6 +50,36 @@ struct IndexPage {
 
 extension IndexPage: Page {
 
+    // MARK: Constants
+
+    /// The path the page is served at; ``RootController`` registers its route against it, and the page builds its canonical URL from it.
+    static let path = "/"
+
+    // MARK: Computed
+
+    /// The canonical URL of the page's edition in its language, or `nil` when the origin is unknown.
+    ///
+    /// The origin alone for the default language, since canonical URLs carry no trailing slash — `TrailingSlashRedirectMiddleware` enforces
+    /// that on every path but the root, which has nothing to strip.
+    var canonicalURL: String? {
+        siteOrigin.map {
+            Language(of: locale).url(
+                origin: $0,
+                path: Self.path
+            )
+        }
+    }
+
+    /// The site-wide metadata, preceded by the `hreflang` alternates tying the page's language editions together.
+    @HTMLBuilder
+    var metadata: some HTML {
+        languageAlternates(
+            origin: siteOrigin,
+            path: Self.path
+        )
+        siteMetadata
+    }
+
     // MARK: Properties
 
     var content: some HTML {
diff --git a/Services/Website/Sources/Library/Internal/Types/Language.swift b/Services/Website/Sources/Library/Internal/Types/Language.swift
new file mode 100644
index 0000000..079383a
--- /dev/null
+++ b/Services/Website/Sources/Library/Internal/Types/Language.swift
@@ -0,0 +1,100 @@
+import Foundation
+import Localization
+
+/// A language the website serves, as its String Catalog names it.
+///
+/// The catalog stays the single source of truth: a locale appears in ``all`` once it has a localization, with no code change. The default
+/// language owns the site's bare paths; every other language answers under a prefix of its own, so each edition has a stable URL a search
+/// engine can index and the pages' `hreflang` alternates have somewhere to point.
+struct Language: Hashable, Sendable {
+
+    // MARK: Properties
+
+    /// The language's identifier, as the String Catalog names it (e.g. `en`, `nl`).
+    let identifier: String
+
+    // MARK: Initializers
+
+    /// Creates the language with the given identifier, whether or not the catalog serves it.
+    ///
+    /// Unvalidated so the URL rules can be exercised — and a language pinned — without the catalog shipping that localization first.
+    /// - Parameter identifier: the language's identifier.
+    init(identifier: String) {
+        self.identifier = identifier
+    }
+
+    /// Creates the language a locale reads as, falling back to ``default`` for anything the catalog does not serve.
+    /// - Parameter locale: the locale a page is localized to.
+    init(of locale: Locale) {
+        guard
+            let identifier = locale.language.languageCode?.identifier,
+            Self.all.contains(Language(identifier: identifier))
+        else {
+            self = .default
+
+            return
+        }
+
+        self.identifier = identifier
+    }
+
+    // MARK: Computed
+
+    /// Whether the language owns the site's unprefixed paths.
+    var isDefault: Bool {
+        self == .default
+    }
+
+    /// The prefix of the language's URLs: empty for the default language, which owns the bare paths.
+    var pathPrefix: String {
+        isDefault ? "" : "/\(identifier)"
+    }
+
+    // MARK: Methods
+
+    /// The language's URL path for a page's bare path; the root collapses onto the prefix alone, so a Dutch home is `/nl`, not `/nl/`.
+    /// - Parameter barePath: the page's unprefixed path, as ``RootController`` registers it for the default language.
+    /// - Returns: the path this language's edition of the page is served at.
+    func path(_ barePath: String) -> String {
+        guard barePath == "/" else {
+            return pathPrefix + barePath
+        }
+
+        return pathPrefix.isEmpty ? barePath : pathPrefix
+    }
+
+    /// The absolute URL of the page's edition in this language; the default language's root stays the bare origin, keeping canonicals slashless.
+    /// - Parameters:
+    ///   - origin: the site's public origin, without a trailing slash.
+    ///   - barePath: the page's unprefixed path.
+    /// - Returns: the absolute URL this language's edition of the page is served at.
+    func url(
+        origin: String,
+        path barePath: String
+    ) -> String {
+        let path = path(barePath)
+
+        return path == "/" ? origin : origin + path
+    }
+
+}
+
+// MARK: - Catalog
+
+extension Language {
+
+    // MARK: Computed
+
+    /// Every language the module's String Catalog provides a localization for, in the catalog list's stable order.
+    static var all: [Language] {
+        LanguageList()
+            .all
+            .map(Language.init(identifier:))
+    }
+
+    /// The language served when no supported language matches a request: the catalog's source language.
+    static var `default`: Language {
+        .init(identifier: LanguageList().default)
+    }
+
+}
diff --git a/Services/Website/Sources/Library/Public/Controllers/RootController.swift b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
index 98b0559..c6dde33 100644
--- a/Services/Website/Sources/Library/Public/Controllers/RootController.swift
+++ b/Services/Website/Sources/Library/Public/Controllers/RootController.swift
@@ -25,15 +25,18 @@ public struct RootController<Context: LocalizedRequestContext> {
     /// Creates a root controller.
     /// - Parameters:
     ///   - assetVersion: the version token appended to the page's asset URLs, or `nil` (the default) to leave them unversioned.
+    ///   - siteOrigin: the public origin the page derives its canonical URL and language alternates from, or `nil` (the default) to omit them.
     ///   - analytics: the analytics tracker the landing page embeds, or `nil` (the default) to omit it.
     public init(
         assetVersion: String? = nil,
+        siteOrigin: String? = nil,
         analytics: Analytics? = nil
     ) {
         self.responses = .init(bundle: .module) {
             IndexPage(
                 locale: $0,
                 assetVersion: assetVersion,
+                siteOrigin: siteOrigin,
                 analytics: analytics
             )
         }
@@ -55,6 +58,15 @@ extension RootController: RouterController {
             use: index
         )
 
+        // Every non-default language answers under a prefix of its own, so the `hreflang` alternates the page advertises
+        // resolve and a crawler can index each edition at a stable URL. A single-language catalog adds none.
+        for language in Language.all where !language.isDefault {
+            routes.get(
+                .init(language.path(IndexPage.path)),
+                use: index(in: language)
+            )
+        }
+
         return routes
     }
 
@@ -84,6 +96,23 @@ private extension RootController {
         )
     }
 
+    /// Builds the handler serving the landing page in one fixed language, for the routes carrying the language in their path.
+    ///
+    /// The path *is* the language choice, so the negotiated context language is ignored: a prefixed URL answers in its language for every
+    /// visitor and every crawler alike, which is what lets a search engine index it as that edition.
+    /// - Parameter language: the language the route serves.
+    /// - Returns: the handler answering requests for that edition of the page.
+    func index(
+        in language: Language
+    ) -> @Sendable (Request, Context) -> Response {
+        { request, _ in
+            responses.response(
+                for: language.identifier,
+                request: request
+            )
+        }
+    }
+
 }
 
 // MARK: - Constants
@@ -91,7 +120,7 @@ private extension RootController {
 private extension RouterPath {
     /// A namespace for the ``RootController`` route paths.
     enum Root {
-        /// The path of the landing page.
-        static let index: RouterPath = "/"
+        /// The path of the landing page; the page builds its canonical URL from the same constant.
+        static let index: RouterPath = .init(IndexPage.path)
     }
 }
diff --git a/Services/Website/Tests/Library/Cases/Internal/Extensions/PageDefaultsTests.swift b/Services/Website/Tests/Library/Cases/Internal/Extensions/PageDefaultsTests.swift
new file mode 100644
index 0000000..bad8fb5
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Internal/Extensions/PageDefaultsTests.swift
@@ -0,0 +1,128 @@
+import Elementary
+import Foundation
+import Infrastructure
+import Testing
+
+@testable import WebsiteLibrary
+
+@Suite(
+    "Page+Defaults extension",
+    .tags(.extensionTests)
+)
+struct PageDefaultsTests {
+
+    // MARK: Computed tests
+
+    @Test
+    func `pairs english with a territory for its social card locale`() {
+        #expect(StubPage().ogLocale == "en_US")
+    }
+
+    /// Open Graph prefers `language_TERRITORY`, but a scraper accepts the bare code — better than pinning a territory the site never named.
+    @Test
+    func `leaves an unpaired language as a bare code`() {
+        #expect(StubPage(locale: .init(identifier: "nl")).ogLocale == "nl")
+    }
+
+    // MARK: Method tests
+
+    @Test
+    func `renders no language alternates without an origin`() {
+        let html = StubPage().languageAlternates(
+            origin: nil,
+            path: "/",
+            languages: Self.languages
+        ).render()
+
+        #expect(html.isEmpty)
+    }
+
+    @Test
+    func `renders no language alternates for a single language`() {
+        let html = StubPage().languageAlternates(
+            origin: "https://example.com",
+            path: "/",
+            languages: [.default]
+        ).render()
+
+        #expect(html.isEmpty)
+    }
+
+    /// The default language keeps the bare root; the prefixed edition collapses onto its prefix rather than carrying a trailing slash.
+    @Test
+    func `renders an alternate per language and an x-default at the root`() {
+        let html = StubPage().languageAlternates(
+            origin: "https://example.com",
+            path: "/",
+            languages: Self.languages
+        ).render()
+
+        #expect(html.contains(#"<link rel="alternate" hreflang="en" href="https://example.com">"#))
+        #expect(html.contains(#"<link rel="alternate" hreflang="nl" href="https://example.com/nl">"#))
+        #expect(html.contains(#"<link rel="alternate" hreflang="x-default" href="https://example.com">"#))
+    }
+
+    @Test
+    func `prefixes the alternates of a nested page`() {
+        let html = StubPage().languageAlternates(
+            origin: "https://example.com",
+            path: "/privacy",
+            languages: Self.languages
+        ).render()
+
+        #expect(html.contains(#"<link rel="alternate" hreflang="en" href="https://example.com/privacy">"#))
+        #expect(html.contains(#"<link rel="alternate" hreflang="nl" href="https://example.com/nl/privacy">"#))
+        #expect(html.contains(#"<link rel="alternate" hreflang="x-default" href="https://example.com/privacy">"#))
+    }
+
+}
+
+// MARK: - Helpers
+
+private extension PageDefaultsTests {
+
+    // MARK: Constants
+
+    /// A two-language set, standing in for the multi-language catalog the template itself does not ship.
+    static let languages: [Language] = [
+        .default,
+        .init(identifier: "nl")
+    ]
+
+    // MARK: Types
+
+    /// The barest ``Page`` conformance, so the shared defaults can be exercised without a real page's content.
+    struct StubPage: Page {
+
+        // MARK: Properties
+
+        let assetVersion: String? = nil
+        let locale: Locale
+
+        // MARK: Initializers
+
+        init(locale: Locale = .init(identifier: "en")) {
+            self.locale = locale
+        }
+
+        // MARK: Properties
+
+        var content: some HTML {
+            HTMLRaw("")
+        }
+
+        var scripts: [any Asset] {
+            []
+        }
+
+        var stylesheets: [any Asset] {
+            []
+        }
+
+        var title: String {
+            "Stub"
+        }
+
+    }
+
+}
diff --git a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
index 8f81109..5e49a81 100644
--- a/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
+++ b/Services/Website/Tests/Library/Cases/Internal/Pages/IndexPageTests.swift
@@ -39,6 +39,32 @@ struct IndexPageTests {
         #expect(!IndexPage(locale: .init(identifier: "en")).render().contains(#"rel="preload""#))
     }
 
+    @Test
+    func `renders no canonical URL until an origin is given`() {
+        #expect(!IndexPage(locale: .init(identifier: "en")).render().contains(#"rel="canonical""#))
+    }
+
+    @Test
+    func `renders the canonical URL as the bare origin for the default language`() {
+        // The root is the one path with no trailing slash for `TrailingSlashRedirectMiddleware` to strip.
+        let html = IndexPage(
+            locale: .init(identifier: "en"),
+            siteOrigin: "https://example.com"
+        ).render()
+
+        #expect(html.contains(#"<link rel="canonical" href="https://example.com">"#))
+    }
+
+    @Test
+    func `renders no language alternates for a single-language catalog`() {
+        // The template serves one language, so a set naming one edition would tell a crawler nothing.
+        #expect(Language.all.count == 1)
+        #expect(!IndexPage(
+            locale: .init(identifier: "en"),
+            siteOrigin: "https://example.com"
+        ).render().contains("hreflang"))
+    }
+
     @Test
     func `renders versioned asset URLs when given a version`() {
         let html = IndexPage(
diff --git a/Services/Website/Tests/Library/Cases/Internal/Types/LanguageTests.swift b/Services/Website/Tests/Library/Cases/Internal/Types/LanguageTests.swift
new file mode 100644
index 0000000..4453ab3
--- /dev/null
+++ b/Services/Website/Tests/Library/Cases/Internal/Types/LanguageTests.swift
@@ -0,0 +1,109 @@
+import Foundation
+import Testing
+
+@testable import WebsiteLibrary
+
+@Suite(
+    "Language type",
+    .tags(.type)
+)
+struct LanguageTests {
+
+    // MARK: Catalog tests
+
+    /// The template ships an English-only catalog, so a site adding a language sees this pin fail and reviews the URL rules below.
+    @Test
+    func `derives its languages from the String Catalog`() {
+        #expect(Language.all == [Language(identifier: "en")])
+        #expect(Language.default == Language(identifier: "en"))
+    }
+
+    // MARK: Initializer tests
+
+    @Test
+    func `reads the language a locale names`() {
+        #expect(Language(of: .init(identifier: "en")).identifier == "en")
+    }
+
+    @Test
+    func `reads a regional locale as its primary language`() {
+        #expect(Language(of: .init(identifier: "en_GB")).identifier == "en")
+    }
+
+    @Test
+    func `falls back to the default for a language the catalog does not serve`() {
+        #expect(Language(of: .init(identifier: "fr")) == .default)
+    }
+
+    // MARK: Computed tests
+
+    @Test
+    func `owns the bare paths as the default language`() {
+        let language = Language.default
+
+        #expect(language.isDefault)
+        #expect(language.pathPrefix.isEmpty)
+    }
+
+    @Test
+    func `prefixes its paths as a non-default language`() {
+        let language = Language(identifier: "nl")
+
+        #expect(!language.isDefault)
+        #expect(language.pathPrefix == "/nl")
+    }
+
+    // MARK: Method tests
+
+    @Test(arguments: zip(
+        ["/", "/privacy"],
+        ["/", "/privacy"]
+    ))
+    func `path`(
+        forDefaultLanguageAt barePath: String,
+        expects path: String
+    ) {
+        #expect(Language.default.path(barePath) == path)
+    }
+
+    /// The root collapses onto the prefix alone: a trailing slash is the very spelling `TrailingSlashRedirectMiddleware` redirects away from.
+    @Test(arguments: zip(
+        ["/", "/privacy"],
+        ["/nl", "/nl/privacy"]
+    ))
+    func `path`(
+        forPrefixedLanguageAt barePath: String,
+        expects path: String
+    ) {
+        #expect(Language(identifier: "nl").path(barePath) == path)
+    }
+
+    @Test(arguments: zip(
+        ["/", "/privacy"],
+        ["https://example.com", "https://example.com/privacy"]
+    ))
+    func `url`(
+        forDefaultLanguageAt barePath: String,
+        expects url: String
+    ) {
+        #expect(Language.default.url(
+            origin: "https://example.com",
+            path: barePath
+        ) == url)
+    }
+
+    @Test(arguments: zip(
+        ["/", "/privacy"],
+        ["https://example.com/nl", "https://example.com/nl/privacy"]
+    ))
+    func `url`(
+        forPrefixedLanguageAt barePath: String,
+        expects url: String
+    ) {
+        #expect(Language(identifier: "nl").url(
+            origin: "https://example.com",
+            path: barePath
+        ) == url)
+    }
+
+}
diff --git a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
index 1d0752f..a07cc2d 100644
--- a/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
+++ b/Services/Website/Tests/Library/Cases/Public/Controllers/RootControllerTests.swift
@@ -131,6 +131,37 @@ struct RootControllerTests {
         }
     }
 
+    @Test
+    func `serves the landing page with a canonical URL when an origin is configured`() async throws {
+        try await app(
+            siteOrigin: "https://example.com"
+        ).test(.router) { client in
+            try await client.execute(
+                uri: "/",
+                method: .get
+            ) { response in
+                #expect(String(buffer: response.body).contains(#"<link rel="canonical" href="https://example.com">"#))
+            }
+        }
+    }
+
+    /// The template's catalog serves one language, so the default owns every path and no prefixed route is registered.
+    @Test
+    func `registers no prefixed route for a single-language catalog`() async throws {
+        let prefixed = Language.all.filter { !$0.isDefault }
+
+        #expect(prefixed.isEmpty)
+
+        try await app.test(.router) { client in
+            try await client.execute(
+                uri: "/en",
+                method: .get
+            ) { response in
+                #expect(response.status == .notFound)
+            }
+        }
+    }
+
     @Test
     func `embeds no analytics tracker by default`() async throws {
         try await app.test(.router) { client in
@@ -176,13 +207,15 @@ private extension RootControllerTests {
     // MARK: Methods
 
     /// Builds an application whose root controller appends the given version token to the landing
-    /// page's asset URLs and embeds the given analytics tracker.
+    /// page's asset URLs, derives its absolute links from the given origin, and embeds the given analytics tracker.
     /// - Parameters:
     ///   - assetVersion: the version token appended to the page's asset URLs.
+    ///   - siteOrigin: the public origin the page derives its canonical URL and language alternates from, or `nil` (the default) to omit them.
     ///   - analytics: the analytics tracker the landing page embeds, or `nil` (the default) to omit it.
     /// - Returns: the configured application.
     func app(
         assetVersion: String? = nil,
+        siteOrigin: String? = nil,
         analytics: Analytics? = nil
     ) -> some ApplicationProtocol {
         let router = Router(context: WebsiteRequestContext.self)
@@ -193,6 +226,7 @@ private extension RootControllerTests {
 
         router.addRoutes(RootController<WebsiteRequestContext>(
             assetVersion: assetVersion,
+            siteOrigin: siteOrigin,
             analytics: analytics
         ).routes)
 
diff --git a/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift b/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
index 7fe73f7..bccc43a 100644
--- a/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
+++ b/Services/Website/Tests/Library/Utils/Extensions/Tag+Constants.swift
@@ -5,6 +5,8 @@ extension Tag {
     @Tag static var controller: Tag
     /// Tests exercising an enumeration of the Website library.
     @Tag static var enumeration: Tag
+    /// Tests exercising an extension of the Website library.
+    @Tag static var extensionTests: Tag
     /// Tests exercising a page of the Website library.
     @Tag static var page: Tag
     /// Tests exercising a type of the Website library.
-- 
2.54.0


From daf764f10f6a5d3a3a5495970f7e9605ea4ff19d Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 22:01:47 +0200
Subject: [PATCH 109/117] Fixed the sitemap for the Website service target.

---
 Services/Website/README.md                    | 2 ++
 Services/Website/Resources/Static/sitemap.xml | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/Services/Website/README.md b/Services/Website/README.md
index 57c1076..d0f016a 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -85,6 +85,8 @@ The catalog's source language is the **default** and owns the site's bare paths;
 
 Given a `site.origin`, each page then emits the `hreflang` alternates tying its editions together — one per language plus an `x-default` pointing at the default language's edition, whose bare URL negotiates the language and so is the right landing for everyone unmatched. A single-language site emits none: a set naming one edition tells a search engine nothing it cannot already see. `Page+Defaults`' `languageAlternates(origin:path:languages:)` takes the language set, so a page translated into only some of them narrows it rather than advertising an edition that does not exist.
 
+`sitemap.xml` is the one part that does *not* follow the catalog: it is a static file, so a new language needs its editions added by hand — `/nl`, `/nl/<page>`, one `<loc>` each, alongside the default language's. Give each the same spelling the page's own canonical carries (the root is the bare origin, with no trailing slash), or the two disagree about which URL is canonical.
+
 Visitors switch language two ways, both handled by `LocalizationMiddleware` ahead of the routes: a `?lang=` query parameter (what a language switcher links to) and the leading path segment. Either beats `Accept-Language`; a value naming no supported language is ignored. The path segment matters beyond the routed pages — it is what makes an *unrouted* path under a language's prefix answer its not-found page in that language.
 
 ## Configuration
diff --git a/Services/Website/Resources/Static/sitemap.xml b/Services/Website/Resources/Static/sitemap.xml
index 01242ae..af88bb0 100644
--- a/Services/Website/Resources/Static/sitemap.xml
+++ b/Services/Website/Resources/Static/sitemap.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
-    <loc>https://site.example.com/</loc>
+    <loc>https://site.example.com</loc>
   </url>
 </urlset>
-- 
2.54.0


From 277045c1a1efcb1dd9c6d3c94ea067650b321614 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sun, 30 Aug 2026 23:01:48 +0200
Subject: [PATCH 110/117] Set the canonical site origin in the Website library
 target.

The template's new `site.origin` key arrived empty, as bootstrap fills it in.
Pointing it at the origin robots.txt and sitemap.xml already carry turns on the
canonical and hreflang links, and the HTTPS redirect the production compose
already trusts the forwarded proto for.
---
 .../Sources/Library/Public/Extensions/String+Constants.swift    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
index d02a3fc..2ec035c 100644
--- a/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
+++ b/Services/Website/Sources/Library/Public/Extensions/String+Constants.swift
@@ -61,6 +61,6 @@ extension String {
         /// Bootstrap writes the canonical URL it prompts for here, leaving it empty for the placeholder. An empty or non-HTTPS origin disables
         /// the HTTPS redirect, which `https.trustForwardedProto` must enable besides — a `301` is cached for a long time, so it is never issued
         /// at a host nobody named.
-        public static let origin = ""
+        public static let origin = "https://ccn.rock-n-co.de"
     }
 }
-- 
2.54.0


From c8100fd93cac80b646eb7f2e3ad5d027747b4d70 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 4 Sep 2026 14:29:05 +0200
Subject: [PATCH 111/117] Pinned git to HTTP/1.1 for the Dockerfile in the
 Website service target to keep the packages on a transport Github handles
 correctly.

---
 Services/Website/Dockerfile | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Services/Website/Dockerfile b/Services/Website/Dockerfile
index df4967d..c4bea90 100644
--- a/Services/Website/Dockerfile
+++ b/Services/Website/Dockerfile
@@ -39,6 +39,10 @@ RUN export DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true \
     && apt-get install -y libjemalloc-dev \
     && rm -rf /var/lib/apt/lists/*
 
+# Pin git to HTTP/1.1 for the dependency clones. GitHub answers the git-upload-pack POST with a 401 when it is sent
+# over HTTP/2 by the git 2.43 that Noble ships, which SPM reports as a clone failure asking for a username.
+RUN git config --global http.version HTTP/1.1
+
 # Set up a build area
 WORKDIR /build
 
-- 
2.54.0


From f0086ee4616087357a09c8277d1018bdb3871189 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 31 Aug 2026 23:01:02 +0200
Subject: [PATCH 112/117] Added the alternate locales to the Social Card in the
 Infrastructure package.

---
 .../Sources/Public/Types/SocialCard.swift            | 12 +++++++++---
 .../Public/Types/SocialCard/SocialCardTag.swift      |  1 +
 .../Tests/Cases/Public/Types/SocialCardTests.swift   |  3 +++
 3 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
index 0fe4a74..e8a8d3d 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard.swift
@@ -7,6 +7,9 @@ public struct SocialCard: Sendable {
 
     // MARK: Properties
 
+    /// The locales of the card's other language editions, in Open Graph's `language_TERRITORY` form; empty to omit their tags.
+    public let alternateLocales: [String]
+
     /// The card's share image, or `nil` to omit its tags.
     public let image: Image?
 
@@ -43,6 +46,7 @@ public struct SocialCard: Sendable {
     ///   - siteName: the name of the site the card belongs to, or `nil` (the default) to omit its tag.
     ///   - locale: the locale of the card's text, ideally in Open Graph's `language_TERRITORY` form (e.g. `en_US`), or `nil` (the default)
     ///     to omit its tag.
+    ///   - alternateLocales: the locales the card's page is also published in, in the same form; empty (the default) to omit their tags.
     ///   - image: the card's share image, or `nil` (the default) to omit its tags.
     ///   - type: the Open Graph type of the object the card describes. Defaults to `website`.
     ///   - style: the layout a Twitter card scraper gives the card. Defaults to ``Style/summaryLargeImage``.
@@ -52,10 +56,12 @@ public struct SocialCard: Sendable {
         url: String? = nil,
         siteName: String? = nil,
         locale: String? = nil,
+        alternateLocales: [String] = [],
         image: Image? = nil,
         type: String = "website",
         style: Style = .summaryLargeImage
     ) {
+        self.alternateLocales = alternateLocales
         self.image = image
         self.locale = locale
         self.siteName = siteName
@@ -68,8 +74,8 @@ public struct SocialCard: Sendable {
 
     // MARK: Computed
 
-    /// The card's meta tags, in a stable order: the Open Graph type, site name, title, description, URL, and locale, then the image group, and
-    /// the Twitter card style last. A tag whose fact the card does not carry is left out.
+    /// The card's meta tags, in a stable order: the Open Graph type, site name, title, description, URL, locale, and alternate locales, then the
+    /// image group, and the Twitter card style last. A tag whose fact the card does not carry is left out.
     public var tags: [Tag] {
         let tags: [Tag?] = [
             Tag(type, name: .type),
@@ -78,7 +84,7 @@ public struct SocialCard: Sendable {
             summary.map { Tag($0, name: .description) },
             url.map { Tag($0, name: .url) },
             locale.map { Tag($0, name: .locale) },
-        ] + (image?.tags ?? []) + [
+        ] + alternateLocales.map { Tag($0, name: .localeAlternate) } + (image?.tags ?? []) + [
             Tag(style.rawValue, name: .twitter),
         ]
 
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
index ec446a5..1924635 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
@@ -60,6 +60,7 @@ extension SocialCard.Tag {
         case imageWidth = "og:image:width"
         /// The `og:locale` tag, carrying the locale of the card's text.
         case locale = "og:locale"
+        case localeAlternate = "og:locale:alternate"
         /// The `og:site_name` tag, carrying the name of the site the card belongs to.
         case siteName = "og:site_name"
         /// The `og:title` tag, carrying the card's title.
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
index 6849302..a1c2a1e 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/SocialCardTests.swift
@@ -18,6 +18,7 @@ struct SocialCardTests {
             url: "https://site.example/",
             siteName: "A Site",
             locale: "en",
+            alternateLocales: ["nl_NL", "de_DE"],
             image: .init(
                 url: "https://site.example/img/card.png",
                 width: 2400,
@@ -33,6 +34,8 @@ struct SocialCardTests {
             .init("A summary.", name: .description),
             .init("https://site.example/", name: .url),
             .init("en", name: .locale),
+            .init("nl_NL", name: .localeAlternate),
+            .init("de_DE", name: .localeAlternate),
             .init("https://site.example/img/card.png", name: .image),
             .init("2400", name: .imageWidth),
             .init("1260", name: .imageHeight),
-- 
2.54.0


From 0b3ef2890ecabc89bf81f7a53198a2c027724070 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 31 Aug 2026 21:56:09 +0200
Subject: [PATCH 113/117] Updated the Localized HTML Collection response in the
 Infrastructure package to make `Vary: Accept-Language` opt-in for localized
 responses.

---
 Packages/Infrastructure/README.md             |  4 ++--
 .../Middlewares/LocalizationMiddleware.swift  |  8 ++++---
 .../Middlewares/NotFoundMiddleware.swift      |  4 ++++
 .../LocalizedHTMLCollectionResponse.swift     | 22 ++++++++++++++-----
 4 files changed, 27 insertions(+), 11 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 8fd2d8d..1fd1a04 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -10,13 +10,13 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Link previews | `SocialCard`, its `Image` and `Style`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, the open `Name` and `Kind` vocabularies, and the site-wide initializer building the `Organization`/`WebSite` pair |
 | Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to a tag), the tracker script `Attribute`s it derives, the optional session `recorder` script paired with it, and the `origin` its preconnect hint targets |
-| Responses | `CachedHTMLResponse`, `LocalizedHTMLCollectionResponse` |
+| Responses | `CachedHTMLResponse`, and `LocalizedHTMLCollectionResponse` rendering one of them per catalog language |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
 
 ## Design rules
 The package holds only what every service can reuse. Anything a service owns is injected, never referenced.
-- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. What a type needs, it takes as a parameter: the `bundle:` whose String Catalog names the supported languages, the `document:` closure that builds a page for a locale, a `Page` conformer's `metadata` and its optional head concerns (`summary`, `canonicalURL`, `socialCard`, `structuredData`, `analytics`). URLs arrive absolute and fully formed — composing them stays with the page.
+- **No site-specific content.** No page markup, no asset catalog, no `Bundle.module` lookups. What a type needs, it takes as a parameter: the `bundle:` whose String Catalog names the supported languages, the `document:` closure that builds a page for a locale, a `Page` conformer's `metadata` and its optional head concerns (`summary`, `canonicalURL`, `socialCard`, `structuredData`, `analytics`). URLs arrive absolute and fully formed — composing them stays with the page. The same holds for request semantics: only the caller knows whether it negotiates the language or pins it by route, so `variesOnAcceptLanguage:` declares whether the responses carry `Vary: Accept-Language`.
 - **Types own their format; `Page` renders generically.** Each head concern derives its own render-ready form — `SocialCard.tags`, `StructuredData.payload`, `Analytics.attributes` — which `Page` applies without knowing the vocabulary. A page's `scripts` and the tracker render as `defer`red head tags, the tracker preceded by a `preconnect` to its cross-origin host.
 - **Nodes are joined by `@id`, not repetition.** A node another page must point at gets its identifier from a helper rather than a hand-spelled fragment — `organizationID(forSiteURL:)` names the node the site-wide initializer builds, and that initializer's `founder` takes such an identifier back. A service adds the helper for any node it owns, so neither side can drift.
 - **Services fill the gaps once, via extensions.** A service restores its convenient call sites retroactively — the Website's `*+Defaults` are the pattern. The open schema.org vocabularies work the same way: the package declares the shared `Property.Name` and `Node.Kind` constants, a service adds its own.
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
index c7adec7..f8bb021 100644
--- a/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/LocalizationMiddleware.swift
@@ -9,9 +9,11 @@ import Localization
 /// `Accept-Language` header, negotiates the best supported match (falling back to the default language), and stores it on the context's
 /// ``LocalizedRequestContext/language``.
 ///
-/// The query parameter is the deliberate override a language switcher links to; failing that, a leading path segment naming a supported language
-/// pins it, so an unrouted path under a language's prefix — its not-found page — answers in that language. Values naming no supported language
-/// are ignored, leaving the header. The request is passed through untouched — the path and routing are unaffected.
+/// The query parameter is a deliberate override; failing that, a leading path segment naming a supported language pins it, so an unrouted path under
+/// a language's prefix — its not-found page — answers in that language. Values naming no supported language are ignored, leaving the header. The
+/// request is passed through untouched — the path and routing are unaffected.
+///
+/// A site whose page routes pin their language by URL consults this only for responses that belong to no URL — in practice, its not-found page.
 public struct LocalizationMiddleware<Context: LocalizedRequestContext> {
 
     // MARK: Properties
diff --git a/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift b/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift
index b5f51e6..e1ba556 100644
--- a/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift
+++ b/Packages/Infrastructure/Sources/Public/Middlewares/NotFoundMiddleware.swift
@@ -7,6 +7,9 @@ import Hummingbird
 /// Placed ahead of `FileMiddleware` in the middleware chain, it catches the `.notFound` error that bubbles up when no file exists for the requested
 /// path and responds with the rendered error page and a `404 Not Found` status. The page is served in the language stored on the context by
 /// ``LocalizationMiddleware``, falling back to the default language.
+///
+/// Its responses declare `Vary: Accept-Language`: where the page routes pin their language by URL, this is the one responder that negotiates.
+/// An unrouted path names no edition, so no canonical URL contradicts the header.
 public struct NotFoundMiddleware<Context: LocalizedRequestContext> {
 
     // MARK: Properties
@@ -27,6 +30,7 @@ public struct NotFoundMiddleware<Context: LocalizedRequestContext> {
         self.responses = .init(
             bundle: bundle,
             status: .notFound,
+            variesOnAcceptLanguage: true,
             document: document
         )
     }
diff --git a/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift b/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
index b497105..9a635c8 100644
--- a/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
+++ b/Packages/Infrastructure/Sources/Public/Responses/LocalizedHTMLCollectionResponse.swift
@@ -7,8 +7,12 @@ import Localization
 /// A per-language collection of pre-rendered HTML responses.
 ///
 /// At initialization it renders the document once for each language the bundle's ``LanguageList`` reports and caches the bytes, mirroring
-/// ``CachedHTMLResponse``'s render-once model but keyed by language. Each cached response carries a `Content-Language` header and
-/// `Vary: Accept-Language`, so shared caches key on the negotiated language instead of serving one language to everyone.
+/// ``CachedHTMLResponse``'s render-once model but keyed by language. Each cached response carries a `Content-Language` header naming the
+/// language it was rendered in.
+///
+/// `Vary: Accept-Language` is the caller's to declare, since only the caller knows how it picks the language: a responder that negotiates the
+/// header sets it, so shared caches key on the language rather than serving one to everyone; a responder that pins the language by route does
+/// not, since the header would announce a negotiation that never happens.
 public struct LocalizedHTMLCollectionResponse: Sendable {
 
     // MARK: Properties
@@ -25,21 +29,27 @@ public struct LocalizedHTMLCollectionResponse: Sendable {
     /// - Parameters:
     ///   - bundle: the bundle whose String Catalog names the languages the document is rendered for.
     ///   - status: the status applied to every response. Defaults to `.ok`.
+    ///   - variesOnAcceptLanguage: whether the responses declare `Vary: Accept-Language`. Defaults to `false`; a responder that
+    ///     negotiates the header passes `true`.
     ///   - document: builds the document to render for a given locale.
     public init<Document: HTMLDocument>(
         bundle: Bundle,
         status: HTTPResponse.Status = .ok,
+        variesOnAcceptLanguage: Bool = false,
         document: (Locale) -> Document
     ) {
         self.list = .init(bundle: bundle)
         self.responses = list.all
             .reduce(into: [:]) { responses, language in
+                var headers: HTTPFields = [.contentLanguage: language]
+
+                if variesOnAcceptLanguage {
+                    headers[.vary] = "Accept-Language"
+                }
+
                 responses[language] = CachedHTMLResponse(
                     status: status,
-                    additionalHeaders: [
-                        .contentLanguage: language,
-                        .vary: "Accept-Language",
-                    ],
+                    additionalHeaders: headers,
                     document: document(.init(
                         identifier: language
                     ))
-- 
2.54.0


From a9a62e10df3f790bb606fb0d15af1d5ffbc2049c Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Mon, 31 Aug 2026 23:36:03 +0200
Subject: [PATCH 114/117] Added the site languages to the Structured Data in
 the Infrastructure package.

---
 .../Sources/Public/Types/StructuredData.swift | 21 ++++++++++++++-----
 .../StructuredDataProperty.swift              |  2 ++
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
index 38d0acd..8ffb15b 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData.swift
@@ -65,6 +65,7 @@ public extension StructuredData {
     ///   - areaServed: the area the organization serves, or `nil` (the default) to omit its property.
     ///   - email: the address the organization is written to, or `nil` (the default) to omit its property.
     ///   - logo: the absolute URL of the organization's logo, or `nil` (the default) to omit its property.
+    ///   - inLanguage: the language codes the site is published in; empty (the default) to omit the property.
     ///   - profiles: the absolute URLs of the organization's public profiles, or empty (the default) to omit their property.
     ///   - founder: the `@id` of the `Person` node founding the organization, or `nil` (the default) to omit its property.
     init(
@@ -75,6 +76,7 @@ public extension StructuredData {
         areaServed: String? = nil,
         email: String? = nil,
         logo: String? = nil,
+        inLanguage: [String] = [],
         profiles: [String] = [],
         founder: String? = nil
     ) {
@@ -116,6 +118,19 @@ public extension StructuredData {
             organization.append(.init(.founder, value: .reference(founder)))
         }
 
+        var website: [Property] = [
+            .init(.name, value: .string(name)),
+            .init(.url, value: .string(url)),
+            .init(.publisher, value: .reference(id)),
+        ]
+
+        if !inLanguage.isEmpty {
+            website.append(.init(
+                .inLanguage,
+                value: .array(inLanguage.map(Value.string))
+            ))
+        }
+
         self.init(nodes: [
             .init(
                 type: .organization,
@@ -124,11 +139,7 @@ public extension StructuredData {
             ),
             .init(
                 type: .website,
-                properties: [
-                    .init(.name, value: .string(name)),
-                    .init(.url, value: .string(url)),
-                    .init(.publisher, value: .reference(id)),
-                ]
+                properties: website
             ),
         ])
     }
diff --git a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
index b311bdb..6ef5c1d 100644
--- a/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/StructuredData/StructuredDataProperty.swift
@@ -79,6 +79,8 @@ public extension StructuredData.Property.Name {
     static let email: Self = "email"
     /// The person who founded an organization.
     static let founder: Self = "founder"
+    /// The language a creative work — a site, a page — is published in.
+    static let inLanguage: Self = "inLanguage"
     /// The absolute URL of an organization's logo.
     static let logo: Self = "logo"
     /// The name of the thing a node describes.
-- 
2.54.0


From a71edd37ab5ddf85636d7959e4650bc19bac1057 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 4 Sep 2026 14:57:29 +0200
Subject: [PATCH 115/117] Updated the event tagging for the
 AnalyticsEvent+Tagging extension in the Infrastructure package to support
 attribute-capable tags.

---
 .../Public/Extensions/AnalyticsEvent+Tagging.swift     |  2 +-
 .../Public/Extensions/AnalyticsEventTaggingTests.swift | 10 ++++++++++
 .../Tests/Cases/Public/Types/StructuredDataTests.swift |  3 ++-
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/Packages/Infrastructure/Sources/Public/Extensions/AnalyticsEvent+Tagging.swift b/Packages/Infrastructure/Sources/Public/Extensions/AnalyticsEvent+Tagging.swift
index 2605648..8207a05 100644
--- a/Packages/Infrastructure/Sources/Public/Extensions/AnalyticsEvent+Tagging.swift
+++ b/Packages/Infrastructure/Sources/Public/Extensions/AnalyticsEvent+Tagging.swift
@@ -12,7 +12,7 @@ public extension Analytics.Event {
     /// ```
     ///
     /// - Returns: one HTML attribute per event attribute, applied verbatim.
-    func tagging<Tag: HTMLTrait.Attributes.Global>() -> [HTMLAttribute<Tag>] {
+    func tagging<Tag: MarkupTagDefinition & MarkupTrait.AllowsAttributes>() -> [HTMLAttribute<Tag>] {
         attributes.map {
             .custom(
                 name: $0.name,
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Extensions/AnalyticsEventTaggingTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Extensions/AnalyticsEventTaggingTests.swift
index 174225c..3501bb1 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Extensions/AnalyticsEventTaggingTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Extensions/AnalyticsEventTaggingTests.swift
@@ -46,4 +46,14 @@ struct AnalyticsEventTaggingTests {
         #expect(attributes.count == event.attributes.count)
     }
 
+    @Test
+    func `applies the event name to an SVG tag`() {
+        // `SVGTag.path` is no `HTMLTrait.Attributes.Global`, so this stops compiling if the method narrows back to HTML tags.
+        let rendered = SVG.path {}
+            .attributes(contentsOf: Analytics.Event(name: "logo").tagging())
+            .render()
+
+        #expect(rendered.contains(#"data-umami-event="logo""#))
+    }
+
 }
diff --git a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
index c2a8603..f7eac81 100644
--- a/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
+++ b/Packages/Infrastructure/Tests/Cases/Public/Types/StructuredDataTests.swift
@@ -17,6 +17,7 @@ struct StructuredDataTests {
             name: "A Site",
             url: "https://site.example/",
             logo: "https://site.example/logo.png",
+            inLanguage: ["en", "nl"],
             profiles: [
                 "https://social.example/a-site",
                 "https://videos.example/a-site",
@@ -26,7 +27,7 @@ struct StructuredDataTests {
         #expect(data.payload == #"{"@context":"https://schema.org","@graph":["# +
             #"{"@type":"Organization","@id":"https://site.example/#organization","name":"A Site","url":"https://site.example/","logo":"https://site.example/logo.png","# +
             #""sameAs":["https://social.example/a-site","https://videos.example/a-site"]},"# +
-            #"{"@type":"WebSite","name":"A Site","url":"https://site.example/","publisher":{"@id":"https://site.example/#organization"}}]}"#
+            #"{"@type":"WebSite","name":"A Site","url":"https://site.example/","publisher":{"@id":"https://site.example/#organization"},"inLanguage":["en","nl"]}]}"#
         )
     }
 
-- 
2.54.0


From 779bdd542a4a445b3c078fb13cb13d0d0d052dec Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 4 Sep 2026 15:01:21 +0200
Subject: [PATCH 116/117] Updated the READMEs to cover site languages and event
 tagging.

---
 Packages/Infrastructure/README.md | 2 +-
 Services/Website/README.md        | 4 +++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index 1fd1a04..ae93c77 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -9,7 +9,7 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
 | Link previews | `SocialCard`, its `Image` and `Style`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, the open `Name` and `Kind` vocabularies, and the site-wide initializer building the `Organization`/`WebSite` pair |
-| Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to a tag), the tracker script `Attribute`s it derives, the optional session `recorder` script paired with it, and the `origin` its preconnect hint targets |
+| Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to any attribute-bearing HTML or SVG tag), the tracker script `Attribute`s it derives, the optional session `recorder` script paired with it, and the `origin` its preconnect hint targets |
 | Responses | `CachedHTMLResponse`, and `LocalizedHTMLCollectionResponse` rendering one of them per catalog language |
 | Contexts | `LocalizedRequestContext` |
 | Constants | The `HTTPField.Name` header names, `Int.RateLimit` limits, and `String.Security` header values the middlewares default to |
diff --git a/Services/Website/README.md b/Services/Website/README.md
index d0f016a..e00147c 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -61,7 +61,7 @@ Four of those are page-authored and optional. `IndexPage` supplies `canonicalURL
 | `summary` | `<meta name="description">` | The page's one-line description. |
 | `canonicalURL` | `<link rel="canonical">` | Absolute URL. `IndexPage` derives it from `site.origin` and the page's own language; an unset origin omits it (see [Language editions](#language-editions)). |
 | `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, share image. Scrapers require absolute URLs, so the page composes them from its own origin; `Page+Defaults` supplies the locale as `ogLocale`. |
-| `structuredData` | `<script type="application/ld+json">` | A `StructuredData` graph of schema.org nodes; `StructuredData(name:url:logo:profiles:)` builds the site-wide `Organization` + `WebSite` pair. The payload is an inert data block, so the `Content-Security-Policy` does not apply to it. |
+| `structuredData` | `<script type="application/ld+json">` | A `StructuredData` graph of schema.org nodes; `StructuredData(name:url:logo:inLanguage:profiles:)` builds the site-wide `Organization` + `WebSite` pair, `inLanguage` declaring the languages the site publishes in (see [Language editions](#language-editions)). The payload is an inert data block, so the `Content-Security-Policy` does not apply to it. |
 
 The fifth, `analytics`, is *configuration*-authored rather than page-authored: the executable builds an `Analytics` from the `analytics.*` keys and hands it to `RootController` and `NotFoundMiddleware`, which pass it to both pages. It renders as a `<link rel="preconnect">` plus a deferred `<script>` carrying the [Umami](https://umami.is) `data-` attributes, and — unlike the structured data — it *is* executable, so the `Content-Security-Policy` must allow its origin. It is empty by default; see [Analytics](#analytics) for how to turn it on.
 
@@ -85,6 +85,8 @@ The catalog's source language is the **default** and owns the site's bare paths;
 
 Given a `site.origin`, each page then emits the `hreflang` alternates tying its editions together — one per language plus an `x-default` pointing at the default language's edition, whose bare URL negotiates the language and so is the right landing for everyone unmatched. A single-language site emits none: a set naming one edition tells a search engine nothing it cannot already see. `Page+Defaults`' `languageAlternates(origin:path:languages:)` takes the language set, so a page translated into only some of them narrows it rather than advertising an edition that does not exist.
 
+The same set belongs in the site-wide structured data: `StructuredData`'s `inLanguage` declares it on the `WebSite` node, so a crawler reads the site's languages from the graph as well as from the alternates.
+
 `sitemap.xml` is the one part that does *not* follow the catalog: it is a static file, so a new language needs its editions added by hand — `/nl`, `/nl/<page>`, one `<loc>` each, alongside the default language's. Give each the same spelling the page's own canonical carries (the root is the bare origin, with no trailing slash), or the two disagree about which URL is canonical.
 
 Visitors switch language two ways, both handled by `LocalizationMiddleware` ahead of the routes: a `?lang=` query parameter (what a language switcher links to) and the leading path segment. Either beats `Accept-Language`; a value naming no supported language is ignored. The path segment matters beyond the routed pages — it is what makes an *unrouted* path under a language's prefix answer its not-found page in that language.
-- 
2.54.0


From b2bfb734c6afeffc6ccd898a705abb391c8a4d90 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Fri, 4 Sep 2026 15:13:29 +0200
Subject: [PATCH 117/117] Documented the alternate locales of the Social Card
 in the Infrastructure package.

---
 Packages/Infrastructure/README.md                             | 2 +-
 .../Sources/Public/Types/SocialCard/SocialCardTag.swift       | 1 +
 Services/Website/README.md                                    | 4 ++--
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Packages/Infrastructure/README.md b/Packages/Infrastructure/README.md
index ae93c77..9571378 100644
--- a/Packages/Infrastructure/README.md
+++ b/Packages/Infrastructure/README.md
@@ -7,7 +7,7 @@ The shared [Hummingbird](https://github.com/hummingbird-project/hummingbird) too
 | Routing | `RouterController`, `RouteCollectionBuilder`, the `addController` extension on `RouterMethods` |
 | Middlewares | `SecurityHeadersMiddleware`, `HTTPSRedirectMiddleware`, `TrailingSlashRedirectMiddleware`, `VaryMiddleware`, `RateLimitMiddleware`, `LocalizationMiddleware` (negotiating from a `lang` query parameter, then a leading path segment, then `Accept-Language`), `NotFoundMiddleware` |
 | Pages and assets | `Page`, `Asset`, `AssetExtension`, `FingerprintAssets` |
-| Link previews | `SocialCard`, its `Image` and `Style`, and the `Tag` meta tags it derives |
+| Link previews | `SocialCard`, its `locale` and the `alternateLocales` of its other language editions, its `Image` and `Style`, and the `Tag` meta tags it derives |
 | Structured data | `StructuredData`, the `Node`, `Property`, and `Value` types of its schema.org graph, the open `Name` and `Kind` vocabularies, and the site-wide initializer building the `Organization`/`WebSite` pair |
 | Analytics | `Analytics`, the `Event`s a page reports (with `tagging()` to apply one to any attribute-bearing HTML or SVG tag), the tracker script `Attribute`s it derives, the optional session `recorder` script paired with it, and the `origin` its preconnect hint targets |
 | Responses | `CachedHTMLResponse`, and `LocalizedHTMLCollectionResponse` rendering one of them per catalog language |
diff --git a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
index 1924635..d286881 100644
--- a/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
+++ b/Packages/Infrastructure/Sources/Public/Types/SocialCard/SocialCardTag.swift
@@ -60,6 +60,7 @@ extension SocialCard.Tag {
         case imageWidth = "og:image:width"
         /// The `og:locale` tag, carrying the locale of the card's text.
         case locale = "og:locale"
+        /// The `og:locale:alternate` tag, carrying the locale of one other language edition of the card's page; repeated once per edition.
         case localeAlternate = "og:locale:alternate"
         /// The `og:site_name` tag, carrying the name of the site the card belongs to.
         case siteName = "og:site_name"
diff --git a/Services/Website/README.md b/Services/Website/README.md
index e00147c..08c6709 100644
--- a/Services/Website/README.md
+++ b/Services/Website/README.md
@@ -60,7 +60,7 @@ Four of those are page-authored and optional. `IndexPage` supplies `canonicalURL
 | --- | --- | --- |
 | `summary` | `<meta name="description">` | The page's one-line description. |
 | `canonicalURL` | `<link rel="canonical">` | Absolute URL. `IndexPage` derives it from `site.origin` and the page's own language; an unset origin omits it (see [Language editions](#language-editions)). |
-| `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, share image. Scrapers require absolute URLs, so the page composes them from its own origin; `Page+Defaults` supplies the locale as `ogLocale`. |
+| `socialCard` | Open Graph + Twitter `<meta>` tags | A `SocialCard` — title, summary, URL, site name, locale, alternate locales, share image. Scrapers require absolute URLs, so the page composes them from its own origin; `Page+Defaults` supplies the locale as `ogLocale`. |
 | `structuredData` | `<script type="application/ld+json">` | A `StructuredData` graph of schema.org nodes; `StructuredData(name:url:logo:inLanguage:profiles:)` builds the site-wide `Organization` + `WebSite` pair, `inLanguage` declaring the languages the site publishes in (see [Language editions](#language-editions)). The payload is an inert data block, so the `Content-Security-Policy` does not apply to it. |
 
 The fifth, `analytics`, is *configuration*-authored rather than page-authored: the executable builds an `Analytics` from the `analytics.*` keys and hands it to `RootController` and `NotFoundMiddleware`, which pass it to both pages. It renders as a `<link rel="preconnect">` plus a deferred `<script>` carrying the [Umami](https://umami.is) `data-` attributes, and — unlike the structured data — it *is* executable, so the `Content-Security-Policy` must allow its origin. It is empty by default; see [Analytics](#analytics) for how to turn it on.
@@ -85,7 +85,7 @@ The catalog's source language is the **default** and owns the site's bare paths;
 
 Given a `site.origin`, each page then emits the `hreflang` alternates tying its editions together — one per language plus an `x-default` pointing at the default language's edition, whose bare URL negotiates the language and so is the right landing for everyone unmatched. A single-language site emits none: a set naming one edition tells a search engine nothing it cannot already see. `Page+Defaults`' `languageAlternates(origin:path:languages:)` takes the language set, so a page translated into only some of them narrows it rather than advertising an edition that does not exist.
 
-The same set belongs in the site-wide structured data: `StructuredData`'s `inLanguage` declares it on the `WebSite` node, so a crawler reads the site's languages from the graph as well as from the alternates.
+The same set belongs in the site-wide structured data: `StructuredData`'s `inLanguage` declares it on the `WebSite` node, so a crawler reads the site's languages from the graph as well as from the alternates. A page's social card says the same to a scraper: its `locale` is the edition the page *is*, and `SocialCard`'s `alternateLocales` names the rest, each mapped through `ogLocales` the way `ogLocale` maps the page's.
 
 `sitemap.xml` is the one part that does *not* follow the catalog: it is a static file, so a new language needs its editions added by hand — `/nl`, `/nl/<page>`, one `<loc>` each, alongside the default language's. Give each the same spelling the page's own canonical carries (the root is the bare origin, with no trailing slash), or the two disagree about which URL is canonical.
 
-- 
2.54.0