> 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/administration-and-branding/admin-guide.md).

# Administration Guide

Walkthrough of administrative consoles and management workflows for instance and tenant admins.

This guide walks administrators through the web consoles in the Blazor management interface, covering instance-level controls, tenant provisioning, monetization, branding, and organization governance.

***

## 1. Administrative Consoles & Routes

| Administration Scope        | Typical Role           | UI Entry Points                           | Capabilities                                                                                                                                                                                                                                                                                     |
| --------------------------- | ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Instance Administration** | Instance Administrator | `/settings/instance` or `/admin/instance` | [Multi-Tenant Governance](/islamu-event/documentation/readme/security-and-identity/multi-tenancy.md), tenant lifecycle and plans, domain guidance, global quotas, storage, SMTP and [platform monetization](/islamu-event/documentation/readme/events-and-ticketing/paid-events-and-payouts.md). |
| **Tenant Administration**   | Tenant Administrator   | `/settings/admin`                         | [Tenant Branding](/islamu-event/documentation/readme/administration-and-branding/white-labeling.md), lookups, navigation, custom footers, event templates, and [custom registration properties](/islamu-event/documentation/readme/events-and-ticketing/custom-properties.md).                   |
| **Organization Management** | Organization Admin     | `/settings/organization/{id}`             | Organization profile, membership approvals, verified organizer status, and API keys.                                                                                                                                                                                                             |
| **Group Management**        | Group Admin            | `/settings/group/{id}`                    | Group profile, public event listings, group branding, and members.                                                                                                                                                                                                                               |

***

## 2. Instance Administration

Use `/settings/instance` or `/admin/instance` to open the unified console. SingleTenant deployments show **Administration**, combining instance infrastructure and directory settings. MultiTenant deployments show **Instance Administration**; tenant-only controls remain under **Tenant Administration** at `/settings/admin`. Tenant management and tenant plans remain available from the console navigation. Health, provider status, domain guidance and operational warnings are retained. Delegated tenant-only administrators can manage tenant settings in SingleTenant mode; instance infrastructure remains restricted to instance administrators.

For a dedicated administration host, configure `INSTANCE_ADMIN_PUBLIC_ORIGIN` with its exact browser-facing origin. Compose defaults to `http://admin.localhost:7002`; the isolated local-agent profile uses `http://admin.localhost:5200`. Visiting that host's root opens instance settings. The retired `CONTROL_PLANE_PUBLIC_ORIGIN` variable has no compatibility fallback. External Event Control Plane fleet management remains a separate integration, not a second embedded administration console.

The authentication provider card names Local when Local Identity is selected, alongside any enabled external sign-in providers. An SMTP warning means the instance's saved host or sender settings are missing; running a development Mailpit service alone does not configure or enable platform email delivery.

### Getting Started After Setup

Open `/settings/instance?section=getting-started` after fresh sign-in. The checklist separates **Required before public disclosure**, **Required before paid events**, and **Recommended**. Each server-reported check retains its current state, requirement category, reason and remediation authority. An optional capability shown under Recommended does not become a setup prerequisite.

Use the offered operator-identity and provider actions; missing actions are not permissions you can recover by changing a browser role or URL. The identity editor uses the server's operator-kind and country choices, with labeled controls and visible guidance. If choices are unavailable, refresh rather than inventing a country or legal form. Registration identifiers are optional; complete only facts that apply to your operator. Saving uses the document's current revision and edit permission. Instance and directory identities remain independent.

### Prepare A Private Default Directory

A directory in **Provisioning** is private even when its operator identity is complete. The completed setup administrator can manage its branding and operator identity with the existing default-tenant permissions. Saving those documents never publishes the directory.

Local administrators can replace the temporary password and sign in afresh while the directory remains private. Replacement requires the protected, short-lived challenge from temporary-password sign-in, not the completed setup secret. The private administrator session does not grant public directory access.

In SingleTenant mode, authenticated instance administrators can read the default directory through the instance-administration tenant-detail API and follow its `activate` link when offered. Only the fixed default directory is accepted; this does not enable the multi-tenant fleet console. Document editing still requires that directory's tenant-admin grant, not merely a platform role.

