siesa-agents 2.1.26 → 2.1.27

package/bmad-core/data/architecture-patterns.md

@@ -7,7 +7,7 @@
 
 ### Folder Structure
 
-Next.js 15 App Router Structure with Clean Architecture + DDD:
+Next.js 16 App Router Structure with Clean Architecture + DDD:
 
 ```
 ├── app/                         # Next.js App Router directory
@@ -107,7 +107,7 @@ Use MCP to install Shadcn components instead of creating manually.
 
 ### Framework Selection Rules
 
-**Default**: Always use Next.js 15 with App Router unless explicitly told otherwise.
+**Default**: Always use Next.js 16 with App Router unless explicitly told otherwise.
 
 **Exceptions**: Only use pure React + Vite when user specifically mentions offline-first functionality or requests non-Next.js setup.
 
@@ -116,146 +116,300 @@ Use MCP to install Shadcn components instead of creating manually.
 ## Backend Architecture
 
 ### Architecture Style
-- **Hexagonal Architecture** (Ports & Adapters) + **Domain-Driven Design (DDD)**
+- **Clean Architecture** + **Domain-Driven Design (DDD)** + **Microservices**
+
+### Technology Stack
+- **.NET 10** with **C# Minimal API**
+- **Entity Framework Core** with **PostgreSQL**
+- **UUID (Guid)** primary keys mandatory
+- **linq2db**, **DynamicLinq**, **LinqKit** for advanced queries
+- **FluentValidation** for validation
+- **xUnit** for testing
+- **Scalar** for API documentation (NO Swagger)
+- **QuestPDF** for PDF generation
 
 ### Folder Structure
 
-MonoRepo Structure with Hexagonal Architecture + DDD:
+.NET Solution Structure with Clean Architecture + DDD + Microservices:
 
 ```
