greenfield-workflow

Greenfield Feature Workflow

A step-by-step workflow for implementing entirely new features from scratch in this NestJS Clean Architecture project. Follow the 12 steps in order — each step builds on the previous one.

For a complete worked example (Comment entity through all 12 steps), read references/complete-greenfield-example.md.

When to Use This Skill

• Creating an entirely new resource/entity (e.g., Comment, Tag, Category)
• Building a feature that spans all layers from domain to controller
• User says "add", "create", "implement", "new entity", or "greenfield"

Pre-Flight Checklist

Before writing any code, confirm these with the user or infer from context:

1. Entity name — singular, PascalCase (e.g., Comment, Tag)
2. Fields and types — list every field, its TypeScript type, and whether it's optional
3. Relations — does it belong to a user? Does it reference another entity (e.g., Task)?
4. Use cases needed — CRUD operations? Custom operations (e.g., publish, archive)?
5. Authorization — does it need CASL subject registration? What can each role do?
6. Migration — does it need a new database table?

If any of these are unclear, ask the user before proceeding.

The 12-Step Implementation Flow

Execute these steps IN ORDER. Each step produces one or more files.

---

Step 1: Domain Entity

File: src/domain/entities/{entity}.entity.ts

Create the domain entity as a pure TypeScript class with zero framework imports.

• Define enums (if any) and export them from the same file
• Use readonly for id, createdAt, updatedAt — these are immutable
• Use private _field + public getter for fields with business rules (e.g., status transitions)
• Use plain public for freely mutable fields (e.g., title, description)
• Add state transition methods that enforce business rules (e.g., complete(), publish())
• Constructor receives all fields as parameters

Follow the pattern in the existing TaskEntity:

constructor(
  public readonly id: number,
  public userId: number,
  public content: string,
  private _status: StatusEnum,
  public readonly createdAt: Date,
  public readonly updatedAt: Date,
)

---

Step 2: Repository Interface

File: src/domain/repositories/{entity}.repository.interface.ts

Define the contract for data access. This file exports both a Symbol and an interface with the same name.

• Export the Symbol constant: export const I{Entity}Repository = Symbol('I{Entity}Repository')
• Export the interface with the same name
• Define search/filter param interfaces (e.g., ISearch{Entities}Params)
• Only accept and return domain entities — never TypeORM entities
• Include methods for each data operation: find{Entities}, create{Entity}, findOne{Entity}, update{Entity}, delete{Entity}

---

Step 3: Use Cases

Directory: src/use-cases/{entities}/ (plural, kebab-case)

Create one file per operation. Each file contains exactly one class with one execute() method.

• File naming: create-{entity}.use-case.ts, get-list-{entities}.use-case.ts, get-detail-{entity}.use-case.ts, update-{entity}.use-case.ts, delete-{entity}.use-case.ts
• Mark with @Injectable()
• Inject repository via @Inject(I{Entity}Repository) private readonly {entity}Repository: I{Entity}Repository
• Single execute() method that takes typed input and returns a Promise
• Apply business rules here (not in controller, not in repository)
• Throw domain exceptions for business rule violations

---

Step 4: TypeORM Entity

File: src/infrastructure/databases/postgresql/entities/{entity}.entity.ts

Create the database mapping for the domain entity.

• @Entity('{entities}') — table name is plural, lowercase
• Import enums from the domain entity file — do not redefine them
• Use @PrimaryGeneratedColumn({ type: 'bigint', primaryKeyConstraintName: 'PK_{entities}_id' })
• Use @Column() with explicit types: 'bigint', 'varchar', 'text', 'smallint', 'timestamp'
• Use @CreateDateColumn({ name: 'created_at' }) and @UpdateDateColumn({ name: 'updated_at' })
• Use snake_case for column names: @Column('bigint', { name: 'user_id' })
• Add @Index() decorators for foreign key columns
• Add @ManyToOne / @OneToMany relations if the entity references other entities
• Class name is the entity name without "Entity" suffix (e.g., Comment, not CommentEntity)

---

Step 5: Repository Implementation

File: src/infrastructure/databases/postgresql/repositories/{entity}.repository.ts

Implement the repository interface from Step 2.

• implements I{Entity}Repository
• Inject TypeORM repository: @InjectRepository({TypeORMEntity}) private readonly {entity}Repository: Repository<{TypeORMEntity}>
• Mark with @Injectable()
• MUST have a private toEntity() method that converts TypeORM entity → domain entity
• Every method that returns data must call toEntity() before returning
• Never expose TypeORM entities outside this class
• Use this.{entity}Repository.find(), .findOne(), .save(), .update(), .delete()

---

Step 6: DTOs

Directory: src/adapters/controllers/{entities}/dto/

Create one DTO per operation that accepts client input.

• create-{entity}.dto.ts — fields the client sends to create
• get-list-{entities}.dto.ts — query/filter parameters
• update-{entity}.dto.ts — fields the client can update (usually all optional)
• Use class-validator decorators: @IsNotEmpty(), @IsString(), @IsOptional(), @MaxLength(), @IsEnum(), etc.
• Use @ApiProperty() from @nestjs/swagger for every field (Swagger docs)
• No business logic — DTOs are pure data shapes

---

Step 7: Presenters

Directory: src/adapters/controllers/{entities}/presenters/

Create one presenter per operation that returns data to the client.

• create-{entity}.presenter.ts, get-list-{entities}.presenter.ts, get-detail-{entity}.presenter.ts
• Constructor receives a domain entity and maps fields to response shape
• Add @ApiProperty() for every exposed field
• Add a static fromList(entities: {Entity}Entity[]): {Presenter}[] method for list endpoints
• Never expose internal fields (e.g., _status) — use the getter value

