Nexus.Reader/.agent/skills/nexus-dotnet-architect/SKILL.md

---
name: nexus-dotnet-architect
description: Guides the development of production-grade .NET 10 APIs and microservices for the Nexus project, enforcing Clean Architecture, CQRS, Result Pattern, Mapster, no async void, specific project standards like Multi-Tenancy and EF Core migrations, and backend development best practices like caching, resilience, observability, and AI-powered code analysis. Use when building backend services or APIs within the Nexus ecosystem.
---

# Nexus Dotnet Architect Skill

## Overview

This skill provides expert guidance for developing production-grade .NET 10 APIs and microservices within the Nexus project ecosystem. It enforces a strict adherence to the defined architecture, technical constraints, and development workflow, ensuring high performance, maintainability, and scalability.

## Core Principles & Constraints

This skill mandates the following architectural and development standards:

### Architecture

- **Clean Architecture:** Strict separation of concerns: `Domain` -> `Application` <- `Infrastructure`.
- **CQRS Pattern:** Mandatory use of `MediatR`. All business logic must reside in handlers, not UI components.
- **Result Pattern:** Zero exceptions for flow control. All handlers must return `Result<T>` via `FluentResult`.
- **Mapping:** Exclusive use of `Mapster`. No other mapping libraries are permitted.

### Technical Constraints

- **Platform:** Target .NET 10 with **Native AOT** compatibility. Optimize for mobile performance.
- **UI Framework:** Blazor Component Model. Use isolated Razor Components (`.razor` + `.razor.css`). No raw HTML/CSS in components.
- **Directory Structure:** `/src` for application code and `/tests` for testing code at the solution root level.

### Development Workflow

- **Verification-Led:** Define tests and verification steps *before* writing feature code.
- **Step-by-Step Execution:** Break complex tasks into manageable, verifiable chunks.
- **Layer Integrity:** Constantly check for and prevent illegal cross-layer dependencies (e.g., `Application` depending on `Infrastructure`).
- **Mandatory Build Gate:** After **every** code change, run `dotnet build NexusReader.slnx --no-restore` from the solution root. The agent must not proceed if there are any `error CS*` compiler errors. Build warnings are acceptable.

### API & Microservice Focus

- Develop production-grade APIs and microservices using C# and ASP.NET Core.
- Leverage modern C# features.
- Implement robust data access patterns, including EF Core and Dapper.
- Incorporate caching strategies and performance optimization.

## Project Specific Standards

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

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

### Auditing & Verification

- **Audit Scripts:** Use `src/.agent/skills/nexus-architecture-standards/scripts/arch_check.sh` (or equivalent logic) to scan for illegal cross-layer imports. This script should be run regularly to maintain layer integrity.
- **Reference Materials:** Refer to `src/.agent/skills/nexus-architecture-standards/artifacts/layer_matrix.md` for a clear definition of layer dependencies.

## Backend Development Patterns

### Architecture & Design

- **API Design:** Follow RESTful principles, use clear and consistent naming conventions.
- **Microservices Principles:** Design for independent deployability, scalability, and fault isolation.
- **Domain-Driven Design (DDD):** Apply DDD concepts where appropriate to model complex business domains.

### Dependency Injection

- Utilize the built-in .NET Core Dependency Injection container.
- Register services with appropriate lifetimes (Scoped, Singleton, Transient).
- Prefer constructor injection.

### Caching

- Implement distributed caching using **Redis** for improved performance and reduced database load.
- Apply caching strategies judiciously (e.g., cache-aside, read-through, write-through).

### Database Optimization

- **Entity Framework Core (EF Core):** Optimize queries, use `AsNoTracking()`, leverage projections, and manage migrations effectively.
- **Dapper:** Utilize Dapper for performance-critical queries where EF Core might be too slow.
- **Connection Pooling:** Ensure database connections are managed efficiently.

### Resilience Patterns

- **Retry Policies:** Implement retry logic for transient failures (e.g., network issues, temporary service unavailability) using libraries like Polly.
- **Circuit Breaker:** Protect against cascading failures by implementing circuit breaker patterns.
- **Timeouts:** Configure appropriate timeouts for external service calls and database operations.

### Observability

- **Logging:** Implement structured logging using a robust logging framework (e.g., Serilog).
- **Monitoring:** Integrate with monitoring solutions (e.g., Application Insights, Prometheus) for metrics and performance tracking.
- **Distributed Tracing:** Enable distributed tracing to track requests across multiple services.

## Code Review & Quality Assurance

### Static Analysis

- Scan code for common bugs, anti-patterns, and style violations.
- Ensure adherence to project coding standards.

### Security Review (OWASP)

- Identify potential security vulnerabilities based on OWASP Top 10 guidelines.
- Check for common security flaws like injection vulnerabilities, broken authentication, etc.

### Performance Optimization

- Analyze code for performance bottlenecks.
- Suggest improvements for efficiency and resource utilization.

### Infrastructure-as-Code (IaC) Assessment

- Review IaC definitions (e.g., Terraform, Dockerfile) for security and best practices.

## Review Process

The code reviewer follows a structured, 10-step approach to provide feedback:

1. **Understand Context:** Analyze the code and its purpose.
2. **Static Analysis:** Perform initial checks for common issues.
3. **Security Scan:** Identify potential security vulnerabilities.
4. **Performance Check:** Evaluate for performance bottlenecks.
5. **IaC Review:** Assess infrastructure code if applicable.
6. **Best Practices Check:** Verify adherence to established patterns.
7. **Constructive Feedback:** Provide clear, actionable suggestions.
8. **Prioritization:** Rank feedback by severity (critical, high, medium, low).
9. **Educational Tone:** Explain *why* a change is recommended.
10. **Final Summary:** Consolidate findings and recommendations.

## Resources

- **EF Core Best Practices:** See `references/ef-core-best-practices.md` for detailed guidance on optimizing EF Core usage.
- **Implementation Playbook:** Refer to `resources/implementation-playbook.md` for detailed examples and implementation guidance.