aurora-development

When to Use

This is the PRIMARY skill for IMPLEMENTING code in Aurora/NestJS projects.

Use this skill when:

• Writing business logic in command/query handlers (validations, rules, checks)
• Implementing any custom code in Aurora-generated handlers
• Creating guards, interceptors, pipes, or custom decorators
• Implementing NestJS-specific features (middleware, exception filters)
• Working with dependency injection (DI) and inversion of control (IoC)
• Integrating with Sequelize ORM
• Testing with Jest (unit and e2e)

Note: For understanding CQRS architecture (what are Commands, Handlers, etc.), see aurora-cqrs skill.

Always combine with:

• prettier skill for code formatting (MANDATORY after every edit)
• typescript skill for strict type patterns
• aurora-cqrs skill for CQRS architecture reference (structure, editable zones)
• aurora-project-structure skill for file locations
• aurora-criteria skill for QueryStatement filters

Critical Patterns

⚠️ FIRST DECISION: Where Does the Logic Go? (MANDATORY GATE)

Before writing ANY code, classify the operation:

Is it a DOMAIN OPERATION? (provision, cancel, approve, reject, activate, close, etc.)
│
├─ YES → Create Command + Handler + Service in @app/application/<operation>/
│        The @api handler ONLY does: commandBus.dispatch(new CustomCommand(...))
│        Business validations go in the @app CommandHandler.execute()
│        Persistence + events go in the @app Service.main()
│        SEE: patterns.md → Pattern 4 for full example
│
└─ NO → It's standard CRUD or simple orchestration
         Use existing generated commands/queries

⚠️ NEVER put business logic (validations, status checks, repository queries, if/throw) in @api handlers. Even if you see existing @api handlers in the codebase that do this (e.g., IAM account handlers), those are LEGACY EXCEPTIONS for cross-module orchestration, NOT a pattern to follow for domain operations.

⚠️ Domain operations with additionalApis ALWAYS need their own @app layer (Command + Handler + Service). The @api handler is ONLY a thin dispatcher.

⚠️ Code Formatting (CRITICAL!)

MANDATORY: Use prettier skill after EVERY file modification

# Quick reference (see prettier skill for full details)
npm run format -- <file-path>

❌ NEVER skip formatting or leave unformatted code

⚠️ Business Logic Placement (CRITICAL!)

✅ Command Handler (execute() method)

PUT HERE: Business validations, complex rules, pre-validation queries, duplicate checks, external service calls, transformations before persisting.

❌ Service (main() method)

DO NOT PUT HERE: Business validations, business rules, pre-validation queries.

Services are ONLY for: Creating aggregate with factory pattern, persisting via repository, publishing domain events.

🔑 Decision Tree

What am I implementing?
│
├─ Validation, business rule, pre-check query
│  └─ ✅ Command Handler (execute method)
│      - Inject repository if you need queries
│      - Add logic BEFORE calling service
│
└─ Persistence, aggregate creation, events
   └─ ✅ Service (main method)
       - NO validations here
       - Only create, persist, publish events

For detailed handler and service examples, see Handler Examples.

⚠️ @api Handlers Rule (CRITICAL!)

@api handlers MUST ONLY dispatch commands/queries. No business logic, no repository queries, no if/throw logic. See aurora-cqrs skill for full details.

⚠️ Querying with Relations (CRITICAL!)

BEFORE writing queries that need related data:

1. ✅ Read .aurora.yaml schema using aurora-schema skill
2. ✅ Identify relationships in aggregateProperties
3. ✅ Use include in QueryStatement (see aurora-criteria skill)

/* #region AI-generated code */
const queryStatement: QueryStatement = {
  where: { id: unitId },
  include: [{ association: 'model' }], // Field name from YAML relationship
};
/* #endregion AI-generated code */

Benefits: Single query (avoid N+1 problem), better performance.

Marking Custom Code

Always mark custom code with AI-generated comments:

/* #region AI-generated code */
// Custom logic here
/* #endregion AI-generated code */

Detailed References

