siesa-agents 2.1.22 → 2.1.23

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

@@ -112,3 +112,150 @@ Use MCP to install Shadcn components instead of creating manually.
 **Exceptions**: Only use pure React + Vite when user specifically mentions offline-first functionality or requests non-Next.js setup.
 
 **Reasoning**: Next.js provides better developer experience, built-in optimization, and easier deployment while maintaining PWA capabilities.
+
+## Backend Architecture
+
+### Architecture Style
+- **Hexagonal Architecture** (Ports & Adapters) + **Domain-Driven Design (DDD)**
+
+### Folder Structure
+
+MonoRepo Structure with Hexagonal Architecture + DDD:
+
+```
+├── 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
+│   │
+│   ├── inventory-service/             # Inventory domain microservice
+│   └── user-service/                  # User domain microservice
+│
+├── 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
+│
+├── tools/                            # Development tools
+├── nx.json                          # Nx workspace configuration
+├── package.json                     # Root package.json
+└── tsconfig.base.json               # Base TypeScript config
+```
+
+### Core Principles
+
+#### 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)
+
+#### 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)
+- No direct database access between services
+
+#### 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
+
+### Framework Selection Rules
+
+**Default**: Always use NestJS 10+ with TypeScript for backend services.
+
+**Database**: Prisma ORM only - no raw SQL queries allowed.
+
+**Testing**: Jest + Supertest with TDD approach.
+
+**Documentation**: Swagger/OpenAPI auto-generated from decorators.
+
+**Reasoning**: NestJS provides excellent DI container, decorator-based development, and native support for microservices patterns while enforcing SOLID principles.

package/bmad-core/data/backend-standards.md

@@ -1,43 +1,32 @@
 # Backend Development Standards
 
-## Architecture Principles
-
-### Hexagonal Architecture Implementation
-- **Application Core**: Domain entities, value objects, aggregates, and domain services
-- **Primary Ports**: Use cases, commands, queries, and application services  
-- **Primary Adapters**: REST controllers, GraphQL resolvers, message handlers
-- **Secondary Ports**: Repository interfaces, external service interfaces
-- **Secondary Adapters**: Prisma repositories, HTTP clients, message publishers
-
-### Dependency Rules
-- Application core must not depend on external frameworks
-- All dependencies point inward toward the domain
-- Use dependency inversion for all external concerns
-- Interfaces defined in application layer, implementations in infrastructure
+> **Note**: For architecture patterns and principles (Hexagonal Architecture, DDD, folder structure), see [architecture-patterns.md](./architecture-patterns.md)
 
 ## Technology Stack Standards
 
 ### Core Technologies
 - **NestJS**: 10+ with TypeScript and decorators
 - **TypeScript**: Strict mode enabled, no `any` types
-- **Prisma**: ORM for database operations (no raw queries)
-- **Jest**: Unit and integration testing
-- **Class-validator**: Request validation and transformation
+- **Prisma**: ORM for database operations (no raw queries allowed)
+- **Jest + Supertest**: Unit, integration, and E2E testing
+- **Class-validator + Class-transformer**: DTO validation
 
-### Framework Selection Rules
-- **Default**: Always use NestJS 10+ with TypeScript
-- **Database**: Prisma ORM only - no raw SQL queries allowed
-- **Testing**: TDD approach with Jest and Supertest
-- **Documentation**: Swagger/OpenAPI for all endpoints
+### Framework Standards
+- **Default Framework**: NestJS 10+ with TypeScript
+- **Database**: Prisma ORM only - no raw SQL queries
+- **Testing**: TDD approach with comprehensive test coverage
+- **Documentation**: Swagger/OpenAPI auto-generated from decorators
+- **Messaging**: NestJS Microservices (Redis, RabbitMQ, or gRPC)
 
 ### Development Tools
-- **Nx**: MonoRepo management and build system
+- **Nx**: MonoRepo management and build orchestration
 - **ESLint + Prettier**: Code quality and formatting
-- **Husky**: Git hooks for pre-commit validation
-- **Winston**: Structured logging
-- **Redis**: Caching and message transport
+- **Husky**: Pre-commit hooks for quality gates
+- **Winston**: Structured logging with log levels
+- **Redis**: Caching, session storage, and message transport
+- **Passport + JWT**: Authentication and authorization
 