---

Step 8: Controller

File: src/adapters/controllers/{entities}/{entities}.controller.ts

Create the HTTP controller. Keep it thin — no business logic.

• @Controller('{entities}') + @ApiTags('{Entities}')
• @UseGuards(JwtAuthGuard, PoliciesGuard) at class level
• Add common @ApiResponse decorators for 401, 403, 500
• Each endpoint follows this pattern: receive request → call use case → wrap in presenter → return
• Use @User('id') to get the authenticated user's ID from the JWT
• Use @CheckPolicies({ action, subject }) for CASL authorization on each endpoint
• Use @ApiExtraModels(), @ApiOperation(), @ApiResponseType() / @ApiCreatedResponseType() for Swagger
• Import use cases, DTOs, and presenters using path aliases

---

Step 9: Module

File: src/modules/{entity}.module.ts

Wire everything together with NestJS dependency injection.

• Import TypeOrmModule.forFeature([{TypeORMEntity}]) for the database entity
• Import CaslModule and ExceptionsModule
• Bind the repository interface Symbol to the concrete implementation:

  { provide: I{Entity}Repository, useClass: {Entity}Repository }
  

• Register all use cases as providers
• Register the controller(s) in controllers
• Then import this module in src/app.module.ts — add it to the imports array

---

Step 10: CASL Authorization (if needed)

Update CASL if the new entity needs authorization rules.

1. Add subject to TSubject in src/domain/services/ability.interface.ts:

   export type TSubject = 'all' | 'Task' | '{Entity}'
   

2. Add rules in src/infrastructure/services/casl/casl-ability.factory.ts:

   • Admin: already has can('manage', 'all') — no change needed
   • Regular user: add specific permissions:

     can('read', '{Entity}')
     can(['create', 'update', 'delete'], '{Entity}')
     

---

Step 11: Database Migration

Generate and run the migration inside the Docker container.

docker exec -it app-api npm run migration:generate --name=create-{entities}-table
docker exec -it app-api npm run migration:run

Review the generated migration file in database/migrations/ before running. Verify:

• Table name matches @Entity() decorator
• Column types match @Column() decorators
• Indexes are created for foreign keys
• Constraints are named correctly

---

Step 12: Tests

Create tests following the project's Arrange → Act → Assert pattern.

a) Stub File

File: test/stubs/{entity}.stub.ts

Create a factory function with an overrides parameter:

export const create{Entity}Stub = (overrides: Partial<{...}> = {}): {Entity}Entity => {
  return new {Entity}Entity(
    overrides.id ?? 1,
    overrides.userId ?? 1,
    // ... defaults for all fields
  )
}

b) Use Case Tests

Directory: test/use-cases/{entities}/

One spec file per use case. Each test:

• Creates a TestingModule with the use case and a mocked repository
• Uses jest.fn() for repository methods
• Uses jest.spyOn().mockResolvedValue() for specific test cases
• Asserts the repository was called with correct arguments
• Asserts the return value matches expectations
• Variable naming: inputX, mockX, actualX, expectedX

c) Controller Tests

Directory: test/adapters/controllers/{entities}/

• Mock all use cases with { execute: jest.fn() }
• Override PoliciesGuard with { canActivate: () => true }
• Provide 'ABILITY_FACTORY_INTERFACE' as empty object
• Test each endpoint: verify use case called correctly, verify presenter wrapping

---

Decision Trees

Use these to handle common variations:

Question	If Yes	If No
Does this entity belong to a user?	Add userId: number field, filter by userId in repository queries, use @User('id') in controller	Skip userId, queries don't filter by user
Does it need authorization?	Add to TSubject, update casl-ability.factory.ts, use @CheckPolicies	Skip CASL steps, may not need PoliciesGuard
Does it have state transitions?	Use private _status + getter + transition methods in domain entity	Use plain public field
Does it relate to existing entities?	Add @ManyToOne/@OneToMany in TypeORM entity, add foreign key column	No relation decorators needed
Does it need list filtering?	Create search params interface in repository, add GetList{Entities}Dto with filter fields	Simple findAll without params

---

Post-Implementation Checklist

Run these commands inside the Docker container to verify everything works:

# All tests pass
docker exec -it app-api npm run test

# Build succeeds (TypeScript compilation)
docker exec -it app-api npm run build

# Lint clean
docker exec -it app-api npm run lint

# Migration generated and applied
docker exec -it app-api npm run migration:run

Also verify manually:

• Module is imported in app.module.ts
• CASL subject is registered (if needed)
• All use cases are registered as providers in the module
• Repository Symbol is bound to implementation in module providers
• TypeORM entity is in forFeature([]) array
• All imports use path aliases (@domain/*, @use-cases/*, @adapters/*, @infrastructure/*)

---

Reference

For a complete worked example implementing a Comment entity through all 12 steps with full TypeScript code, see: references/complete-greenfield-example.md

For layer-by-layer architecture details, see the nestjs-clean-architecture skill.

Related Skills

Use these specialized skills for deeper guidance on specific steps:

• testing-patterns — Step 12 (Tests): exact TestingModule setup, Symbol token mocking, stub factory patterns, AAA naming
• casl-authorization — Step 10 (CASL): adding TSubject, ability factory rules, @CheckPolicies, CASL vs ownership
• exception-handling — Step 3 (Use Cases): IException injection, error codes, when to use each exception type
• swagger-api-docs — Steps 6-8 (DTOs/Presenters/Controller): custom ApiResponseType decorators, @ApiExtraModels, @ApiProperty