Scaffold Clean Architecture

Guide for scaffolding and managing Java Spring Boot projects with the Bancolombia Clean Architecture Gradle plugin.

Plugin Setup

Requires Java 17+ and Gradle 9.2.1+. Add to build.gradle:

plugins {
    id 'co.com.bancolombia.cleanArchitecture' version '4.2.0'
}

Quick Start

mkdir my-project && cd my-project
echo "plugins { id 'co.com.bancolombia.cleanArchitecture' version '4.2.0' }" > build.gradle
gradle wrapper
./gradlew ca --name=MyProject
./gradlew gep --type webflux
./gradlew bootRun

Core Tasks

All tasks are Gradle tasks. Short aliases are available for each.

Generate Project (ca)

Creates the full clean architecture structure.

./gradlew ca --name=MyProject --package=co.com.bancolombia --type=reactive --lombok=true

Parameter	Values	Default
--name	String	cleanArchitecture
--package	String	co.com.bancolombia
--type	reactive, imperative	reactive
--lombok	true, false	true
--metrics	true, false	true
--mutation	true, false	true
--java-version	17, 21, 25	25

Generated structure:

📦Project
┣ 📂applications/app-service/   (MainApplication, configs, resources)
┣ 📂domain/model/               (domain models)
┣ 📂domain/usecase/             (business logic)
┣ 📂infrastructure/driven-adapters/
┣ 📂infrastructure/entry-points/
┣ 📂infrastructure/helpers/
┗ 📂deployment/

Generate Model (gm)

Creates a domain model class + gateway interface.

./gradlew gm --name=Product

Generates: domain/model/.../model/Product.java + domain/model/.../model/gateways/ProductRepository.java

Generate Use Case (guc)

Creates a use case class in the domain layer.

./gradlew guc --name=CreateOrder

Generates: domain/usecase/.../usecase/createorder/CreateOrderUseCase.java

Generate Driven Adapter (gda)

Creates infrastructure adapters. Read references/driven-adapters.md for the full catalog of types and parameters.

./gradlew gda --type=jpa
./gradlew gda --type=mongodb
./gradlew gda --type=r2dbc
./gradlew gda --type=restconsumer --url=https://api.example.com
./gradlew gda --type=redis --mode=template
./gradlew gda --type=s3
./gradlew gda --type=dynamodb
./gradlew gda --type=sqs
./gradlew gda --type=secrets --secrets-backend=aws_secrets_manager
./gradlew gda --type=asynceventbus --tech=kafka
./gradlew gda --type=generic --name=MyAdapter

Generate Entry Point (gep)

Creates infrastructure entry points. Read references/entry-points.md for the full catalog of types and parameters.

./gradlew gep --type=webflux
./gradlew gep --type=restmvc --server=tomcat
./gradlew gep --type=graphql
./gradlew gep --type=kafka
./gradlew gep --type=sqs
./gradlew gep --type=rsocket
./gradlew gep --type=mcp
./gradlew gep --type=agent --name=my-agent
./gradlew gep --type=generic --name=MyEntryPoint

Validate Structure (validateStructure | vs)

Validates that project dependency rules aren't violated (Clean Architecture Dependency Rule: source code dependencies can only point inwards).

./gradlew validateStructure
./gradlew vs

Validations performed:

1. Model module: no dependencies at all
2. UseCase module: dependency to Model module ONLY
3. Infrastructure modules: allow external deps + Model/UseCase, but NOT AppService

Whitelisting dependencies (e.g. for BOMs):

// build.gradle
cleanPlugin {
    modelProps {
        whitelistedDependencies = "my-bom, <dep2>, <depN..>"
    }
}

Delete Module (deleteModule | dm)

Deletes a sub project module.

./gradlew deleteModule --module=[name]
./gradlew dm --module=[name]

Workflow

When the user wants to create a new project or add modules, follow this sequence:

1. Ask what they need (project name, reactive/imperative, which adapters and entry points)
2. If no project exists yet, generate it with ca
3. Generate models with gm for each domain entity
4. Generate use cases with guc for each business operation
5. Generate driven adapters with gda for external integrations
6. Generate entry points with gep for how the app is exposed
7. Run with ./gradlew bootRun

Always run commands from the project root where build.gradle lives. Use ./gradlew (not gradle) after the wrapper is generated.

Important Notes

• Running ca on an existing project overrides main.gradle, build.gradle, and gradle.properties
• The --type=reactive project uses WebFlux (non-blocking), --type=imperative uses Spring MVC
• For driven adapters with secrets (JPA, MongoDB, Redis), add --secret=true to enable secrets manager integration
• Entry points like webflux and restmvc support --authorization, --versioning, --swagger, and --from-swagger options