Codegen Blueprint generates projects where architectural boundaries are not conventions — they are observable, testable, and enforced by the build from day one.
Before you run a single command, here is the irreducible proof:
- a real architectural boundary is violated
- the build evaluates that intent
- the build fails deterministically
No application startup. No runtime checks. No conventions to trust.
Visual proof — build-time failure (inspectable without cloning):
This failure is produced by a generated ArchUnit rule and evaluated during mvn verify. Nothing runs. The build itself enforces the architecture.
See the guardrails in action in under a minute:
git clone https://github.com/blueprint-platform/codegen-blueprint
cd codegen-blueprint
./mvnw clean package
java -jar target/codegen-blueprint-*.jar \
--cli springboot \
--group-id demo \
--artifact-id demo \
--name "Demo" \
--description "Demo project" \
--package-name demo \
--layout hexagonal \
--guardrails strict \
--dependency webThen:
cd demo
./mvnw verify👉 Break a boundary → watch the build fail
This is the fastest way to understand what Codegen Blueprint actually does.
Especially in an AI-assisted development era, where code is produced faster than it is reviewed, architectural drift is no longer a risk — it is the default.
- Architectural rules are generated, not documented
- Violations are detected at build time
- The feedback is deterministic and explicit
- Architecture cannot silently drift
👉 Proof — Explained Walkthrough
This shows:
- the generated structure
- the exact forbidden change
- the precise ArchUnit rule that fails
- the corresponding build output
👉 Proof — Console Execution (GREEN → RED → GREEN)
This path is for readers who want hands‑on verification using mvn verify.
- Your codebase started clean — then architecture drifted silently once things were “up and running”.
- A new developer (or a rushed change) shipped code into the wrong layer — and the only “rule” was tribal knowledge.
- Reviews turned into “is this the right boundary?” debates — because nothing was executable.
Codegen Blueprint exists for the moment when architectural intent must stop being assumed and start being observable, testable, and enforced by the build.
It is designed for teams who care about architectural integrity over time, and want boundaries that remain visible and verifiable as systems, teams, and pressure evolve.
Background reading
If you want the broader architectural context behind this repository:
Why Architecture Drift Is Faster Than Ever — And Why AI Makes Guardrails Mandatory > Why build-time architecture guardrails matter — especially under AI-speed refactoring.
The Project That Finally Taught Me Hexagonal Architecture > The real project journey behind the engine — how architectural struggle, reset, and rebuild shaped Codegen Blueprint.
- 🤔 Should you clone this repository?
- 🛡 1.0.x GA promise (non-negotiable)
- ⚡ What is Codegen Blueprint (today)?
- 🎯 Who is this for?
- 🧱 Architecture Overview
- 🥇 What makes Codegen Blueprint different?
- 🧪 Executable Architecture — proof
- 📦 Release & compatibility discipline
- 🚫 What we explicitly do NOT guarantee
- 🧩 Generate vs deliver capabilities (cross-cutting concerns)
- 🧩 Part of the Blueprint Platform
- 🧭 1.0.x Release Scope
- 🔌 Inbound & Outbound Adapters
- 🔄 CLI Usage (Spring Boot)
- 🧪 Guardrails — Architecture Feedback Loop
- 🧪 Testing & CI (This Repository)
- 🚀 Vision & Roadmap
- 🤝 Contributing
- ⭐ Real World Feedback
- 🛡 License
Clone this project if architecture drift has ever cost you time, quality, or trust — and you want boundaries that are observable in the build, not implied in docs.
Codegen Blueprint is not a faster way to scaffold a project.
It turns architectural intent into executable guardrails with fast, deterministic feedback during mvn verify.
- You optimize for long‑term maintainability, not day‑one scaffolding speed.
- You want build‑time signals when boundaries are crossed.
- You prefer explicit contracts over tribal knowledge and reviewer debates.
- You only need a quick starter template without build-time guardrails.
- You expect cross‑cutting runtime behavior (security/logging/etc.) to be generated as boilerplate.
What you get with every generated project (1.0.x):
- Architecture guardrails included by default (
basic) — explicit opt-out only (--guardrails none) - Build-time enforcement via generated ArchUnit tests (
mvn verify) - Deterministic failure when boundaries are violated (no runtime, no conventions)
- Explicit modes (
basic/strict) — you choose the enforcement level
This is not a guideline — it is a build-enforced contract.
Source of truth (binding): Executable Architecture Contract — 1.0.x GA
A CLI that generates Spring Boot projects with architecture already enforced by the build — not left to conventions.
It gives you, from day one:
- Deterministic project generation (same input → same output)
- Buildable, test-ready output (
mvn verifypasses immediately) - Explicit architecture choice:
standard(layered) orhexagonal - Build-time guardrails via generated ArchUnit tests
- Framework-free domain by construction
📌 Current GA profile: springboot-maven-java
Spring Boot 3.4 / 3.5 · Java 21 · Maven 3.9+
This is not a template. This is architecture generated as an executable contract.
Codegen Blueprint uses deterministic patch versions.
| Input | Resolved version |
|---|---|
| 3.5 | 3.5.13 |
| 3.4 | 3.4.13 |
This ensures:
- reproducible builds
- consistent outputs
- no implicit "latest version" resolution
This is for teams who want architecture to stay correct under pressure — not just start clean.
You’ll get the most value if:
- You’ve seen architecture drift after initial delivery
- You want fast feedback when boundaries are violated
- You prefer enforced structure over review-time debates
| If you are... | You get... |
|---|---|
| Platform Engineer | Org-wide standards that are enforced by build |
| Lead Architect | Boundaries that are observable and testable |
| Developer | Less ambiguity, faster feedback loops |
| New Team Member | Structure that teaches the architecture implicitly |
📘 Canonical platform definition:
→ Architecture as a Product — Platform Specification
This repository is the executable implementation of that idea.
Architecture here is not described — it is:
- generated
- evaluated
- verified at build time
The generator itself is built using Hexagonal Architecture — as a structural constraint, not a style.
This ensures the engine:
- stays framework-agnostic
- evolves across delivery surfaces (CLI → REST)
- avoids core rewrites over time
At its core:
- Domain & use cases define what happens
- Adapters define how it is triggered
The core remains stable. Adapters evolve.
Spring Boot is a delivery adapter, not a foundation.
(contract → rulebook → guides → collaboration)
-
🔒 Executable Architecture Contract — 1.0.x GA Executable Architecture Contract — 1.0.x GA
-
📜 Architecture Guardrails Rulebook (semantics) Architecture Guardrails Rulebook
-
🧭 Hexagonal Architecture Guide Hexagonal Architecture Guide
-
🧠 Architecture Governance & AI Protocol Architecture Governance & AI Protocol
Most generators optimize for starting fast.
Codegen Blueprint optimizes for staying correct over time.
| Focus area | Traditional generators | Codegen Blueprint |
|---|---|---|
| Goal | Start quickly | Stay correct over time |
| Architecture boundaries | Docs / conventions | Build-enforced |
| Drift detection | Manual | Automatic (build-time) |
| Domain isolation | Optional | By construction |
| Long-term evolution | Out of scope | First-class concern |
It doesn’t try to make starting easier — it makes drift impossible to ignore.
👉 Executable Architecture Proof
Versions represent architecture contracts, not feature counts.
- MAJOR → contract reset
- MINOR → backward-compatible expansion
- PATCH → stabilization only
This project is intentionally constrained to protect architectural integrity.
Most generators solve cross-cutting concerns by generating more code.
That approach does not scale.
Every generated service becomes a new copy of:
- security rules
- logging configuration
- error handling
Over time, this leads to:
- architecture drift
- copy-paste divergence
- painful, inconsistent upgrades
Codegen Blueprint takes a different approach.
| Approach | What actually happens | Long-term effect |
|---|---|---|
| Generate code | Cross-cutting logic is duplicated into every service | ❌ Drift, duplication, upgrade friction |
| Deliver as capabilities | Behavior is centralized, versioned, and applied consistently | ✔ Consistency, alignment, easier upgrades |
Cross-cutting concerns should not be copied. They should be delivered, versioned, and governed.
codegen-blueprint is the entry point of the Blueprint Platform.
It establishes the foundation where:
- architecture is explicit
- boundaries are testable
- behavior can later be delivered as capabilities
→ This repository focuses on structure and enforcement. → Platform capabilities (security, observability, etc.) are layered on top, not generated into code.
🔗 Learn more at the Blueprint Platform GitHub organization
📌 The
mainbranch reflects the 1.0.x GA contract line.
- Deterministic generation — same input → same output
- CLI as the source of truth — no hidden behavior
- Explicit architecture choice — standard or hexagonal
- Build-time guardrails — via generated ArchUnit tests
- Test-ready output —
mvn verifypasses by default - Profile-driven stack selection — controlled, predictable
- Framework-free domain core — no Spring in the domain
These are contractual guarantees, not best-effort behavior.
Full contract: Executable Architecture Contract — 1.0.x GA
The engine is structured so that the core stays stable while delivery evolves.
| Adapter | Status | Description |
|---|---|---|
| CLI | ✔ GA Ready | Primary entry point for project generation |
| REST | 🚧 Planned | Future interactive onboarding and generation workflows |
The generator produces a complete, buildable service skeleton:
- Maven POM + Maven Wrapper
- Main & test source structure
- Domain + Application + Adapter layout
- Application configuration (
application.yml) - Optional sample code (standard / hexagonal)
- Optional architecture guardrails (ArchUnit tests)
- README and project documentation
Guardrails are generated artifacts, not hardcoded into the engine.
The core stays clean: domain depends on nothing — adapters depend on the domain.
This section documents the actual CLI contract — what is generated today.
Codegen Blueprint runs as a Spring Boot executable JAR.
java -jar <jar> --cli springboot <options...>java -jar codegen-blueprint-1.0.2.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 \
--guardrails strict \
--sample-code basic \
--dependency web \
--target-dir /path/to/outputTip:
target/codegen-blueprint-1.0.2.jar
| Option | Required | Default | Description |
|---|---|---|---|
--group-id |
✔ | – | Maven groupId |
--artifact-id |
✔ | – | Maven artifactId |
--name |
✔ | – | Project name |
--description |
✔ | – | Description (min 10 chars) |
--package-name |
✔ | – | Base package |
--build-tool |
✖ | maven | Currently only Maven |
--language |
✖ | java | Currently only Java |
--java |
✖ | 21 | Generated project Java version |
--boot |
✖ | 3.5 | Spring Boot version |
--layout |
✖ | standard | standard / hexagonal |
--guardrails |
✖ | basic | none / basic / strict |
--sample-code |
✖ | none | none / basic |
--dependency |
✖ | – | Controlled dependency alias |
--target-dir |
✖ | . | Output directory |
Dependencies are intentionally constrained.
web
data_jpa
validation
actuator
security
devtools
- Unknown aliases fail fast
- Repeatable:
--dependency web --dependency actuator
This is not a free-form generator.
Dependencies are:
- explicitly modeled
- version-aligned
- constrained by design
Architectural intent is decided at generation time.
greeting/
├── pom.xml
├── .gitignore
├── .mvn/
├── src/
│ ├── main/
│ └── test/
- buildable (
mvn verify) - testable
- architecture-aware
standard (layered)
controller/
service/
repository/
domain/
config/
hexagonal (ports & adapters)
domain/
application/
adapter/
bootstrap/
Guardrails create a fast, explicit feedback loop at build time — while context is still fresh.
They do not replace design decisions or reviews. They make architectural boundaries:
- visible
- testable
- impossible to ignore once violated
Use this as a practical starting point:
| Situation | Recommended mode |
|---|---|
| First-time adoption / onboarding | basic |
| Proof, demo, or strict architecture validation | strict |
| Exceptional / temporary cases only | none |
| Mode | Intent & Behavior |
|---|---|
basic |
Default (1.0.x GA). Balanced enforcement. Protects core boundaries without blocking adoption. |
strict |
Strong enforcement. Fails fast on boundary violations. Best for proof-grade validation and critical systems. |
none |
Explicit opt-out. Use only when you intentionally bypass architectural enforcement. |
Default is
basicto reduce friction.strictis recommended once boundaries must become a hard contract.
When guardrails are enabled:
mvn verify- Architecture rules are executed as generated ArchUnit tests
- Violations fail the build deterministically
- No runtime execution
- No implicit conventions
If the boundary is wrong, the build fails — immediately.
Codegen Blueprint intentionally does not generate runtime cross-cutting concerns:
- security
- logging
- observability
These are designed to be delivered later as:
- versioned capabilities
- shared libraries
- governed platform behavior
The generator focuses on structure and enforcement, not runtime duplication.
This repository validates both the generator and its output.
- The generator itself (domain, application, adapters)
- Real generated projects (standard + hexagonal)
mvn verifyThis runs:
- unit tests
- integration tests
- internal architecture rules
The pipeline ensures:
A generator build cannot be green if generated projects are broken.
| JDK | Purpose |
|---|---|
| Java 21 | Full GA validation (generator + generated projects) |
| Java 25 | Forward-compat smoke signal |
Additional checks:
- CodeQL (security)
- JaCoCo + Codecov (coverage)
Generated projects are not assumed to work. They are built and verified continuously.
Architecture is treated as a continuously validated contract — not a one-time setup.
Architecture should not only be defined — it should:
- execute
- remain observable
- stay verifiable months later
Blueprint Platform exists to make architecture:
- explicit
- testable
- evolvable at scale
This is achieved through:
- Architecture as a product (structure + guardrails)
- Capabilities delivered via libraries (not generated code)
- Consistency that survives team and system growth
The platform evolves in layers:
- Prove the contract — deterministic generation + guardrails
- Expand delivery surfaces — CLI → REST (same core)
- Introduce capabilities — shared, versioned behavior
- Expand stacks carefully — only after contract maturity
Structure first. Capabilities later. Expansion last.
Phase 1 — Contract & Proof (1.0.x GA)
- Deterministic generation
- Executable guardrails
- Verified generated output
Phase 2 — Delivery Surfaces
- REST adapter
- Interactive onboarding
Phase 3 — Platform Capabilities
- Security, observability, resilience via shared libraries
Phase 4 — Stack Expansion
- Gradle, Kotlin, additional ecosystems
| Without Blueprint | With Blueprint |
|---|---|
| Architecture drifts silently | Drift becomes visible at build time |
| Boilerplate spreads | Capabilities stay centralized |
| Onboarding is slow | Structure teaches implicitly |
| Standards depend on discipline | Standards are enforced by construction |
The platform evolves → projects stay clean → consistency holds.
Contributions are welcome, especially in:
- Guardrails and architecture improvements
- New profiles and adapters
- Documentation and examples
Start here:
- GitHub Discussions — design and ideas
- GitHub Issues — bugs and tasks
If you're using Codegen Blueprint in real projects, I'd genuinely like to hear:
- where it helped
- where it failed
- what felt missing
This directly shapes the platform direction.
Barış Saylı — Creator & Maintainer
- GitHub: https://github.com/bsayli
- LinkedIn: https://www.linkedin.com/in/bsayli
- Dev.to: https://dev.to/barissayli
- Medium: https://medium.com/@baris.sayli
MIT — see LICENSE.