From 187dcf9aebf838e0a9d37689758e6cee9ac3a960 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Thu, 5 Nov 2026 20:02:02 +0100
Subject: [PATCH] refactor(branding): follow the module layout (moves only)

constants, settings, services, the branding service, presets and the
tenant-overridable definitions and resolution move to branding/core/;
image validation and the reaper to branding/assets/; deps, the shared-
props provider and endpoints to branding/web/; the form components from
components/ to ui/components/. Tests mirror the areas.
branding.{constants,settings,services,tenant_branding,images} and
branding.endpoints.assets stay as deprecated aliases until 0.0.46.

Claude-Session: https://claude.ai/code/session_01FXHA3ZicrtZ4C5QPEgxfgq
---
 CHANGELOG.md                                  |   1 +
 docs/module-layout.md                         |   2 +-
 docs/modules/branding.md                      |   4 +-
 host/tests/test_module_layout.py              |   7 +-
 modules/branding/branding/assets/__init__.py  |   1 +
 modules/branding/branding/assets/images.py    | 121 +++++++++
 .../branding/branding/{ => assets}/reaper.py  |   2 +-
 modules/branding/branding/constants.py        | 231 +----------------
 .../branding/branding/contracts/schemas.py    |   2 +-
 modules/branding/branding/core/__init__.py    |   5 +
 modules/branding/branding/core/constants.py   | 230 ++++++++++++++++
 .../branding/branding/{ => core}/presets.py   |   0
 .../branding/branding/{ => core}/service.py   |  18 +-
 modules/branding/branding/core/services.py    |  38 +++
 modules/branding/branding/core/settings.py    | 102 ++++++++
 .../branding/branding/core/tenant_branding.py | 242 +++++++++++++++++
 .../branding/{ => core}/tenant_definitions.py |   4 +-
 .../branding/branding/endpoints/__init__.py   |   1 +
 modules/branding/branding/endpoints/assets.py | 190 +-------------
 modules/branding/branding/images.py           | 122 +--------
 modules/branding/branding/module.py           |  22 +-
 modules/branding/branding/pages/Manage.tsx    |  18 +-
 modules/branding/branding/services.py         |  39 +--
 modules/branding/branding/settings.py         | 103 +-------
 modules/branding/branding/tenant_branding.py  | 245 +-----------------
 .../{ => ui}/components/BannerField.tsx       |   0
 .../{ => ui}/components/BrandingPreview.tsx   |   0
 .../{ => ui}/components/ColorField.tsx        |   0
 .../{ => ui}/components/DesignPackField.tsx   |   0
 .../{ => ui}/components/FooterField.tsx       |   0
 .../{ => ui}/components/ImageDropzones.tsx    |   0
 .../{ => ui}/components/PresetField.tsx       |   0
 .../{ => ui}/components/PreviewSurfaces.tsx   |   0
 .../{ => ui}/components/PreviewTabs.tsx       |   0
 .../branding/{ => ui}/components/dirty.ts     |   0
 .../branding/{ => ui}/components/hex.ts       |   0
 modules/branding/branding/web/__init__.py     |   1 +
 modules/branding/branding/{ => web}/deps.py   |   4 +-
 .../branding/web/endpoints/__init__.py        |   0
 .../branding/{ => web}/endpoints/api.py       |   8 +-
 .../branding/branding/web/endpoints/assets.py | 187 +++++++++++++
 .../{ => web}/endpoints/tenant_api.py         |  12 +-
 .../branding/{ => web}/endpoints/views.py     |   4 +-
 .../branding/{ => web}/shared_props.py        |   8 +-
 .../branding/tests-js/color-field.test.tsx    |   8 +-
 .../branding/tests-js/dirty-state.test.tsx    |   4 +-
 .../images/test_branding_images.py}           |   2 +-
 .../images/test_branding_logo_dark.py}        |   4 +-
 .../reaper/test_branding_asset_lifecycle.py}  |   0
 .../{ => assets/reaper}/test_branding_reap.py |   6 +-
 .../reaper}/test_branding_reap_ordering.py    |   5 +-
 .../tests/{ => core/module}/test_branding.py  |   8 +-
 .../module}/test_branding_menu_permission.py  |   2 +-
 .../module/test_branding_menu_section.py}     |   2 +-
 .../presets/test_branding_presets.py}         |   4 +-
 .../settings/test_branding_banner.py}         |   6 +-
 .../settings/test_branding_design_pack.py}    |   4 +-
 .../settings/test_branding_footer_links.py}   |   6 +-
 .../settings/test_branding_footer_text.py}    |   6 +-
 .../test_branding_tenant_branding.py}         |   2 +-
 .../test_branding_tenant_branding_assets.py}  |   4 +-
 .../test_branding_tenant_branding_cost.py}    |   4 +-
 .../test_branding_tenant_review_fixes.py}     |   8 +-
 .../test_branding_clear_route_scope.py        |   0
 .../test_branding_platform_files.py           |   2 +-
 .../endpoints/test_branding_public_assets.py} |   0
 scripts/tests/test_check_no_double_cast.py    |   2 +-
 67 files changed, 1072 insertions(+), 991 deletions(-)
 create mode 100644 modules/branding/branding/assets/__init__.py
 create mode 100644 modules/branding/branding/assets/images.py
 rename modules/branding/branding/{ => assets}/reaper.py (98%)
 create mode 100644 modules/branding/branding/core/__init__.py
 create mode 100644 modules/branding/branding/core/constants.py
 rename modules/branding/branding/{ => core}/presets.py (100%)
 rename modules/branding/branding/{ => core}/service.py (92%)
 create mode 100644 modules/branding/branding/core/services.py
 create mode 100644 modules/branding/branding/core/settings.py
 create mode 100644 modules/branding/branding/core/tenant_branding.py
 rename modules/branding/branding/{ => core}/tenant_definitions.py (98%)
 rename modules/branding/branding/{ => ui}/components/BannerField.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/BrandingPreview.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/ColorField.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/DesignPackField.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/FooterField.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/ImageDropzones.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/PresetField.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/PreviewSurfaces.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/PreviewTabs.tsx (100%)
 rename modules/branding/branding/{ => ui}/components/dirty.ts (100%)
 rename modules/branding/branding/{ => ui}/components/hex.ts (100%)
 create mode 100644 modules/branding/branding/web/__init__.py
 rename modules/branding/branding/{ => web}/deps.py (86%)
 create mode 100644 modules/branding/branding/web/endpoints/__init__.py
 rename modules/branding/branding/{ => web}/endpoints/api.py (96%)
 create mode 100644 modules/branding/branding/web/endpoints/assets.py
 rename modules/branding/branding/{ => web}/endpoints/tenant_api.py (91%)
 rename modules/branding/branding/{ => web}/endpoints/views.py (95%)
 rename modules/branding/branding/{ => web}/shared_props.py (95%)
 rename modules/branding/tests/{test_images.py => assets/images/test_branding_images.py} (99%)
 rename modules/branding/tests/{test_logo_dark.py => assets/images/test_branding_logo_dark.py} (98%)
 rename modules/branding/tests/{test_asset_lifecycle.py => assets/reaper/test_branding_asset_lifecycle.py} (100%)
 rename modules/branding/tests/{ => assets/reaper}/test_branding_reap.py (96%)
 rename modules/branding/tests/{ => assets/reaper}/test_branding_reap_ordering.py (96%)
 rename modules/branding/tests/{ => core/module}/test_branding.py (97%)
 rename modules/branding/tests/{ => core/module}/test_branding_menu_permission.py (92%)
 rename modules/branding/tests/{test_menu_section.py => core/module/test_branding_menu_section.py} (92%)
 rename modules/branding/tests/{test_presets.py => core/presets/test_branding_presets.py} (97%)
 rename modules/branding/tests/{test_banner.py => core/settings/test_branding_banner.py} (96%)
 rename modules/branding/tests/{test_design_pack.py => core/settings/test_branding_design_pack.py} (97%)
 rename modules/branding/tests/{test_footer_links.py => core/settings/test_branding_footer_links.py} (97%)
 rename modules/branding/tests/{test_footer_text.py => core/settings/test_branding_footer_text.py} (95%)
 rename modules/branding/tests/{test_tenant_branding.py => core/tenant_branding/test_branding_tenant_branding.py} (99%)
 rename modules/branding/tests/{test_tenant_branding_assets.py => core/tenant_branding/test_branding_tenant_branding_assets.py} (99%)
 rename modules/branding/tests/{test_tenant_branding_cost.py => core/tenant_branding/test_branding_tenant_branding_cost.py} (97%)
 rename modules/branding/tests/{test_ship_review.py => core/tenant_branding/test_branding_tenant_review_fixes.py} (96%)
 rename modules/branding/tests/{ => web/endpoints}/test_branding_clear_route_scope.py (100%)
 rename modules/branding/tests/{ => web/endpoints}/test_branding_platform_files.py (98%)
 rename modules/branding/tests/{test_public_assets.py => web/endpoints/test_branding_public_assets.py} (100%)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 14610b0e3..02681dd0e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,6 +41,7 @@ All notable changes to this project are documented in this file. The format is b
 - `keycloak` follows the module layout: `keycloak.core.{constants,settings,state}`, `keycloak.identity.{provider,oidc,renewal,directory,persistence,tokens,jwks}` and `keycloak.web.endpoints`. `keycloak.{constants,settings,provider,jwks,tokens}` still import, with a `DeprecationWarning`, until 0.0.46.
 - `oidc` follows the module layout: `oidc.core.{constants,settings,presets,state,runtime}`, `oidc.identity.{provider,client,discovery,renewal,directory,persistence,tokens,jwks}` and `oidc.web.endpoints`. `oidc.{settings,provider,jwks}` still import, with a `DeprecationWarning`, until 0.0.46; other old `oidc.*` paths are gone.
 - `api_tokens` follows the module layout: `api_tokens.core.{constants,settings,services,tenant_cleanup,user_cleanup}`, `api_tokens.credentials.{format,scopes,owner,service,resolver,audit}` (`tokens.py` is now `credentials/format.py`), `api_tokens.web.{deps,endpoints}`, and the page components and types move to `ui/`. `api_tokens.{constants,service,resolver,tokens}` still import, with a `DeprecationWarning`, until 0.0.46.
+- `branding` follows the module layout: `branding.core.{constants,settings,services,service,presets,tenant_definitions,tenant_branding}`, `branding.assets.{images,reaper}`, `branding.web.{deps,shared_props,endpoints}`, and the form components move from `components/` to `ui/components/`. `branding.{constants,settings,services,tenant_branding,images}` and `branding.endpoints.assets` still import, with a `DeprecationWarning`, until 0.0.46.
 
 ### Fixed
 
diff --git a/docs/module-layout.md b/docs/module-layout.md
index ee59fb857..339edb0eb 100644
--- a/docs/module-layout.md
+++ b/docs/module-layout.md
@@ -216,7 +216,7 @@ when a later module PR moves files.
 | audit_log | 13 | 18 | flat |
 | auth | 8 | 20 | flat |
 | background_tasks | 49 | 83 | flat |
-| branding | 13 | 20 | flat |
+| branding | 2 (+6 shims) | 0 | follows this layout |
 | dashboard | 2 | 0 | follows this layout |
 | feature_flags | 3 (+1 shim) | 0 | follows this layout |
 | file_storage | 39 | 65 | flat |
diff --git a/docs/modules/branding.md b/docs/modules/branding.md
index 00a57c154..6ace06e08 100644
--- a/docs/modules/branding.md
+++ b/docs/modules/branding.md
@@ -167,7 +167,7 @@ Note the exact property: the bytes must look like **some** allowed image format,
 
 ### Asset lifecycle
 
-Replacing or clearing an image deletes the file it stopped referencing, so repeated logo tweaks don't leave orphans in `file_storage` — system and tenant images alike (`branding.reaper`):
+Replacing or clearing an image deletes the file it stopped referencing, so repeated logo tweaks don't leave orphans in `file_storage` — system and tenant images alike (`branding.assets.reaper`):
 
 - **After commit.** The delete is queued with `register_on_commit` and runs, in a session of its own, once the settings write is durable. Deleting in the request removed the bytes before that: a late rollback left the setting pointing at a file that was gone.
 - **Only when unreferenced.** A file another image field of the same owner still holds — the logo and the dark logo sharing one upload — is kept; the check runs again at reap time.
@@ -265,7 +265,7 @@ page translates, with the English text as fallback. Server-side error details
 (validator messages) are still shown as sent — they come from pydantic and are
 not keyed.
 
-Reads resolve per request (`branding.tenant_branding.resolve`): the request's
+Reads resolve per request (`branding.core.tenant_branding.resolve`): the request's
 tenant overrides on top of the system theme, falling back field by field. The
 provider leaves the merged object on `request.state.branding`, which the root
 template's pre-hydration `<head>` prefers. A hand-edited invalid override
