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/...).

• 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.