mjasin
150cbcdc29
Critical fixes (review findings #1, #2, #3): - Create IEbookRepository abstraction in Application layer - Remove illegal EF Core dependency from IngestEbookCommandHandler - Create EbookRepository implementation in Infrastructure/Persistence - Create ISyncBroadcaster in Application/Abstractions/Messaging - Create SignalRSyncBroadcaster in Infrastructure/RealTime - Move UpdateReadingProgressCommandHandler from Infrastructure → Application - Add EbookId to GetReaderPageQuery and IEpubReader signature - Rewrite EpubReaderService: DB-resolved file path, remove auto-provisioning - Split EpubService.cs into EpubReaderService.cs + EpubMetadataExtractor.cs - Add CurrentEbookId to IReaderNavigationService and ReaderNavigationService - Update WasmEpubReader and /api/epub endpoint for new signature High severity fixes (#4, #6, #7, #8, #16): - Change BookStorageService registration from Singleton → Scoped - Fix empty catch{} in ReaderCanvas JS interop init — now logs warnings - Replace all Console.WriteLine with ILogger in KnowledgeService + ReaderCanvas - Cache JsonSerializerOptions as static field in KnowledgeService - Wrap SyncService Task.Run body in comprehensive try/catch with ILogger Medium/Low fixes (#11, #13, #14, #15, #18, #20): - BookIngestionModal.DisposeAsync now nullifies _epubBytes (50MB array) - KnowledgeCoordinator.OnGraphUpdated: Action<T> → Func<T, Task> - BookStorageService: Path.Combine → forward-slash string interpolation - SignalR CancellationToken passed as named parameter (not payload arg)
141 lines
7.1 KiB
Markdown
141 lines
7.1 KiB
Markdown
---
|
|
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.
|