🏗️ 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.Domains contains the host (including the platform organisation).
• Subdomain match: if the host is under the platform domain, the first label (e.g. brad in brad.yourdomain.com) is used as the organisation slug.
• Main domain match: when the host equals a domain in Organisation.Domains, that organisation is selected.
• 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 while you are on the platform host. The cookie override is only applied for page routes (not APIs/static assets) and only when the current resolved tenant is the platform.

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.

The goal is that platform-owned configuration can be applied consistently when browsing tenants on the platform host, while organisation-owned configuration still applies when you are accessing an organisation via its custom domain.

Where configuration lives

Effective organisation rule (Option B)

The effective organisation is determined by IEffectiveOrganisationSettingsService using: UsePlatformBrandingForSubdomainOrgs and whether the current host is the organisation’s custom domain.

• If the flag is false, the system always uses the current organisation’s settings.
• If the flag is true and the organisation is accessed via a custom domain, organisation-owned settings are used.
• If the flag is true and the organisation is accessed via a subdomain, platform-owned settings are used.