🏗️ 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 TenantResolutionMiddleware. 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. brad in brad.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)

Mongo repositories use ITenantContext to decide where to read/write:

• MongoRepository<TEntity> uses CurrentTenantDatabaseName (tenant DB) and applies an organisation id filter for org-scoped entities.
• PlatformMongoRepository<TEntity> always uses PlatformDatabaseName (platform DB), letting platform-owned entities be stored and queried consistently.

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 TenantResolutionMiddleware 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 controls whether custom hostnames resolve to organisations via Organisation.Domain. Custom domains are direct access aliases only: /api/org/switch does not auto-redirect to a custom hostname. Users must navigate to the custom domain directly for it to take effect.

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.blazorblueprint.net) 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 UsePlatformBrandingForSubdomainOrgs all enabled:

Turning off UsePlatformBrandingForSubdomainOrgs 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 UsePlatformBrandingForSubdomainOrgs 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:

• UsePlatformBrandingForSubdomainOrgs = false → every org uses its own settings (or inherits if empty).
• UsePlatformBrandingForSubdomainOrgs = true + request on the org's custom domain → org-owned settings apply; the full /Admin/* surface is available.
• UsePlatformBrandingForSubdomainOrgs = 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 platform's current values but 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.
• 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.

Per-org private workspaces are configured outside the feature-flag table. Each organisation has a SiteSettings.PublicAccess field (default true) toggled by the Private workspace (members only) switch in /Admin/OrganisationSettings. When off, PrivateWorkspaceMiddleware redirects anonymous visitors to /Account/Login, robots.txt returns Disallow: /, and /sitemap.xml returns 404.

Configuration entry points

Configuration entry points after the platform-move refactor: AI / SMS / inbound-email integrations (OpenAI, N8N, Twilio, MailgunInbound) are platform-shared — manage at /Platform/ApiIntegrations and /Platform/Webhooks. Payment credentials (Stripe / GoCardless / 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/PaymentConfiguration.

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