brownfield-workflow

Brownfield Development Workflow

Guide for safely modifying, extending, or refactoring existing features in the NestJS Clean Architecture project.

For before/after code examples of every change type, read references/change-patterns.md.

---

Step 1: Impact Analysis

Before touching any code, answer these questions:

1. Which layers are affected? Trace the change from domain → use cases → adapters → infrastructure. A field addition touches all layers; a business logic tweak may only touch use cases.
2. Which files need modification? List every file. Use find_symbol or grep to locate all references to the entity, interface, or method being changed.
3. Are there existing tests that need updating? Search test/ for imports of the affected entity, stub, or use case. Check test/stubs/ first — stub changes propagate everywhere.
4. Does this require a database migration? Any schema change (column add/remove/rename, relation, default change) requires a migration. Pure logic changes do not.
5. Could this break existing API consumers? Adding optional fields is safe. Removing fields, renaming fields, or changing response shapes is breaking.

Record the answers before proceeding. This prevents half-finished changes across layers.

---

Step 2: Classify the Change

Identify which type matches the requested change and follow its file modification order.

Type A — Add a Field to an Existing Entity

Modify files in this exact order:

1. Domain entity (src/domain/entities/<entity>.entity.ts) — Add the field to the constructor. Use public for simple fields, private _field + getter if there is a business rule. Optional fields use ? suffix.
2. Repository interface (src/domain/repositories/<entity>.repository.interface.ts) — Update param interfaces (ISearch*Params, ICount*Params) if the field is filterable or sortable.
3. TypeORM entity (src/infrastructure/databases/postgresql/entities/<entity>.entity.ts) — Add @Column() with appropriate options ({ nullable: true } for optional, { default: value } for defaults). Import enums from domain entity.
4. Repository implementation (src/infrastructure/databases/postgresql/repositories/<entity>.repository.ts) — Update toEntity() to pass the new field. Update buildWhereCondition() if the field is filterable. Update query select or find options if needed.
5. DTOs (src/adapters/controllers/<feature>/dto/) — Add the field with class-validator decorators and @ApiProperty. Add to create DTO if settable on creation, update DTO if editable.
6. Presenters (src/adapters/controllers/<feature>/presenters/) — Add the field mapping in the constructor. Add @ApiProperty for Swagger documentation.
7. Migration — Generate: docker exec -it app-api npm run migration:generate --name=add-<field>-to-<table>
8. Test stubs (test/stubs/<entity>.stub.ts) — Add the new field to the stub factory. This is critical — stubs propagate to all tests.
9. Tests — Update use case tests, controller tests, and any infrastructure tests that assert on the entity shape.

Type B — Add a New Endpoint to an Existing Controller

Create/modify files in this order:

1. Use case (src/use-cases/<feature>/) — Create a new file: <action>-<entity>.use-case.ts. One class, one execute() method. Inject repository via @Inject(IEntityRepository).
2. Repository interface — Add new method to the interface if the use case needs a query that does not exist yet (e.g., deleteTask).
3. Repository implementation — Implement the new method. Always return/accept domain entities.
4. DTO (src/adapters/controllers/<feature>/dto/) — Create a new DTO if the endpoint accepts a request body or query params.
5. Presenter (src/adapters/controllers/<feature>/presenters/) — Create a new presenter if the endpoint returns data in a new shape.
6. Controller (src/adapters/controllers/<feature>/<feature>.controller.ts) — Add the new method. Inject the new use case in the constructor. Apply @CheckPolicies, @ApiBearerAuth. Follow the thin controller pattern: receive → delegate → present.
7. Module (src/modules/<feature>.module.ts) — Register the new use case in providers.
8. CASL — If the action is new (e.g., delete), update casl-ability.factory.ts to grant the permission and add 'delete' action handling for the subject.
9. Tests — Create test/use-cases/<feature>/<action>-<entity>.use-case.spec.ts. Update test/adapters/controllers/<feature>/<feature>.controller.spec.ts to cover the new method.

Type C — Add a Relation Between Entities

Modify files in this order:

1. Domain entity — Add the related entity reference as an optional field (e.g., public comments?: CommentEntity[]). Do NOT import TypeORM here.
2. Repository interface — Update query param interfaces if the relation affects filtering. Add methods for fetching with relations if needed.
3. TypeORM entity — Add @ManyToOne, @OneToMany, or @ManyToMany decorator with @JoinColumn. Use { nullable: true } for optional relations. Always specify the inverse side.
4. Repository implementation — Update queries to include relations: ['relatedEntity'] where needed. Update toEntity() to map nested entities.
5. Migration — Generate: docker exec -it app-api npm run migration:generate --name=add-<entity>-<related>-relation
6. Presenters — Decide whether to include related data in existing presenters or create a dedicated nested presenter.
7. Tests — Update stubs to include the relation field. Update all affected tests.

Type D — Add or Change Enum Values

Modify files in this order:

1. Domain entity (src/domain/entities/<entity>.entity.ts) — Add or modify enum values. Never remove values that exist in the database.
2. TypeORM entity — Verify @Column({ default: ... }) still references a valid value. Update if the default changes.
3. Migration — Only needed if the column default or a database constraint changes. If the enum is stored as an integer, no migration is needed for adding values.
4. DTOs — Update @IsEnum() validators. If the new value should be accepted in create/update, verify the DTO allows it.
5. CASL ability factory — Check if authorization rules depend on the enum (e.g., status-based access). Update rules if needed.
6. Tests — Update all stubs and test expectations that reference the enum. Search for the enum name across test/.

Type E — Modify Business Logic in a Use Case

Modify files in this order:

1. Use case (src/use-cases/<feature>/) — Modify the execute() method. If new data is needed, inject additional repositories or services.
2. Repository interface — Add or update methods if the use case needs new queries. Keep method signatures accepting/returning domain entities only.
3. Repository implementation — Implement any new interface methods.
4. Tests — This is the most critical step. Update test/use-cases/<feature>/ to cover the new logic paths. Add test cases for edge cases and error conditions.

Type F — Refactor or Move Code Between Layers

Follow this safety procedure:

1. Identify current location and target location. Verify the move does not violate the dependency rule (dependencies point inward: infrastructure → domain ← use-cases).
2. Find all references — Use find_referencing_symbols or grep across the entire src/ and test/ trees. List every file that imports the symbol being moved.
3. Move the code — Copy to the new location, update the class/file name if conventions differ.
4. Update all imports — Change every import statement found in step 2. Use path aliases (@domain/*, @use-cases/*, @adapters/*, @infrastructure/*).
5. Delete the old file — Only after all imports are updated.
6. Check for circular dependencies — Run docker exec -it app-api npm run build and look for circular dependency warnings.
7. Run full test suite — docker exec -it app-api npm run test to verify nothing broke.

---

Step 3: Migration Strategy

When to generate a migration (schema change)

• Adding, removing, or renaming a column
• Adding a relation (foreign key)
• Changing a column default, type, or constraint

Command: docker exec -it app-api npm run migration:generate --name=<kebab-case-description>

When to create an empty migration (data-only)

• Populating a new column with computed values
• Backfilling data from another table

Command: docker exec -it app-api npm run migration:create --name=<kebab-case-description>

Naming convention

Use kebab-case, be descriptive: add-due-date-to-tasks, add-task-comment-relation, backfill-task-priorities.

Rules

• Always run migrations inside Docker: docker exec -it app-api npm run migration:run
• Never edit committed migration files — always create a new migration.
• Test rollback: docker exec -it app-api npm run migration:revert

---

Step 4: Backward Compatibility Checklist

Before finalizing any change, verify:

• New fields are optional (nullable: true) or have sensible defaults — never add a required column without a default to a table with existing data.
• No fields were removed from presenters — removing a field from the API response is a breaking change. Deprecate first if needed.
• No database columns were renamed — add a new column, migrate data, then deprecate the old one in a separate release.
• No enum values that are stored in the database were removed or renumbered — existing rows would become invalid.
• No existing endpoint signatures changed — adding optional parameters is safe; removing or renaming parameters is breaking.

---

Step 5: Testing Update Strategy

Follow this order to minimize cascading test failures:

1. Update stubs first (test/stubs/<entity>.stub.ts) — Stubs are imported by many tests. Updating them first ensures consistency across the test suite.
2. Update unit tests — Fix or add tests in test/use-cases/, test/adapters/controllers/, and test/infrastructure/ as needed.
3. Run the full test suite: docker exec -it app-api npm run test
4. Check coverage: docker exec -it app-api npm run test:cov — Verify coverage did not drop.

Test naming convention

• Variable naming: inputX, mockX, actualX, expectedX
• Pattern: Arrange → Act → Assert
• One describe block per method, one it block per behavior

---

Quick Reference: Change Type → Files Affected

Change Type	Domain	Repo Interface	Use Case	TypeORM Entity	Repo Impl	DTO	Presenter	Controller	Module	Migration	Tests
A: Add field	✅	Maybe	—	✅	✅	✅	✅	—	—	✅	✅
B: Add endpoint	—	Maybe	✅ New	—	Maybe	✅	✅	✅	✅	—	✅
C: Add relation	✅	Maybe	Maybe	✅	✅	—	Maybe	—	—	✅	✅
D: Change enum	✅	—	—	Maybe	—	✅	Maybe	—	—	Maybe	✅
E: Modify business logic	—	Maybe	✅	—	Maybe	—	—	—	—	—	✅
F: Refactor/move code	Maybe	Maybe	Maybe	Maybe	Maybe	—	—	Maybe	Maybe	—	✅

Related Skills

• testing-patterns — exact patterns for writing/updating tests after brownfield changes
• exception-handling — adding error handling when extending use cases
• swagger-api-docs — updating Swagger decorators when adding/modifying endpoints
• casl-authorization — updating CASL rules when adding new subjects or actions