-## Domain-Driven Design Standards
+## Domain-Driven Design Implementation
 
 ### Entity Structure
 ```typescript
@@ -46,7 +35,6 @@ export class UserEntity extends AggregateRoot {
     public readonly id: UserId,
     private _email: EmailValueObject,
     private _name: NameValueObject,
-    private _createdAt: Date,
   ) {
     super();
   }
@@ -56,7 +44,6 @@ export class UserEntity extends AggregateRoot {
       UserId.generate(),
       EmailValueObject.create(props.email),
       NameValueObject.create(props.name),
-      new Date(),
     );
     user.addDomainEvent(new UserCreatedEvent(user.id));
     return user;
@@ -91,11 +78,6 @@ export class EmailValueObject {
     }
   }
 
-  private isValidEmail(email: string): boolean {
-    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-    return emailRegex.test(email);
-  }
-
   equals(other: EmailValueObject): boolean {
     return this.value === other.value;
   }
@@ -106,15 +88,45 @@ export class EmailValueObject {
 }
 ```
 
-### Repository Interface Pattern
+### Repository Pattern
 ```typescript
+// Interface (in application/ports/repositories)
 export interface UserRepositoryInterface {
   save(user: UserEntity): Promise<UserEntity>;
   findById(id: UserId): Promise<UserEntity | null>;
   findByEmail(email: EmailValueObject): Promise<UserEntity | null>;
-  findAll(criteria: FindUsersCriteria): Promise<UserEntity[]>;
   delete(id: UserId): Promise<void>;
 }
+
+// Implementation (in infrastructure/repositories)
+@Injectable()
+export class PrismaUserRepository implements UserRepositoryInterface {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async save(user: UserEntity): Promise<UserEntity> {
+    const data = {
+      id: user.id.toString(),
+      email: user.email.toString(),
+      name: user.name.toString(),
+    };
+
+    const savedUser = await this.prisma.user.upsert({
+      where: { id: data.id },
+      update: data,
+      create: data,
+    });
+
+    return this.toDomain(savedUser);
+  }
+
+  private toDomain(prismaUser: User): UserEntity {
+    return UserEntity.reconstitute({
+      id: UserId.create(prismaUser.id),
+      email: EmailValueObject.create(prismaUser.email),
+      name: NameValueObject.create(prismaUser.name),
+    });
+  }
+}
 ```
 
 ## Use Case Standards
