Architecture

The golden slice: adding a module

One complete path from table creation to go-live, which is also what the skeleton generator does for you.

The golden slice is the smallest complete path for one new module: table, entity, query, endpoint, permission, menu, test — none missing.

Seven steps

Create the table with Liquibase (db/changelog) and write accurate column comments.
Run the generator to produce DO / Mapper / XML / Repository.
For dynamic queries, write QueryXxxDTO and annotate each field with @QueryField.
Simple CRUD goes Controller to AppService to Repository to Convert.
Logic involving flows, rules or multiple aggregates goes into domain/handler/<module>/XxxHandler; AppService only calls it.
Implement ErrorCode for any new error code and complete the i18n text in all three languages.
Run ./gradlew build once.

./gradlew generateModule -Pname=demo

Output	Notes
Directory skeleton	generated to the layering rules, no manual package creation
Migration script	a new changeset with a non-conflicting number
Test skeleton	generated code ships with tests; the build must pass first try
Registrations	module, permission codes and menus are registered automatically

The build passes on the first run (including architecture guards and contract consistency).
Permission codes are registered and no literal permission code appears in code.
Menus are registered and the front end does not hardcode routes.
Column comments on the new table are complete and the soft-delete column is NOT NULL DEFAULT 0.

Tip: these four are not advice. They are what the skeleton generator and the build guarantee together.

Last updated 2026-10-09Edit this page →