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

name, description

name

description

nexus-dotnet-architect

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.