scaffold-clean-architecture: a Gradle plugin that generates a Java clean architecture project

A generator, not a framework

The repository description is a Gradle plugin to create a clean application in Java that already works, and it follows our best practices. The README restates it as a Gradle plugin to create a java application based on Clean Architecture following our best practices.

That is a narrower and more useful claim than it first appears. The plugin does not offer a runtime, a set of annotations or a persistence layer that your application depends on. It writes out a project. Once generated, the output is a Gradle project with a directory layout and a set of conventions, and from that point on it is an ordinary Java codebase with no dependency on the plugin.

That distinction decides who the tool is for. The audience is a team that has already agreed on a way of structuring Java services and wants the agreement encoded in a generator rather than in a wiki page that new starters have to read and remember. The our in our best practices makes the origin explicit: this is Bancolombia publishing the conventions it applies internally.

The topics attached to the repository list architecture, gradle, java, open-source and scaffolding, which is an accurate summary.

The primary language is listed as Mustache, and that is the most informative single fact in the repository metadata. It tells you the plugin is a template generator. The structure it produces is not hard-coded in Java logic; it is written as templates, rendered with the Mustache template engine, and the output is assembled from those templates. The primary language being a template format rather than Java is also a statement about where the maintenance effort goes: into the templates, not into the generator.

The licence is Apache-2.0, the default branch is master, and the recent releases are v5.0.2 and v4.7.4, both published on 2026-10-19, with v5.0.1 from 2026-10-15. The last push was on 2026-10-19.

The README is a pointer, and the documentation is the product

The README is unusually short, and the reason is visible in its Getting Started section. It says: please follow our Getting Started Guide to create your first project, linking to bancolombia.github.io/scaffold-clean-architecture/docs/intro.

Everything else in the README is badges. There is a workflow badge for gradle-actions, a SonarCloud quality gate status badge and a maintainability rating badge, a codecov coverage badge, an Apache 2.0 licence badge, an OpenSSF Best Practices badge, and a Scorecards supply-chain security badge.

So the operational content lives on a hosted documentation site rather than in the repository, and that has a practical consequence for anyone evaluating this: the README alone will not tell you what the generated project looks like, which directories are produced, what the module boundaries are, or what the conventions actually are. Those answers are in the guide.

What the badge row does tell you is a fair amount about how the project is run. The gradle-actions workflow badge means the plugin is built by CI. The SonarCloud quality gate and maintainability badges mean a static analysis gate runs against the source and that maintainability is tracked as a first-class metric, not just code coverage. The codecov badge means coverage is reported. The OpenSSF Best Practices and Scorecards badges cover the supply-chain side: dependency hygiene, pinned actions, and the sort of checks that say something about whether a plugin you run inside your build can be trusted with your dependency graph.

None of that is documentation, but for a tool whose entire job is to write code into your repository, the quality of the generator's own source is the thing you are trusting.

The docs directory is present in the tree, alongside a docs/ subdirectory for the site, and the examples-ca/ directory is named for the example applications, which is where you would look for a generated project to read rather than to run.

What the repository layout says about the generation pipeline

The top-level entries describe a build that is more than a Gradle plugin jar.

There is the ordinary set: build.gradle, settings.gradle, gradle.properties, the gradle/ directory and the gradlew and gradlew.bat wrapper scripts, so the repository builds with a pinned Gradle version and does not need Gradle installed.

Then there are three shell scripts, and their names describe the pipeline. sh_dependencies.json is a JSON file with a sh_ prefix, which reads like a manifest of the dependencies the generator resolves. sh_generate_project.sh is the script that generates a project, which is the plugin's actual entry point in script form. sh_publish_plugin_local.sh is for publishing the plugin locally, which is the step you need when you want to try a change to the generator without publishing to a public repository.

That last one is the tell that this is a generator with an iteration loop. A plugin that can only be tested by publishing it is awkward to work on, and a local publish script shortens the loop between changing a template and seeing the generated output.

The config/ directory holds configuration, the src/ directory holds the plugin and template sources, and the examples-ca/ directory holds example applications. The examples directory is the more interesting of the two for an adopter, because a generated project that already works is the only reliable way to see what the conventions look like in practice.

The scaffolding topic tag covers all of this. The project is not a library you depend on at runtime, so the whole of its value is concentrated in the moment of generation, and the repository is arranged around that: templates in one place, configuration in another, example output in a third, and scripts that move between them.

Templating with Mustache, and what that choice implies

The choice of Mustache as the primary language tells you more about the project than any amount of documentation would, so it is worth spelling out what it means.

Mustache is a logic-less template engine. There is no conditional logic, no loops with arbitrary expressions and no helper functions available inside a template. A template receives a data structure and substitutes values into it, and that is all it does.

For a scaffolding tool this is a real constraint rather than an arbitrary one, and it has consequences in both directions.

The upside is that a template cannot contain behaviour. Whatever conditional logic a generated project needs, the generator has to compute it before rendering, in Java, and pass the answer in as data. The result is that the templates stay declarative and the decisions stay in testable code. For a generator whose output is going to be committed to a repository and reviewed by humans, that separation is worth something.

The other upside is diffability. A Mustache template is mostly literal text with placeholders in it, so a template reads much like the file it produces. When someone asks why the generated Gradle file has a particular dependency, the answer is visible in the template rather than buried in a builder chain.

The cost is expressiveness. Anything conditional has to be lifted out of the template, and a generator with many variations across configurations can end up with a lot of data plumbing to feed a template that is otherwise simple. The trade is that the complexity moves into Java where it can be tested, rather than staying in the template where it cannot.

That choice also makes the plugin portable in a way a code-generating plugin with its own template language would not be. Mustache is a small, well-understood dependency, and the generated output does not depend on the template engine at all.

Release tooling and the two-branch version numbers

Two files in the tree point at how releases are managed. CHANGELOG.md is present, so the history is written down rather than left in Git tags. And .releaserc is present, which is the configuration file for semantic-release, the tool that derives a version number and a changelog entry from conventional commit messages.

The release records show something you should notice before you pin a version. The recent releases are v5.0.2 and v4.7.4, both published on 2026-10-19, and v5.0.1 from 2026-10-15. Two release lines moving on the same day, one at 5.0.2 and one at 4.7.4, with the 5.x line also having 5.0.1 three days earlier.

A parallel major line like that is usually a maintenance branch. The 4.x line is being maintained with fixes while the 5.x line carries the current work, and both get published. For a consumer, that means there are two supported streams and the choice matters: the 5.x line is where new behaviour lands, and the 4.x line is what existing projects are probably on.

The .pre-commit-config.yaml at the root indicates that the project itself uses pre-commit hooks, so formatting and lint checks run before a commit lands rather than in a separate CI step. That is consistent with the rest of the setup, where the CI badges are the enforcement point and the local tooling is the convenience layer.

The gradle/ directory with the wrapper scripts is the other detail. Pinning the Gradle version in the repository means a contributor and a CI runner build with the same Gradle, which matters for a plugin because Gradle API changes between versions are a common source of build breakage.

SECURITY.md is present too, so the project documents how to report a vulnerability in the generator itself. For a plugin that writes code into other people's repositories and runs inside their builds, that is the file you would check before adopting it.

Where the generator is the wrong tool

There are three limits, and the first is the one that decides whether this project applies to you at all.

The first is the coupling to one stack. This generates a Java application on Gradle following one company's clean architecture layout. If your team has settled on a different structure, a different build tool, or a different language, none of the value transfers. A generator's value is that its output matches what you would have written, and if you would have written something different then the generated project is a starting point you have to unpick rather than a shortcut.

The second is the staleness question that every scaffolding tool faces. The conventions encoded in the templates were correct when they were written. Architecture moves slowly, but a template that hard-codes a dependency version, a package name pattern or a library choice will age, and when it ages the generated project starts new work in a slightly wrong direction. The existence of v4.7.4 alongside v5.0.2 suggests the maintainers do maintain the templates, but it also suggests that the 4.x templates are a distinct set that no longer reflect the current best practice.

There is a related risk that is specific to generators. Because the output is committed to your repository, the generator's decisions become your code. If the generated project has a dependency you would not have chosen, or a package layout you disagree with, you now own undoing that. The plugin does not help you keep the generated project in sync with later versions of itself, which is the ongoing cost that the plugin's own convenience hides.

The third is that the documentation is external. For a tool whose entire behaviour is a set of conventions, having those conventions in a hosted guide rather than in the repository means you cannot read them offline, and it means a change to the guide and a change to the templates are not versioned together. The README points to it, and the guide is where the real instructions are, but that is a dependency on a site rather than on a file.

The honest alternative depends on the situation. For a team that has no agreed structure, a generator that encodes one specific company's practice is a reasonable way to start, because it stops the argument and produces something coherent. For a team that already has a house style, a small internal generator or a template repository you own will fit better, because it will encode your conventions rather than someone else's. And for a team that wants to understand the architecture before committing to it, reading the example applications in examples-ca/ and then writing the first project by hand is often faster than generating one and then arguing with its layout.

Editorial conclusion

Adopt scaffold-clean-architecture if you are starting a Java service inside Bancolombia or want their clean architecture layout and conventions generated rather than hand-assembled, since the plugin produces a project that already works. Do not adopt it if you need a different architecture, language or build tool, because the generator is specific to Java and Gradle. Before you use it, read the getting started guide linked from the README, and note the last push was on 2026-10-19 with releases v5.0.2 and v4.7.4 published the same day.

Frequently asked questions

Official sources

1. bancolombia/scaffold-clean-architecture on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases