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

4. MediatR Patterns

• Queries: Read-only operations. Should return Result<T>. Use AsNoTracking() in EF Core.
• Commands: State-changing operations. Should return Result or Result<T>.

Audit Scripts

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

Reference Materials

• Layer Dependency Matrix