> 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/getting-started/architecture-and-request-flows.md). # Architecture & Request Flows Understand browser routing, application operations, authority, tenancy, and durable effects. ISLAMU Event follows [Clean Architecture](/islamu-event/documentation/readme/contributing/clean-architecture.md). The Domain and Application layers own business rules; Persistence and Infrastructure implement data and provider concerns; `Explore.API` composes the runtime; and `Explore.Blazor` (Backend-for-Frontend / BFF) manages the browser session. *** ## 1. Browser Request Flow 1. The browser connects over HTTPS to the Blazor BFF (`Explore.Blazor`). 2. The BFF owns the encrypted session cookie and obtains or refreshes access tokens via [Keycloak Authentication](/islamu-event/documentation/readme/security-and-identity/authentication.md). 3. The BFF proxies requests to `Explore.API`, forwarding the bearer JWT and resolved [Multi-Tenant Context](/islamu-event/documentation/readme/security-and-identity/multi-tenancy.md). 4. The API evaluates caller permissions and invokes the requested application operation before reading or changing stored data. 5. The API response embeds dynamic [HAL Links](/islamu-event/documentation/readme/security-and-identity/authorization.md#the-golden-rule-of-client-ui-affordances) indicating which follow-up actions the user is authorized to perform right now. > \[!NOTE] The browser client never inspects user roles or JWT claims to invent action buttons. Action affordances are strictly driven by server-issued HAL links. *** ## 2. Write (Command) Flow 1. **Endpoint Boundary**: Authentication and high-level route policies run first. 2. **Resource Authorization**: Evaluates the caller, tenant boundary, and target entity state via [Authorization (Local RBAC or Cerbos)](/islamu-event/documentation/readme/security-and-identity/authorization.md). 3. **Domain Validation**: The application operation validates the business rules. 4. **Atomic Settlement**: A single serializable transaction commits state changes to PostgreSQL or SQLite. 5. **Transactional Outbox**: Side effects (such as [Transactional Emails](/islamu-event/documentation/readme/communications-and-notifications/email-smtp.md), [Outgoing Webhooks](/islamu-event/documentation/readme/integrations-and-ai/webhooks.md), or [AT Protocol Federation](/islamu-event/documentation/readme/federation-and-open-protocols/at-protocol-and-bluesky-jetstream.md)) are written to outbox tables within the same database transaction. 6. **HAL Affordance**: The response returns the updated resource with freshly computed `_links`. *** ## 3. External Callback Flow Incoming provider callbacks (such as Stripe payment confirmations, registration webhooks, or moderation events) use dedicated signature verification: * The payload signature is verified before processing (see [Webhooks & Callbacks](/islamu-event/documentation/readme/integrations-and-ai/webhooks.md)). * Intake is idempotently recorded before effects are applied to domain state. * Browser return URLs or client redirects are **never** treated as payment truth (see [Paid Events & Payouts](/islamu-event/documentation/readme/events-and-ticketing/paid-events-and-payouts.md)). *** ## 4. Operational Probes & Health * **`/alive`**: Confirms that the Kestrel web host process is executing. * **`/health`**: Evaluates active connections to PostgreSQL, Keycloak, storage, and policy engines (see [Troubleshooting & Health](/islamu-event/documentation/readme/configuration-and-operations/troubleshooting-and-health.md#health-check-endpoints-reference)). * **`/metrics`**: Exposes Prometheus-compatible operational measurements. *** ## 5. Durable Authority Patterns * **Notifications**: The [In-App Notification Inbox](/islamu-event/documentation/readme/communications-and-notifications/in-app-notifications.md) remains the authoritative state; Web Push and SSE merely notify the client to pull updates. * **Commercial Truth**: Signed webhook events and ledger reconciliation establish payment state (see [Paid Events & Payouts](/islamu-event/documentation/readme/events-and-ticketing/paid-events-and-payouts.md)). * **Federation**: Local lifecycle state strictly governs outbound publication; cursor settlements commit atomically (see [AT Protocol Federation](/islamu-event/documentation/readme/federation-and-open-protocols/at-protocol-and-bluesky-jetstream.md)). * **Privacy Erasure**: Account deletion establishes an immutable anti-resurrection fence before triggering external background deletions (see [Privacy Erasure & GDPR Compliance](/islamu-event/documentation/readme/security-and-identity/privacy-erasure.md)). *** ## Related Guides & Next Steps * [**Self-Hosting Overview**](/islamu-event/documentation/readme/self-hosting.md) — Select the optimal deployment topology for your organization. * [**Authentication Architecture**](/islamu-event/documentation/readme/security-and-identity/authentication.md) — Learn how OIDC tokens, cookies, and Keycloak realms interact. * [**Authorization & Access Control**](/islamu-event/documentation/readme/security-and-identity/authorization.md) — Understand Local RBAC vs. Cerbos PDP and HAL affordance gating. * [**Clean Architecture Guide**](/islamu-event/documentation/readme/contributing/clean-architecture.md) — Deep dive into Domain, Application, and Persistence boundaries. --- # 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/getting-started/architecture-and-request-flows.md?ask=&goal= ``` `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.