Scaffolding of Clean Architecture

Gradle plugin to create a java and kotlin application based on Clean Architecture following our best practices!

• Scaffolding of Clean Architecture
• Plugin Implementation
• Tasks
  • Generate Project
  • Generate Model for Java and Kotlin
  • Generate Use Case for Java and Kotlin
  • Generate Driven Adapter
  • Generate Entry Point
  • Generate Helper
  • Generate Pipeline
  • Generate Acceptance Test
  • Validate Structure
  • Delete Module
  • Update Project
• How can I help?
• Whats Next?

Plugin Implementation

To use the plugin you need Gradle version 6.9 or later, to start add the following section into your build.gradle file.

plugins {
    id "co.com.bancolombia.cleanArchitecture" version "2.4.5"
}

Or if is a new project execute this script in the root directory of your project.

echo "plugins {
    id \"co.com.bancolombia.cleanArchitecture\" version \"2.4.5\"
}" > build.gradle

To use the plugin you need Gradle version 6.9 or later, to start add the following section into your build.gradle.kts file.

plugins {
    id("co.com.bancolombia.cleanArchitecture") version "2.4.5"
}

Or if is a new project execute this script in the root directory of your project.

echo "plugins {
    id(\"co.com.bancolombia.cleanArchitecture\") version \"2.4.5\"
}" > build.gradle.kts

Tasks

The Scaffolding Clean Architecture plugin will allow you run 8 tasks:

Generate Project

The cleanArchitecture | ca task will generate a clean architecture structure in your project, this task has four optional parameters; package , type, name and coverage. If you run this task on an existing project it will override the main.gradle, build.gradle and gradle.properties files.

• package = <package.we.need>: You can specify the main or default package of your project. Default Value = co.com.bancolombia

• type = <imperative | reactive>: With this parameter the task will generate a POO project. Default Value = imperative

• name = NameProject: This parameter is going to specify the name of the project. Default Value = cleanArchitecture

• coverage = <jacoco | cobertura>: This parameter is going to specify the coverage tool for the project. Default Value = jacoco

• lombok = <true | false>: Specify if you want to use this plugin . Default Value = true

• metrics = <true | false>: Specify if you want to enable this feature with micrometer . Default Value = true

• language = <JAVA | KOTLIN>: Specify if you want to use this plugin . Default Value = JAVA

• javaVersion = <VERSION_1_8 | VERSION_11 | VERSION_17>: Java version . Default Value = VERSION_11

gradle cleanArchitecture --package=co.com.bancolombia --type=imperative --name=NameProject --coverage=jacoco --lombok=true
gradle ca --package=co.com.bancolombia --type=imperative --name=NameProject --coverage=jacoco --lombok=true

The structure will look like this for java:

📦NameProject
┣ 📂applications
┃ ┗ 📂app-service
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📂main
┃ ┃ ┃ ┃ ┣ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂config
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜[configs and beans]
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜MainApplication.java
┃ ┃ ┃ ┃ ┗ 📂resources
┃ ┃ ┃ ┃ ┃ ┣ 📜[properties]
┃ ┃ ┃ ┗ 📂test
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┗ 📜build.gradle
┣ 📂deployment
┃ ┣ 📜[Dockerfile, Pipelines as a code]
┣ 📂domain
┃ ┣ 📂model
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📂main
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┗ 📂test
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┗ 📜build.gradle
┃ ┗ 📂usecase
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📂main
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┗ 📂test
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂usecase
┃ ┃ ┗ 📜build.gradle
┣ 📂infrastructure
┃ ┣ 📂driven-adapters
┃ ┣ 📂entry-points
┃ ┗ 📂helpers
┣ 📜.gitignore
┣ 📜build.gradle
┣ 📜gradle.properties
┣ 📜lombok.config
┣ 📜main.gradle
┣ 📜README.md
┗ 📜settings.gradle

The structure will look like this for kotlin:

📦NameProject
┣ 📂applications
┃ ┗ 📂app-service
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📂main
┃ ┃ ┃ ┃ ┣ 📂kotlin
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂config
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜[configs and beans]
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜MainApplication.kt
┃ ┃ ┃ ┃ ┗ 📂resources
┃ ┃ ┃ ┃ ┃ ┣ 📜[properties]
┃ ┃ ┃ ┗ 📂test
┃ ┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┗ 📜build.gradle.kts
┣ 📂deployment
┃ ┣ 📜[Dockerfile, Pipelines as a code]
┣ 📂domain
┃ ┣ 📂model
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📂main
┃ ┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┗ 📂test
┃ ┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┗ 📜build.gradle.kts
┃ ┗ 📂usecase
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📂main
┃ ┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┗ 📂test
┃ ┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂usecase
┃ ┃ ┗ 📜build.gradle.kts
┣ 📂infrastructure
┃ ┣ 📂driven-adapters
┃ ┣ 📂entry-points
┃ ┗ 📂helpers
┣ 📜.gitignore
┣ 📜build.gradle.kts
┣ 📜gradle.properties
┣ 📜lombok.config
┣ 📜README.md
┗ 📜settings.gradle.kts