Activation is explicit and rechecks current identity and configured capacity. If another administrator changes the identity first, activation uses that latest revision. Reload a conflicting edit instead of overwriting it. Repeating a successful activation does not create duplicate lifecycle history. Public pages remain unavailable until activation succeeds. No migration or new setting is needed; setup-completion and getting-started screens are unchanged by this API capability.

### Local Accounts

Open `/settings/instance?section=local-accounts`. The Local accounts entry appears only when the server advertises the capability for your current instance access. Tenant administration does not grant permission to manage these shared credentials.

Use **Create local account** to enter the person's email and name. A successful creation reveals a generated temporary password once. Record the operation ID, hand over the password privately, then select **Dismiss credential**. The recipient must replace that temporary password before ordinary sign-in; no email delivery is required for this supervised handover. Do not save credential-bearing responses in logs, scripts or support tickets.

For an eligible existing account, **Issue temporary credential** requires a reason. Reset invalidates its previous credential and sessions, preserves verification, and requires another private password replacement. Missing or invalid credential metadata is shown as unknown; the screen does not invent a reset action for it.

If an issuance response is lost, keep its operation ID and use **Check operation**. Status reads never repeat issuance or reveal the password. Use **Reconcile** only when offered to complete interrupted account linking. If handover is no longer possible, inspect the resulting account and perform a separately authorized reset with a new operation ID. Refreshing or reopening the section cannot recover a previously dismissed password. See [Authentication](/islamu-event/documentation/readme/security-and-identity/authentication.md) for the sign-in and recovery boundaries.

An access-denied or conflict response can arrive after the credential change was saved. Keep the original operation reference until its status is known; cancelling its form or checking another operation does not resolve it. These references stay only in the open component, so record them before leaving the section.

Successful issuance and recovery refresh the account details on your current page without dismissing the password handover. Accounts are ordered oldest-first: a newly created account may be on a later page rather than page one. If refreshing account details fails, further resets remain unavailable until a refresh succeeds; the current password handover stays visible.

### Event resource governance

Resource policy uses the existing native settings and configuration-manifest workflow. Instance administrators set the ceilings; tenant administrators may restrict them, not expand them. Instance locks remain effective in SingleTenant mode. A batch containing an invalid or widening choice is rejected as a whole. The **Event resources** section in instance governance shows the current instance policy, its source and locks. The corresponding section under tenant policies shows effective tenant values, including inherited instance limits. The displayed configured source identifies where the stored override came from; after an instance administrator tightens a ceiling, the effective value can be lower than a tenant's earlier override. An unavailable edit action or locked setting is read-only; refresh after an access denial or policy change before editing again. Tenant controls offer only values at or below the current effective numeric ceilings and subsets of currently enabled delivery types, audiences, file types and HTTPS origins. Only the instance section can opt in to unscanned documents. After a save or denial, the policy controls reload and keyboard focus returns to the original control when available, or to the section heading if that control was replaced; the result is announced separately.

API clients can read `GET /api/settings/instance/event-resources` as an instance administrator, or `GET /api/settings/tenant/EventResources` in the current tenant. Both return private effective settings with `source`, `isLocked`, `canEdit` and `reason`. Follow the returned `edit` HAL link when present to submit a strict `UpdateSettingBatchDto` by `PUT`; it is not a permanent permission. Instance reads and writes require current instance administrator authority. A signed-in non-administrator receives 403, and an anonymous caller receives 401. Tenant writes still enforce instance ceilings and fresh locks on the server even if the browser has an older edit link. Before serving resource reads on an existing development database, apply the latest generated application migrations using the selected provider's migration service. This includes `AlignAtprotoRecordDidCollation`, which keeps federated event eligibility and resource access consistent; MariaDB uses the MySQL migration catalog. Until the migration is applied, SQL Server may deny affected resource reads as unavailable rather than expose data using a mismatched identifier comparison.

