---
name: nexus-clean-architecture
description: Clean Architecture & CQRS implementation for .NET 10 with Blazor Hybrid
---
# Clean Architecture Standards

- **Project Structure (Layered):**
  - `NexusReader.Domain`: Enterprise business rules (Entities, Value Objects, Domain Events).
  - `NexusReader.Application`: Application business rules (Commands, Queries, DTOs, Mappings, Interfaces).
  - `NexusReader.Infrastructure`: Data access, external services, and platform-specific implementations.
  - `NexusReader.UI.Shared`: UI logic and Blazor components.
  - `NexusReader.Maui` / `NexusReader.Web`: Platform host projects.

- **CQRS & Messaging:**
  - **MediatR**: Use standard `MediatR` for decoupling.
  - **Queries**: Read-only operations, return `Task<Result<T>>`.
  - **Commands**: State-changing operations, return `Task<Result>` or `Task<Result<T>>`.
  - **Handlers**: Located in `Application` layer, grouped by feature (e.g., `Queries/Reader/...`).
  - **Client-Server Boundaries**: DO NOT execute MediatR handlers directly from WASM/MAUI clients if the handler relies on server-only infrastructure (e.g., `AppDbContext`, `IHubContext`). Instead, the client must trigger an API or SignalR endpoint, and the server dispatches the MediatR command.

- **Functional Error Handling:**
  - Mandatory use of `FluentResults`.
  - No exceptions for business logic flow. Handlers must return `Result.Ok()` or `Result.Fail()`.

- **UI Architecture (Atomic Design):**
  - Components in `NexusReader.UI.Shared` must follow Atomic Design:
    - `Atoms`: Smallest functional units (Buttons, Inputs).
    - `Molecules`: Groups of atoms (Search Bar, Form Field).
    - `Organisms`: Complex UI sections (Navigation, Header).
    - `Pages`: Composed organisms forming a full view.

- **Object Mapping:**
  - Use `Mapster` for all DTO/Entity mappings.
  - Centralize configuration in `NexusReader.Application/Mappings/MappingConfig.cs`.
  - No `AutoMapper` allowed.

- **Cross-Platform Strategy:**
  - Maximize code sharing in `NexusReader.UI.Shared`.
  - Use `IPlatformService` (or similar abstractions) for native features, implemented in `Infrastructure.Mobile` or Maui projects.

- **Code Validation (CRITICAL):**
  - **Mandatory Build Verification**: After any code change, the agent MUST run `dotnet build` on the solution. The agent must verify that the build completes with `Exit code: 0` and without errors before concluding the task or requesting user feedback.