Nexus.Reader/.agents/skills/nexus-clean-architecture.md

name, description

name	description
nexus-clean-architecture	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.