| Setting                                     | Default and operator effect                                                                      |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `event_resources.enabled_delivery_types`    | Stored files and external links; disabling a type removes attendee access to affected resources. |
| `event_resources.enabled_audiences`         | All supported audiences; disabling one hides resources whose policy uses it.                     |
| `event_resources.permitted_file_types`      | PDF, OOXML Word (`.docx`) and OOXML PowerPoint (`.pptx`) only.                                   |
| `event_resources.max_upload_bytes`          | 10 MiB, also bounded by the current storage limits.                                              |
| `event_resources.allow_unscanned_documents` | `false`; only instance administrators can opt in. Tenant overrides are rejected.                 |
| `event_resources.external_origins`          | Empty; explicitly allow each HTTPS origin before external delivery.                              |
| `event_resources.audit_retention_days`      | 30 days; allowed range 0–90. Zero disables collection; tenants may shorten retention.            |
| `event_resources.max_active_resources`      | 500; allowed range 0–500. Zero prevents new resource creation.                                   |

Origin entries are authoritative HTTPS authorities, such as `https://materials.example.org`. Do not include a trailing slash, path, query, fragment, credentials or wildcard. Alternate spellings, including uppercase hosts and explicit default ports, are rejected rather than silently normalized. Tenant origin lists must be subsets of the instance list.

Tightening an instance ceiling takes effect in fresh resource checks even if an older tenant override remains stored. Existing resources can still be repaired, withdrawn or deleted by their authorized managers; a disabled policy does not trap them in an unmanageable state. Enabling a delivery type does not bypass audience eligibility, provider authorization or file safety checks.

Resource-management audit cleanup runs hourly through the platform scheduler, including when resource delivery is disabled. It removes complete expired rows; retention zero removes existing rows on the next sweep. Subject erasure clears manager attribution without deleting shared event resources. Keep the scheduler enabled while retained audit data remains.

### Resource-policy deployment activation (operator API)

Remote event-resource policies use a deployment-level activation fence. This operator API is separate from resource authoring or publication; activating a provider does not enable a resource or bypass instance governance.

Use `/api/event-resource-provider-activation` with current instance administrator authority. Responses are private and non-cacheable. The binding read also requires an authenticated account: anonymous callers receive 401, while signed-in accounts without current instance-administrator authority receive 403. `Idempotency-Key` does not replay an earlier activation receipt: each retry rechecks current administrator authority and deployment state.

1. Read `GET /bindings` for the current binding revision. Register or update a deployment through `PUT /bindings`, supplying its UUIDv7 deployment ID, normalized gRPC endpoint aliases, explicit scope, policy version and the expected binding revision. Empty scope selects Cerbos root policy. Keep every alias for the same physical policy deployment under the same ID; aliases cannot later be removed or transferred to another deployment.
2. Before an external policy writer changes a bound deployment, call `POST /begin` with its deployment ID. Resource authority closes immediately. Known application-managed publishers fence their own writes, but every external writer must participate too.
3. Stop previous writers and verify the declared scope/version across all reachable replicas. Call `POST /activate` with the operation ID and epoch from the current operation receipt, the scope/version, confirmation that previous writers have stopped, the positive reachable-replica count, and the number running the declared policy. Both counts must agree. Set `frozenParentPolicyContractConfirmed` to `true` only after verifying the parent event moderation policies and their derived-role dependencies against the frozen principal contract. Custom rules that use the legacy raw `nowUtc` attribute must be migrated to derived-time predicates before activation. Omitting or declining this confirmation keeps the operation closed.
4. If publication is uncertain, cancelled, incomplete or failed, keep access closed. Start a new operation, repair the deployment, verify convergence and activate that new operation. An older receipt cannot activate a newer operation. After a binding conflict, reload the binding revision before making another change.

The application cannot discover undeclared aliases or unannounced remote edits. Replica counts and convergence are operator attestations, not measurements inferred from an upload response. Do not treat the local epoch as a remote policy revision. Manage these bindings only through this protocol, not generic settings editing or configuration-manifest import.

### Background Scheduler