Generate Model for Java and Kotlin

The generateModel | gm task will generate a class and interface in model layer, this task has one required parameter name.

   gradle generateModel --name=[modelName]
   gradle gm --name [modelName]

This task will generate something like that:

📦domain
┣ 📂model
┃ ┣ 📂src
┃ ┃ ┣ 📂main
┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┗ 📂model
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂gateways
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜ModelRepository.java
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜Model.java
┃ ┃ ┗ 📂test
┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┗ 📂model
┃ ┗ 📜build.gradle

This task will generate something like that for kotlin:

📦domain
┣ 📂model
┃ ┣ 📂src
┃ ┃ ┣ 📂main
┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┗ 📂model
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂gateways
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜ModelRepository.kt
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜Model.kt
┃ ┃ ┗ 📂test
┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┗ 📂model
┃ ┗ 📜build.gradle.kts

Generate Use Case for Java and Kotlin

The generateUseCase | guc task will generate a class in model layer, this task has one required parameter name.

   gradle generateUseCase --name=[useCaseName]
   gradle guc --name [useCaseName]

This task will generate something like that:

📦domain
┗ 📂usecase
┃ ┣ 📂src
┃ ┃ ┣ 📂main
┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┗ 📂usecase
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂business
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜BusinessUseCase.java
┃ ┃ ┗ 📂test
┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┗ 📂usecase
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂business
┃ ┗ 📜build.gradle

This task will generate something like that for kotlin:

📦domain
┗ 📂usecase
┃ ┣ 📂src
┃ ┃ ┣ 📂main
┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┗ 📂usecase
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂business
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜BusinessUseCase.kt
┃ ┃ ┗ 📂test
┃ ┃ ┃ ┗ 📂kotlin
┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┗ 📂usecase
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂business
┃ ┗ 📜build.gradle.kts

Generate Driven Adapter

The generateDrivenAdapter | gda task will generate a module in Infrastructure layer, this task has one required parameter type.
Whether you'll use generic one also parameter name is required.

   gradle generateDrivenAdapter --type=[drivenAdapterType]
   gradle gda --type [drivenAdapterType]

Reference for drivenAdapterType	Name	Additional Options	Java	Kotlin
generic	Empty Driven Adapter	--name [name]	☑	☑
jpa	JPA Repository	--secret [true-false]	☑	☑
mongodb	Mongo Repository	--secret [true-false]	☑	☑
asynceventbus	Async Event Bus		☑	☑
restconsumer	Rest Client Consumer	--url [url]	☑	☑
redis	Redis	--mode [template-repository] --secret [true-false]	☑	☑
rsocket	RSocket Requester		☑	☑
r2dbc	R2dbc Postgresql Client		☑	☑
kms	AWS Key Management Service		☑	☑
secrets	Secrets Manager Bancolombia		☑	☑
s3	AWS Simple Storage Service		☑	☑
mq	JMS MQ Client to send messages		☑	☑
ktor	HTTP client for kotlin		☐	☑
dynamodb	Dynamo DB adapter		☑	☑
sqs	SQS message sender		☑	☑

This task will generate something like that:

📦infrastructure
┣ 📂driven-adapters
┃ ┗ 📂jpa-repository
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📂main
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂jpa
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂config
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜DBSecret.java
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂helper
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜AdapterOperations.java
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📜JPARepository.java
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📜JPARepositoryAdapter.java
┃ ┃ ┃ ┗ 📂test
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂jpa
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂helper
┃ ┃ ┗ 📜build.gradle

Generate Entry Point

The generateEntryPoint | gep task will generate a module in Infrastructure layer, this task has one required parameter type.
Whether you'll use generic one also parameter name is required.

gradle generateEntryPoint --type=[entryPointType]
gradle gep --type [entryPointType]

Reference for entryPointType	Name	Additional Options	Java	Kotlin
generic	Empty Entry Point	--name [name]	☑	☑
restmvc	API REST (Spring Boot Starter Web)	--server [serverOption] default undertow	☑	☑
webflux	API REST (Spring Boot Starter WebFlux)	--router [true, false] default true	☑	☑
rsocket	Rsocket Controller Entry Point		☑	☑
graphql	API GraphQL	--pathgql [name path] default /graphql	☑	☑
asynceventhandler	Async Event Handler		☑	☑
mq	JMS MQ Client to listen messages		☑	☑
sqs	SQS Listener		☑	☑