diff --git a/host/tests/test_module_layout.py b/host/tests/test_module_layout.py
index 2cb3bbc7c..15a2b69fb 100644
--- a/host/tests/test_module_layout.py
+++ b/host/tests/test_module_layout.py
@@ -34,6 +34,7 @@
 # Add named domain areas here only when they contain several related features.
 DOMAIN_AREAS: dict[str, frozenset[str]] = {
     "api_tokens": frozenset({"credentials"}),
+    "branding": frozenset({"assets"}),
     "keycloak": frozenset({"identity"}),
     "mail": frozenset({"delivery"}),
     "oidc": frozenset({"identity"}),
@@ -66,12 +67,6 @@
         workers_state.py
         """.split()
     ),
-    "branding": frozenset(
-        """
-        components constants.py deps.py endpoints images.py presets.py reaper.py service.py
-        services.py settings.py shared_props.py tenant_branding.py tenant_definitions.py
-        """.split()
-    ),
     "file_storage": frozenset(
         """
         aggregates.py audit_labels.py backend_guard.py backends body_limits.py checksum.py
diff --git a/modules/branding/branding/assets/__init__.py b/modules/branding/branding/assets/__init__.py
new file mode 100644
index 000000000..a5b1c8095
--- /dev/null
+++ b/modules/branding/branding/assets/__init__.py
@@ -0,0 +1 @@
+"""Branding images: upload validation and reaping files nothing references."""
diff --git a/modules/branding/branding/assets/images.py b/modules/branding/branding/assets/images.py
new file mode 100644
index 000000000..eb1323631
--- /dev/null
+++ b/modules/branding/branding/assets/images.py
@@ -0,0 +1,121 @@
+"""Upload validation for branding images.
+
+The declared ``Content-Type`` on a multipart part is chosen by the caller, so
+it is a claim rather than a fact. An admin who uploads ``payload.html`` renamed
+``logo.png`` would otherwise have it stored and later served back under an
+``image/*`` type. Every accepted format therefore has to also *look* like
+itself in its first bytes.
+
+Mirrors the allow-list and signature check in the IIASA.GeoWiki Branding module
+(``GeoWikiBrandingConsts``), including its deliberate omission of SVG.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+from fastapi import HTTPException, UploadFile
+
+if TYPE_CHECKING:
+    from file_storage.contracts.schemas import StoredFileOut
+    from file_storage.service import FileStorageService
+
+# Raster + icon only. SVG is excluded on purpose: it is an XML document that can
+# carry <script>, so serving one back from our own origin would be stored XSS.
+# The asset route defends in depth (attachment + nosniff), but the narrower
+# allow-list is what actually keeps executable markup out of the store.
+ALLOWED_IMAGE_TYPES: Final = frozenset(
+    {
+        "image/png",
+        "image/jpeg",
+        "image/webp",
+        "image/gif",
+        "image/x-icon",
+        "image/vnd.microsoft.icon",
+    }
+)
+
+MAX_IMAGE_BYTES: Final = 2 * 1024 * 1024  # 2 MB
+
+ALLOWED_IMAGE_HINT: Final = "Allowed: PNG, JPEG, WEBP, GIF, ICO."
+
+# Enough for the longest signature we test (WEBP needs 12 bytes).
+_PROBE_BYTES: Final = 16
+
+# (offset, literal) pairs; a format matches when every pair matches.
+_SIGNATURES: Final[tuple[tuple[tuple[int, bytes], ...], ...]] = (
+    ((0, b"\x89PNG\r\n\x1a\n"),),  # PNG
+    ((0, b"\xff\xd8\xff"),),  # JPEG
+    ((0, b"GIF87a"),),  # GIF
+    ((0, b"GIF89a"),),
+    ((0, b"RIFF"), (8, b"WEBP")),  # WEBP
+    ((0, b"\x00\x00\x01\x00"),),  # ICO (Windows icon resource)
+)
+
+
+def normalize_content_type(raw: str | None) -> str:
+    """Strip any ``; charset=…`` parameter and lowercase the media type."""
+    if not raw:
+        return ""
+    return raw.split(";", 1)[0].strip().lower()
+
+
+def has_recognized_image_signature(head: bytes) -> bool:
+    """True when ``head`` starts with the magic number of an allowed format."""
+    return any(
+        all(head[at : at + len(literal)] == literal for at, literal in signature)
+        for signature in _SIGNATURES
+    )
+
+
+async def validate_image(file: UploadFile) -> None:
+    """Reject anything that isn't a small, genuine raster/icon image.
+
+    Leaves ``file`` rewound to the start so the caller can hand it straight to
+    ``file_storage``.
+    """
+    content_type = normalize_content_type(file.content_type)
+    if content_type not in ALLOWED_IMAGE_TYPES:
+        raise HTTPException(
+            status_code=415,
+            detail=f"Unsupported image type {content_type or 'unknown'!r}. {ALLOWED_IMAGE_HINT}",
+        )
+
+    # ``size`` is populated by Starlette's multipart parser. When it isn't (a
+    # non-multipart caller), file_storage still enforces its own ceiling, so
+    # this stays an early, friendlier guard rather than the only one.
+    if file.size is not None and file.size > MAX_IMAGE_BYTES:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Image exceeds {MAX_IMAGE_BYTES} bytes.",
+        )
+
+    head = await file.read(_PROBE_BYTES)
+    await file.seek(0)
+    if not has_recognized_image_signature(head):
+        raise HTTPException(
+            status_code=415,
+            detail=(
+                f"File does not look like an image — its content does not match "
+                f"{content_type!r}. {ALLOWED_IMAGE_HINT}"
+            ),
+        )
+
+
+async def store_image(
+    storage: FileStorageService, file: UploadFile, *, platform: bool = False
+) -> StoredFileOut:
+    """Hand a validated image to ``file_storage``, answering 413 when the quota is full.
+
+    ``file_storage`` enforces ``quota_bytes`` on every upload; its own endpoint
+    maps the refusal to 413, but branding calls the service directly, so an
+    unmapped ``QuotaExceededError`` would surface as a 500.
+    """
+    from file_storage.upload_support import QuotaExceededError
+
+    try:
+        return await storage.upload(file, platform=platform)
+    except QuotaExceededError:
+        raise HTTPException(
+            status_code=413, detail="The storage quota is full; the image was not saved."
+        ) from None
diff --git a/modules/branding/branding/reaper.py b/modules/branding/branding/assets/reaper.py
similarity index 98%
rename from modules/branding/branding/reaper.py
rename to modules/branding/branding/assets/reaper.py
index 3c8f8d4ab..437f2eddd 100644
--- a/modules/branding/branding/reaper.py
+++ b/modules/branding/branding/assets/reaper.py
@@ -26,7 +26,7 @@
 from simple_module_db import tenant_context
 from simple_module_db.callbacks import register_on_commit
 
-from branding.constants import PACKAGE, TENANT_IMAGE_FIELDS
+from branding.core.constants import PACKAGE, TENANT_IMAGE_FIELDS
 
 if TYPE_CHECKING:
     from fastapi import FastAPI
diff --git a/modules/branding/branding/constants.py b/modules/branding/branding/constants.py
index 748444e2f..43e7f9865 100644
--- a/modules/branding/branding/constants.py
+++ b/modules/branding/branding/constants.py
@@ -1,230 +1,11 @@
-"""Branding module constants."""
+"""Moved to :mod:`branding.core.constants`; this alias goes in 0.0.46 (module layout)."""
 
 from __future__ import annotations
 
-import re
-from typing import Final
+import importlib
+import sys
 
-from simple_module_core.design_packs import SLUG_RE
+from simple_module_core.deprecation import deprecated_module
 
-ROUTE_PREFIX: Final = "/api/branding"
-VIEW_PREFIX: Final = "/admin/branding"
-# Trailing slash: the browse route is registered at "/" under VIEW_PREFIX, so
-# linking to the bare prefix costs a 307 round trip on every navigation.
-MENU_URL: Final = f"{VIEW_PREFIX}/"
-
-PACKAGE: Final = "branding"
-
-# Modules this one depends on (kept as constants so the depends_on list doesn't
-# carry bare string literals — see scripts/check_hardcoded_strings.py).
-_MODULE_SETTINGS: Final = "Settings"
-_MODULE_FILE_STORAGE: Final = "FileStorage"
-
-# Inertia page identifier. The view endpoint renders this as a literal (so the
-# SM003/SM004 static-AST diagnostics can pair it with pages/Manage.tsx); a test
-# asserts the literal matches this constant.
-_PAGE_MANAGE: Final = "Branding/Manage"
-
-PERM_VIEW: Final = "branding.view"
-PERM_MANAGE: Final = "branding.manage"
-
-# A #rrggbb hex colour (single source of truth for both the settings and the
-# update-DTO validators).
-HEX_COLOR_RE: Final = re.compile(r"^#[0-9a-fA-F]{6}$")
-MAX_APP_NAME_LEN: Final = 60
-
-# ── Site-wide announcement banner ──────────────────────────────────────
-# An empty message hides the banner entirely; severity drives its colour.
-MAX_BANNER_MESSAGE_LEN: Final = 500
-BANNER_SEVERITY_INFO: Final = "info"
-BANNER_SEVERITIES: Final = (BANNER_SEVERITY_INFO, "warning", "danger")
-BANNER_SEVERITY_ERROR: Final = f"banner_severity must be one of {', '.join(BANNER_SEVERITIES)}"
-
-
-def normalize_banner_severity(value: str | None) -> str:
-    """Coerce a severity to a known value, falling back to ``info``.
-
-    Used by the *settings* validator rather than the DTO: settings hydrate from
-    the DB, where a hand-edited or since-removed severity must degrade to a
-    readable banner instead of refusing to boot. The update DTO rejects unknown
-    values outright so the API gives a clear 422.
-    """
-    candidate = (value or "").strip().lower()
-    return candidate if candidate in BANNER_SEVERITIES else BANNER_SEVERITY_INFO
-
-
-def clean_banner_message(value: str) -> str:
-    """Trim + bound the banner text (shared by the settings and update DTO)."""
-    cleaned = value.strip()
-    if len(cleaned) > MAX_BANNER_MESSAGE_LEN:
-        raise ValueError(f"banner_message must be at most {MAX_BANNER_MESSAGE_LEN} characters")
-    return cleaned
-
-
-# A design-pack slug. Aliased from the framework's own pattern so branding and
-# DesignPack can never disagree about what a valid slug is.
-DESIGN_PACK_RE: Final = SLUG_RE
-DESIGN_PACK_ERROR: Final = (
-    "design_pack must be a lowercase slug (letters, digits and dashes, "
-    "not starting with a dash) or empty"
-)
-
-# Image upload guard-rails live in branding.images (allow-list, size ceiling and
-# magic-number sniffing), which owns the whole "is this really an image?" question.
-
-# ── Public asset routes ────────────────────────────────────────────────
-# Branding serves its own logo and favicon instead of linking file_storage's
-# download route, which is gated by ``file-storage.download``. No logged-out
-# request carries that permission, and the sign-in page, the public landing
-# page and every ``<link rel="icon">`` are exactly where the logo has to show.
-# Only the two ids currently stored in branding settings are served here, so
-# this is not a way to read arbitrary files out of file_storage.
-#: One-click look. ``{key}`` names a preset from ``branding.presets``.
-PATH_PRESET: Final = "/presets/{key}"
-
-PATH_LOGO: Final = "/logo"
-PATH_LOGO_DARK: Final = "/logo-dark"
-PATH_FAVICON: Final = "/favicon"
-LOGO_URL: Final = ROUTE_PREFIX + PATH_LOGO
-LOGO_DARK_URL: Final = ROUTE_PREFIX + PATH_LOGO_DARK
-FAVICON_URL: Final = ROUTE_PREFIX + PATH_FAVICON
-
-# Cache policy, mirroring IIASA.GeoWiki's BrandingImageCache. The published URL
-# carries ``?v=<file_id>``, and a replaced image is a *new* file_storage id — so
-# a versioned request is content-addressed and safe to pin for a year. A request
-# without a usable version must never be immutable: that same URL can serve new
-# bytes later, so it gets a short cache and self-corrects.
-ASSET_VERSION_QUERY_KEY: Final = "v"
-ASSET_MAX_AGE_VERSIONED: Final = 365 * 24 * 60 * 60
-ASSET_MAX_AGE_UNVERSIONED: Final = 60 * 60
-
-
-def clean_app_name(value: str) -> str:
-    """Normalise + validate an app name (shared by the settings + update DTO).
-
-    The name is surfaced in HTML titles and—critically—email ``Subject``
-    headers, so control characters (notably CR/LF) must be rejected: an
-    embedded newline would otherwise pass a bare ``strip()`` and then raise
-    when set as a header, breaking every transactional email.
-    """
-    cleaned = value.strip()
-    if not cleaned:
-        raise ValueError("app_name must not be blank")
-    if len(cleaned) > MAX_APP_NAME_LEN:
-        raise ValueError(f"app_name must be at most {MAX_APP_NAME_LEN} characters")
-    if any(ord(ch) < 0x20 for ch in cleaned):
-        raise ValueError("app_name must not contain control characters")
-    return cleaned
-
-
-# ── Footer text ────────────────────────────────────────────────────────
-# The caption beside the footer links. Blank means "use the framework's own"
-# (`© {year} · MIT`), so a deployment that never sets this is unchanged —
-# and one that does stops publishing the framework's licence as its own.
-MAX_FOOTER_TEXT_LEN: Final = 200
-
-
-def clean_footer_text(value: str) -> str:
-    """Trim + bound the footer caption (shared by the settings and update DTO)."""
-    cleaned = value.strip()
-    if len(cleaned) > MAX_FOOTER_TEXT_LEN:
-        raise ValueError(f"footer_text must be at most {MAX_FOOTER_TEXT_LEN} characters")
-    # The caption is rendered into HTML and into transactional email headers;
-    # a stray newline breaks the latter outright.
-    if any(ord(ch) < 0x20 for ch in cleaned):
-        raise ValueError("footer_text must not contain control characters")
-    return cleaned
-
-
-# ── Footer links ───────────────────────────────────────────────────────
-# An empty list means "use the framework's own links" (`BRAND_FOOTER_LINKS`
-# in @simple-module-py/ui), so an existing deployment that never sets these
-# keeps the footer it has today.
-MAX_FOOTER_LINKS: Final = 6
-MAX_FOOTER_LINK_LABEL_LEN: Final = 40
-MAX_FOOTER_LINK_HREF_LEN: Final = 500
-
-#: Schemes an admin-supplied footer href may use, plus site-relative paths.
-#:
-#: This is a real allow-list, not tidiness: the href is rendered straight into
-#: an ``<a href>`` on every page of the site, signed-in or not, so
-#: ``javascript:`` (and ``data:``) would turn the branding screen into a stored
-#: XSS sink for anyone holding ``branding.manage``.
-FOOTER_LINK_SCHEMES: Final = ("http://", "https://", "mailto:")
-FOOTER_LINK_HREF_ERROR: Final = (
-    "footer link href must start with " + ", ".join(FOOTER_LINK_SCHEMES) + " or /"
-)
-#: Backslashes are rejected outright. Browsers normalise ``\`` to ``/`` in the
-#: authority position of a special-scheme URL, so ``/\evil.example.com`` reads
-#: as a site-relative path but navigates to ``https://evil.example.com`` — the
-#: exact bypass the ``//host`` rule below exists to close. No legitimate footer
-#: target needs a raw backslash; ``%5C`` still works for one in a path.
-FOOTER_LINK_BACKSLASH_ERROR: Final = "footer link href must not contain a backslash"
-
-
-def clean_footer_label(value: str) -> str:
-    """Normalise + validate a footer link's visible text."""
-    cleaned = value.strip()
-    if not cleaned:
-        raise ValueError("footer link label must not be blank")
-    if len(cleaned) > MAX_FOOTER_LINK_LABEL_LEN:
-        raise ValueError(
-            f"footer link label must be at most {MAX_FOOTER_LINK_LABEL_LEN} characters"
-        )
-    if any(ord(ch) < 0x20 for ch in cleaned):
-        raise ValueError("footer link label must not contain control characters")
-    return cleaned
-
-
-def clean_footer_href(value: str) -> str:
-    """Normalise + validate a footer link's target.
-
-    Scheme-relative ``//host`` is rejected along with everything else outside
-    the allow-list: it reads as a relative path but navigates off-site, so
-    allowing it would make the ``/`` rule mean something other than "this site".
-    Backslashes go with it — a browser reads ``/\\host`` the same way.
-    """
-    cleaned = value.strip()
-    if not cleaned:
-        raise ValueError("footer link href must not be blank")
-    if len(cleaned) > MAX_FOOTER_LINK_HREF_LEN:
-        raise ValueError(f"footer link href must be at most {MAX_FOOTER_LINK_HREF_LEN} characters")
-    if any(ord(ch) < 0x20 for ch in cleaned):
-        raise ValueError("footer link href must not contain control characters")
-    if "\\" in cleaned:
-        raise ValueError(FOOTER_LINK_BACKSLASH_ERROR)
-    lowered = cleaned.lower()
-    relative = cleaned.startswith("/") and not cleaned.startswith("//")
-    if not relative and not lowered.startswith(FOOTER_LINK_SCHEMES):
-        raise ValueError(FOOTER_LINK_HREF_ERROR)
-    return cleaned
-
-
-# ── Per-tenant branding (#373) ─────────────────────────────────────────
-# The fields a tenant may override for itself, as ``branding.<field>`` rows at
-# settings' TENANT scope. Deliberately not the banner (the platform's channel
-# for maintenance notices, which a tenant must not be able to silence) nor the
-# footer links (a JSON list with an XSS-relevant allow-list, kept platform-only
-# until it has a tenant-facing editor).
-TENANT_IMAGE_FIELDS: Final = ("logo_file_id", "logo_dark_file_id", "favicon_file_id")
-TENANT_FIELDS: Final = (
-    "app_name",
-    "primary_color",
-    "design_pack",
-    "footer_text",
-    *TENANT_IMAGE_FIELDS,
-)
-#: ``/api/branding/tenant/{asset}`` — upload (POST) / clear (DELETE) one of the
-#: active tenant's own images.
-PATH_TENANT_ASSET: Final = "/tenant/{asset}"
-TENANT_ASSETS: Final = {
-    "logo": "logo_file_id",
-    "logo-dark": "logo_dark_file_id",
-    "favicon": "favicon_file_id",
-}
-#: Detail of the 422 a generic settings write of a tenant image key gets.
-IMAGE_KEY_GENERIC_WRITE_ERROR: Final = (
-    "Branding images are set through /api/branding/tenant/{asset}, not the settings routes."
-)
-#: Floor for the per-tenant cache; settings' invalidation notices clear it sooner.
-TENANT_CACHE_TTL_SECONDS: Final = 30
+deprecated_module("branding.constants", remove_in="0.0.46", use="branding.core.constants")
+sys.modules[__name__] = importlib.import_module("branding.core.constants")
diff --git a/modules/branding/branding/contracts/schemas.py b/modules/branding/branding/contracts/schemas.py
index 2f98436a4..471fcc49d 100644
--- a/modules/branding/branding/contracts/schemas.py
+++ b/modules/branding/branding/contracts/schemas.py
@@ -5,7 +5,7 @@
 from pydantic import field_validator
 from sqlmodel import Field, SQLModel
 
-from branding.constants import (
+from branding.core.constants import (
     BANNER_SEVERITIES,
     BANNER_SEVERITY_ERROR,
     DESIGN_PACK_ERROR,
diff --git a/modules/branding/branding/core/__init__.py b/modules/branding/branding/core/__init__.py
new file mode 100644
index 000000000..8ebfc678e
--- /dev/null
+++ b/modules/branding/branding/core/__init__.py
@@ -0,0 +1,5 @@
+"""What every branding feature builds on.
+
+Constants, settings, the services container, the branding service, presets and
+tenant-overridable definitions and resolution.
+"""
diff --git a/modules/branding/branding/core/constants.py b/modules/branding/branding/core/constants.py
new file mode 100644
index 000000000..9c648c962
--- /dev/null
+++ b/modules/branding/branding/core/constants.py
@@ -0,0 +1,230 @@
+"""Branding module constants."""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+from simple_module_core.design_packs import SLUG_RE
+
+ROUTE_PREFIX: Final = "/api/branding"
+VIEW_PREFIX: Final = "/admin/branding"
+# Trailing slash: the browse route is registered at "/" under VIEW_PREFIX, so
+# linking to the bare prefix costs a 307 round trip on every navigation.
+MENU_URL: Final = f"{VIEW_PREFIX}/"
+
+PACKAGE: Final = "branding"
+
+# Modules this one depends on (kept as constants so the depends_on list doesn't
+# carry bare string literals — see scripts/check_hardcoded_strings.py).
+_MODULE_SETTINGS: Final = "Settings"
+_MODULE_FILE_STORAGE: Final = "FileStorage"
+
+# Inertia page identifier. The view endpoint renders this as a literal (so the
+# SM003/SM004 static-AST diagnostics can pair it with pages/Manage.tsx); a test
+# asserts the literal matches this constant.
+_PAGE_MANAGE: Final = "Branding/Manage"
+
+PERM_VIEW: Final = "branding.view"
+PERM_MANAGE: Final = "branding.manage"
+
+# A #rrggbb hex colour (single source of truth for both the settings and the
+# update-DTO validators).
+HEX_COLOR_RE: Final = re.compile(r"^#[0-9a-fA-F]{6}$")
+MAX_APP_NAME_LEN: Final = 60
+
+# ── Site-wide announcement banner ──────────────────────────────────────
+# An empty message hides the banner entirely; severity drives its colour.
+MAX_BANNER_MESSAGE_LEN: Final = 500
+BANNER_SEVERITY_INFO: Final = "info"
+BANNER_SEVERITIES: Final = (BANNER_SEVERITY_INFO, "warning", "danger")
+BANNER_SEVERITY_ERROR: Final = f"banner_severity must be one of {', '.join(BANNER_SEVERITIES)}"
+
+
+def normalize_banner_severity(value: str | None) -> str:
+    """Coerce a severity to a known value, falling back to ``info``.
+
+    Used by the *settings* validator rather than the DTO: settings hydrate from
+    the DB, where a hand-edited or since-removed severity must degrade to a
+    readable banner instead of refusing to boot. The update DTO rejects unknown
+    values outright so the API gives a clear 422.
+    """
+    candidate = (value or "").strip().lower()
+    return candidate if candidate in BANNER_SEVERITIES else BANNER_SEVERITY_INFO
+
+
+def clean_banner_message(value: str) -> str:
+    """Trim + bound the banner text (shared by the settings and update DTO)."""
+    cleaned = value.strip()
+    if len(cleaned) > MAX_BANNER_MESSAGE_LEN:
+        raise ValueError(f"banner_message must be at most {MAX_BANNER_MESSAGE_LEN} characters")
+    return cleaned
+
+
+# A design-pack slug. Aliased from the framework's own pattern so branding and
+# DesignPack can never disagree about what a valid slug is.
+DESIGN_PACK_RE: Final = SLUG_RE
+DESIGN_PACK_ERROR: Final = (
+    "design_pack must be a lowercase slug (letters, digits and dashes, "
+    "not starting with a dash) or empty"
+)
+
+# Image upload guard-rails live in branding.assets.images (allow-list, size ceiling and
+# magic-number sniffing), which owns the whole "is this really an image?" question.
+
+# ── Public asset routes ────────────────────────────────────────────────
+# Branding serves its own logo and favicon instead of linking file_storage's
+# download route, which is gated by ``file-storage.download``. No logged-out
+# request carries that permission, and the sign-in page, the public landing
+# page and every ``<link rel="icon">`` are exactly where the logo has to show.
+# Only the two ids currently stored in branding settings are served here, so
+# this is not a way to read arbitrary files out of file_storage.
+#: One-click look. ``{key}`` names a preset from ``branding.core.presets``.
+PATH_PRESET: Final = "/presets/{key}"
+
+PATH_LOGO: Final = "/logo"
+PATH_LOGO_DARK: Final = "/logo-dark"
+PATH_FAVICON: Final = "/favicon"
+LOGO_URL: Final = ROUTE_PREFIX + PATH_LOGO
+LOGO_DARK_URL: Final = ROUTE_PREFIX + PATH_LOGO_DARK
+FAVICON_URL: Final = ROUTE_PREFIX + PATH_FAVICON
+
+# Cache policy, mirroring IIASA.GeoWiki's BrandingImageCache. The published URL
+# carries ``?v=<file_id>``, and a replaced image is a *new* file_storage id — so
+# a versioned request is content-addressed and safe to pin for a year. A request
+# without a usable version must never be immutable: that same URL can serve new
+# bytes later, so it gets a short cache and self-corrects.
+ASSET_VERSION_QUERY_KEY: Final = "v"
+ASSET_MAX_AGE_VERSIONED: Final = 365 * 24 * 60 * 60
+ASSET_MAX_AGE_UNVERSIONED: Final = 60 * 60
+
+
+def clean_app_name(value: str) -> str:
+    """Normalise + validate an app name (shared by the settings + update DTO).
+
+    The name is surfaced in HTML titles and—critically—email ``Subject``
+    headers, so control characters (notably CR/LF) must be rejected: an
+    embedded newline would otherwise pass a bare ``strip()`` and then raise
+    when set as a header, breaking every transactional email.
+    """
+    cleaned = value.strip()
+    if not cleaned:
+        raise ValueError("app_name must not be blank")
+    if len(cleaned) > MAX_APP_NAME_LEN:
+        raise ValueError(f"app_name must be at most {MAX_APP_NAME_LEN} characters")
+    if any(ord(ch) < 0x20 for ch in cleaned):
+        raise ValueError("app_name must not contain control characters")
+    return cleaned
+
+
+# ── Footer text ────────────────────────────────────────────────────────
+# The caption beside the footer links. Blank means "use the framework's own"
+# (`© {year} · MIT`), so a deployment that never sets this is unchanged —
+# and one that does stops publishing the framework's licence as its own.
+MAX_FOOTER_TEXT_LEN: Final = 200
+
+
+def clean_footer_text(value: str) -> str:
+    """Trim + bound the footer caption (shared by the settings and update DTO)."""
+    cleaned = value.strip()
+    if len(cleaned) > MAX_FOOTER_TEXT_LEN:
+        raise ValueError(f"footer_text must be at most {MAX_FOOTER_TEXT_LEN} characters")
+    # The caption is rendered into HTML and into transactional email headers;
+    # a stray newline breaks the latter outright.
+    if any(ord(ch) < 0x20 for ch in cleaned):
+        raise ValueError("footer_text must not contain control characters")
+    return cleaned
+
+
+# ── Footer links ───────────────────────────────────────────────────────
+# An empty list means "use the framework's own links" (`BRAND_FOOTER_LINKS`
+# in @simple-module-py/ui), so an existing deployment that never sets these
+# keeps the footer it has today.
+MAX_FOOTER_LINKS: Final = 6
+MAX_FOOTER_LINK_LABEL_LEN: Final = 40
+MAX_FOOTER_LINK_HREF_LEN: Final = 500
+
+#: Schemes an admin-supplied footer href may use, plus site-relative paths.
+#:
+#: This is a real allow-list, not tidiness: the href is rendered straight into
+#: an ``<a href>`` on every page of the site, signed-in or not, so
+#: ``javascript:`` (and ``data:``) would turn the branding screen into a stored
+#: XSS sink for anyone holding ``branding.manage``.
+FOOTER_LINK_SCHEMES: Final = ("http://", "https://", "mailto:")
+FOOTER_LINK_HREF_ERROR: Final = (
+    "footer link href must start with " + ", ".join(FOOTER_LINK_SCHEMES) + " or /"
+)
+#: Backslashes are rejected outright. Browsers normalise ``\`` to ``/`` in the
+#: authority position of a special-scheme URL, so ``/\evil.example.com`` reads
+#: as a site-relative path but navigates to ``https://evil.example.com`` — the
+#: exact bypass the ``//host`` rule below exists to close. No legitimate footer
+#: target needs a raw backslash; ``%5C`` still works for one in a path.
+FOOTER_LINK_BACKSLASH_ERROR: Final = "footer link href must not contain a backslash"
+
+
+def clean_footer_label(value: str) -> str:
+    """Normalise + validate a footer link's visible text."""
+    cleaned = value.strip()
+    if not cleaned:
+        raise ValueError("footer link label must not be blank")
+    if len(cleaned) > MAX_FOOTER_LINK_LABEL_LEN:
+        raise ValueError(
+            f"footer link label must be at most {MAX_FOOTER_LINK_LABEL_LEN} characters"
+        )
+    if any(ord(ch) < 0x20 for ch in cleaned):
+        raise ValueError("footer link label must not contain control characters")
+    return cleaned
+
+
+def clean_footer_href(value: str) -> str:
+    """Normalise + validate a footer link's target.
+
+    Scheme-relative ``//host`` is rejected along with everything else outside
+    the allow-list: it reads as a relative path but navigates off-site, so
+    allowing it would make the ``/`` rule mean something other than "this site".
+    Backslashes go with it — a browser reads ``/\\host`` the same way.
+    """
+    cleaned = value.strip()
+    if not cleaned:
+        raise ValueError("footer link href must not be blank")
+    if len(cleaned) > MAX_FOOTER_LINK_HREF_LEN:
+        raise ValueError(f"footer link href must be at most {MAX_FOOTER_LINK_HREF_LEN} characters")
+    if any(ord(ch) < 0x20 for ch in cleaned):
+        raise ValueError("footer link href must not contain control characters")
+    if "\\" in cleaned:
+        raise ValueError(FOOTER_LINK_BACKSLASH_ERROR)
+    lowered = cleaned.lower()
+    relative = cleaned.startswith("/") and not cleaned.startswith("//")
+    if not relative and not lowered.startswith(FOOTER_LINK_SCHEMES):
+        raise ValueError(FOOTER_LINK_HREF_ERROR)
+    return cleaned
+
+
+# ── Per-tenant branding (#373) ─────────────────────────────────────────
+# The fields a tenant may override for itself, as ``branding.<field>`` rows at
+# settings' TENANT scope. Deliberately not the banner (the platform's channel
+# for maintenance notices, which a tenant must not be able to silence) nor the
+# footer links (a JSON list with an XSS-relevant allow-list, kept platform-only
+# until it has a tenant-facing editor).
+TENANT_IMAGE_FIELDS: Final = ("logo_file_id", "logo_dark_file_id", "favicon_file_id")
+TENANT_FIELDS: Final = (
+    "app_name",
+    "primary_color",
+    "design_pack",
+    "footer_text",
+    *TENANT_IMAGE_FIELDS,
+)
+#: ``/api/branding/tenant/{asset}`` — upload (POST) / clear (DELETE) one of the
+#: active tenant's own images.
+PATH_TENANT_ASSET: Final = "/tenant/{asset}"
+TENANT_ASSETS: Final = {
+    "logo": "logo_file_id",
+    "logo-dark": "logo_dark_file_id",
+    "favicon": "favicon_file_id",
+}
+#: Detail of the 422 a generic settings write of a tenant image key gets.
+IMAGE_KEY_GENERIC_WRITE_ERROR: Final = (
+    "Branding images are set through /api/branding/tenant/{asset}, not the settings routes."
+)
+#: Floor for the per-tenant cache; settings' invalidation notices clear it sooner.
+TENANT_CACHE_TTL_SECONDS: Final = 30
diff --git a/modules/branding/branding/presets.py b/modules/branding/branding/core/presets.py
similarity index 100%
rename from modules/branding/branding/presets.py
rename to modules/branding/branding/core/presets.py
diff --git a/modules/branding/branding/service.py b/modules/branding/branding/core/service.py
similarity index 92%
rename from modules/branding/branding/service.py
rename to modules/branding/branding/core/service.py
index 26ac24344..48ddb23cc 100644
--- a/modules/branding/branding/service.py
+++ b/modules/branding/branding/core/service.py
@@ -10,17 +10,23 @@
 
 from typing import TYPE_CHECKING, Any, cast
 
-from branding.constants import FAVICON_URL, LOGO_DARK_URL, LOGO_URL, PACKAGE, TENANT_IMAGE_FIELDS
+from branding.assets.reaper import schedule_reap
 from branding.contracts.schemas import BrandingOut
-from branding.reaper import schedule_reap
-from branding.shared_props import asset_url
+from branding.core.constants import (
+    FAVICON_URL,
+    LOGO_DARK_URL,
+    LOGO_URL,
+    PACKAGE,
+    TENANT_IMAGE_FIELDS,
+)
+from branding.web.shared_props import asset_url
 
 if TYPE_CHECKING:
     from fastapi import FastAPI
     from file_storage.service import FileStorageService
     from sqlalchemy.ext.asyncio import AsyncSession
 
-    from branding.settings import BrandingSettings
+    from branding.core.settings import BrandingSettings
 
 
 def to_out(settings: BrandingSettings) -> BrandingOut:
@@ -84,7 +90,7 @@ async def _swap_asset(self, field: str, file_id: str) -> BrandingOut:
 
         Every upload mints a new ``file_storage`` id, so the file we stop
         referencing here would otherwise sit in the store forever. The reap is
-        queued for after the commit (:mod:`branding.reaper`): deleting the
+        queued for after the commit (:mod:`branding.assets.reaper`): deleting the
         bytes in the request would leave a rolled-back setting pointing at a
         file that is gone. A file another system image field still references
         (logo and dark logo sharing one upload) is kept.
@@ -95,7 +101,7 @@ async def _swap_asset(self, field: str, file_id: str) -> BrandingOut:
         from settings.store import SettingsStore
         from simple_module_core.settings_hydrate import hydrate_settings
 
-        from branding.settings import BrandingSettings
+        from branding.core.settings import BrandingSettings
 
         before = await hydrate_settings(
             BrandingSettings, SettingsStore(SettingService(self.db)), PACKAGE, lenient=True
diff --git a/modules/branding/branding/core/services.py b/modules/branding/branding/core/services.py
new file mode 100644
index 000000000..0dc1a6504
--- /dev/null
+++ b/modules/branding/branding/core/services.py
@@ -0,0 +1,38 @@
+"""Module-scoped state container.
+
+Stored as ``app.state.branding`` by
+:meth:`BrandingModule.register_settings` (via ``register_module_settings``).
+``settings`` is hot-swapped by ``settings.reload.apply_changes_and_reload`` when
+an admin saves changes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from branding.core.settings import BrandingSettings
+from branding.core.tenant_branding import TenantCache
+
+
+@dataclass
+class BrandingServices:
+    """Branding module singletons."""
+
+    settings: BrandingSettings
+    #: Per-app cache of tenants' merged branding (see ``tenant_branding``).
+    tenant_cache: TenantCache = field(default_factory=TenantCache)
+
+    @property
+    def favicon_url(self) -> str | None:
+        """The favicon URL, or ``None`` when no custom favicon is set.
+
+        Exposed here so the root template can emit ``<link rel="icon">`` before
+        React hydrates, without framework code learning branding's route shape:
+        ``branding_head`` reads this attribute duck-typed, exactly as it already
+        reads ``settings.app_name``. Keeps the SM009 framework→plugin boundary
+        intact — branding owns the URL, the framework only forwards it.
+        """
+        from branding.core.constants import FAVICON_URL
+        from branding.web.shared_props import asset_url
+
+        return asset_url(FAVICON_URL, self.settings.favicon_file_id)
diff --git a/modules/branding/branding/core/settings.py b/modules/branding/branding/core/settings.py
new file mode 100644
index 000000000..59e53f8eb
--- /dev/null
+++ b/modules/branding/branding/core/settings.py
@@ -0,0 +1,102 @@
+"""Branding module settings — DB-backed via ``register_module_settings``.
+
+The four values an administrator can customise (app name, logo, favicon,
+primary colour) are stored in the shared settings store at SYSTEM scope,
+hydrated into ``app.state.branding.settings`` at boot, and hot-swapped on save
+through ``settings.reload.apply_changes_and_reload``.
+
+Logo/favicon are stored as ``file_storage`` UUIDs (empty string = unset); the
+frontend derives a download URL from the id.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field, field_validator
+from pydantic_settings import SettingsConfigDict
+from simple_module_core.settings_base import DbBackedSettings
+
+from branding.contracts.schemas import FooterLink, bounded_footer_links
+from branding.core.constants import (
+    BANNER_SEVERITY_INFO,
+    DESIGN_PACK_ERROR,
+    DESIGN_PACK_RE,
+    HEX_COLOR_RE,
+    clean_app_name,
+    clean_banner_message,
+    clean_footer_text,
+    normalize_banner_severity,
+)
+
+DEFAULT_APP_NAME = "SimpleModule"
+
+
+class BrandingSettings(DbBackedSettings):
+    """Customisable application identity."""
+
+    # ``DbBackedSettings`` (not ``BaseSettings``) so the DB is genuinely the
+    # only source: omitting ``env_prefix`` would leave pydantic-settings
+    # reading each field from its bare name — GH #283.
+    model_config = SettingsConfigDict(extra="ignore")
+
+    app_name: str = DEFAULT_APP_NAME
+    primary_color: str = ""  # "" = use the theme default; otherwise "#rrggbb"
+    logo_file_id: str = ""  # file_storage UUID, "" = no custom logo
+    # Variant for the app's always-dark surfaces (sidebar, mobile bar). Unset
+    # falls back to ``logo_file_id``, so a deployment that only ever uploads one
+    # logo behaves exactly as before.
+    logo_dark_file_id: str = ""
+    favicon_file_id: str = ""  # file_storage UUID, "" = no custom favicon
+    design_pack: str = ""  # "" = base tokens only; otherwise a registered slug
+    banner_message: str = ""  # "" = no site-wide banner
+    banner_severity: str = BANNER_SEVERITY_INFO
+    # "" = show the framework's own `© {year} · MIT` caption.
+    footer_text: str = ""
+    # [] = show the framework's own links, so a deployment that never touches
+    # this keeps the footer it has today.
+    footer_links: list[FooterLink] = Field(default_factory=list)
+
+    @field_validator("footer_text")
+    @classmethod
+    def _bounded_footer_text(cls, value: str) -> str:
+        return clean_footer_text(value)
+
+    @field_validator("footer_links")
+    @classmethod
+    def _bounded_links(cls, value: list[FooterLink]) -> list[FooterLink]:
+        return bounded_footer_links(value)
+
+    @field_validator("app_name")
+    @classmethod
+    def _non_empty_name(cls, value: str) -> str:
+        return clean_app_name(value)
+
+    @field_validator("primary_color")
+    @classmethod
+    def _valid_hex(cls, value: str) -> str:
+        if value and not HEX_COLOR_RE.match(value):
+            raise ValueError("primary_color must be a #rrggbb hex string or empty")
+        return value.lower()
+
+    @field_validator("banner_message")
+    @classmethod
+    def _bounded_banner(cls, value: str) -> str:
+        return clean_banner_message(value)
+
+    @field_validator("banner_severity")
+    @classmethod
+    def _known_severity(cls, value: str) -> str:
+        # Normalise rather than reject: these hydrate from the DB at boot, where
+        # an unknown severity must degrade to a readable banner, not stop the
+        # app. The update DTO is the strict one.
+        return normalize_banner_severity(value)
+
+    @field_validator("design_pack")
+    @classmethod
+    def _valid_pack_slug(cls, value: str) -> str:
+        # Shape only — whether a module still provides this pack is checked in
+        # the endpoint. These settings are also hydrated from the DB at boot,
+        # where a pack whose module has since been uninstalled must degrade to
+        # an unstyled site rather than refuse to start.
+        if value and not DESIGN_PACK_RE.match(value):
+            raise ValueError(DESIGN_PACK_ERROR)
+        return value
diff --git a/modules/branding/branding/core/tenant_branding.py b/modules/branding/branding/core/tenant_branding.py
new file mode 100644
index 000000000..a7a04e074
--- /dev/null
+++ b/modules/branding/branding/core/tenant_branding.py
@@ -0,0 +1,242 @@
+"""Per-tenant branding: the request's tenant's overrides over the system theme (#373).
+
+Branding has no table. The system theme is ``app.state.branding.settings``
+(SYSTEM-scope settings, hydrated at boot, hot-swapped on save); a tenant's own
+values are ``branding.<field>`` rows at settings' TENANT scope, for the fields
+in ``TENANT_FIELDS``. :func:`resolve` merges the two for one request.
+
+Cost model:
+
+* ``multi_tenant`` off, or no tenant on the request — returns the system
+  object as is. No lookup, no allocation: a single-tenant install renders
+  exactly as before.
+* a tenant — one read of its override rows per :data:`TENANT_CACHE_TTL_SECONDS`
+  per process, cached by tenant id. The merged result is cached alongside and
+  rebuilt (without a read) when the system object is swapped.
+
+The cache only ever *forgets* on settings' ``settings.values`` invalidation
+notices (a tenant's ``branding.*`` row changed, or a system one — which every
+tenant inherits); the TTL is the floor when a notice is lost.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from cachetools import TTLCache
+from pydantic import ValidationError
+from simple_module_core.app_state import get_services
+
+from branding.core.constants import PACKAGE, TENANT_CACHE_TTL_SECONDS, TENANT_FIELDS
+from branding.core.settings import BrandingSettings
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from settings.service import SettingService
+    from simple_module_core.invalidation import Invalidation, InvalidationBus
+    from starlette.requests import Request
+
+logger = logging.getLogger(__name__)
+
+_PREFIX = f"{PACKAGE}."
+
+
+@dataclass(slots=True)
+class TenantCache:
+    """One app's tenant-branding cache, held as ``app.state.branding.tenant_cache``.
+
+    Per app, not per process: two apps in one process (tests, embedding) must
+    not serve each other's overrides, and an invalidation heard by one must
+    not drop the other's.
+    """
+
+    # tenant id -> (raw overrides, system object merged against, merged result)
+    entries: TTLCache[str, tuple[dict[str, str], BrandingSettings, ResolvedBranding]] = field(
+        default_factory=lambda: TTLCache(maxsize=10_000, ttl=TENANT_CACHE_TTL_SECONDS)
+    )
+    # Bumped by every forget, so a read that started before an invalidation does
+    # not store its (possibly stale) result after it.
+    epoch: int = 0
+    # tenant id -> (epoch the read started in, the read). Single-flight:
+    # concurrent misses for one tenant share one read instead of each opening a
+    # session.
+    inflight: dict[str, tuple[int, asyncio.Future[dict[str, str]]]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedBranding:
+    """The theme one request sees, and which fields its tenant supplied."""
+
+    settings: BrandingSettings
+    tenant_id: str | None = None
+    tenant_fields: frozenset[str] = field(default_factory=frozenset)
+
+    def owner_of(self, name: str) -> str | None:
+        """The tenant owning ``name``'s value, or ``None`` for the platform's."""
+        return self.tenant_id if name in self.tenant_fields else None
+
+
+def forget(app: FastAPI, tenant_id: str | None = None) -> None:
+    """Drop one tenant's entry in ``app``, or every entry when ``tenant_id`` is ``None``."""
+    cache: TenantCache = app.state.branding.tenant_cache
+    cache.epoch += 1
+    # A read already in flight may predate the change: later misses must start
+    # a fresh one rather than join it (its own waiters still get their answer).
+    if tenant_id is None:
+        cache.entries.clear()
+        cache.inflight.clear()
+    else:
+        cache.entries.pop(tenant_id, None)
+        cache.inflight.pop(tenant_id, None)
+
+
+def subscribe(bus: InvalidationBus, app: FastAPI) -> None:
+    from settings.constants import INVALIDATION_CHANNEL
+    from settings.contracts.invalidation import parse_invalidation_key
+
+    def on_settings_changed(inv: Invalidation) -> None:
+        tenant_id, key = parse_invalidation_key(inv.key)
+        if key is not None and not key.startswith(_PREFIX):
+            return  # someone else's setting
+        # A system value is inherited by every tenant without its own override.
+        forget(app, tenant_id)
+
+    bus.subscribe(INVALIDATION_CHANNEL, on_settings_changed)
+
+
+def tenancy_active(app: FastAPI) -> bool:
+    settings = getattr(get_services(app), "settings", None)
+    return bool(getattr(settings, "multi_tenant", False))
+
+
+def request_tenant(request: Request) -> str | None:
+    """The tenant whose branding this request sees; ``None`` means the system's."""
+    if not tenancy_active(request.app):
+        return None
+    return getattr(request.state, "tenant_id", None) or None
+
+
+async def overrides_from(service: SettingService, tenant_id: str) -> dict[str, str]:
+    """The tenant's ``TENANT_FIELDS`` overrides, as seen by ``service``'s session."""
+    from settings.contracts.schemas import SettingScope
+
+    rows = await service.list_by_scope_unmasked(SettingScope.TENANT, tenant_id)
+    out: dict[str, str] = {}
+    for row in rows:
+        name = row.key.removeprefix(_PREFIX)
+        if row.key.startswith(_PREFIX) and name in TENANT_FIELDS:
+            out[name] = row.value
+    return out
+
+
+async def read_overrides(app: FastAPI, tenant_id: str) -> dict[str, str]:
+    """:func:`overrides_from` on a short-lived session of its own.
+
+    Only for reads ahead of a request's own work (shared props, the asset
+    routes): a request that has already written must use its own session.
+    """
+    from settings.service import SettingService
+
+    async with app.state.sm.db.session_factory() as db:
+        return await overrides_from(SettingService(db), tenant_id)
+
+
+def merge(system: BrandingSettings, tenant_id: str, overrides: dict[str, str]) -> ResolvedBranding:
+    """``system`` with ``overrides`` on top; a value that fails validation is dropped.
+
+    Writes are validated, so a bad value means a hand-edited row — it must
+    degrade to the system value for that field, not break every page render.
+
+    An empty-string override is *unset*: the field inherits the platform's
+    value. To go back to inheriting, delete the override; storing ``""`` has
+    the same effect rather than blanking the platform's value.
+
+    The dark logo is paired with the light one: a tenant that overrides the
+    logo but not the dark logo must not be shown the *platform's* dark logo
+    beside its own logo, so the inherited dark logo is dropped and dark
+    surfaces fall back to the tenant's logo.
+    """
+    good = {name: value for name, value in overrides.items() if value != ""}
+    base: dict[str, Any] = system.model_dump()
+    while good:
+        try:
+            values: dict[str, Any] = {**base, **good}
+            if "logo_file_id" in good and "logo_dark_file_id" not in good:
+                values["logo_dark_file_id"] = ""
+            merged = BrandingSettings(**values)
+            return ResolvedBranding(merged, tenant_id, frozenset(good))
+        except ValidationError as exc:
+            bad = {str(err["loc"][0]) for err in exc.errors() if err.get("loc")}
+            logger.warning("Tenant %s branding override(s) %s are invalid.", tenant_id, bad)
+            if not bad & good.keys():
+                break
+            for name in bad:
+                good.pop(name, None)
+    return ResolvedBranding(system, tenant_id, frozenset())
+
+
+def _shared_read(
+    app: FastAPI, cache: TenantCache, tenant_id: str
+) -> tuple[int, asyncio.Future[dict[str, str]]]:
+    """The in-flight override read for ``tenant_id``, started if there is none."""
+    entry = cache.inflight.get(tenant_id)
+    if entry is not None:
+        return entry
+    read = asyncio.ensure_future(read_overrides(app, tenant_id))
+    entry = (cache.epoch, read)
+    cache.inflight[tenant_id] = entry
+
+    def _done(fut: asyncio.Future[dict[str, str]]) -> None:
+        # Retrieve the outcome so a failed read whose every waiter was
+        # cancelled never logs "exception was never retrieved".
+        if not fut.cancelled():
+            fut.exception()
+        if cache.inflight.get(tenant_id) is entry:
+            del cache.inflight[tenant_id]
+
+    read.add_done_callback(_done)
+    return entry
+
+
+async def resolve_for(app: FastAPI, tenant_id: str | None) -> ResolvedBranding:
+    system: BrandingSettings = app.state.branding.settings
+    if not tenant_id:
+        return ResolvedBranding(system)
+    cache: TenantCache = app.state.branding.tenant_cache
+    hit = cache.entries.get(tenant_id)
+    if hit is not None:
+        overrides, merged_against, resolved = hit
+        if merged_against is system:
+            return resolved
+    else:
+        started, read = _shared_read(app, cache, tenant_id)
+        # Shielded: one waiter being cancelled must not cancel everyone's read.
+        overrides = await asyncio.shield(read)
+        if cache.epoch != started:
+            return merge(system, tenant_id, overrides)  # don't cache a racing read
+    resolved = merge(system, tenant_id, overrides)
+    cache.entries[tenant_id] = (overrides, system, resolved)
+    return resolved
+
+
+async def resolve(request: Request) -> ResolvedBranding:
+    """The branding ``request`` sees: its tenant's, falling back to the system's."""
+    return await resolve_for(request.app, request_tenant(request))
+
+
+__all__ = [
+    "ResolvedBranding",
+    "TenantCache",
+    "forget",
+    "merge",
+    "overrides_from",
+    "read_overrides",
+    "request_tenant",
+    "resolve",
+    "resolve_for",
+    "subscribe",
+    "tenancy_active",
+]
diff --git a/modules/branding/branding/tenant_definitions.py b/modules/branding/branding/core/tenant_definitions.py
similarity index 98%
rename from modules/branding/branding/tenant_definitions.py
rename to modules/branding/branding/core/tenant_definitions.py
index 53ba7a170..c4c2b19a7 100644
--- a/modules/branding/branding/tenant_definitions.py
+++ b/modules/branding/branding/core/tenant_definitions.py
@@ -31,7 +31,7 @@
 from pydantic import ValidationError
 from simple_module_core.app_state import get_design_packs
 
-from branding.constants import (
+from branding.core.constants import (
     IMAGE_KEY_GENERIC_WRITE_ERROR,
     PACKAGE,
     ROUTE_PREFIX,
@@ -39,7 +39,7 @@
     TENANT_FIELDS,
     TENANT_IMAGE_FIELDS,
 )
-from branding.settings import BrandingSettings
+from branding.core.settings import BrandingSettings
 
 if TYPE_CHECKING:
     from fastapi import FastAPI
diff --git a/modules/branding/branding/endpoints/__init__.py b/modules/branding/branding/endpoints/__init__.py
index e69de29bb..2b3685b41 100644
--- a/modules/branding/branding/endpoints/__init__.py
+++ b/modules/branding/branding/endpoints/__init__.py
@@ -0,0 +1 @@
+"""Deprecated package path: the endpoints moved to :mod:`branding.web.endpoints` (module layout)."""
diff --git a/modules/branding/branding/endpoints/assets.py b/modules/branding/branding/endpoints/assets.py
index 24e86c826..b5fb4e763 100644
--- a/modules/branding/branding/endpoints/assets.py
+++ b/modules/branding/branding/endpoints/assets.py
@@ -1,187 +1,13 @@
-"""Anonymous branding image routes — the logo and favicon a guest must see.
-
-These are the only unauthenticated routes branding registers. They resolve the
-file id from ``app.state.branding.settings`` and stream that one file, so they
-expose exactly the two images an administrator designated as public branding
-and nothing else in ``file_storage``.
-
-Which image, and whose (#373): the request's tenant — from the subdomain for
-an anonymous visitor, the active organisation for a member — else the system.
-The file id is never taken from the request (``?v=`` is only a cache key):
-
-* a value the **tenant** set is read as that tenant's file — under
-  ``tenant_context(tenant)``, so only a row the tenant owns matches;
-* a **system** value is read as a *platform* file (``platform=True``): an
-  ``all_tenants()`` lookup restricted to rows owned by
-  ``file_storage.scope.PLATFORM_TENANT_ID``.
-
-Either way a setting pointed at someone else's file id serves a 404, never
-their file.
-"""
+"""Moved to :mod:`branding.web.endpoints.assets`; this alias goes in 0.0.46 (module layout)."""
 
 from __future__ import annotations
 
-import logging
-import uuid
-
-from fastapi import APIRouter, Depends, HTTPException, Request
-from fastapi.responses import RedirectResponse, StreamingResponse
-from file_storage.deps import get_file_storage_service
-from file_storage.service import (
-    FileStorageService,
-    RedirectDownload,
-    StoredFileNotFoundError,
-    StreamDownload,
-)
-from simple_module_db import tenant_context
-
-from branding import constants
-from branding.images import ALLOWED_IMAGE_TYPES, normalize_content_type
-from branding.tenant_branding import ResolvedBranding, resolve
-
-router = APIRouter()
-
-logger = logging.getLogger(__name__)
-
-
-def _cache_headers(request: Request, file_id: uuid.UUID, tenant_id: str | None) -> dict[str, str]:
-    """Shared caching only where the URL alone determines the bytes.
-
-    ``tenant_id`` is the *request's* tenant. The same URL answers per tenant
-    (session, tenant header or subdomain), and a shared cache keys on the URL
-    alone — so only a request with **no** tenant, whose ``?v=`` names the very
-    file served (a content address), may be stored ``public`` and pinned for a
-    year. Everything else is ``private``: a request with a tenant is pinned in
-    the browser only when ``?v=`` matches, varying on what selects the tenant
-    (the session cookie, the tenant header); an unversioned or stale ``?v=`` is
-    ``no-cache``, so the next page — maybe in another organisation — revalidates.
-    """
-    version = request.query_params.get(constants.ASSET_VERSION_QUERY_KEY)
-    matches = bool(version) and version == str(file_id)
-    if tenant_id is None:
-        if matches:
-            return {
-                "Cache-Control": f"public, max-age={constants.ASSET_MAX_AGE_VERSIONED}, immutable"
-            }
-        return {"Cache-Control": "private, no-cache"}
-    if matches:
-        headers = {
-            "Cache-Control": f"private, max-age={constants.ASSET_MAX_AGE_VERSIONED}, immutable"
-        }
-    else:
-        headers = {"Cache-Control": "private, no-cache"}
-    # What selects the tenant: the session cookie and the tenant header (a
-    # subdomain is part of the cache key already). The session middleware adds
-    # ``Cookie`` itself when this request read the session, so it is named
-    # here only otherwise — never twice.
-    session = request.scope.get("session")
-    vary = [] if getattr(session, "accessed", False) else ["Cookie"]
-    if header := getattr(request.app.state.sm.settings, "tenant_header", "") or "":
-        vary.append(header)
-    if vary:
-        headers["Vary"] = ", ".join(vary)
-    return headers
-
+import importlib
+import sys
 
-def _configured_file_id(resolved: ResolvedBranding, field: str) -> uuid.UUID:
-    raw = getattr(resolved.settings, field, "")
-    if not raw:
-        raise HTTPException(status_code=404, detail="No branding image is set.")
-    try:
-        return uuid.UUID(raw)
-    except ValueError as exc:
-        # Settings are hydrated from the DB, so a hand-edited row can hold junk.
-        # A broken image beats a 500 on the sign-in page.
-        logger.warning("Branding %s holds a non-UUID value %r.", field, raw)
-        raise HTTPException(status_code=404, detail="No branding image is set.") from exc
+from simple_module_core.deprecation import deprecated_module
 
-
-async def _download(storage: FileStorageService, file_id: uuid.UUID, owner: str | None):
-    """The file as its owner sees it: a platform file when ``owner`` is ``None``."""
-    if owner is None:
-        return await storage.download(file_id, platform=True)
-    with tenant_context(owner):
-        return await storage.download(file_id)
-
-
-async def _serve(
-    request: Request, storage: FileStorageService, field: str
-) -> RedirectResponse | StreamingResponse:
-    if getattr(request.app.state, "branding", None) is None:
-        raise HTTPException(status_code=404, detail="No branding image is set.")
-    resolved = await resolve(request)
-    file_id = _configured_file_id(resolved, field)
-    request_tenant = resolved.tenant_id
-    owner = resolved.owner_of(field)
-    try:
-        download = await _download(storage, file_id, owner)
-    except StoredFileNotFoundError as exc:
-        if owner is None:
-            # Referenced file went away underneath us. 404 uncached, so the next
-            # request retries once the setting is fixed rather than caching a miss.
-            logger.warning("Branding %s references missing file %s.", field, file_id)
-            raise HTTPException(status_code=404, detail="Branding image is unavailable.") from exc
-        # The tenant's own image was deleted (through the Files API, say) while
-        # its override still names it. Show the platform's image instead of a
-        # dead one; the override is left for the tenant to replace or reset.
-        logger.warning("Tenant %s branding %s references missing file %s.", owner, field, file_id)
-        file_id = _configured_file_id(ResolvedBranding(request.app.state.branding.settings), field)
-        try:
-            download = await _download(storage, file_id, None)
-        except StoredFileNotFoundError as missing:
-            raise HTTPException(
-                status_code=404, detail="Branding image is unavailable."
-            ) from missing
-
-    if normalize_content_type(download.file.content_type) not in ALLOWED_IMAGE_TYPES:
-        # Uploads are validated, so this is a hand-edited (or pre-validation)
-        # setting naming some other file: never serve it as branding.
-        logger.warning("Branding %s references non-image file %s.", field, file_id)
-        raise HTTPException(status_code=404, detail="Branding image is unavailable.")
-
-    if isinstance(download, RedirectDownload):
-        # Deliberately uncached: the target is a presigned URL that expires, so
-        # caching the redirect would hand out a dead link after the TTL.
-        return RedirectResponse(url=download.url, status_code=302)
-
-    assert isinstance(download, StreamDownload)
-    row = download.file
-    return StreamingResponse(
-        download.body,
-        media_type=row.content_type,
-        headers={
-            **_cache_headers(request, file_id, request_tenant),
-            "Content-Length": str(row.size_bytes),
-            "ETag": f'"{row.checksum_sha256}"',
-            # `attachment` is ignored for subresource loads (<img>, <link
-            # rel="icon">) but stops a direct visit rendering the bytes as a
-            # document at our origin; `nosniff` pins the declared type. The
-            # upload allow-list already excludes SVG — this is the second layer.
-            "Content-Disposition": "attachment",
-            "X-Content-Type-Options": "nosniff",
-        },
-    )
-
-
-@router.get(constants.PATH_LOGO, response_model=None)
-async def serve_logo(
-    request: Request,
-    storage: FileStorageService = Depends(get_file_storage_service),
-) -> RedirectResponse | StreamingResponse:
-    return await _serve(request, storage, "logo_file_id")
-
-
-@router.get(constants.PATH_LOGO_DARK, response_model=None)
-async def serve_logo_dark(
-    request: Request,
-    storage: FileStorageService = Depends(get_file_storage_service),
-) -> RedirectResponse | StreamingResponse:
-    return await _serve(request, storage, "logo_dark_file_id")
-
-
-@router.get(constants.PATH_FAVICON, response_model=None)
-async def serve_favicon(
-    request: Request,
-    storage: FileStorageService = Depends(get_file_storage_service),
-) -> RedirectResponse | StreamingResponse:
-    return await _serve(request, storage, "favicon_file_id")
+deprecated_module(
+    "branding.endpoints.assets", remove_in="0.0.46", use="branding.web.endpoints.assets"
+)
+sys.modules[__name__] = importlib.import_module("branding.web.endpoints.assets")
diff --git a/modules/branding/branding/images.py b/modules/branding/branding/images.py
index eb1323631..f4fa4abdf 100644
--- a/modules/branding/branding/images.py
+++ b/modules/branding/branding/images.py
@@ -1,121 +1,11 @@
-"""Upload validation for branding images.
-
-The declared ``Content-Type`` on a multipart part is chosen by the caller, so
-it is a claim rather than a fact. An admin who uploads ``payload.html`` renamed
-``logo.png`` would otherwise have it stored and later served back under an
-``image/*`` type. Every accepted format therefore has to also *look* like
-itself in its first bytes.
-
-Mirrors the allow-list and signature check in the IIASA.GeoWiki Branding module
-(``GeoWikiBrandingConsts``), including its deliberate omission of SVG.
-"""
+"""Moved to :mod:`branding.assets.images`; this alias goes in 0.0.46 (module layout)."""
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Final
-
-from fastapi import HTTPException, UploadFile
-
-if TYPE_CHECKING:
-    from file_storage.contracts.schemas import StoredFileOut
-    from file_storage.service import FileStorageService
-
-# Raster + icon only. SVG is excluded on purpose: it is an XML document that can
-# carry <script>, so serving one back from our own origin would be stored XSS.
-# The asset route defends in depth (attachment + nosniff), but the narrower
-# allow-list is what actually keeps executable markup out of the store.
-ALLOWED_IMAGE_TYPES: Final = frozenset(
-    {
-        "image/png",
-        "image/jpeg",
-        "image/webp",
-        "image/gif",
-        "image/x-icon",
-        "image/vnd.microsoft.icon",
-    }
-)
-
-MAX_IMAGE_BYTES: Final = 2 * 1024 * 1024  # 2 MB
-
-ALLOWED_IMAGE_HINT: Final = "Allowed: PNG, JPEG, WEBP, GIF, ICO."
-
-# Enough for the longest signature we test (WEBP needs 12 bytes).
-_PROBE_BYTES: Final = 16
-
-# (offset, literal) pairs; a format matches when every pair matches.
-_SIGNATURES: Final[tuple[tuple[tuple[int, bytes], ...], ...]] = (
-    ((0, b"\x89PNG\r\n\x1a\n"),),  # PNG
-    ((0, b"\xff\xd8\xff"),),  # JPEG
-    ((0, b"GIF87a"),),  # GIF
-    ((0, b"GIF89a"),),
-    ((0, b"RIFF"), (8, b"WEBP")),  # WEBP
-    ((0, b"\x00\x00\x01\x00"),),  # ICO (Windows icon resource)
-)
-
-
-def normalize_content_type(raw: str | None) -> str:
-    """Strip any ``; charset=…`` parameter and lowercase the media type."""
-    if not raw:
-        return ""
-    return raw.split(";", 1)[0].strip().lower()
-
-
-def has_recognized_image_signature(head: bytes) -> bool:
-    """True when ``head`` starts with the magic number of an allowed format."""
-    return any(
-        all(head[at : at + len(literal)] == literal for at, literal in signature)
-        for signature in _SIGNATURES
-    )
-
-
-async def validate_image(file: UploadFile) -> None:
-    """Reject anything that isn't a small, genuine raster/icon image.
-
-    Leaves ``file`` rewound to the start so the caller can hand it straight to
-    ``file_storage``.
-    """
-    content_type = normalize_content_type(file.content_type)
-    if content_type not in ALLOWED_IMAGE_TYPES:
-        raise HTTPException(
-            status_code=415,
-            detail=f"Unsupported image type {content_type or 'unknown'!r}. {ALLOWED_IMAGE_HINT}",
-        )
-
-    # ``size`` is populated by Starlette's multipart parser. When it isn't (a
-    # non-multipart caller), file_storage still enforces its own ceiling, so
-    # this stays an early, friendlier guard rather than the only one.
-    if file.size is not None and file.size > MAX_IMAGE_BYTES:
-        raise HTTPException(
-            status_code=413,
-            detail=f"Image exceeds {MAX_IMAGE_BYTES} bytes.",
-        )
-
-    head = await file.read(_PROBE_BYTES)
-    await file.seek(0)
-    if not has_recognized_image_signature(head):
-        raise HTTPException(
-            status_code=415,
-            detail=(
-                f"File does not look like an image — its content does not match "
-                f"{content_type!r}. {ALLOWED_IMAGE_HINT}"
-            ),
-        )
-
-
-async def store_image(
-    storage: FileStorageService, file: UploadFile, *, platform: bool = False
-) -> StoredFileOut:
-    """Hand a validated image to ``file_storage``, answering 413 when the quota is full.
+import importlib
+import sys
 
-    ``file_storage`` enforces ``quota_bytes`` on every upload; its own endpoint
-    maps the refusal to 413, but branding calls the service directly, so an
-    unmapped ``QuotaExceededError`` would surface as a 500.
-    """
-    from file_storage.upload_support import QuotaExceededError
+from simple_module_core.deprecation import deprecated_module
 
-    try:
-        return await storage.upload(file, platform=platform)
-    except QuotaExceededError:
-        raise HTTPException(
-            status_code=413, detail="The storage quota is full; the image was not saved."
-        ) from None
+deprecated_module("branding.images", remove_in="0.0.46", use="branding.assets.images")
+sys.modules[__name__] = importlib.import_module("branding.assets.images")
diff --git a/modules/branding/branding/module.py b/modules/branding/branding/module.py
index 12a941114..cb35c49dd 100644
--- a/modules/branding/branding/module.py
+++ b/modules/branding/branding/module.py
@@ -17,8 +17,8 @@
 from simple_module_core.permissions import PermissionRegistry
 from simple_module_core.public_routes import PublicRouteRegistry
 
-from branding import constants
-from branding.constants import MENU_URL
+from branding.core import constants
+from branding.core.constants import MENU_URL
 
 if TYPE_CHECKING:
     from simple_module_core.invalidation import InvalidationBus
@@ -38,8 +38,8 @@ class BrandingModule(ModuleBase):
     def register_settings(self, app: FastAPI) -> None:
         from simple_module_core.module_settings import register_module_settings
 
-        from branding.services import BrandingServices
-        from branding.settings import BrandingSettings
+        from branding.core.services import BrandingServices
+        from branding.core.settings import BrandingSettings
 
         register_module_settings(
             app,
@@ -52,12 +52,12 @@ def register_settings(self, app: FastAPI) -> None:
         )
         # Tenants may override a subset for themselves (#373), through
         # settings' tenant surface; resolved per request by tenant_branding.
-        from branding.tenant_definitions import register_tenant_definitions
+        from branding.core.tenant_definitions import register_tenant_definitions
 
         register_tenant_definitions(app)
 
     def register_invalidations(self, bus: InvalidationBus, app: FastAPI) -> None:
-        from branding.tenant_branding import subscribe
+        from branding.core.tenant_branding import subscribe
 
         subscribe(bus, app)
 
@@ -97,10 +97,10 @@ def register_menu_items(self, registry: MenuRegistry) -> None:
         )
 
     def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
-        from branding.endpoints.api import router as api
-        from branding.endpoints.assets import router as assets
-        from branding.endpoints.tenant_api import router as tenant_api
-        from branding.endpoints.views import router as views
+        from branding.web.endpoints.api import router as api
+        from branding.web.endpoints.assets import router as assets
+        from branding.web.endpoints.tenant_api import router as tenant_api
+        from branding.web.endpoints.views import router as views
 
         api_router.include_router(api)
         # Tenant owners/admins upload their organisation's own images (#373).
@@ -113,7 +113,7 @@ def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None
     async def on_startup(self, app: FastAPI) -> None:
         from simple_module_hosting.shared_props import register_inertia_shared_provider
 
-        from branding.shared_props import branding_shared_props
+        from branding.web.shared_props import branding_shared_props
 
         register_inertia_shared_provider(app, branding_shared_props)
 
diff --git a/modules/branding/branding/pages/Manage.tsx b/modules/branding/branding/pages/Manage.tsx
index e30be7ec8..194e30d32 100644
--- a/modules/branding/branding/pages/Manage.tsx
+++ b/modules/branding/branding/pages/Manage.tsx
@@ -10,15 +10,15 @@ import { type ApiResult, apiFetch, apiResult } from '@simple-module-py/ui/lib/ap
 import type { SharedProps } from '@simple-module-py/ui/types';
 import { useMemo, useState } from 'react';
 import { toast } from 'sonner';
-import { BannerField, type BannerSeverity } from '../components/BannerField';
-import { ColorField } from '../components/ColorField';
-import { DesignPackField, type DesignPackOption } from '../components/DesignPackField';
-import { type BrandingForm, countBrandingChanges } from '../components/dirty';
-import { FooterField } from '../components/FooterField';
-import { isValidColor, normalizeHex } from '../components/hex';
-import { ImageDropzones, type ImageKind } from '../components/ImageDropzones';
-import { PresetField, type PresetOption } from '../components/PresetField';
-import { PreviewTabs } from '../components/PreviewTabs';
+import { BannerField, type BannerSeverity } from '../ui/components/BannerField';
+import { ColorField } from '../ui/components/ColorField';
+import { DesignPackField, type DesignPackOption } from '../ui/components/DesignPackField';
+import { type BrandingForm, countBrandingChanges } from '../ui/components/dirty';
+import { FooterField } from '../ui/components/FooterField';
+import { isValidColor, normalizeHex } from '../ui/components/hex';
+import { ImageDropzones, type ImageKind } from '../ui/components/ImageDropzones';
+import { PresetField, type PresetOption } from '../ui/components/PresetField';
+import { PreviewTabs } from '../ui/components/PreviewTabs';
 import { api } from './api';
 
 /** Matches `BUILTIN_PRESETS[0]` in `branding/presets.py`. */
diff --git a/modules/branding/branding/services.py b/modules/branding/branding/services.py
index df6f0564b..eb140d3ed 100644
--- a/modules/branding/branding/services.py
+++ b/modules/branding/branding/services.py
@@ -1,38 +1,11 @@
-"""Module-scoped state container.
-
-Stored as ``app.state.branding`` by
-:meth:`BrandingModule.register_settings` (via ``register_module_settings``).
-``settings`` is hot-swapped by ``settings.reload.apply_changes_and_reload`` when
-an admin saves changes.
-"""
+"""Moved to :mod:`branding.core.services`; this alias goes in 0.0.46 (module layout)."""
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
-
-from branding.settings import BrandingSettings
-from branding.tenant_branding import TenantCache
-
-
-@dataclass
-class BrandingServices:
-    """Branding module singletons."""
-
-    settings: BrandingSettings
-    #: Per-app cache of tenants' merged branding (see ``tenant_branding``).
-    tenant_cache: TenantCache = field(default_factory=TenantCache)
-
-    @property
-    def favicon_url(self) -> str | None:
-        """The favicon URL, or ``None`` when no custom favicon is set.
+import importlib
+import sys
 
-        Exposed here so the root template can emit ``<link rel="icon">`` before
-        React hydrates, without framework code learning branding's route shape:
-        ``branding_head`` reads this attribute duck-typed, exactly as it already
-        reads ``settings.app_name``. Keeps the SM009 framework→plugin boundary
-        intact — branding owns the URL, the framework only forwards it.
-        """
-        from branding.constants import FAVICON_URL
-        from branding.shared_props import asset_url
+from simple_module_core.deprecation import deprecated_module
 
-        return asset_url(FAVICON_URL, self.settings.favicon_file_id)
+deprecated_module("branding.services", remove_in="0.0.46", use="branding.core.services")
+sys.modules[__name__] = importlib.import_module("branding.core.services")
diff --git a/modules/branding/branding/settings.py b/modules/branding/branding/settings.py
index e277a4a89..e8d5d0802 100644
--- a/modules/branding/branding/settings.py
+++ b/modules/branding/branding/settings.py
@@ -1,102 +1,11 @@
-"""Branding module settings — DB-backed via ``register_module_settings``.
-
-The four values an administrator can customise (app name, logo, favicon,
-primary colour) are stored in the shared settings store at SYSTEM scope,
-hydrated into ``app.state.branding.settings`` at boot, and hot-swapped on save
-through ``settings.reload.apply_changes_and_reload``.
-
-Logo/favicon are stored as ``file_storage`` UUIDs (empty string = unset); the
-frontend derives a download URL from the id.
-"""
+"""Moved to :mod:`branding.core.settings`; this alias goes in 0.0.46 (module layout)."""
 
 from __future__ import annotations
 
-from pydantic import Field, field_validator
-from pydantic_settings import SettingsConfigDict
-from simple_module_core.settings_base import DbBackedSettings
-
-from branding.constants import (
-    BANNER_SEVERITY_INFO,
-    DESIGN_PACK_ERROR,
-    DESIGN_PACK_RE,
-    HEX_COLOR_RE,
-    clean_app_name,
-    clean_banner_message,
-    clean_footer_text,
-    normalize_banner_severity,
-)
-from branding.contracts.schemas import FooterLink, bounded_footer_links
-
-DEFAULT_APP_NAME = "SimpleModule"
-
-
-class BrandingSettings(DbBackedSettings):
-    """Customisable application identity."""
-
-    # ``DbBackedSettings`` (not ``BaseSettings``) so the DB is genuinely the
-    # only source: omitting ``env_prefix`` would leave pydantic-settings
-    # reading each field from its bare name — GH #283.
-    model_config = SettingsConfigDict(extra="ignore")
-
-    app_name: str = DEFAULT_APP_NAME
-    primary_color: str = ""  # "" = use the theme default; otherwise "#rrggbb"
-    logo_file_id: str = ""  # file_storage UUID, "" = no custom logo
-    # Variant for the app's always-dark surfaces (sidebar, mobile bar). Unset
-    # falls back to ``logo_file_id``, so a deployment that only ever uploads one
-    # logo behaves exactly as before.
-    logo_dark_file_id: str = ""
-    favicon_file_id: str = ""  # file_storage UUID, "" = no custom favicon
-    design_pack: str = ""  # "" = base tokens only; otherwise a registered slug
-    banner_message: str = ""  # "" = no site-wide banner
-    banner_severity: str = BANNER_SEVERITY_INFO
-    # "" = show the framework's own `© {year} · MIT` caption.
-    footer_text: str = ""
-    # [] = show the framework's own links, so a deployment that never touches
-    # this keeps the footer it has today.
-    footer_links: list[FooterLink] = Field(default_factory=list)
-
-    @field_validator("footer_text")
-    @classmethod
-    def _bounded_footer_text(cls, value: str) -> str:
-        return clean_footer_text(value)
-
-    @field_validator("footer_links")
-    @classmethod
-    def _bounded_links(cls, value: list[FooterLink]) -> list[FooterLink]:
-        return bounded_footer_links(value)
-
-    @field_validator("app_name")
-    @classmethod
-    def _non_empty_name(cls, value: str) -> str:
-        return clean_app_name(value)
-
-    @field_validator("primary_color")
-    @classmethod
-    def _valid_hex(cls, value: str) -> str:
-        if value and not HEX_COLOR_RE.match(value):
-            raise ValueError("primary_color must be a #rrggbb hex string or empty")
-        return value.lower()
-
-    @field_validator("banner_message")
-    @classmethod
-    def _bounded_banner(cls, value: str) -> str:
-        return clean_banner_message(value)
+import importlib
+import sys
 
-    @field_validator("banner_severity")
-    @classmethod
-    def _known_severity(cls, value: str) -> str:
-        # Normalise rather than reject: these hydrate from the DB at boot, where
-        # an unknown severity must degrade to a readable banner, not stop the
-        # app. The update DTO is the strict one.
-        return normalize_banner_severity(value)
+from simple_module_core.deprecation import deprecated_module
 
-    @field_validator("design_pack")
-    @classmethod
-    def _valid_pack_slug(cls, value: str) -> str:
-        # Shape only — whether a module still provides this pack is checked in
-        # the endpoint. These settings are also hydrated from the DB at boot,
-        # where a pack whose module has since been uninstalled must degrade to
-        # an unstyled site rather than refuse to start.
-        if value and not DESIGN_PACK_RE.match(value):
-            raise ValueError(DESIGN_PACK_ERROR)
-        return value
+deprecated_module("branding.settings", remove_in="0.0.46", use="branding.core.settings")
+sys.modules[__name__] = importlib.import_module("branding.core.settings")
diff --git a/modules/branding/branding/tenant_branding.py b/modules/branding/branding/tenant_branding.py
index d4a93a33f..91f3d3215 100644
--- a/modules/branding/branding/tenant_branding.py
+++ b/modules/branding/branding/tenant_branding.py
@@ -1,242 +1,13 @@
-"""Per-tenant branding: the request's tenant's overrides over the system theme (#373).
-
-Branding has no table. The system theme is ``app.state.branding.settings``
-(SYSTEM-scope settings, hydrated at boot, hot-swapped on save); a tenant's own
-values are ``branding.<field>`` rows at settings' TENANT scope, for the fields
-in ``TENANT_FIELDS``. :func:`resolve` merges the two for one request.
-
-Cost model:
-
-* ``multi_tenant`` off, or no tenant on the request — returns the system
-  object as is. No lookup, no allocation: a single-tenant install renders
-  exactly as before.
-* a tenant — one read of its override rows per :data:`TENANT_CACHE_TTL_SECONDS`
-  per process, cached by tenant id. The merged result is cached alongside and
-  rebuilt (without a read) when the system object is swapped.
-
-The cache only ever *forgets* on settings' ``settings.values`` invalidation
-notices (a tenant's ``branding.*`` row changed, or a system one — which every
-tenant inherits); the TTL is the floor when a notice is lost.
-"""
+"""Moved to :mod:`branding.core.tenant_branding`; this alias goes in 0.0.46 (module layout)."""
 
 from __future__ import annotations
 
-import asyncio
-import logging
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
-
-from cachetools import TTLCache
-from pydantic import ValidationError
-from simple_module_core.app_state import get_services
-
-from branding.constants import PACKAGE, TENANT_CACHE_TTL_SECONDS, TENANT_FIELDS
-from branding.settings import BrandingSettings
-
-if TYPE_CHECKING:
-    from fastapi import FastAPI
-    from settings.service import SettingService
-    from simple_module_core.invalidation import Invalidation, InvalidationBus
-    from starlette.requests import Request
-
-logger = logging.getLogger(__name__)
-
-_PREFIX = f"{PACKAGE}."
-
-
-@dataclass(slots=True)
-class TenantCache:
-    """One app's tenant-branding cache, held as ``app.state.branding.tenant_cache``.
-
-    Per app, not per process: two apps in one process (tests, embedding) must
-    not serve each other's overrides, and an invalidation heard by one must
-    not drop the other's.
-    """
-
-    # tenant id -> (raw overrides, system object merged against, merged result)
-    entries: TTLCache[str, tuple[dict[str, str], BrandingSettings, ResolvedBranding]] = field(
-        default_factory=lambda: TTLCache(maxsize=10_000, ttl=TENANT_CACHE_TTL_SECONDS)
-    )
-    # Bumped by every forget, so a read that started before an invalidation does
-    # not store its (possibly stale) result after it.
-    epoch: int = 0
-    # tenant id -> (epoch the read started in, the read). Single-flight:
-    # concurrent misses for one tenant share one read instead of each opening a
-    # session.
-    inflight: dict[str, tuple[int, asyncio.Future[dict[str, str]]]] = field(default_factory=dict)
-
-
-@dataclass(frozen=True, slots=True)
-class ResolvedBranding:
-    """The theme one request sees, and which fields its tenant supplied."""
-
-    settings: BrandingSettings
-    tenant_id: str | None = None
-    tenant_fields: frozenset[str] = field(default_factory=frozenset)
-
-    def owner_of(self, name: str) -> str | None:
-        """The tenant owning ``name``'s value, or ``None`` for the platform's."""
-        return self.tenant_id if name in self.tenant_fields else None
-
-
-def forget(app: FastAPI, tenant_id: str | None = None) -> None:
-    """Drop one tenant's entry in ``app``, or every entry when ``tenant_id`` is ``None``."""
-    cache: TenantCache = app.state.branding.tenant_cache
-    cache.epoch += 1
-    # A read already in flight may predate the change: later misses must start
-    # a fresh one rather than join it (its own waiters still get their answer).
-    if tenant_id is None:
-        cache.entries.clear()
-        cache.inflight.clear()
-    else:
-        cache.entries.pop(tenant_id, None)
-        cache.inflight.pop(tenant_id, None)
-
-
-def subscribe(bus: InvalidationBus, app: FastAPI) -> None:
-    from settings.constants import INVALIDATION_CHANNEL
-    from settings.contracts.invalidation import parse_invalidation_key
-
-    def on_settings_changed(inv: Invalidation) -> None:
-        tenant_id, key = parse_invalidation_key(inv.key)
-        if key is not None and not key.startswith(_PREFIX):
-            return  # someone else's setting
-        # A system value is inherited by every tenant without its own override.
-        forget(app, tenant_id)
-
-    bus.subscribe(INVALIDATION_CHANNEL, on_settings_changed)
-
-
-def tenancy_active(app: FastAPI) -> bool:
-    settings = getattr(get_services(app), "settings", None)
-    return bool(getattr(settings, "multi_tenant", False))
-
-
-def request_tenant(request: Request) -> str | None:
-    """The tenant whose branding this request sees; ``None`` means the system's."""
-    if not tenancy_active(request.app):
-        return None
-    return getattr(request.state, "tenant_id", None) or None
-
-
-async def overrides_from(service: SettingService, tenant_id: str) -> dict[str, str]:
-    """The tenant's ``TENANT_FIELDS`` overrides, as seen by ``service``'s session."""
-    from settings.contracts.schemas import SettingScope
-
-    rows = await service.list_by_scope_unmasked(SettingScope.TENANT, tenant_id)
-    out: dict[str, str] = {}
-    for row in rows:
-        name = row.key.removeprefix(_PREFIX)
-        if row.key.startswith(_PREFIX) and name in TENANT_FIELDS:
-            out[name] = row.value
-    return out
-
-
-async def read_overrides(app: FastAPI, tenant_id: str) -> dict[str, str]:
-    """:func:`overrides_from` on a short-lived session of its own.
-
-    Only for reads ahead of a request's own work (shared props, the asset
-    routes): a request that has already written must use its own session.
-    """
-    from settings.service import SettingService
-
-    async with app.state.sm.db.session_factory() as db:
-        return await overrides_from(SettingService(db), tenant_id)
-
-
-def merge(system: BrandingSettings, tenant_id: str, overrides: dict[str, str]) -> ResolvedBranding:
-    """``system`` with ``overrides`` on top; a value that fails validation is dropped.
-
-    Writes are validated, so a bad value means a hand-edited row — it must
-    degrade to the system value for that field, not break every page render.
-
-    An empty-string override is *unset*: the field inherits the platform's
-    value. To go back to inheriting, delete the override; storing ``""`` has
-    the same effect rather than blanking the platform's value.
-
-    The dark logo is paired with the light one: a tenant that overrides the
-    logo but not the dark logo must not be shown the *platform's* dark logo
-    beside its own logo, so the inherited dark logo is dropped and dark
-    surfaces fall back to the tenant's logo.
-    """
-    good = {name: value for name, value in overrides.items() if value != ""}
-    base: dict[str, Any] = system.model_dump()
-    while good:
-        try:
-            values: dict[str, Any] = {**base, **good}
-            if "logo_file_id" in good and "logo_dark_file_id" not in good:
-                values["logo_dark_file_id"] = ""
-            merged = BrandingSettings(**values)
-            return ResolvedBranding(merged, tenant_id, frozenset(good))
-        except ValidationError as exc:
-            bad = {str(err["loc"][0]) for err in exc.errors() if err.get("loc")}
-            logger.warning("Tenant %s branding override(s) %s are invalid.", tenant_id, bad)
-            if not bad & good.keys():
-                break
-            for name in bad:
-                good.pop(name, None)
-    return ResolvedBranding(system, tenant_id, frozenset())
-
-
-def _shared_read(
-    app: FastAPI, cache: TenantCache, tenant_id: str
-) -> tuple[int, asyncio.Future[dict[str, str]]]:
-    """The in-flight override read for ``tenant_id``, started if there is none."""
-    entry = cache.inflight.get(tenant_id)
-    if entry is not None:
-        return entry
-    read = asyncio.ensure_future(read_overrides(app, tenant_id))
-    entry = (cache.epoch, read)
-    cache.inflight[tenant_id] = entry
-
-    def _done(fut: asyncio.Future[dict[str, str]]) -> None:
-        # Retrieve the outcome so a failed read whose every waiter was
-        # cancelled never logs "exception was never retrieved".
-        if not fut.cancelled():
-            fut.exception()
-        if cache.inflight.get(tenant_id) is entry:
-            del cache.inflight[tenant_id]
-
-    read.add_done_callback(_done)
-    return entry
-
-
-async def resolve_for(app: FastAPI, tenant_id: str | None) -> ResolvedBranding:
-    system: BrandingSettings = app.state.branding.settings
-    if not tenant_id:
-        return ResolvedBranding(system)
-    cache: TenantCache = app.state.branding.tenant_cache
-    hit = cache.entries.get(tenant_id)
-    if hit is not None:
-        overrides, merged_against, resolved = hit
-        if merged_against is system:
-            return resolved
-    else:
-        started, read = _shared_read(app, cache, tenant_id)
-        # Shielded: one waiter being cancelled must not cancel everyone's read.
-        overrides = await asyncio.shield(read)
-        if cache.epoch != started:
-            return merge(system, tenant_id, overrides)  # don't cache a racing read
-    resolved = merge(system, tenant_id, overrides)
-    cache.entries[tenant_id] = (overrides, system, resolved)
-    return resolved
-
-
-async def resolve(request: Request) -> ResolvedBranding:
-    """The branding ``request`` sees: its tenant's, falling back to the system's."""
-    return await resolve_for(request.app, request_tenant(request))
+import importlib
+import sys
 
+from simple_module_core.deprecation import deprecated_module
 
-__all__ = [
-    "ResolvedBranding",
-    "TenantCache",
-    "forget",
-    "merge",
-    "overrides_from",
-    "read_overrides",
-    "request_tenant",
-    "resolve",
-    "resolve_for",
-    "subscribe",
-    "tenancy_active",
-]
+deprecated_module(
+    "branding.tenant_branding", remove_in="0.0.46", use="branding.core.tenant_branding"
+)
+sys.modules[__name__] = importlib.import_module("branding.core.tenant_branding")
diff --git a/modules/branding/branding/components/BannerField.tsx b/modules/branding/branding/ui/components/BannerField.tsx
similarity index 100%
rename from modules/branding/branding/components/BannerField.tsx
rename to modules/branding/branding/ui/components/BannerField.tsx
diff --git a/modules/branding/branding/components/BrandingPreview.tsx b/modules/branding/branding/ui/components/BrandingPreview.tsx
similarity index 100%
rename from modules/branding/branding/components/BrandingPreview.tsx
rename to modules/branding/branding/ui/components/BrandingPreview.tsx
diff --git a/modules/branding/branding/components/ColorField.tsx b/modules/branding/branding/ui/components/ColorField.tsx
similarity index 100%
rename from modules/branding/branding/components/ColorField.tsx
rename to modules/branding/branding/ui/components/ColorField.tsx
diff --git a/modules/branding/branding/components/DesignPackField.tsx b/modules/branding/branding/ui/components/DesignPackField.tsx
similarity index 100%
rename from modules/branding/branding/components/DesignPackField.tsx
rename to modules/branding/branding/ui/components/DesignPackField.tsx
diff --git a/modules/branding/branding/components/FooterField.tsx b/modules/branding/branding/ui/components/FooterField.tsx
similarity index 100%
rename from modules/branding/branding/components/FooterField.tsx
rename to modules/branding/branding/ui/components/FooterField.tsx
diff --git a/modules/branding/branding/components/ImageDropzones.tsx b/modules/branding/branding/ui/components/ImageDropzones.tsx
similarity index 100%
rename from modules/branding/branding/components/ImageDropzones.tsx
rename to modules/branding/branding/ui/components/ImageDropzones.tsx
diff --git a/modules/branding/branding/components/PresetField.tsx b/modules/branding/branding/ui/components/PresetField.tsx
similarity index 100%
rename from modules/branding/branding/components/PresetField.tsx
rename to modules/branding/branding/ui/components/PresetField.tsx
diff --git a/modules/branding/branding/components/PreviewSurfaces.tsx b/modules/branding/branding/ui/components/PreviewSurfaces.tsx
similarity index 100%
rename from modules/branding/branding/components/PreviewSurfaces.tsx
rename to modules/branding/branding/ui/components/PreviewSurfaces.tsx
diff --git a/modules/branding/branding/components/PreviewTabs.tsx b/modules/branding/branding/ui/components/PreviewTabs.tsx
similarity index 100%
rename from modules/branding/branding/components/PreviewTabs.tsx
rename to modules/branding/branding/ui/components/PreviewTabs.tsx
diff --git a/modules/branding/branding/components/dirty.ts b/modules/branding/branding/ui/components/dirty.ts
similarity index 100%
rename from modules/branding/branding/components/dirty.ts
rename to modules/branding/branding/ui/components/dirty.ts
diff --git a/modules/branding/branding/components/hex.ts b/modules/branding/branding/ui/components/hex.ts
similarity index 100%
rename from modules/branding/branding/components/hex.ts
rename to modules/branding/branding/ui/components/hex.ts
diff --git a/modules/branding/branding/web/__init__.py b/modules/branding/branding/web/__init__.py
new file mode 100644
index 000000000..03913595c
--- /dev/null
+++ b/modules/branding/branding/web/__init__.py
@@ -0,0 +1 @@
+"""The HTTP side: request deps, endpoints and the shared-props provider."""
diff --git a/modules/branding/branding/deps.py b/modules/branding/branding/web/deps.py
similarity index 86%
rename from modules/branding/branding/deps.py
rename to modules/branding/branding/web/deps.py
index e01289089..58405b7ab 100644
--- a/modules/branding/branding/deps.py
+++ b/modules/branding/branding/web/deps.py
@@ -10,7 +10,7 @@
 from simple_module_db.deps import get_db
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from branding.service import BrandingService
+from branding.core.service import BrandingService
 
 
 async def get_branding_service(
@@ -20,7 +20,7 @@ async def get_branding_service(
 ) -> BrandingService:
     # FastAPI caches dependencies per request, so ``storage`` shares this very
     # session; a replaced image is reaped only after it commits (see
-    # ``branding.reaper``), so a rollback never strands the setting.
+    # ``branding.assets.reaper``), so a rollback never strands the setting.
     return BrandingService(request.app, db, storage)
 
 
diff --git a/modules/branding/branding/web/endpoints/__init__.py b/modules/branding/branding/web/endpoints/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/modules/branding/branding/endpoints/api.py b/modules/branding/branding/web/endpoints/api.py
similarity index 96%
rename from modules/branding/branding/endpoints/api.py
rename to modules/branding/branding/web/endpoints/api.py
index bc4925865..b012b364e 100644
--- a/modules/branding/branding/endpoints/api.py
+++ b/modules/branding/branding/web/endpoints/api.py
@@ -8,11 +8,11 @@
 from simple_module_core.app_state import get_design_packs
 from simple_module_hosting.permissions import RequiresPermission
 
-from branding import constants
+from branding.assets.images import store_image, validate_image
 from branding.contracts.schemas import BrandingOut, BrandingUpdate
-from branding.deps import BrandingServiceDep
-from branding.images import store_image, validate_image
-from branding.presets import find_preset
+from branding.core import constants
+from branding.core.presets import find_preset
+from branding.web.deps import BrandingServiceDep
 
 router = APIRouter()
 
diff --git a/modules/branding/branding/web/endpoints/assets.py b/modules/branding/branding/web/endpoints/assets.py
new file mode 100644
index 000000000..77728c60b
--- /dev/null
+++ b/modules/branding/branding/web/endpoints/assets.py
@@ -0,0 +1,187 @@
+"""Anonymous branding image routes — the logo and favicon a guest must see.
+
+These are the only unauthenticated routes branding registers. They resolve the
+file id from ``app.state.branding.settings`` and stream that one file, so they
+expose exactly the two images an administrator designated as public branding
+and nothing else in ``file_storage``.
+
+Which image, and whose (#373): the request's tenant — from the subdomain for
+an anonymous visitor, the active organisation for a member — else the system.
+The file id is never taken from the request (``?v=`` is only a cache key):
+
+* a value the **tenant** set is read as that tenant's file — under
+  ``tenant_context(tenant)``, so only a row the tenant owns matches;
+* a **system** value is read as a *platform* file (``platform=True``): an
+  ``all_tenants()`` lookup restricted to rows owned by
+  ``file_storage.scope.PLATFORM_TENANT_ID``.
+
+Either way a setting pointed at someone else's file id serves a 404, never
+their file.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.responses import RedirectResponse, StreamingResponse
+from file_storage.deps import get_file_storage_service
+from file_storage.service import (
+    FileStorageService,
+    RedirectDownload,
+    StoredFileNotFoundError,
+    StreamDownload,
+)
+from simple_module_db import tenant_context
+
+from branding.assets.images import ALLOWED_IMAGE_TYPES, normalize_content_type
+from branding.core import constants
+from branding.core.tenant_branding import ResolvedBranding, resolve
+
+router = APIRouter()
+
+logger = logging.getLogger(__name__)
+
+
+def _cache_headers(request: Request, file_id: uuid.UUID, tenant_id: str | None) -> dict[str, str]:
+    """Shared caching only where the URL alone determines the bytes.
+
+    ``tenant_id`` is the *request's* tenant. The same URL answers per tenant
+    (session, tenant header or subdomain), and a shared cache keys on the URL
+    alone — so only a request with **no** tenant, whose ``?v=`` names the very
+    file served (a content address), may be stored ``public`` and pinned for a
+    year. Everything else is ``private``: a request with a tenant is pinned in
+    the browser only when ``?v=`` matches, varying on what selects the tenant
+    (the session cookie, the tenant header); an unversioned or stale ``?v=`` is
+    ``no-cache``, so the next page — maybe in another organisation — revalidates.
+    """
+    version = request.query_params.get(constants.ASSET_VERSION_QUERY_KEY)
+    matches = bool(version) and version == str(file_id)
+    if tenant_id is None:
+        if matches:
+            return {
+                "Cache-Control": f"public, max-age={constants.ASSET_MAX_AGE_VERSIONED}, immutable"
+            }
+        return {"Cache-Control": "private, no-cache"}
+    if matches:
+        headers = {
+            "Cache-Control": f"private, max-age={constants.ASSET_MAX_AGE_VERSIONED}, immutable"
+        }
+    else:
+        headers = {"Cache-Control": "private, no-cache"}
+    # What selects the tenant: the session cookie and the tenant header (a
+    # subdomain is part of the cache key already). The session middleware adds
+    # ``Cookie`` itself when this request read the session, so it is named
+    # here only otherwise — never twice.
+    session = request.scope.get("session")
+    vary = [] if getattr(session, "accessed", False) else ["Cookie"]
+    if header := getattr(request.app.state.sm.settings, "tenant_header", "") or "":
+        vary.append(header)
+    if vary:
+        headers["Vary"] = ", ".join(vary)
+    return headers
+
+
+def _configured_file_id(resolved: ResolvedBranding, field: str) -> uuid.UUID:
+    raw = getattr(resolved.settings, field, "")
+    if not raw:
+        raise HTTPException(status_code=404, detail="No branding image is set.")
+    try:
+        return uuid.UUID(raw)
+    except ValueError as exc:
+        # Settings are hydrated from the DB, so a hand-edited row can hold junk.
+        # A broken image beats a 500 on the sign-in page.
+        logger.warning("Branding %s holds a non-UUID value %r.", field, raw)
+        raise HTTPException(status_code=404, detail="No branding image is set.") from exc
+
+
+async def _download(storage: FileStorageService, file_id: uuid.UUID, owner: str | None):
+    """The file as its owner sees it: a platform file when ``owner`` is ``None``."""
+    if owner is None:
+        return await storage.download(file_id, platform=True)
+    with tenant_context(owner):
+        return await storage.download(file_id)
+
+
+async def _serve(
+    request: Request, storage: FileStorageService, field: str
+) -> RedirectResponse | StreamingResponse:
+    if getattr(request.app.state, "branding", None) is None:
+        raise HTTPException(status_code=404, detail="No branding image is set.")
+    resolved = await resolve(request)
+    file_id = _configured_file_id(resolved, field)
+    request_tenant = resolved.tenant_id
+    owner = resolved.owner_of(field)
+    try:
+        download = await _download(storage, file_id, owner)
+    except StoredFileNotFoundError as exc:
+        if owner is None:
+            # Referenced file went away underneath us. 404 uncached, so the next
+            # request retries once the setting is fixed rather than caching a miss.
+            logger.warning("Branding %s references missing file %s.", field, file_id)
+            raise HTTPException(status_code=404, detail="Branding image is unavailable.") from exc
+        # The tenant's own image was deleted (through the Files API, say) while
+        # its override still names it. Show the platform's image instead of a
+        # dead one; the override is left for the tenant to replace or reset.
+        logger.warning("Tenant %s branding %s references missing file %s.", owner, field, file_id)
+        file_id = _configured_file_id(ResolvedBranding(request.app.state.branding.settings), field)
+        try:
+            download = await _download(storage, file_id, None)
+        except StoredFileNotFoundError as missing:
+            raise HTTPException(
+                status_code=404, detail="Branding image is unavailable."
+            ) from missing
+
+    if normalize_content_type(download.file.content_type) not in ALLOWED_IMAGE_TYPES:
+        # Uploads are validated, so this is a hand-edited (or pre-validation)
+        # setting naming some other file: never serve it as branding.
+        logger.warning("Branding %s references non-image file %s.", field, file_id)
+        raise HTTPException(status_code=404, detail="Branding image is unavailable.")
+
+    if isinstance(download, RedirectDownload):
+        # Deliberately uncached: the target is a presigned URL that expires, so
+        # caching the redirect would hand out a dead link after the TTL.
+        return RedirectResponse(url=download.url, status_code=302)
+
+    assert isinstance(download, StreamDownload)
+    row = download.file
+    return StreamingResponse(
+        download.body,
+        media_type=row.content_type,
+        headers={
+            **_cache_headers(request, file_id, request_tenant),
+            "Content-Length": str(row.size_bytes),
+            "ETag": f'"{row.checksum_sha256}"',
+            # `attachment` is ignored for subresource loads (<img>, <link
+            # rel="icon">) but stops a direct visit rendering the bytes as a
+            # document at our origin; `nosniff` pins the declared type. The
+            # upload allow-list already excludes SVG — this is the second layer.
+            "Content-Disposition": "attachment",
+            "X-Content-Type-Options": "nosniff",
+        },
+    )
+
+
+@router.get(constants.PATH_LOGO, response_model=None)
+async def serve_logo(
+    request: Request,
+    storage: FileStorageService = Depends(get_file_storage_service),
+) -> RedirectResponse | StreamingResponse:
+    return await _serve(request, storage, "logo_file_id")
+
+
+@router.get(constants.PATH_LOGO_DARK, response_model=None)
+async def serve_logo_dark(
+    request: Request,
+    storage: FileStorageService = Depends(get_file_storage_service),
+) -> RedirectResponse | StreamingResponse:
+    return await _serve(request, storage, "logo_dark_file_id")
+
+
+@router.get(constants.PATH_FAVICON, response_model=None)
+async def serve_favicon(
+    request: Request,
+    storage: FileStorageService = Depends(get_file_storage_service),
+) -> RedirectResponse | StreamingResponse:
+    return await _serve(request, storage, "favicon_file_id")
diff --git a/modules/branding/branding/endpoints/tenant_api.py b/modules/branding/branding/web/endpoints/tenant_api.py
similarity index 91%
rename from modules/branding/branding/endpoints/tenant_api.py
rename to modules/branding/branding/web/endpoints/tenant_api.py
index 76a073586..cccdd5c48 100644
--- a/modules/branding/branding/endpoints/tenant_api.py
+++ b/modules/branding/branding/web/endpoints/tenant_api.py
@@ -5,7 +5,7 @@
 points the tenant's ``branding.<field>`` override at it; ``DELETE`` removes the
 override, so the tenant falls back to the system image. The replaced file is
 reaped in the tenant's own scope once the write commits, unless another of the
-tenant's image fields still references it (:mod:`branding.reaper`).
+tenant's image fields still references it (:mod:`branding.assets.reaper`).
 
 Guarded like every other tenant-settings write: ``settings.tenant.edit``
 (tenant owner/admin) and the tenant comes from ``request.state.tenant_id``
@@ -25,12 +25,12 @@
 from settings.tenant_scope import active_tenant
 from simple_module_hosting.permissions import RequiresPermission
 
-from branding.constants import PACKAGE, PATH_TENANT_ASSET, TENANT_ASSETS, TENANT_IMAGE_FIELDS
+from branding.assets.images import store_image, validate_image
+from branding.assets.reaper import schedule_reap
 from branding.contracts.schemas import BrandingOut
-from branding.images import store_image, validate_image
-from branding.reaper import schedule_reap
-from branding.service import to_out
-from branding.tenant_branding import merge, overrides_from
+from branding.core.constants import PACKAGE, PATH_TENANT_ASSET, TENANT_ASSETS, TENANT_IMAGE_FIELDS
+from branding.core.service import to_out
+from branding.core.tenant_branding import merge, overrides_from
 
 router = APIRouter(dependencies=[Depends(RequiresPermission(PERM_TENANT_EDIT))])
 
diff --git a/modules/branding/branding/endpoints/views.py b/modules/branding/branding/web/endpoints/views.py
similarity index 95%
rename from modules/branding/branding/endpoints/views.py
rename to modules/branding/branding/web/endpoints/views.py
index 910c3a5d2..488c867c8 100644
--- a/modules/branding/branding/endpoints/views.py
+++ b/modules/branding/branding/web/endpoints/views.py
@@ -8,8 +8,8 @@
 from simple_module_hosting.permissions import RequiresPermission
 from simple_module_inertia import InertiaResponse
 
-from branding import constants
-from branding.presets import BUILTIN_PRESETS
+from branding.core import constants
+from branding.core.presets import BUILTIN_PRESETS
 
 router = APIRouter()
 
diff --git a/modules/branding/branding/shared_props.py b/modules/branding/branding/web/shared_props.py
similarity index 95%
rename from modules/branding/branding/shared_props.py
rename to modules/branding/branding/web/shared_props.py
index 57d7b059c..36671a261 100644
--- a/modules/branding/branding/shared_props.py
+++ b/modules/branding/branding/web/shared_props.py
@@ -11,7 +11,7 @@
 
 from simple_module_hosting.inertia_deps import INERTIA_HEADER
 
-from branding.constants import (
+from branding.core.constants import (
     ASSET_VERSION_QUERY_KEY,
     FAVICON_URL,
     LOGO_DARK_URL,
@@ -21,7 +21,7 @@
 if TYPE_CHECKING:
     from starlette.requests import Request
 
-    from branding.settings import BrandingSettings
+    from branding.core.settings import BrandingSettings
 
 
 def asset_url(base: str, file_id: str) -> str | None:
@@ -98,8 +98,8 @@ async def branding_shared_props(request: Request) -> dict:
     Defensive — returns ``{}`` if the branding state isn't mounted yet, so a
     half-booted app never errors a page render.
     """
-    from branding.services import BrandingServices
-    from branding.tenant_branding import resolve
+    from branding.core.services import BrandingServices
+    from branding.core.tenant_branding import resolve
 
     if getattr(request.app.state, "branding", None) is None or not renders_a_page(request):
         return {}
diff --git a/modules/branding/tests-js/color-field.test.tsx b/modules/branding/tests-js/color-field.test.tsx
index 70a50c43c..fb0d38f1d 100644
--- a/modules/branding/tests-js/color-field.test.tsx
+++ b/modules/branding/tests-js/color-field.test.tsx
@@ -14,10 +14,10 @@ configureI18n({
   },
 });
 
-import { type PreviewBrand, previewInk } from '../branding/components/BrandingPreview';
-import { ColorField } from '../branding/components/ColorField';
-import { isValidColor, normalizeHex } from '../branding/components/hex';
-import { SignInPreview } from '../branding/components/PreviewSurfaces';
+import { type PreviewBrand, previewInk } from '../branding/ui/components/BrandingPreview';
+import { ColorField } from '../branding/ui/components/ColorField';
+import { isValidColor, normalizeHex } from '../branding/ui/components/hex';
+import { SignInPreview } from '../branding/ui/components/PreviewSurfaces';
 
 function Harness({ initial }: { initial: string }) {
   const [value, setValue] = useState(initial);
diff --git a/modules/branding/tests-js/dirty-state.test.tsx b/modules/branding/tests-js/dirty-state.test.tsx
index 89df0d07e..189bb4e87 100644
--- a/modules/branding/tests-js/dirty-state.test.tsx
+++ b/modules/branding/tests-js/dirty-state.test.tsx
@@ -10,8 +10,8 @@ configureI18n({
   },
 });
 
-import { type BrandingForm, countBrandingChanges } from '../branding/components/dirty';
-import { PresetField } from '../branding/components/PresetField';
+import { type BrandingForm, countBrandingChanges } from '../branding/ui/components/dirty';
+import { PresetField } from '../branding/ui/components/PresetField';
 
 const BASELINE: BrandingForm = {
   appName: 'Acme Admin',
diff --git a/modules/branding/tests/test_images.py b/modules/branding/tests/assets/images/test_branding_images.py
similarity index 99%
rename from modules/branding/tests/test_images.py
rename to modules/branding/tests/assets/images/test_branding_images.py
index 235ffad81..7e15efb5f 100644
--- a/modules/branding/tests/test_images.py
+++ b/modules/branding/tests/assets/images/test_branding_images.py
@@ -10,7 +10,7 @@
 import io
 
 import pytest
-from branding.images import (
+from branding.assets.images import (
     ALLOWED_IMAGE_TYPES,
     MAX_IMAGE_BYTES,
     has_recognized_image_signature,
diff --git a/modules/branding/tests/test_logo_dark.py b/modules/branding/tests/assets/images/test_branding_logo_dark.py
similarity index 98%
rename from modules/branding/tests/test_logo_dark.py
rename to modules/branding/tests/assets/images/test_branding_logo_dark.py
index aae6a17e0..9e3027606 100644
--- a/modules/branding/tests/test_logo_dark.py
+++ b/modules/branding/tests/assets/images/test_branding_logo_dark.py
@@ -19,8 +19,8 @@
 
 import httpx
 import pytest
-from branding.settings import BrandingSettings
-from branding.shared_props import branding_payload
+from branding.core.settings import BrandingSettings
+from branding.web.shared_props import branding_payload
 from file_storage.models import StoredFile
 from file_storage.service import FileStorageService, StreamDownload
 
diff --git a/modules/branding/tests/test_asset_lifecycle.py b/modules/branding/tests/assets/reaper/test_branding_asset_lifecycle.py
similarity index 100%
rename from modules/branding/tests/test_asset_lifecycle.py
rename to modules/branding/tests/assets/reaper/test_branding_asset_lifecycle.py
diff --git a/modules/branding/tests/test_branding_reap.py b/modules/branding/tests/assets/reaper/test_branding_reap.py
similarity index 96%
rename from modules/branding/tests/test_branding_reap.py
rename to modules/branding/tests/assets/reaper/test_branding_reap.py
index 15bbf6f4a..8cef565f7 100644
--- a/modules/branding/tests/test_branding_reap.py
+++ b/modules/branding/tests/assets/reaper/test_branding_reap.py
@@ -8,9 +8,9 @@
 from __future__ import annotations
 
 import pytest
-from branding import tenant_branding
-from branding.endpoints import tenant_api
-from branding.service import BrandingService
+from branding.core import tenant_branding
+from branding.core.service import BrandingService
+from branding.web.endpoints import tenant_api
 from file_storage.models import StoredFile
 from settings.contracts.schemas import SettingScope, SettingUpsert
 from settings.service import SettingService
diff --git a/modules/branding/tests/test_branding_reap_ordering.py b/modules/branding/tests/assets/reaper/test_branding_reap_ordering.py
similarity index 96%
rename from modules/branding/tests/test_branding_reap_ordering.py
rename to modules/branding/tests/assets/reaper/test_branding_reap_ordering.py
index 40ab6e8a6..ae50d5619 100644
--- a/modules/branding/tests/test_branding_reap_ordering.py
+++ b/modules/branding/tests/assets/reaper/test_branding_reap_ordering.py
@@ -9,8 +9,9 @@
 import asyncio
 import gc
 
-from branding import reaper, tenant_branding
-from branding.tenant_branding import TenantCache
+from branding.assets import reaper
+from branding.core import tenant_branding
+from branding.core.tenant_branding import TenantCache
 from file_storage.models import StoredFile
 from settings.contracts.schemas import SettingScope
 from settings.service import SettingService
diff --git a/modules/branding/tests/test_branding.py b/modules/branding/tests/core/module/test_branding.py
similarity index 97%
rename from modules/branding/tests/test_branding.py
rename to modules/branding/tests/core/module/test_branding.py
index 3454fded4..37f6bf080 100644
--- a/modules/branding/tests/test_branding.py
+++ b/modules/branding/tests/core/module/test_branding.py
@@ -7,8 +7,8 @@
 
 import httpx
 import pytest
-from branding.settings import BrandingSettings
-from branding.shared_props import branding_payload, branding_shared_props
+from branding.core.settings import BrandingSettings
+from branding.web.shared_props import branding_payload, branding_shared_props
 
 # ── Unit: settings validation ──────────────────────────────────────────
 
@@ -234,8 +234,8 @@ def test_page_constant_matches_view_literal() -> None:
     # (the literal is required inline for SM003/SM004 static AST pairing).
     import inspect
 
-    from branding import constants
-    from branding.endpoints import views
+    from branding.core import constants
+    from branding.web.endpoints import views
 
     assert constants._PAGE_MANAGE == "Branding/Manage"
     assert f'"{constants._PAGE_MANAGE}"' in inspect.getsource(views.manage)
diff --git a/modules/branding/tests/test_branding_menu_permission.py b/modules/branding/tests/core/module/test_branding_menu_permission.py
similarity index 92%
rename from modules/branding/tests/test_branding_menu_permission.py
rename to modules/branding/tests/core/module/test_branding_menu_permission.py
index e12fd047b..5b1454a71 100644
--- a/modules/branding/tests/test_branding_menu_permission.py
+++ b/modules/branding/tests/core/module/test_branding_menu_permission.py
@@ -1,7 +1,7 @@
 """Branding navigation follows the page guard rather than role names (#698)."""
 
 import pytest
-from branding.constants import MENU_URL, PERM_VIEW
+from branding.core.constants import MENU_URL, PERM_VIEW
 from branding.module import BrandingModule
 from simple_module_core.menu import MenuRegistry, MenuSection
 
diff --git a/modules/branding/tests/test_menu_section.py b/modules/branding/tests/core/module/test_branding_menu_section.py
similarity index 92%
rename from modules/branding/tests/test_menu_section.py
rename to modules/branding/tests/core/module/test_branding_menu_section.py
index a8733a29b..a0948106b 100644
--- a/modules/branding/tests/test_menu_section.py
+++ b/modules/branding/tests/core/module/test_branding_menu_section.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from branding.constants import MENU_URL
+from branding.core.constants import MENU_URL
 from branding.module import BrandingModule
 from simple_module_core.menu import MenuRegistry, MenuSection
 
diff --git a/modules/branding/tests/test_presets.py b/modules/branding/tests/core/presets/test_branding_presets.py
similarity index 97%
rename from modules/branding/tests/test_presets.py
rename to modules/branding/tests/core/presets/test_branding_presets.py
index 3fb985b06..4289f8008 100644
--- a/modules/branding/tests/test_presets.py
+++ b/modules/branding/tests/core/presets/test_branding_presets.py
@@ -10,7 +10,7 @@
 
 import httpx
 import pytest
-from branding.presets import BUILTIN_PRESETS, PRESET_FIELDS, BrandingPreset, find_preset
+from branding.core.presets import BUILTIN_PRESETS, PRESET_FIELDS, BrandingPreset, find_preset
 from settings.invalidation import reload_package
 from settings.service import SettingService
 from settings.store import SettingsStore
@@ -48,7 +48,7 @@ def test_every_preset_only_touches_appearance() -> None:
 
 
 def test_every_preset_sets_a_valid_hex_colour() -> None:
-    from branding.constants import HEX_COLOR_RE
+    from branding.core.constants import HEX_COLOR_RE
 
     for preset in BUILTIN_PRESETS:
         colour = preset.values.get("primary_color")
diff --git a/modules/branding/tests/test_banner.py b/modules/branding/tests/core/settings/test_branding_banner.py
similarity index 96%
rename from modules/branding/tests/test_banner.py
rename to modules/branding/tests/core/settings/test_branding_banner.py
index 4da28e82e..3156f171f 100644
--- a/modules/branding/tests/test_banner.py
+++ b/modules/branding/tests/core/settings/test_branding_banner.py
@@ -11,10 +11,10 @@
 
 import httpx
 import pytest
-from branding.constants import MAX_BANNER_MESSAGE_LEN, normalize_banner_severity
 from branding.contracts.schemas import BrandingUpdate
-from branding.settings import BrandingSettings
-from branding.shared_props import branding_payload
+from branding.core.constants import MAX_BANNER_MESSAGE_LEN, normalize_banner_severity
+from branding.core.settings import BrandingSettings
+from branding.web.shared_props import branding_payload
 
 # ── Unit: settings normalise ───────────────────────────────────────────
 
diff --git a/modules/branding/tests/test_design_pack.py b/modules/branding/tests/core/settings/test_branding_design_pack.py
similarity index 97%
rename from modules/branding/tests/test_design_pack.py
rename to modules/branding/tests/core/settings/test_branding_design_pack.py
index b558ffeb6..b61e4fb29 100644
--- a/modules/branding/tests/test_design_pack.py
+++ b/modules/branding/tests/core/settings/test_branding_design_pack.py
@@ -11,8 +11,8 @@
 import httpx
 import pytest
 from branding.contracts.schemas import BrandingUpdate
-from branding.settings import BrandingSettings
-from branding.shared_props import branding_payload
+from branding.core.settings import BrandingSettings
+from branding.web.shared_props import branding_payload
 from simple_module_core.design_packs import DesignPack
 
 _GCA = DesignPack(value="gca", label="Canopy Atlas")
diff --git a/modules/branding/tests/test_footer_links.py b/modules/branding/tests/core/settings/test_branding_footer_links.py
similarity index 97%
rename from modules/branding/tests/test_footer_links.py
rename to modules/branding/tests/core/settings/test_branding_footer_links.py
index 4fd9fab21..1fc388b1a 100644
--- a/modules/branding/tests/test_footer_links.py
+++ b/modules/branding/tests/core/settings/test_branding_footer_links.py
@@ -9,10 +9,10 @@
 from __future__ import annotations
 
 import pytest
-from branding.constants import MAX_FOOTER_LINKS
 from branding.contracts.schemas import BrandingUpdate, FooterLink
-from branding.settings import BrandingSettings
-from branding.shared_props import branding_payload
+from branding.core.constants import MAX_FOOTER_LINKS
+from branding.core.settings import BrandingSettings
+from branding.web.shared_props import branding_payload
 from httpx import AsyncClient
 from pydantic import ValidationError
 
diff --git a/modules/branding/tests/test_footer_text.py b/modules/branding/tests/core/settings/test_branding_footer_text.py
similarity index 95%
rename from modules/branding/tests/test_footer_text.py
rename to modules/branding/tests/core/settings/test_branding_footer_text.py
index 66fae0ede..f46ba511a 100644
--- a/modules/branding/tests/test_footer_text.py
+++ b/modules/branding/tests/core/settings/test_branding_footer_text.py
@@ -8,10 +8,10 @@
 from __future__ import annotations
 
 import pytest
-from branding.constants import MAX_FOOTER_TEXT_LEN
 from branding.contracts.schemas import BrandingUpdate
-from branding.settings import BrandingSettings
-from branding.shared_props import branding_payload
+from branding.core.constants import MAX_FOOTER_TEXT_LEN
+from branding.core.settings import BrandingSettings
+from branding.web.shared_props import branding_payload
 from httpx import AsyncClient
 from pydantic import ValidationError
 
diff --git a/modules/branding/tests/test_tenant_branding.py b/modules/branding/tests/core/tenant_branding/test_branding_tenant_branding.py
similarity index 99%
rename from modules/branding/tests/test_tenant_branding.py
rename to modules/branding/tests/core/tenant_branding/test_branding_tenant_branding.py
index c882909a6..4cf670753 100644
--- a/modules/branding/tests/test_tenant_branding.py
+++ b/modules/branding/tests/core/tenant_branding/test_branding_tenant_branding.py
@@ -10,7 +10,7 @@
 
 import httpx
 import pytest
-from branding import tenant_branding
+from branding.core import tenant_branding
 from settings.constants import INVALIDATION_CHANNEL
 from settings.contracts.invalidation import invalidation_key
 from settings.contracts.schemas import SettingScope, SettingUpsert
diff --git a/modules/branding/tests/test_tenant_branding_assets.py b/modules/branding/tests/core/tenant_branding/test_branding_tenant_branding_assets.py
similarity index 99%
rename from modules/branding/tests/test_tenant_branding_assets.py
rename to modules/branding/tests/core/tenant_branding/test_branding_tenant_branding_assets.py
index e89f7c8d2..9f6cb7d6d 100644
--- a/modules/branding/tests/test_tenant_branding_assets.py
+++ b/modules/branding/tests/core/tenant_branding/test_branding_tenant_branding_assets.py
@@ -10,8 +10,8 @@
 
 import httpx
 import pytest
-from branding import tenant_branding
-from branding.constants import LOGO_URL
+from branding.core import tenant_branding
+from branding.core.constants import LOGO_URL
 from file_storage.models import StoredFile
 from file_storage.scope import PLATFORM_TENANT_ID
 from settings.contracts.schemas import SettingScope, SettingUpsert
diff --git a/modules/branding/tests/test_tenant_branding_cost.py b/modules/branding/tests/core/tenant_branding/test_branding_tenant_branding_cost.py
similarity index 97%
rename from modules/branding/tests/test_tenant_branding_cost.py
rename to modules/branding/tests/core/tenant_branding/test_branding_tenant_branding_cost.py
index 85db14806..a594c0efb 100644
--- a/modules/branding/tests/test_tenant_branding_cost.py
+++ b/modules/branding/tests/core/tenant_branding/test_branding_tenant_branding_cost.py
@@ -10,8 +10,8 @@
 import asyncio
 
 import pytest
-from branding import tenant_branding
-from branding.shared_props import renders_a_page
+from branding.core import tenant_branding
+from branding.web.shared_props import renders_a_page
 from starlette.requests import Request
 
 
diff --git a/modules/branding/tests/test_ship_review.py b/modules/branding/tests/core/tenant_branding/test_branding_tenant_review_fixes.py
similarity index 96%
rename from modules/branding/tests/test_ship_review.py
rename to modules/branding/tests/core/tenant_branding/test_branding_tenant_review_fixes.py
index 6d436503f..487385c0a 100644
--- a/modules/branding/tests/test_ship_review.py
+++ b/modules/branding/tests/core/tenant_branding/test_branding_tenant_review_fixes.py
@@ -4,10 +4,10 @@
 from __future__ import annotations
 
 import httpx
-from branding import tenant_branding
-from branding.services import BrandingServices
-from branding.settings import BrandingSettings
-from branding.tenant_branding import TenantCache, merge
+from branding.core import tenant_branding
+from branding.core.services import BrandingServices
+from branding.core.settings import BrandingSettings
+from branding.core.tenant_branding import TenantCache, merge
 from settings.constants import INVALIDATION_CHANNEL
 from settings.contracts.invalidation import parse_invalidation_key
 from settings.contracts.schemas import SettingScope, SettingUpsert
diff --git a/modules/branding/tests/test_branding_clear_route_scope.py b/modules/branding/tests/web/endpoints/test_branding_clear_route_scope.py
similarity index 100%
rename from modules/branding/tests/test_branding_clear_route_scope.py
rename to modules/branding/tests/web/endpoints/test_branding_clear_route_scope.py
diff --git a/modules/branding/tests/test_branding_platform_files.py b/modules/branding/tests/web/endpoints/test_branding_platform_files.py
similarity index 98%
rename from modules/branding/tests/test_branding_platform_files.py
rename to modules/branding/tests/web/endpoints/test_branding_platform_files.py
index 8fec72b37..d716cdaa5 100644
--- a/modules/branding/tests/test_branding_platform_files.py
+++ b/modules/branding/tests/web/endpoints/test_branding_platform_files.py
@@ -14,7 +14,7 @@
 
 import httpx
 import pytest
-from branding.constants import LOGO_URL
+from branding.core.constants import LOGO_URL
 from file_storage.models import StoredFile
 from file_storage.scope import PLATFORM_TENANT_ID
 from simple_module_db import all_tenants
diff --git a/modules/branding/tests/test_public_assets.py b/modules/branding/tests/web/endpoints/test_branding_public_assets.py
similarity index 100%
rename from modules/branding/tests/test_public_assets.py
rename to modules/branding/tests/web/endpoints/test_branding_public_assets.py
diff --git a/scripts/tests/test_check_no_double_cast.py b/scripts/tests/test_check_no_double_cast.py
index f30caa49c..6ca1be05c 100644
--- a/scripts/tests/test_check_no_double_cast.py
+++ b/scripts/tests/test_check_no_double_cast.py
@@ -31,7 +31,7 @@ def test_marker_two_lines_above_does_not_count():
 def test_is_checked_directories():
     assert is_checked(Path("modules/users/users/pages/Login.tsx"))
     assert is_checked(Path("modules/users/users/pages/Users/Edit.tsx"))
-    assert is_checked(Path("modules/branding/branding/components/dirty.ts"))
+    assert is_checked(Path("modules/branding/branding/ui/components/dirty.ts"))
     assert is_checked(Path("modules/users/users/hooks/useThing.ts"))
     assert is_checked(Path("modules/users/users/ui/utils/format.ts"))
     assert is_checked(Path("modules/users/users/auth_local/components/AuthIntro.tsx"))