🏗️ Architecture

Clean Architecture Benefits

• Separation of Concerns: Each layer has a single responsibility
• Testability: Business logic isolated from infrastructure
• Maintainability: Changes in one layer don't affect others
• Flexibility: Easy to swap databases, UI frameworks, or external services

Tenant resolution (hostname -> tenant)

Requests are mapped to a tenant using WebTenantResolutionMiddleware. It normalizes the incoming host, resolves which Organisation owns that hostname, then sets the tenant database + tenant organisation id via ITenantContextSetter.

Resolution rules (high level):

• Exact domain match: any active organisation whose Organisation.Domain equals the full request host (including the platform organisation). Arbitrary subdomains of a tenant's custom domain (e.g. anything.customer.com when the org's Domain is only customer.com) do not resolve — each organisation owns exactly one domain.
• Platform subdomain match: if the host ends with the platform organisation's Domain, the first label (e.g. acme in acme.yourdomain.com) must match a tenant's organisation Name.
• Localhost: resolves to the platform organisation.
• Single-org mode: resolves to the platform organisation by default (and uses the single non-platform org only when it is the only active tenant).

Tenant resolution results are cached briefly (in-memory) and cleared when admin actions update domain mappings.

Multi-org mode supports a cookie override: BB_SelectedOrg can select which organisation is used when the resolved tenant is the platform (for example on localhost for local development, or when Features:SubdomainOrganisations is false and org switching is cookie-based). When Features:SubdomainOrganisations is true, the cookie is suppressed on the platform's configured public hostname so that a stale value left over from visiting a tenant subdomain does not incorrectly override the main marketing/apex site back to that tenant. When subdomain routing is off, the cookie remains active on the platform hostname because it is the primary mechanism for org switching.

Repository scoping (tenant DB vs platform DB)

Application code depends only on two backend-neutral abstractions — never on a database driver — and each uses ITenantContext to decide where to read/write:

• IRepository<TEntity> is tenant-scoped: it targets the current tenant DB and applies an organisation id filter for org-scoped entities.
• IPlatformRepository<TEntity> always targets the platform DB, letting platform-owned entities be stored and queried consistently.

Each database backend supplies its own implementation of that pair — the MongoDB driver for the default backend, and a shared EF Core implementation for the PostgreSQL / SQL Server backends — so call sites stay identical whichever backend is configured.

Routing modes (single-org / subdomain / custom domain)

How a request is mapped to an organisation depends on the routing feature flags and the request hostname. On the platform's configured apex/marketing hostname, tenant context follows the host (platform). Cookie-based selection applies on localhost and other cases where the cookie is still used; routing to subdomains is controlled by the selection flow in /api/org/switch.

• Single-org mode: Features:MultiOrganisation is false → users only operate on the platform organisation context (no org switching UI).
• Cookie-based routing (platform host): Features:SubdomainOrganisations is false → /Org/Select sets BB_SelectedOrg, and WebTenantResolutionMiddleware applies the tenant override on page routes.
• Subdomain routing: Features:SubdomainOrganisations is true → selecting an organisation redirects to <organisationName>.<platformDomain> (for non-custom-domain orgs; name is the stored Organisation.Name).
• Custom domain aliases: Features:CustomDomainOrganisations gates the custom-domain feature end to end — both configuring a hostname (the domain field on /Admin/Organisation and the /Platform/CustomDomains page) and honouring one when a request arrives. Turning it off takes every tenant custom domain offline immediately. WebTenantResolutionMiddleware matches a host against Organisation.Domain and requires DomainVerified, and then discards the match for any non-platform organisation while the flag is off — deliberately, because gating only the admin page left a withdrawn feature still routing live traffic. The platform organisation is exempt, so the operator's own site keeps working and the failure is invisible from where they are standing. Treat this flag as a deployment-shape decision made once, not a switch to experiment with on a running system. Nothing is retired when it goes off: each organisation keeps its Domain, its DomainVerified state and its history, so turning the flag back on restores every route with no re-verification. To retire one domain, clear it on that organisation instead. Whether selecting an organisation sends you to its custom domain is a separate flag, ForwardToCustomDomain (below). With it off — the code default — custom domains are direct-access aliases only: /api/org/switch does not redirect, and users navigate to the custom domain themselves. With it on, picking an org that has a verified custom domain forwards to it. Either way that flag governs the org-picker flow only, never ordinary request routing.

Auth cookies remain valid via the normal session-cookie flow; cookie scoping (host-only vs shared parent-domain) is handled in the auth cookie configuration.