Additionally, if you'll use a restmvc, you can specify the web server on which the application will run. By default, undertow.

   gradle generateEntryPoint --type=restmvc --server=[serverOption]
   gradle gep --type=restmvc --server=[serverOption]

Reference for serverOption	Name
undertow	Undertow server (default)
tomcat	Tomcat server
jetty	Jetty server

This task will generate something like that:

📦infrastructure
┣ 📂entry-points
┃ ┗ 📂generic
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📂main
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂generic
┃ ┃ ┃ ┗ 📂test
┃ ┃ ┃ ┃ ┗ 📂java
┃ ┃ ┃ ┃ ┃ ┗ 📂[package]
┃ ┃ ┃ ┃ ┃ ┃ ┗ 📂generic
┃ ┃ ┗ 📜build.gradle

Generate Helper

The generateHelper | gh task will generate a module in Infrastructure layer, this task has one required parameter name.

   gradle generateHelper --name=[helperName]
   gradle gh --name=[helperName]

Generate Pipeline

The generatePipeline | gpl task will generate CI pipeline inside the folder "./deployment/", this task has one required parameter type.

   gradle generatePipeline --type=[pipelineType]
   gradle gpl --type=[pipelineType]

Reference for pipelineType	Name
azure	Azure Pipeline
github	GitHub Action
jenkins	Jenkins Pipeline
circleci	CircleCI Pipeline

Generate Acceptance Test

The generateAcceptanceTest | gat task will generate subproject by karate framework inside the folder "./deployment/",this task does not have required parameters.

      gradle generateAcceptanceTest
      gradle gat 

Karate is an open-source tool to combine API test-automation, mocks, performance-testing and even UI automation into a single, unified framework. The BDD syntax popularized by Cucumber is language-neutral, and easy for even non-programmers. Assertions and HTML reports are built-in, and you can run tests in parallel for speed.

Validate Structure

The validateStructure | vs Validate that project references aren't violated.

   gradle validateStructure
   gradle vs

Dependency Rules

One important point made by Robert C. Martin on Clean Architecture is the Dependency Rule, that can be summarized like this: source code dependencies can only point inwards. Nothing in an inner circle can know anything at all about something in an outer circle. In particular, the name of something declared in an outer circle must not be mentioned by the code in an inner circle.

Having that in mind, the validateStructure | vs task performs the following validations:

1. Model module: to have no dependencies at all.
2. UseCase module: to declare dependency to the Model module ONLY, and no other additional dependencies.
3. Infrastructure Layer modules:
   • Allow declaration of any external dependency.
   • Allow declaration of dependency on Model and/or UseCase modules.
   • Avoid declaration of dependency AppService module.

Whitelisting dependencies:

Some dependencies, specially when working with BOMs (Bills of Materials), are injected transversally to the project, making the validation task to flag failures to rules 1 and 2. To avoid this scenario, or other you may encounter, you can configure a set of whitelisted dependencies.

Example:

1. Let's say you have declared a BOM in your project:

   dependencies {
     implementation(platform("com.myorg:my-bom:0.0.1"))
   }

2. This will make validateStructure | vs to flag a failure indicating an error like this:

   Validating Model Module
    --- Dependency com.myorg:some-bom is not allowed in Model Layer

3. To avoid this, you can white list your BOM like this:

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

   Indicating only the name of the dependencies comma-separated.

Delete Module

The deleteModule | dm task will delete a sub project, this task has one required parameter module.

   gradle deleteModule --module=[name]
   gradle dm --module=[name]

Update Project

The updateCleanArchitecture | u task will update plugin and dependencies in all sub projects, this task has one optional parameter dependencies if you only want to update some dependencies the dependency need to contain the group, and the artifact for example for the dependency cleanArchitecture you will need to append co.com.bancolombia:cleanArchitecture. It also updates the spring, lombok, gradle and some other dependencies according to the plugin version that you are using, ocassionally it could make changes in other project structural files. We recommend that you commit your changes to git before running this command, but you can skip the verification passing --git false.

   gradle updateCleanArchitecture --dependencies=[dependency1, dependency2, ...]
   gradle u --dependencies=[dependency1, dependency2, ...]

How can I help?

Review the issues, we hear new ideas. Read more Contributing

Whats Next?

Read more About Clean Architecure