@@ -133,20 +145,19 @@ export class CreateUserUseCase {
   async execute(command: CreateUserCommand): Promise<UserResponseDto> {
     // 1. Validate business rules
     await this.validateUserDoesNotExist(command.email);
-    
+
     // 2. Create domain entity
     const user = UserEntity.create({
       email: command.email,
       name: command.name,
     });
-    
+
     // 3. Persist entity
     const savedUser = await this.userRepository.save(user);
-    
+
     // 4. Publish domain events
     await this.eventBus.publishAll(savedUser.getUncommittedEvents());
-    savedUser.markEventsAsCommitted();
-    
+
     // 5. Return response DTO
     return UserResponseDto.fromEntity(savedUser);
   }
@@ -172,20 +183,16 @@ export class CreateUserCommand {
   @IsNotEmpty()
   @Length(2, 50)
   readonly name: string;
-
-  @IsOptional()
-  @IsString()
-  readonly organizationId?: string;
 }
 ```
 
 ## Testing Standards
 
 ### Testing Strategy
-- **Unit Tests**: Domain entities, value objects, use cases
-- **Integration Tests**: Repository implementations, external services
-- **E2E Tests**: Complete API workflows
-- **Contract Tests**: External service integrations
+- **Unit Tests**: Domain entities, value objects, use cases (isolated logic)
+- **Integration Tests**: Repository implementations, database operations
+- **E2E Tests**: Complete API workflows with Supertest
+- **TDD Approach**: Write tests before implementation
 
 ### Test Structure
 ```typescript
@@ -198,19 +205,8 @@ describe('CreateUserUseCase', () => {
     const module = await Test.createTestingModule({
       providers: [
         CreateUserUseCase,
-        {
-          provide: USER_REPOSITORY,
-          useValue: {
-            save: jest.fn(),
-            findByEmail: jest.fn(),
-          },
-        },
-        {
-          provide: EVENT_BUS,
-          useValue: {
-            publishAll: jest.fn(),
-          },
-        },
+        { provide: USER_REPOSITORY, useValue: { save: jest.fn(), findByEmail: jest.fn() } },
+        { provide: EVENT_BUS, useValue: { publishAll: jest.fn() } },
       ],
     }).compile();
 
@@ -219,46 +215,33 @@ describe('CreateUserUseCase', () => {
     eventBus = module.get(EVENT_BUS);
   });
 
-  describe('execute', () => {
-    it('should create user successfully', async () => {
-      // Arrange
-      const command = new CreateUserCommand();
-      command.email = 'test@example.com';
-      command.name = 'Test User';
-
-      const expectedUser = UserEntity.create({
-        email: command.email,
-        name: command.name,
-      });
-
-      userRepository.findByEmail.mockResolvedValue(null);
-      userRepository.save.mockResolvedValue(expectedUser);
+  it('should create user successfully', async () => {
+    // Arrange
+    const command = new CreateUserCommand();
+    command.email = 'test@example.com';
+    command.name = 'Test User';
 
-      // Act
-      const result = await useCase.execute(command);
+    userRepository.findByEmail.mockResolvedValue(null);
+    userRepository.save.mockResolvedValue(UserEntity.create(command));
 
-      // Assert
-      expect(result.email).toBe(command.email);
-      expect(userRepository.save).toHaveBeenCalledWith(expect.any(UserEntity));
-      expect(eventBus.publishAll).toHaveBeenCalled();
-    });
+    // Act
+    const result = await useCase.execute(command);
 
-    it('should throw error when user already exists', async () => {
-      // Arrange
-      const command = new CreateUserCommand();
-      command.email = 'existing@example.com';
-      command.name = 'Test User';
+    // Assert
+    expect(result.email).toBe(command.email);
+    expect(userRepository.save).toHaveBeenCalledWith(expect.any(UserEntity));
+    expect(eventBus.publishAll).toHaveBeenCalled();
+  });
 
-      const existingUser = UserEntity.create({
-        email: command.email,
-        name: 'Existing User',
-      });
+  it('should throw error when user already exists', async () => {
+    // Arrange
+    const command = new CreateUserCommand();
+    command.email = 'existing@example.com';
 
-      userRepository.findByEmail.mockResolvedValue(existingUser);
+    userRepository.findByEmail.mockResolvedValue(UserEntity.create(command));
 
-      // Act & Assert
-      await expect(useCase.execute(command)).rejects.toThrow(UserAlreadyExistsException);
-    });
+    // Act & Assert
+    await expect(useCase.execute(command)).rejects.toThrow(UserAlreadyExistsException);
   });
 });
 ```
@@ -277,23 +260,20 @@ export class UserController {
 
   @Post()
   @ApiOperation({ summary: 'Create a new user' })
-  @ApiResponse({ status: 201, description: 'User created successfully', type: UserResponseDto })
+  @ApiResponse({ status: 201, type: UserResponseDto })
   @ApiResponse({ status: 400, description: 'Bad request' })
-  @ApiResponse({ status: 409, description: 'User already exists' })
-  async createUser(@Body() createUserDto: CreateUserDto): Promise<UserResponseDto> {
+  async createUser(@Body() dto: CreateUserDto): Promise<UserResponseDto> {
     const command = new CreateUserCommand();
-    Object.assign(command, createUserDto);
+    Object.assign(command, dto);
     return this.createUserUseCase.execute(command);
   }
 
   @Get(':id')
   @ApiOperation({ summary: 'Get user by ID' })
-  @ApiParam({ name: 'id', description: 'User ID' })
-  @ApiResponse({ status: 200, description: 'User found', type: UserResponseDto })
+  @ApiResponse({ status: 200, type: UserResponseDto })
   @ApiResponse({ status: 404, description: 'User not found' })
   async getUser(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
-    const query = new GetUserQuery(id);
-    return this.getUserUseCase.execute(query);
+    return this.getUserUseCase.execute(new GetUserQuery(id));
   }
 }
 ```
@@ -308,9 +288,7 @@ model User {
   name      String
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
-
-  // Relationships
-  orders Order[]
+  orders    Order[]
 
   @@map("users")
 }
@@ -320,8 +298,6 @@ model Order {
   total    Decimal     @db.Decimal(10, 2)
   status   OrderStatus
   userId   String
-  
-  // Relationships
   user     User        @relation(fields: [userId], references: [id])
   items    OrderItem[]
 
@@ -337,104 +313,60 @@ enum OrderStatus {
 }
 ```
 
-### Repository Implementation
-```typescript
-@Injectable()
-export class PrismaUserRepository implements UserRepositoryInterface {
-  constructor(private readonly prisma: PrismaService) {}
-
-  async save(user: UserEntity): Promise<UserEntity> {
-    const data = {
-      id: user.id.toString(),
-      email: user.email.toString(),
-      name: user.name.toString(),
-    };
-
-    const savedUser = await this.prisma.user.upsert({
-      where: { id: data.id },
-      update: data,
-      create: data,
-    });
-
-    return this.toDomain(savedUser);
-  }
-
-  async findById(id: UserId): Promise<UserEntity | null> {
-    const user = await this.prisma.user.findUnique({
-      where: { id: id.toString() },
-    });
-
-    return user ? this.toDomain(user) : null;
-  }
-
-  private toDomain(prismaUser: User): UserEntity {
-    return UserEntity.reconstitute({
-      id: UserId.create(prismaUser.id),
-      email: EmailValueObject.create(prismaUser.email),
-      name: NameValueObject.create(prismaUser.name),
-      createdAt: prismaUser.createdAt,
-    });
-  }
-}
-```
+### Prisma Best Practices
+- Use enums for fixed value sets
+- Always add indexes on foreign keys
+- Use `@@map` for table naming (plural snake_case)
+- Include `createdAt` and `updatedAt` timestamps
+- Use `cuid()` for primary keys
+- No raw SQL queries - use Prisma Client only
 
 ## Security Standards
 
 ### Authentication & Authorization
-- JWT tokens with proper expiration
-- Role-based access control (RBAC)
-- Input validation on all endpoints
-- Rate limiting for public endpoints
-- HTTPS only in production
+- **JWT Tokens**: Proper expiration and refresh token handling
+- **RBAC**: Role-based access control with Guards
+- **Validation**: Input validation on all endpoints (class-validator)
+- **Rate Limiting**: Throttle public endpoints to prevent abuse
+- **Environment**: HTTPS only in production, secrets in env variables
 
 ### Data Protection
-- Encrypt sensitive data at rest
-- Use environment variables for secrets
-- Implement audit logging
-- Regular security updates
-- OWASP compliance
+- Encrypt sensitive data at rest and in transit
+- Never commit secrets to repository
+- Implement audit logging for critical operations
+- OWASP Top 10 compliance
+- Regular dependency security audits
 
 ## Performance Standards
 
 ### Database Optimization
-- Proper indexing strategies
-- Connection pooling
-- Query optimization
-- Pagination for large datasets
-- Database monitoring
+- Proper indexing on frequently queried fields
+- Connection pooling via Prisma
+- Pagination for large datasets (cursor-based preferred)
+- Avoid N+1 queries with Prisma `include`
+- Query monitoring and slow query logging
 
 ### Caching Strategy
-- Redis for session data
-- Application-level caching
-- HTTP caching headers
-- CDN for static assets
-- Cache invalidation patterns
+- **Redis**: Session data, rate limiting, and frequently accessed data
+- **Application Cache**: In-memory caching for configuration
+- **TTL Strategy**: Appropriate time-to-live for different data types
+- **Invalidation**: Event-driven cache invalidation
 
-## MonoRepo Organization
+## Error Handling
 
-### Shared Libraries Structure
-```
-libs/
-├── common/
-│   ├── decorators/
-│   ├── filters/
-│   ├── guards/
-│   ├── interceptors/
-│   ├── pipes/
-│   └── utils/
-├── domain-core/
-│   ├── base/
-│   ├── interfaces/
-│   └── exceptions/
-└── database/
-    ├── base-repository.ts
-    ├── transaction.decorator.ts
-    └── prisma.service.ts
-```
+### Exception Hierarchy
+- Domain exceptions for business rule violations
+- Application exceptions for use case errors
+- Infrastructure exceptions for external service failures
+- HTTP exception filters for API responses
 
-### Service Independence
-- Each microservice has its own database
-- Shared code through libraries only
-- Independent deployment pipelines
-- Service-to-service communication via events
-- No direct database access between services
+### Error Response Format
+```typescript
+{
+  "statusCode": 400,
+  "message": "User with email already exists",
+  "error": "UserAlreadyExistsException",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "path": "/api/users"
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.22",
+  "version": "2.1.23",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {