Codegen Blueprint is for teams who care less about how fast a project starts
and more about how well its architecture survives over time.
Clone this project if you’ve ever seen a codebase start clean and slowly drift into chaos — where architectural rules exist only in slides, not in code.
Codegen Blueprint is not a faster way to scaffold a project. It is a deliberate way to lock architectural intent into executable, testable constraints that are continuously verified in CI from day zero.
It doesn’t just generate a project —
it generates a project and proves, on every build, that the architecture still holds.
If long-term maintainability, domain purity, and build-time enforced boundaries matter to you, this repository is worth your time.
Every project generated by Codegen Blueprint 1.0.0 ships with the ability to generate enforceable guardrails — not documentation, not conventions, but executable rules that fail your build when architecture drifts.
Codegen Blueprint follows an explicit release discipline where versions represent architectural and compatibility contracts, not feature counts. Starting from 1.0.0 GA, guarantees around generation determinism, structure, and executable architecture enforcement are intentional and protected.
Breaking changes are introduced only in major versions and are never silent.
For details, see:
👉 Release Discipline
Codegen Blueprint is intentionally constrained by design. Some things are not supported — not by accident, but to protect architectural integrity.
Before adopting the project, please review what is explicitly out of scope:
👉 What We Do NOT Guarantee
Codegen Blueprint started as an early experiment in Spring Boot project bootstrapping (codegen-springboot-initializr).
As the project evolved, the focus shifted from “scaffolding” to Executable Architecture — guardrails that can fail the build.
The current main branch reflects this pivot and the architecture-first direction.
Earlier 0.x tags are kept for historical context and experimentation, but they do not define the GA guarantees.
The compatibility and guarantee contract begins with 1.0.0 GA.
Most teams don’t fail because they chose the wrong framework.
They fail because architecture slowly drifts once the project is “up and running.”
What starts as a clean design turns into:
- shortcuts under delivery pressure
- blurred boundaries between layers
- domain logic leaking into frameworks
- “we’ll fix it later” decisions that never get fixed
Traditional project generators help you start fast —
but they disappear the moment the first commit is made.
Codegen Blueprint exists to solve what happens after generation.
It treats architecture as a first-class, executable product:
- Enforces architectural boundaries — layered and/or Hexagonal (opt-in)
- Prevents silent architecture drift
- Protects the domain from frameworks by construction
- Standardizes early decisions across teams — automatically
Executable Architecture — Delivered from day zero. Enforced over time.
Who benefits → Engine capabilities → What teams get
🔗 Part of the Blueprint Platform
https://github.com/blueprint-platform
| Role | Problem Solved |
|---|---|
| Platform Engineering | Org‑wide standardization made enforceable |
| Lead Architects | Governance as Code — constraints auto‑applied |
| Developers | No boilerplate — productivity from day zero |
| New Team Members | Architecture learning curve removed |
Initializr-like convenience → Architecture-first evolution
| Capability Focus | Spring Initializr / JHipster | Codegen Blueprint |
|---|---|---|
| Folder scaffolding | ✔ | ✔ |
| Architecture governance | ✔ | |
| Framework‑free domain | ❌ | ✔ |
| Profile‑driven evolution | ✔ | |
| Anti‑drift roadmap | ❌ | ✔ |
Most generators generate code for cross‑cutting concerns. That approach does not scale.
Codegen Blueprint makes a clear distinction:
| Approach | What happens | Long‑term effect |
|---|---|---|
| Generate code | Copies security, logging, error handling into each service | ❌ Drift, copy‑paste, painful upgrades |
| Enforce via libraries | Centralized, versioned, opt‑in behavior | ✔ Consistency, easy upgrades, governance |
Not everything should be generated. Cross‑cutting concerns should be enforced, not duplicated.
With Blueprint Platform:
- Architecture is generated once
- Behavior is enforced via shared libraries / BOMs
- Upgrades happen in one place, not 50 microservices
This is why Blueprint is not a template collection.
It is architecture as an executable product.
🧩 Same simplicity — better long‑term alignment
- ⚡ What is Codegen Blueprint (Today)?
- 🧪 Executable Architecture — Proof
- 🧭 1.0.0 Release Scope
- 🧱 Architecture Overview
- 🔌 Inbound & Outbound Adapters
- 🔄 CLI Usage (Spring Boot)
- 🧪 Testing & CI (This Repository)
- 🚀 Vision & Roadmap
- ⭐ Support
- 🛡 License
A CLI-driven, profile-based, architecture-aware project generator that turns architectural decisions into executable output.
📌 Current profile: spring-boot-maven-java
Spring Boot 3.5+ · Java 21 · Maven — production-ready baseline
Codegen Blueprint today delivers:
- Deterministic, production-ready project scaffolding
- Clean source layout (main + test) with verified bootstrapping
- Framework-free domain core by construction
- Profile-driven architecture selection (standard / hexagonal)
- Optional architecture enforcement via generated ArchUnit tests
(enabled with--enforcement basic|strict) - Maven configuration, wrapper, and build baseline
- Application configuration (
application.yml) - Optional basic sample code for both:
- standard (layered) layout
- hexagonal (ports & adapters) layout
Architecture is not only generated —
it can be verified and enforced as part of the project output.
Codegen Blueprint does not rely on conventions or documentation to protect architecture.
When strict enforcement is enabled, architectural boundaries are translated into generated, executable rules that are evaluated during the build.
👉 See the full step-by-step executable architecture proof:
Executable Architecture Proof
Architecture isn’t only drawn — it executes here.
Hexagonal Architecture is not a stylistic choice in Codegen Blueprint. It is a structural requirement for the platform’s core promise:
Generate once. Evolve across frameworks, runtimes, and languages — without rewriting the core.
Spring Boot is the first adapter — not the foundation.
📌 Want the architectural deep dive?
- 📜 Architecture Enforcement Contract
Defines what architectural rules exist, when they apply, and what will break the build
→ Architecture Enforcement Contract
- 🔒 Executable Architecture Scope (1.0.0 GA)
Declares which enforcement rules are guaranteed in the 1.0.0 GA release and output scope
→ Executable Architecture Scope (1.0.0 GA)
- 🧭 How to Explore This Codebase (Hexagonal Guide)
Understand ports/adapters, profiles, boundaries
→ Hexagonal Architecture Guide
- 🧠 Architecture Governance & AI Collaboration Protocol
How architectural decisions are made, enforced, and protected
→ Architecture Governance & AI Protocol
codegen-blueprint is the first foundational module of the Blueprint Platform — an architecture‑first project generation ecosystem designed to enable consistent, enforceable, and scalable enterprise development.
Unlike traditional generators that simply scaffold code, Blueprint Platform aims to:
- Standardize enterprise best practices through opinionated architecture and code structure
- Integrate reusable common libraries that encapsulate cross‑cutting concerns (security, logging, error handling, tracing, OpenAPI clients, etc.)
- Enforce architectural integrity using built‑in validation and guardrails (e.g., hexagonal boundaries, naming rules, testable layout)
As the platform evolves, more modules will be introduced to complement codegen-blueprint with:
- Ready‑to‑use behavior‑driven libraries
- Consistent and generics‑aware OpenAPI client generation
- Support for multiple frameworks and technology stacks
🔗 Learn more at the Blueprint Platform GitHub Organization
This aligns with the upcoming Vision & Roadmap section below.
Domain stays clean — Ports and adapters connect everything else.
domain // business logic only
application // orchestrates ports
adapter // inbound/outbound driven by use cases
bootstrap // Spring wiring + config
CLI → Use case layer → Domain → Artifacts → Spring Boot project
- No Spring annotations inside the domain
- Hexagonal from day zero — when opted‑in
- Flexible to evolve with future profiles (CQRS, Layered…)
📌
mainbranch reflects the upcoming 1.0.0 GA.
| Guarantee | Description |
|---|---|
| Deterministic project generation | Same input always produces the same structure |
| CLI-driven generation | No hidden defaults, no UI-only behavior |
| Optional Hexagonal Architecture | Ports & adapters layout generated on demand |
| Optional architecture enforcement | Executable ArchUnit rules (basic / strict) |
| Test-ready output | Generated projects pass mvn verify |
| Profile-driven stack selection | Technology choices defined by profiles |
| Framework-free domain core | No Spring dependencies in the domain |
The 1.0.0 GA profile targets Spring Boot (3.4, 3.5), Java 21, and Maven. The engine is stack-agnostic by design; newer LTS versions (e.g., Java 25) may work but are not part of the GA compatibility contract.
Adapters drive interactions in and out of the core domain — keeping domain logic isolated and testable.
| Adapter | Status | Description |
|---|---|---|
| CLI | ✔ GA Ready | Primary driver to generate services via command-line |
| REST | 🚧 Planned | Future interactive generation + onboarding UX |
Architecture enforcement artifacts are generated, not hard-wired
Everything required to build → run → extend a real service:
- Maven POM + Wrapper
- Main & Test source structure
- Domain + Application + Adapter layout
- Application configuration (YAML)
- Optional basic sample code, depending on selected layout:
- standard (layered) sample slice
- hexagonal (ports & adapters) sample slice
- Optional architecture enforcement tests (ArchUnit)
(enabled via--enforcement basic|strict) - README + project documentation
- Filesystem writer for artifact creation
The domain depends on nothing — adapter depends on the domain.
This section describes the current, accurate CLI contract for Codegen Blueprint 1.0.0. It reflects the actual generated output and avoids aspirational or misleading examples.
java -jar codegen-blueprint-1.0.0.jar \
--cli springboot \
--group-id io.github.blueprintplatform \
--artifact-id greeting \
--name "Greeting" \
--description "Greeting sample built with hexagonal architecture" \
--package-name io.github.blueprintplatform.greeting \
--layout hexagonal \
--enforcement strict \
--sample-code basic \
--dependency web \
--dependency data_jpa \
--dependency actuator \
--target-dir /path/to/output| Option | Required | Default | Description |
|---|---|---|---|
--group-id |
✔ | – | Maven groupId |
--artifact-id |
✔ | – | Maven artifactId (also becomes the project folder name) |
--name |
✔ | – | Human-readable project name |
--description |
✔ | – | Project description (minimum 10 characters) |
--package-name |
✔ | – | Base Java package name |
--build-tool |
✖ | maven |
Build tool (currently only maven) |
--language |
✖ | java |
Programming language (currently only java) |
--java |
✖ | 21 |
Java version (21, 25) — GA target: 21 |
--boot |
✖ | 3.5 |
Spring Boot version (3.4, 3.5) — GA target: 3.5 |
--layout |
✖ | standard |
standard (layered) or hexagonal (ports & adapters) |
--enforcement |
✖ | basic |
Architecture enforcement: none, basic, strict |
--sample-code |
✖ | none |
Sample code level: none, basic |
--dependency |
✖ | – | Dependency alias (repeatable, controlled set) |
--target-dir |
✖ | . |
Target directory for generated output |
Available dependency aliases are intentionally limited and mapped internally to well-known Spring Boot starters.
This avoids uncontrolled dependency sprawl and keeps generated projects aligned with the architecture-first philosophy of Codegen Blueprint.
Available aliases in 1.0.0:
web
data_jpa
validation
actuator
security
devtools
Invalid or unknown aliases will fail fast during CLI execution.
Codegen Blueprint is not a free-form dependency injector.
Dependencies are:
- explicitly modeled
- version-aligned with the selected platform
- constrained by design
This ensures generated projects start with:
- a clean dependency graph
- predictable behavior
- architecture-safe defaults
Dependency freedom is a runtime concern — architectural intent is a generation-time concern.
The output directory name always equals
--artifact-id.
greeting/
├── pom.xml
├── .gitignore
├── .mvn/
│ └── wrapper/
│ └── maven-wrapper.properties
├── src/
│ ├── main/
│ │ ├── java/io/github/blueprintplatform/greeting/...
│ │ └── resources/application.yml
│ └── test/
│ └── java/io/github/blueprintplatform/greeting/...
This output is:
- buildable (
mvn verify) - testable (unit + integration baseline)
- architecture‑aware by construction
standard layout
controller/
service/
repository/
domain/
config/
hexagonal layout
domain/
application/
adapter/
bootstrap/
No Spring annotations are placed inside the domain when hexagonal layout is selected.
Architecture enforcement is opt‑in:
| Mode | Behavior |
|---|---|
none |
No architectural rules generated |
basic |
Generated ArchUnit rules enforcing core boundaries |
strict |
Stricter dependency and layering rules |
When enabled, enforcement rules are generated as executable ArchUnit tests under:
src/test/java/<projectPackage>/architecture/archunit/**
Violations fail the build deterministically during mvn verify.
- Codegen Blueprint does not generate cross‑cutting behavior (security, logging, etc.)
- Those concerns are intended to be enforced via shared libraries in later Blueprint Platform phases
- Generated projects are intentionally minimal, stable, and architecture‑first
Codegen Blueprint optimizes for long‑term architectural integrity, not short‑term scaffolding volume.
This section documents what Codegen Blueprint actually produces today — no demos, no exaggeration, no placeholders.
The following describes the CI pipeline of the Codegen Blueprint repository itself — not the projects generated by the CLI.
It validates both:
- the generator engine (domain, application, adapter)
- the real output produced by the generator (standard & hexagonal)
mvn verifyThis runs the full build lifecycle, including unit tests, integration tests, and architecture rules.
The GitHub Actions workflow executes a matrix build to ensure compatibility, determinism, and architectural integrity across supported Java versions.
Key characteristics:
- Runs on every
pushtomainand all pull requests - Tests multiple JDKs in parallel (Java 21 and Java 25)
- Verifies generated projects, not only the generator engine
- ✔ Generator unit & integration tests
- ✔ Architecture enforcement rules inside the generator itself
- ✔ Generated projects are verified using
mvn verify - ✔ Layout coverage: hexagonal and standard (layered)
- ✔ Enforcement coverage: strict
- ✔ Output coverage: sample basic and no-sample
- ✔ JDK matrix coverage: Java 21 and Java 25
- ✔ Total verification: 4 generated projects per JDK (8 projects per CI run)
- ✔ Code coverage aggregation and reporting
Checkout repository
→ Build & test generator (mvn clean verify)
→ Generate & verify (mvn verify) 4 projects:
- hexagonal + strict + sample basic
- standard + strict + sample basic
- hexagonal + strict + no sample
- standard + strict + no sample
→ Repeat across JDK matrix (21, 25)
→ Upload coverage reports
The pipeline includes:
- JaCoCo — unit + integration test coverage
- CodeQL — static security analysis
- Codecov — aggregated coverage reporting
These checks ensure the generator itself and its generated output remain stable, buildable, and architecture-safe as the platform evolves.
This CI setup explicitly prevents the class of failures where:
“The generator build is green, but the generated project is broken.”
By validating real generated projects across layouts, enforcement modes, and JDK versions, Codegen Blueprint treats architectural guarantees as continuously verified contracts, not one-time scaffolding assumptions.
Architecture should execute, not merely be drawn.
And it should stay enforced — even 6, 12, 24 months later.
Blueprint Platform =
🔹 Architecture-as-a-Product
🔹 Reusable Behavior Libraries
🔹 Enforced Consistency Across Teams
From Day Zero to Production — architecture remains intentional, testable, and aligned.
- Hexagonal / Layered architecture enforcement (opt-in)
- Optional architecture enforcement via generated ArchUnit tests
- Profile-driven CLI generation (Spring Boot · Maven · Java 21)
- Domain purity: no Spring inside the core
- End-to-end testable scaffolding
📌 1.0.0 GA Objective → Zero-drift architectural foundations
- 🔐 Security defaults (OAuth2 / Keycloak)
- 📡 Resilience / Retries / Standardized error handling
- 🔍 Observability: tracing + logs + metrics — auto-wired
- 🧩 Multi-module enterprise service kits (API + Domain + Infra)
- Generics-aware OpenAPI client generation
📌 Libraries become switch-on features, not generated boilerplate
- Gradle & Kotlin support
- Quarkus + future stack profiles
- Visual UI — configure → generate → download
- Drift detection & auto-remediation (governance at scale)
- Platform telemetry for architecture health
📌 Community-driven priorities →
🔗 Participate: Discussions
| Without Blueprint | With Blueprint |
|---|---|
| Architecture drifts silently | Guardrails keep intent executable |
| Boilerplate everywhere | Cross-cutting concerns via libraries |
| Onboarding takes weeks | Day-zero productivity |
| Standards depend on discipline | Standards enforced by construction |
📌 The platform grows → Projects stay clean → Enterprise stays consistent
Blueprint Platform isn’t just code generation —
it is strategic architectural continuity.
We welcome:
- Architecture improvements
- Stack profiles & adapters
- Template & documentation enhancements
Start here → :
If this project saves your team time or headaches:
👉 Please star the repo — it truly helps visibility!
Barış Saylı — Creator & Maintainer
- GitHub — https://github.com/bsayli
- LinkedIn — https://www.linkedin.com/in/bsayli
- Medium — https://medium.com/@baris.sayli
MIT — free for commercial and personal use. See: LICENSE