> For the complete documentation index, see [llms.txt](https://islamu.gitbook.io/islamu-event/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://islamu.gitbook.io/islamu-event/documentation/readme/security-and-identity/multi-tenancy.md).

# Multi-Tenancy

Select deployment mode, resolve tenants, and preserve fail-closed data isolation.

ISLAMU Event defaults to single-tenant operation. To operate multiple independent community centers or organizational chapters from a single deployment, set `DEPLOYMENT_MODE=multi_tenant` in your environment (see [Environment Variables Reference](/islamu-event/documentation/readme/configuration-and-operations/environment-variables.md#1-core-deployment--networking)) before initial onboarding.

***

## Tenant Resolution Hierarchy

Multi-tenant HTTP requests resolve tenant context through a strict, fail-closed sequence:

```mermaid
graph TD
    A[Incoming Request] --> B{BFF Tenant Context Present?}
    B -- Yes --> C[Apply Tenant Boundary]
    B -- No --> D{Admin Host Exclusion?}
    D -- Yes --> E[Route to Instance Admin Console]
    D -- No --> F{Match Custom Domain?}
    F -- Yes --> C
    F -- No --> G{Match Subdomain?}
    G -- Yes --> C
    G -- No --> H[404 Not Found - Fail Closed]
```

1. **Trusted BFF Tenant Context**: Passed via authenticated secure session headers (see [Architecture & Request Flows](/islamu-event/documentation/readme/getting-started/architecture-and-request-flows.md#1-browser-request-flow)).
2. **Admin-Host Exclusion**: Dedicated administrative hostnames (e.g. `admin.example.org`) route exclusively to the [Instance Administration Console](/islamu-event/documentation/readme/administration-and-branding/admin-guide.md).
3. **Custom Domain Matching**: Resolves tenants mapped to external domains (see [Custom Domains & SEO](/islamu-event/documentation/readme/administration-and-branding/custom-domains-and-seo.md)).
4. **Subdomain Matching**: Maps `tenant.events.example.org` to the registered tenant identifier.
5. **Fail Closed**: If no matching tenant is found, the server immediately returns `404 Not Found`. An unknown host will **never** silently fall back to an arbitrary default tenant.

***

## Database & Query Filter Isolation

Every multi-tenant entity implements `ITenantScoped`. EF Core applies global query filters automatically:

* If ambient tenant context is absent, queries evaluate to `false` and return empty sets rather than leaking cross-tenant data.
* System workers and background dispatchers must explicitly opt into cross-tenant processing using bounded tenant predicates.

***

## Governance & Settings Cascade

Settings flow downward through a five-tier hierarchy: $$\text{Instance} \longrightarrow \text{Tenant} \longrightarrow \text{Organization} \longrightarrow \text{Group} \longrightarrow \text{User}$$

Instance administrators can lock specific governance properties (such as footer links, legal notices, or payment gateways) to prevent tenants from modifying them (see [White-Labeling & Branding](/islamu-event/documentation/readme/administration-and-branding/white-labeling.md)).

***

## Acceptance Testing

1. Configure at least two test tenants (`tenant-a.events.local` and `tenant-b.events.local`).
2. Verify that creating an event under Tenant A is invisible to attendees on Tenant B.
3. Access the application using an unmapped hostname and confirm it returns `404 Not Found`.
4. Verify that background outbox workers process messages with the correct tenant context.

***

## Related Guides & Next Steps

* [**Custom Domains & SEO**](/islamu-event/documentation/readme/administration-and-branding/custom-domains-and-seo.md) — Bind custom vanity domains to individual tenants.
* [**White-Labeling & Branding**](/islamu-event/documentation/readme/administration-and-branding/white-labeling.md) — Configure tenant-specific logos, themes, and CSS tokens.
* [**Admin Hierarchy & Scopes**](/islamu-event/documentation/readme/administration-and-branding/admin-hierarchy.md) — Understand permissions for Instance Admins vs. Tenant Admins.
* [**Deployment Tiers & Sizing**](/islamu-event/documentation/readme/self-hosting/deployment-tiers.md) — Review hardware requirements for multi-tenant deployments.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://islamu.gitbook.io/islamu-event/documentation/readme/security-and-identity/multi-tenancy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.