Nexus.Reader/.agent/skills/nexus-architecture-standards/SKILL.md

name, description, tags, version

name	description	tags	version
nexus-architecture-standards	Guidelines and automated checks for maintaining Clean Architecture and SaaS standards in the NexusReader project.	Architecture CleanArchitecture .NET MediatR SaaS MultiTenancy	1.0.0

NexusReader Architecture Standards

This skill defines the architectural guardrails for the NexusReader project to ensure consistency, scalability, and security.

Core Rules

1. Clean Architecture Layers

• Domain: Pure business logic, entities, and enums. Zero dependencies on other layers.
• Application: Use cases, MediatR handlers, and interfaces. Depends ONLY on Domain.
• Infrastructure: Implementation details (DB context, AI services, Auth). Depends on Application and Domain.
• Web/Mobile: Presentation layer. Depends on Application (and Infrastructure for DI setup).

Caution

Application MUST NOT depend on Infrastructure. This is a common failure mode. Always use abstractions (interfaces) in Application and implement them in Infrastructure.

2. Multi-Tenancy (Tenant Isolation)

• Every entity related to user data MUST have a TenantId property.
• Every query MUST filter by TenantId to prevent data leakage.
• Default TenantId is "global" for shared resources.

3. Error Handling

• Use FluentResults (Result<T>) for all Application services and handlers.

• Avoid throwing exceptions for expected business failures; use Result.Fail().

• Commands: State-changing operations. Should return Result or Result<T>.

+### 5. Async Operations (Zero Tolerance for async void) +- All asynchronous operations MUST return Task or ValueTask. +- Event handlers MUST use Func<Task> or async-compatible patterns. +- UI components MUST await all service calls and use InvokeAsync(StateHasChanged) for state updates within async contexts.

6. Database Schema Changes

• Every change to a Domain entity or DbContext MUST be followed by the generation of a new EF Core migration.
• Mandatory Commands:
  • dotnet ef migrations add <MigrationName> --project src/NexusReader.Data --startup-project src/NexusReader.Web
  • dotnet ef database update --project src/NexusReader.Data --startup-project src/NexusReader.Web
• Ensure the migration is applied to all local development environments before proceeding with feature verification.

Audit Scripts

• ArchCheck.sh: A shell script to scan for illegal cross-layer imports.

Reference Materials

• Layer Dependency Matrix