context-scaffold

name	context-scaffold
description	Scaffold new modules, commands, queries, events, or viewstore entities within an existing cpp-context-* service. Use when adding new capabilities to a context service.

Context Service Scaffold

Generates boilerplate for new CQRS components within an existing cpp-context-* repository — commands, queries, domain events, viewstore entities, and Liquibase migrations.

When to Use

• User asks to "add a new command", "create a query", "add a domain event"
• User wants to add a new aggregate or entity to the domain
• User needs a new viewstore table with Liquibase migration
• User wants to add event subscription from another context

Component Templates

New Command

When the user wants to add a new command:

1. Command API ({name}-command/{name}-command-api/)

   • RAML definition under src/raml/
   • JSON schema under src/raml/json/schema/
   • Follow existing naming: {context}.command.{verb}-{noun}.json

2. Command Handler ({name}-command/{name}-command-handler/)

   • Handler class implementing the command processing
   • Follow pattern: {Verb}{Noun}CommandHandler.java
   • Must validate invariants via the aggregate
   • Must produce domain events on success

Example command schema naming:

hearing.command.schedule-hearing.json
hearing.command.update-hearing-details.json
hearing.command.cancel-hearing.json

New Query

When the user wants to add a new query:

1. Query API ({name}-query/{name}-query-api/)

   • RAML definition
   • Response JSON schema

2. Query Handler ({name}-query/{name}-query-handler/)

   • Handler class that reads from the viewstore
   • Must use readOnly=true transactions
   • Never modify state

New Domain Event

1. Event Schema ({name}-domain/{name}-domain-event/src/main/resources/json/schema/)

   • JSON schema file: {context}.events.{noun}-{past-tense-verb}.json
   • Example: hearing.events.hearing-scheduled.json, hearing.events.hearing-cancelled.json

2. Event naming convention: Events are past-tense facts — something that happened.

   • material-added (not add-material)
   • hearing-scheduled (not schedule-hearing)
   • defendant-validation-passed (not validate-defendant)

New Viewstore Entity

1. JPA Entity ({name}-viewstore/)

   • Entity class with @Entity, @Table annotations
   • Repository interface extending JpaRepository

2. Liquibase Migration ({name}-viewstore-liquibase/)

   • New changeset in db/changelog/
   • Follow sequential numbering from existing changesets
   • Include rollback section

Example Liquibase changeset:

<changeSet id="YYYYMMDD-01" author="developer-name">
    <createTable tableName="new_entity">
        <column name="id" type="uuid">
            <constraints primaryKey="true" nullable="false"/>
        </column>
        <column name="created_at" type="timestamp with time zone">
            <constraints nullable="false"/>
        </column>
    </createTable>
    <rollback>
        <dropTable tableName="new_entity"/>
    </rollback>
</changeSet>

New Event Subscription (from another context)

When this service needs to react to events from another bounded context:

1. Add dependency in root pom.xml:

   <dependency>
       <groupId>uk.gov.moj.cpp.{other-context}</groupId>
       <artifactId>{other-context}-event</artifactId>
       <version>${other-context.version}</version>
   </dependency>
   

2. Event source handler in {name}-event-sources/:

   • Handler method annotated to process the external event
   • Must be idempotent — check if event already processed
   • Transform external event data into local viewstore updates

Process

1. Ask the user what component they want to add
2. Read the existing repo structure to understand naming patterns and conventions
3. Read at least one existing example of the same component type in the repo
4. Generate the new component following the exact same patterns
5. If adding a viewstore entity, also generate the Liquibase migration
6. If adding a command, also create the corresponding domain event(s)
7. Remind the user to run mvn clean install to verify the build

Validation

After scaffolding, verify:

• mvn clean compile — all modules compile
• mvn test -pl {affected-module} — existing tests still pass
• JSON schemas validate against the framework's meta-schema
• RAML files reference the correct schemas
• Liquibase changesets have unique IDs and include rollback