For detailed code examples, see:

• Handler Examples — Command/Query handler examples with business logic
• NestJS Components — Guards, Interceptors, Pipes, Decorators, Exception Filters
• Common Patterns — Validation, caching, exception filters, custom domain operations
• Value Objects — Value Object construction rules for partial updates (provision, status changes)
• Testing Patterns — Unit test examples

Code Style & Conventions

Import Order

// 1. Node.js
import { readFile } from 'fs/promises';

// 2. NestJS
import { Injectable, Controller } from '@nestjs/common';
import { CommandHandler } from '@nestjs/cqrs';

// 3. External libraries
import { v4 as uuid } from 'uuid';

// 4. Internal (@app, @domain, @infrastructure)
import { UserRepository } from '@infrastructure/iam/user/repositories/user.repository';

// 5. Relative
import { CreateUserCommand } from './create-user.command';

Naming Conventions

Formatting

• Indentation: 4 spaces
• Braces: New line for classes/methods
• Semicolons: Required
• Quotes: Single quotes

Dependency Injection

Constructor Injection (Preferred)

@Injectable()
export class UserService {
  constructor(
    private readonly repository: UserRepository,
    private readonly logger: Logger,
    private readonly eventBus: EventBus,
  ) {}
}

Module Registration

@Module({
  imports: [CqrsModule],
  controllers: [UserController],
  providers: [UserService, CreateUserHandler, GetUsersHandler, UserRepository],
  exports: [UserService],
})
export class UserModule {}

Decision Trees

When to use Guard vs Interceptor vs Pipe?

Need authentication/authorization?
└─ Use Guard (before route handler)

Need to transform input data?
└─ Use Pipe (before route handler, per parameter)

Need to transform response or add cross-cutting logic?
└─ Use Interceptor (before and after route handler)

Need request/response logging?
└─ Use Middleware or Interceptor

Need to catch and format exceptions?
└─ Use Exception Filter

Where to add custom logic?

Need validation before save?
└─ Add in CommandHandler.execute() before service call

Need to react to events?
└─ Create EventHandler

Need to coordinate multiple operations?
└─ Create Saga

Need to transform data?
└─ Use Mapper

Need custom query logic?
└─ Add in QueryHandler.execute() before/after service call

Need reusable business logic?
└─ Create custom Service and inject in Handler

Best Practices

✅ DO

• Always mark custom code with /* #region AI-generated code */
• Put business logic in handlers, not services
• Inject repository in handlers if you need pre-validation queries
• Use dependency injection for all dependencies
• Create custom services for reusable logic
• Use guards for authentication/authorization
• Use interceptors for logging/caching
• Use pipes for validation
• Write unit tests for handlers
• Follow NestJS naming conventions
• Use TypeScript strict mode (see typescript skill)
• Use enum types from domain/types/ instead of hardcoded strings for enum fields

❌ DON'T

• Don't put business logic in services (put in handlers)
• Don't modify generated files (marked with @aurora-generated)
• Don't bypass repository (always use repository interface)
• Don't use any type (use unknown or generics, see typescript skill)
• Don't forget to commit events (call aggregate.commit())
• Don't create commands/queries manually (use Aurora CLI)
• Don't mix concerns (keep separation of concerns)

Resources

• NestJS Docs: https://docs.nestjs.com
• CQRS Module: https://docs.nestjs.com/recipes/cqrs
• Testing: https://docs.nestjs.com/fundamentals/testing
• Aurora CQRS: .claude/skills/aurora-cqrs/SKILL.md
• TypeScript: .claude/skills/typescript/SKILL.md
• Aurora CLI: .claude/skills/aurora-cli/SKILL.md
• Project Structure: .claude/skills/aurora-project-structure/SKILL.md

Related Skills

• aurora-cqrs - CQRS architecture reference (structure, editable zones, data flow)
• typescript - Strict type patterns
• aurora-project-structure - File locations
• aurora-criteria - QueryStatement for filters
• jest-nestjs - Testing patterns
• supertest-nestjs - E2E API testing