-├── apps/                              # Microservices applications
-│   ├── sales-service/                 # Sales domain microservice
-│   │   ├── src/
-│   │   │   ├── modules/
-│   │   │   │   ├── quotes/           # Quote bounded context
-│   │   │   │   │   ├── application/
-│   │   │   │   │   │   ├── ports/              # Interfaces (secondary ports)
-│   │   │   │   │   │   │   ├── repositories/
-│   │   │   │   │   │   │   └── services/
-│   │   │   │   │   │   ├── use-cases/          # Primary ports
-│   │   │   │   │   │   ├── commands/
-│   │   │   │   │   │   ├── queries/
-│   │   │   │   │   │   └── dto/
-│   │   │   │   │   ├── domain/
-│   │   │   │   │   │   ├── entities/
-│   │   │   │   │   │   ├── value-objects/
-│   │   │   │   │   │   ├── aggregates/
-│   │   │   │   │   │   ├── events/
-│   │   │   │   │   │   └── services/           # Domain services
-│   │   │   │   │   └── infrastructure/        # Adapters (secondary adapters)
-│   │   │   │   │       ├── repositories/      # Prisma implementations
-│   │   │   │   │       ├── services/          # External service adapters
-│   │   │   │   │       └── events/
-│   │   │   │   └── products/                  # Product bounded context
-│   │   │   ├── api/                           # Primary adapters
-│   │   │   │   ├── controllers/
-│   │   │   │   ├── guards/
-│   │   │   │   ├── middlewares/
-│   │   │   │   └── filters/
-│   │   │   ├── config/
-│   │   │   ├── main.ts
-│   │   │   └── app.module.ts
-│   │   ├── test/
-│   │   ├── prisma/
-│   │   │   ├── schema.prisma
-│   │   │   └── migrations/
-│   │   └── package.json
+├── src/
+│   ├── Services/                          # Microservices
+│   │   ├── Sales/                        # Sales domain microservice
+│   │   │   ├── Sales.API/                # Minimal API project
+│   │   │   │   ├── Program.cs            # Application entry point
+│   │   │   │   ├── appsettings.json
+│   │   │   │   ├── Endpoints/            # Minimal API endpoints
+│   │   │   │   │   ├── UserEndpoints.cs
+│   │   │   │   │   └── QuoteEndpoints.cs
+│   │   │   │   ├── Filters/
+│   │   │   │   ├── Middleware/
+│   │   │   │   └── Sales.API.csproj
+│   │   │   │
+│   │   │   ├── Sales.Application/        # Application layer
+│   │   │   │   ├── Quotes/               # Bounded context
+│   │   │   │   │   ├── Commands/
+│   │   │   │   │   │   ├── CreateQuoteCommand.cs
+│   │   │   │   │   │   └── CreateQuoteCommandHandler.cs
+│   │   │   │   │   ├── Queries/
+│   │   │   │   │   │   ├── GetQuoteByIdQuery.cs
+│   │   │   │   │   │   └── GetQuoteByIdQueryHandler.cs
+│   │   │   │   │   ├── DTOs/
+│   │   │   │   │   │   └── QuoteResponseDto.cs
+│   │   │   │   │   ├── Validators/       # FluentValidation
+│   │   │   │   │   │   └── CreateQuoteCommandValidator.cs
+│   │   │   │   │   └── Interfaces/       # Repository interfaces
+│   │   │   │   │       └── IQuoteRepository.cs
+│   │   │   │   └── Sales.Application.csproj
+│   │   │   │
+│   │   │   ├── Sales.Domain/             # Domain layer
+│   │   │   │   ├── Quotes/               # Bounded context
+│   │   │   │   │   ├── Entities/
+│   │   │   │   │   │   └── QuoteEntity.cs
+│   │   │   │   │   ├── ValueObjects/
+│   │   │   │   │   │   ├── QuoteNumber.cs
+│   │   │   │   │   │   └── Money.cs
+│   │   │   │   │   ├── Aggregates/
+│   │   │   │   │   │   └── QuoteAggregate.cs
+│   │   │   │   │   ├── Events/
+│   │   │   │   │   │   └── QuoteCreatedEvent.cs
+│   │   │   │   │   └── Services/         # Domain services
+│   │   │   │   │       └── QuotePricingService.cs
+│   │   │   │   └── Sales.Domain.csproj
+│   │   │   │
+│   │   │   └── Sales.Infrastructure/     # Infrastructure layer
+│   │   │       ├── Data/
+│   │   │       │   ├── ApplicationDbContext.cs
+│   │   │       │   ├── Configurations/   # EF Core configurations
+│   │   │       │   │   ├── QuoteConfiguration.cs
+│   │   │       │   │   └── UserConfiguration.cs
+│   │   │       │   └── Migrations/       # EF Core migrations
+│   │   │       ├── Repositories/         # Repository implementations
+│   │   │       │   └── QuoteRepository.cs
+│   │   │       ├── Services/             # External service adapters
+│   │   │       │   └── EmailService.cs
+│   │   │       └── Sales.Infrastructure.csproj
+│   │   │
+│   │   ├── Inventory/                    # Inventory microservice (independent DB)
+│   │   │   ├── Inventory.API/
+│   │   │   ├── Inventory.Application/
+│   │   │   ├── Inventory.Domain/
+│   │   │   └── Inventory.Infrastructure/
+│   │   │       └── Data/                 # Separate PostgreSQL DB
+│   │   │           └── InventoryDbContext.cs
+│   │   │
+│   │   └── Users/                        # Users microservice (independent DB)
+│   │       ├── Users.API/
+│   │       ├── Users.Application/
+│   │       ├── Users.Domain/
+│   │       └── Users.Infrastructure/
+│   │           └── Data/                 # Separate PostgreSQL DB
+│   │               └── UsersDbContext.cs
 │   │
-│   ├── inventory-service/             # Inventory domain microservice
-│   └── user-service/                  # User domain microservice
+│   └── Shared/                           # Shared libraries
+│       ├── Shared.Domain/                # Shared domain concepts
+│       │   ├── Base/
+│       │   │   ├── AggregateRoot.cs
+│       │   │   ├── Entity.cs
+│       │   │   ├── ValueObject.cs
+│       │   │   └── DomainEvent.cs
+│       │   ├── Interfaces/
+│       │   │   ├── IRepository.cs
+│       │   │   └── IUnitOfWork.cs
+│       │   └── Shared.Domain.csproj
+│       │
+│       ├── Shared.Infrastructure/        # Shared infrastructure
+│       │   ├── Data/
+│       │   │   ├── BaseRepository.cs
+│       │   │   └── UnitOfWork.cs
+│       │   ├── Filters/
+│       │   │   └── ValidationFilter.cs
+│       │   ├── Middleware/
+│       │   │   ├── ExceptionHandlingMiddleware.cs
+│       │   │   └── LoggingMiddleware.cs
+│       │   └── Shared.Infrastructure.csproj
+│       │
+│       └── Shared.Common/                # Common utilities
+│           ├── Extensions/
+│           │   ├── StringExtensions.cs
+│           │   └── GuidExtensions.cs
+│           ├── Helpers/
+│           │   └── DateTimeHelper.cs
+│           ├── Constants/
+│           │   └── ErrorMessages.cs
+│           └── Shared.Common.csproj
 │