When enabled, **Background Scheduler** in Instance Settings shows the current scheduler and job state. If a read is rate-limited or temporarily unavailable, the section shows an error instead of stale job controls. Wait for the service to recover, then select **Refresh**; refreshing does not run, pause or resume jobs.

### Tenant Lifecycle Management

* **Create Tenant**: Provision a new community tenant with a unique slug and primary administrator.
* **Tenant States**:
  * *Active*: Fully operational; events can be published and registered.
  * *Suspended*: Public routes return inactive notices; administrative reads remain accessible.
  * *Archived*: Read-only state prior to scheduled purge.
* **Destructive Purge**: Scheduling a tenant purge requires explicit reason confirmation and typing the tenant slug.

### Platform Monetization

Navigate to `/settings/instance` $\to$ **Monetization** (see [Paid Events & Payouts](/islamu-event/documentation/readme/events-and-ticketing/paid-events-and-payouts.md)):

* **Platform Fee Policy**: Set platform fees across paid ticket sales (configured in basis points and optional fixed charges per currency).
* **Platform Contribution**: Enable optional voluntary contributions during checkout with customizable heading and body text.
* *Note*: Changes use optimistic concurrency revisions; concurrent edits fail safely to prevent accidental overwrites.

***

## 3. Tenant Administration & White-Labeling

Tenant administrators manage their community experience via `/settings/admin`:

### Branding & Appearance

* **Themes & Colors**: Configure brand primary and secondary colors (see [White-Labeling](/islamu-event/documentation/readme/administration-and-branding/white-labeling.md)).
* **Logos & Favicons**: Upload high-resolution community assets.
* **Navigation & Links**: Customize top navigation links and header menus.

### Custom Footers

* Choose footer layouts, social links, and copyright notices.
* Built-in governance locks prevent tenants from removing legally required disclosures (such as Terms of Service and Privacy Policy).

### Custom Registration Properties

* Define custom questions and fields for events and attendee registrations (see [Custom Properties Governance](/islamu-event/documentation/readme/events-and-ticketing/custom-properties.md)).
* Set exposure levels: `Public` (visible on listing), `Private` (visible to organizers only), or `System`.

### Moving Rooms Between Locations

A room can move to another location in the same tenant only when no session, session group, or agenda item still references it. This includes any retained reference on a deleted record: moving a room never rewrites historical schedule links. Non-location edits remain available for scheduled rooms. Create a replacement room at the destination if the original room must remain linked to a schedule.

A successful move preserves the room ID and applies the final name and other submitted edits together. Room names must be unique within the destination location. If the room or its schedule references change concurrently, reload before retrying; a rejected move leaves the original placement intact.

***

## 4. Organization & Group Governance

Organizers create Organizations and Groups to co-host events:

* **Verification Badges**: Instance and tenant admins can mark verified organizations to give attendees trust.
* **Membership Management**: Assign Owner, Admin, and Member roles within an organization (see [Admin Hierarchy](/islamu-event/documentation/readme/administration-and-branding/admin-hierarchy.md)).
* **Payment Connections**: Organizers onboard their own [Stripe Connect](/islamu-event/documentation/readme/events-and-ticketing/paid-events-and-payouts.md) accounts directly through organization settings to receive ticket payouts.

***

## Related Guides & Next Steps

* [**Admin Hierarchy & Scopes**](/islamu-event/documentation/readme/administration-and-branding/admin-hierarchy.md) — Review permission sets across Instance, Tenant, and Event roles.
* [**White-Labeling & Branding**](/islamu-event/documentation/readme/administration-and-branding/white-labeling.md) — Detailed token customization and design tokens.
* [**Custom Domains & SEO**](/islamu-event/documentation/readme/administration-and-branding/custom-domains-and-seo.md) — Route custom domains to tenant storefronts.
* [**Configuration Manifests**](/islamu-event/documentation/readme/configuration-and-operations/configuration-manifests.md) — Export and import declarative tenant settings.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://islamu.gitbook.io/islamu-event/documentation/readme/administration-and-branding/admin-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.