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 01/26] 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

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 02/26] 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

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 03/26] 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

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 04/26] 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(

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 05/26] 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)

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 06/26] 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"
         ),

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 07/26] 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")
+        )
+    }
+
 }

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 08/26] 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
         )

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 09/26] 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
+        }
+
+    }
+
+}

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 10/26] 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()

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 11/26] 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(

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 12/26] 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:

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 13/26] 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`.

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 14/26] 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

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 15/26] 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.

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 16/26] 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(

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 17/26] 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 ------------------------------------------------------
 

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 18/26] 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.

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 19/26] 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

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 20/26] 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

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 21/26] 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()
+    }
+
+}

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 22/26] 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")

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 23/26] 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

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 24/26] 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(

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 25/26] 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(

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 26/26] 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)
+        ])
+    }
+
+}