---
name: nexus-architecture-standards
description: Guidelines and automated checks for maintaining Clean Architecture and SaaS standards in the NexusReader project.
tags: [Architecture, CleanArchitecture, .NET, MediatR, SaaS, MultiTenancy]
version: 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](scripts/arch_check.sh): A shell script to scan for illegal cross-layer imports.

## Reference Materials
- [Layer Dependency Matrix](artifacts/layer_matrix.md)