BlazorBlueprint splits administration into two sections. /Platform/* is where a platform admin manages the whole SaaS — the list of organisations, identity, and the platform organisation's own settings (which double as the fallback for sub-orgs on the platform host). /Admin/* is where an organisation admin manages a single organisation's own settings.

Sub-organisations that live on a subdomain of the platform host (e.g. acme.yourdomain.com) typically inherit platform-level settings for legal, cookies, email, push, PWA and external auth — so the platform experience stays consistent. When the same organisation is accessed via its own custom domain (e.g. acme.com), it is free to override those settings because the site is effectively "its own".

Quick reference: behaviour by host

The short version, for the typical setup with MultiOrganisation, SubdomainOrganisations, CustomDomainOrganisations, and UsePlatformBrandingForOrgsWithoutCustomDomain all enabled:

Turning off UsePlatformBrandingForOrgsWithoutCustomDomain collapses the subdomain row into the custom-domain row — subdomain orgs then behave exactly like custom-domain orgs (inherit until they save their own, full /Admin/* surface available). Use that mode when subdomains represent independent tenant sites rather than "part of the same product experience".

What lives where

"Custom-domain orgs only" means the admin page is visible and editable only when the request is on the organisation's own verified custom domain (or UsePlatformBrandingForOrgsWithoutCustomDomain is off). On the platform host or a tenant subdomain with platform-branding active, those admin pages redirect back to /Admin with a note explaining the setting is managed at platform level.

How the fallback is resolved

For each "shared" setting in the table above (legal, cookies, PWA, email), the system asks: does this organisation have its own row? If yes, use it. If no, fall back to the platform organisation's row. A sub-org silently inherits platform values until an admin explicitly saves their own — at which point the sub-org "diverges" and owns its copy from then on.

Whether a sub-org is allowed to diverge depends on how it's being accessed:

• UsePlatformBrandingForOrgsWithoutCustomDomain = false → every org uses its own settings (or inherits if empty).
• UsePlatformBrandingForOrgsWithoutCustomDomain = true + request on the org's custom domain → org-owned settings apply; the full /Admin/* surface is available.
• UsePlatformBrandingForOrgsWithoutCustomDomain = true + request on a subdomain of the platform → platform settings apply; the corresponding /Admin/* pages are hidden.

This is the "platform branding" gate. It ensures the main marketing site and its tenant subdomains share a single consistent legal/cookie/PWA/email footprint, while custom-domain tenants get the full toolkit to run their site independently.

Two exceptions to the inheritance pattern:

• Site settings are always per-org. Every organisation — including sub-orgs on subdomains — gets its own SiteSettings row at creation, seeded from the organisation-defaults template at /Platform/OrganisationDefaults with the site header set to the org's name. There is no runtime fallback to the platform. Site identity (header, logo, contact, theme) is considered intrinsically per-org.
  
  It is a template, not a copy of the platform organisation's row, and the distinction is load-bearing. Provisioning used to clone the platform org's whole SiteSettings and then blank a list of fields — and the fields nobody remembered to blank (analytics id, OG image, social handle) propagated to every organisation ever created, so every tenant's traffic reported into the operator's own analytics property. The defaults row carries an explicit allow-list instead — theme, locale, launcher, private-by-default — and no file references, because a logo or icon is a file id that resolves against the current tenant and means nothing in another one.
• External authentication inherits for subdomain orgs (their login flow routes through the platform host where the platform's registered OAuth redirect URIs are valid). It does not inherit for custom-domain orgs — OAuth credentials are domain-bound, so a platform Facebook/Google/Microsoft app registered with platform.com/signin-facebook will be rejected by the provider when the callback lands on acme.com/signin-facebook. A custom-domain org that wants external-login buttons has to register its own OAuth app with each provider; otherwise the login page simply hides the buttons rather than showing broken ones.

Routing, tenancy, and runtime behaviour are controlled by flags under Features: in appsettings.json. They can be toggled per environment without code changes.

Read the Shipped column, not Code default. They are two different things and six of these disagree. Code default is the fallback used when the key is absent entirely — what a stripped deployment with no Features: section would get. Shipped is what appsettings.json actually sets, so it is what a fresh install does, and the bold values are the ones where the two differ. Reading the wrong column has produced confident, wrong conclusions more than once: PlatformAdminOrgImpersonation reads as false by code default, but ships true, so platform admins can enter organisations they are not a member of.

Every key below is declared in all three hosts' appsettings.json — the web app, the internal API and the background worker — and a flag read inside a queued job resolves from the worker's configuration rather than the web app's. Change a flag in all three files or in none: an absent key is not neutral, it is a third answer.

Two environment overlays change a value in this table, and both are easy to miss because they sit in a different file. appsettings.Lite.json turns SubdomainOrganisations off, because a one-container one-hostname stack has no wildcard DNS, wildcard certificate or parent-scoped cookie to serve subdomains with. All three hosts' appsettings.Production.json turn RequireEmailConfirmation on — and every shipped compose file runs ASPNETCORE_ENVIRONMENT=Production, so that is what a deployed stack does, whatever the Shipped column says. The column is the base file, which is what a local dotnet run and any custom environment inherit.

Per-org public sites are configured outside the feature-flag table on the Pages page (/Admin/Pages): a SiteSettings.IsPrivate switch (members-only vs public), plus a home-page picker and per-URL hide, chosen from the org's public-URL registry — the allowlist of published pages projected from every plugin's IPublicPageProvider. When IsPrivate is on, the two access walls allow anonymous / non-member visitors ONLY on a registered public URL, the public home, or a plugin-declared public route; robots.txt returns Disallow: / and /sitemap.xml returns 404. Any public surface a plugin publishes — a scan redirect, a public landing page, or similar under its own path prefix — stays reachable regardless: each plugin declares its own public routes via IPublicRouteAllowList, honoured by both gates, so the members-only wall never has to hardcode a plugin's paths.

Configuration entry points

AI provider integrations (OpenAI / OpenRouter / Ollama / N8N) are platform-shared — manage them at /Platform/ApiIntegrations. Platform-default SMS (Twilio) and inbound email (Mailgun) each have their own surface — /Platform/SmsConfiguration and /Platform/InboundEmailConfiguration — and a custom-domain org can override either with its own account at /Admin/SmsConfiguration / /Admin/InboundEmailConfiguration. Payment credentials (Stripe / PayPal) stay per-org for regulatory reasons — manage at /Admin/PaymentSettings. Platform-wide payment policy (which providers tenant orgs are allowed to use, plus the platform's own SaaS-billing credentials) lives at /Platform/PaymentSettings.

Webhook URLs for each provider are surfaced in the integration row's WebhookUrlPathTemplate — paste-ready for the provider's dashboard.