> 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/contributing/clean-architecture.md).

# Clean Architecture

Understand layer ownership, CQRS request flow, repository boundaries, and HAL response assembly.

ISLAMU Event strictly enforces Clean Architecture. Business domain rules are completely isolated from web frameworks, persistence mechanisms, and third-party SDKs. Dependencies point inward:

```
Domain ──> Application ──> Persistence / Infrastructure ──> API & BFF Composition
```

*(Note: The arrows describe compile-time project dependencies, not runtime request execution flow).*

***

## Layer Responsibilities

### 1. Domain (`Explore.Domain`)

The core of the system. Owns aggregates, entities, value objects, domain invariants, state machines, and domain events.

* **Strict Rule**: Zero dependencies on EF Core, ASP.NET Core, HTTP, or third-party libraries.

### 2. Application (`Explore.Application`)

Orchestrates business use cases through explicit commands and queries. Owns application operations, specifications, authorization requirements, immutable request/result contracts and entity-to-response mapping.

* **Strict Rule**: Validators are manually instantiated (no reflection/DI magic). Repositories return entities, never API DTOs.

### 3. Persistence & Infrastructure (`Explore.Persistence`, `Explore.Infrastructure`)

* **Persistence**: Implements database DbContext, entity type configurations, multi-tenant global query filters, and EF Core migrations.
* **Infrastructure**: Implements external adapters: [Email SMTP](/islamu-event/documentation/readme/communications-and-notifications/email-smtp.md), [Storage Providers](/islamu-event/documentation/readme/integrations-and-ai/storage.md), [Stripe Payments](/islamu-event/documentation/readme/events-and-ticketing/paid-events-and-payouts.md), and [AT Protocol Federation](/islamu-event/documentation/readme/federation-and-open-protocols/at-protocol-and-bluesky-jetstream.md).

### 4. API & BFF (`Explore.API`, `Explore.Blazor`)

* **`Explore.API`**: Thin REST controllers that invoke application operations and assemble [Server-Issued HAL Links](/islamu-event/documentation/readme/security-and-identity/authorization.md#the-golden-rule-of-client-ui-affordances).
* **`Explore.Blazor`**: Blazor WebAssembly UI and Backend-for-Frontend (BFF) managing encrypted session cookies and proxying API calls.

***

## Core Invariants

* **Identifiers**: Aggregates use UUIDv7 `Guid`; lookup tables use `int`; pagination cursors use `long`.
* **Endpoints**: GET requests default to `[AllowAnonymous]`; state-mutating commands require `[Authorize]`.
* **Concurrent edits**: When an endpoint requires `If-Match`, send the observed non-empty concurrency GUID in double quotes, for example `If-Match: "0194d714-6800-7000-8000-000000000001"`. Bare GUIDs, weak tags, wildcard/list values, and malformed quotes are rejected. If the version is stale, reload the resource before deciding whether to retry the edit.
* **Multi-Tenancy**: Tenant context resolves strictly from ambient session headers, never from untrusted request body parameters (see [Multi-Tenancy Architecture](/islamu-event/documentation/readme/security-and-identity/multi-tenancy.md)).
* **Outbox Reliability**: Side effects (email dispatch, webhooks, search indexing) commit to transactional outboxes within the same database transaction (see [Architecture & Request Flows](/islamu-event/documentation/readme/getting-started/architecture-and-request-flows.md#2-write-command-flow)).

***

## Related Guides & Next Steps

* [**Local Development Guide**](/islamu-event/documentation/readme/contributing/local-development.md) — Set up your developer environment.
* [**TUnit Testing Conventions**](/islamu-event/documentation/readme/contributing/tunit.md) — Authoring unit and integration tests.
* [**Authorization & HAL Affordances**](/islamu-event/documentation/readme/security-and-identity/authorization.md) — Understand why the server issues action links.
* [**Architecture & Request Flows**](/islamu-event/documentation/readme/getting-started/architecture-and-request-flows.md) — Detailed sequence diagrams of the CQRS pipeline.


---

# 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/contributing/clean-architecture.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.