-├── libs/                              # Shared libraries
-│   ├── common/                       # Common utilities
-│   │   ├── src/
-│   │   │   ├── decorators/
-│   │   │   ├── filters/
-│   │   │   ├── guards/
-│   │   │   ├── interceptors/
-│   │   │   ├── pipes/
-│   │   │   ├── types/
-│   │   │   └── utils/
-│   │   └── package.json
-│   │
-│   ├── domain-core/                  # Shared domain concepts
-│   │   ├── src/
-│   │   │   ├── base/
-│   │   │   │   ├── aggregate-root.ts
-│   │   │   │   ├── entity.ts
-│   │   │   │   ├── value-object.ts
-│   │   │   │   └── domain-event.ts
-│   │   │   ├── interfaces/
-│   │   │   └── exceptions/
-│   │   └── package.json
-│   │
-│   └── database/                     # Shared database utilities
-│       ├── src/
-│       │   ├── base-repository.ts
-│       │   ├── transaction.decorator.ts
-│       │   └── prisma.service.ts
-│       └── package.json
+├── tests/                                # Test projects
+│   ├── Sales.UnitTests/
+│   │   ├── Domain/
+│   │   ├── Application/
+│   │   └── Sales.UnitTests.csproj
+│   ├── Sales.IntegrationTests/
+│   │   ├── Repositories/
+│   │   ├── API/
+│   │   └── Sales.IntegrationTests.csproj
+│   ├── Inventory.UnitTests/
+│   └── Users.UnitTests/
+│
+├── docker/                               # Docker configurations (Production only)
+│   ├── docker-compose.yml
+│   └── Dockerfiles/
+│       ├── Sales.Dockerfile
+│       ├── Inventory.Dockerfile
+│       └── Users.Dockerfile
 │
-├── tools/                            # Development tools
-├── nx.json                          # Nx workspace configuration
-├── package.json                     # Root package.json
-└── tsconfig.base.json               # Base TypeScript config
+└── YourSolution.sln                      # Solution file
 ```
 
-### Core Principles
+### Microservices Communication Patterns
+
+#### 1. Synchronous Communication (REST)
+```csharp
+// HTTP client for inter-service communication
+public class InventoryServiceClient
+{
+    private readonly HttpClient _httpClient;
+
+    public InventoryServiceClient(HttpClient httpClient)
+    {
+        _httpClient = httpClient;
+    }
+
+    public async Task<ProductAvailabilityDto> CheckProductAvailabilityAsync(
+        Guid productId, 
+        CancellationToken cancellationToken)
+    {
+        var response = await _httpClient.GetAsync(
+            $"/api/products/{productId}/availability", 
+            cancellationToken);
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<ProductAvailabilityDto>(cancellationToken);
+    }
+}
+```
 
-#### Hexagonal Architecture First
-Strict separation of concerns following ports & adapters pattern:
-- **Domain Layer**: Pure business logic with entities, value objects, aggregates, and domain services
-- **Application Layer**: Use cases orchestrating domain logic, defining ports (interfaces)
-- **Infrastructure Layer**: Adapters implementing ports (Prisma repos, HTTP clients, message publishers)
-- **API Layer**: Primary adapters exposing application via REST/GraphQL (controllers, resolvers)
+#### 2. Asynchronous Communication (Message Broker)
+- **RabbitMQ** or **Azure Service Bus** for event-driven architecture
+- Each microservice publishes domain events
+- Other services subscribe to relevant events
 
-#### Domain-Driven Design
-Business logic drives all architectural decisions:
-- **Bounded Contexts**: Each module represents a bounded context (quotes, products, billing)
-- **Ubiquitous Language**: Code reflects business terminology
-- **Aggregates**: Consistency boundaries for domain entities
-- **Domain Events**: Communicate changes across bounded contexts
-- **Repository Pattern**: Abstract data access behind interfaces
-
-#### Dependency Rules
-- Domain layer has zero dependencies on frameworks or external libraries
-- All dependencies point inward toward the domain core
-- Use dependency inversion for all external concerns (databases, APIs, messaging)
-- Interfaces defined in application layer, implementations in infrastructure layer
-
-#### Microservices Independence
-- Each microservice has its own database (no shared databases)
-- Shared code through libraries only (common, domain-core, database)
-- Independent deployment pipelines per service
-- Service-to-service communication via events (async messaging)
+#### 3. gRPC for High-Performance Communication
+- Use for internal high-throughput service-to-service calls
+- Protocol Buffers for efficient serialization
+
+### Database per Microservice Pattern
+
+**Key Principles:**
+- Each microservice has its own PostgreSQL database
 - No direct database access between services
+- Data consistency via eventual consistency and sagas
+- Each database uses UUID (Guid) primary keys
+
+**Connection String Pattern:**
+```json
+{
+  "ConnectionStrings": {
+    "SalesDb": "Host=localhost;Database=sales_db;Username=admin;Password=***",
+    "InventoryDb": "Host=localhost;Database=inventory_db;Username=admin;Password=***",
+    "UsersDb": "Host=localhost;Database=users_db;Username=admin;Password=***"
+  }
+}
+```
 
-#### Test-Driven Development
-- Unit tests for domain entities, value objects, and use cases
-- Integration tests for repository implementations
-- E2E tests for complete API workflows
-- TDD approach: write tests before implementation
-
-#### Type Safety & Validation
-- Leverage TypeScript strict mode for compile-time safety
-- Domain validation in value objects and entities
-- DTO validation at API boundaries with class-validator
-- No `any` types allowed
-
-#### Security by Design
-- Authentication and authorization at every layer
-- Input validation on all endpoints
-- OWASP Top 10 compliance
-- Audit logging for critical operations
+### Core Backend Principles
 
-### Framework Selection Rules
+#### Clean Architecture Layers
+1. **Domain Layer** - Business entities, value objects, domain services (no dependencies)
+2. **Application Layer** - Commands, queries, validators, interfaces (depends on Domain)
+3. **Infrastructure Layer** - EF Core, repositories, external services (depends on Application)
+4. **Presentation Layer** - Minimal API endpoints (depends on Application)
 
-**Default**: Always use NestJS 10+ with TypeScript for backend services.
+#### UUID Primary Keys
+```csharp
+public abstract class Entity
+{
+    public Guid Id { get; protected set; } = Guid.NewGuid();
+}
+```
 
-**Database**: Prisma ORM only - no raw SQL queries allowed.
+#### Entity Framework Core Configuration
+```csharp
+public class QuoteConfiguration : IEntityTypeConfiguration<QuoteEntity>
+{
+    public void Configure(EntityTypeBuilder<QuoteEntity> builder)
+    {
+        builder.ToTable("Quotes");
+        builder.HasKey(q => q.Id);
+        
+        builder.Property(q => q.Id)
+            .HasColumnType("uuid")
+            .IsRequired();
+        
+        builder.OwnsOne(q => q.QuoteNumber, qn =>
+        {
+            qn.Property(n => n.Value)
+                .HasColumnName("QuoteNumber")
+                .HasMaxLength(50)
+                .IsRequired();
+        });
+    }
+}
+```
 
-**Testing**: Jest + Supertest with TDD approach.
+#### Test-Driven Development
+- Write xUnit tests before or alongside implementation
+- Use EF Core InMemory for fast unit tests
+- Use PostgreSQL Test Containers for integration tests
+- Mock external dependencies
+
+#### FluentValidation Usage
+```csharp
+public class CreateQuoteCommandValidator : AbstractValidator<CreateQuoteCommand>
+{
+    public CreateQuoteCommandValidator()
+    {
+        RuleFor(x => x.CustomerId)
+            .NotEmpty()
+            .WithMessage("Customer ID is required");
+
+        RuleFor(x => x.Items)
+            .NotEmpty()
+            .WithMessage("At least one item is required");
+    }
+}
+```
 
-**Documentation**: Swagger/OpenAPI auto-generated from decorators.
+#### Scalar API Documentation
+Register Scalar instead of Swagger in Program.cs:
+```csharp
+app.MapScalarApiReference();  // NOT app.UseSwagger()
+```
 
-**Reasoning**: NestJS provides excellent DI container, decorator-based development, and native support for microservices patterns while enforcing SOLID principles.
+## Summary
+
+### Frontend
+- **Framework**: Next.js 16 with TypeScript and App Router
+- **Architecture**: Clean Architecture + DDD
+- **State**: Zustand
+- **UI**: shadcn/ui + Radix UI + TailwindCSS v4
+- **Testing**: Vitest + React Testing Library
+- **Validation**: Zod + React Hook Form
+
+### Backend
+- **Framework**: .NET 10 with C# Minimal API
+- **Architecture**: Clean Architecture + DDD + Microservices
+- **Database**: PostgreSQL (one per microservice)
+- **ORM**: Entity Framework Core + linq2db + DynamicLinq + LinqKit
+- **Validation**: FluentValidation
+- **Testing**: xUnit + EF Core InMemory + PostgreSQL Test Containers
+- **Documentation**: Scalar (NO Swagger)
+- **Primary Keys**: UUID (Guid) mandatory
+- **PDF Generation**: QuestPDF
+
+### Key Principles
+1. **Clean Architecture** - Strict layer separation in both frontend and backend
+2. **Domain-Driven Design** - Business logic drives all decisions
+3. **Test-Driven Development** - Tests before/alongside implementation
+4. **Database per Microservice** - Complete isolation between services
+5. **Type Safety** - TypeScript (frontend) and C# (backend) strong typing
+6. **Docker for Production** - Local development without containers