Codegen Blueprint is for teams who care less about how fast a project starts
and more about how well its architecture survives over time.

• Your codebase started clean — then architecture drifted silently once things were “up and running”.
• A new developer (or a rushed change) put code in the wrong layer — and the only “rule” was tribal knowledge.
• A review turned into “is this the right boundary?” debates — because nothing was executable.

Codegen Blueprint exists for that exact moment.

• Java 21
• Maven 3.9+
• macOS or Linux
• Windows: use WSL2 (Ubuntu recommended) — the proof runner requires bash, unzip, and executable permissions (chmod)

Goal: see GREEN → RED → GREEN purely via build-time architecture guardrails.

No app startup. No runtime checks. Just deterministic feedback during mvn verify.

mvn -q clean package

cd docs/demo
chmod +x proof-runner.sh
CODEGEN_JAR=../../target/codegen-blueprint-1.0.0.jar ./proof-runner.sh

Windows note

Run the commands above inside WSL2. The proof runner is a Bash script and relies on standard Unix tooling.

• ✅ A project is generated with strict guardrails
• ✅ mvn verify passes (baseline)
• ❌ An intentional architectural boundary violation is introduced
• ❌ mvn verify fails deterministically with a generated ArchUnit rule
• ✅ The violation is reverted and the build returns to green

👉 Full walkthrough (screenshots + exact failures): Executable Architecture Proof

If you’re looking for a fast scaffold, use Spring Initializr. If you want architecture that stays observable and executable over time, start here.

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 turn architectural intent into executable, testable guardrails that provide fast, build-time feedback from day zero.

It doesn’t just generate a project — it generates a project whose architectural boundaries remain continuously verifiable on every build.

If long-term maintainability, domain purity, and early visibility when boundary drift begins matter to you, this repository is worth your time.

Every project generated by Codegen Blueprint 1.0.0 can include executable architectural guardrails — when enabled. Not documentation, not conventions — but generated, executable rules that make architectural drift visible immediately.

These guardrails provide early, unambiguous build-time feedback, turning architectural intent into a living contract rather than a set of guidelines.

When boundaries are crossed, the build does not silently succeed — it signals the drift clearly, while context is still fresh and easy to correct.

This is not about punishment or restriction.
It is about protecting architectural intent as the system evolves.

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 guardrails 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.

In Blueprint, Executable Architecture is the outcome,
guardrails are the mechanism that enforce it at build time,
and governance is how those rules evolve safely over time.

Governance is the discipline of evolving the guardrails contract (today implemented as generated ArchUnit rules) without silently changing what the build guarantees.

Guardrails here means explicit, non-negotiable architectural constraints that are evaluated automatically during mvn verify (not guidelines, not documentation).

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 address what happens after generation.

It treats architecture as a first-class, executable product that:

• Makes architectural boundaries visible — layered and/or Hexagonal (opt-in)
• Surfaces architectural drift early, before it becomes structural damage
• Keeps the domain insulated from frameworks by construction
• Aligns early decisions across teams — automatically and consistently

Executable Architecture — Delivered from day zero. Sustained over time.

🔗 Part of the Blueprint Platform → blueprint-platform

🤝 Contributing

Initializr-like convenience → Architecture-first evolution

Most generators generate code for cross-cutting concerns.
That approach does not scale.

Codegen Blueprint makes a deliberate distinction:

Not everything should be generated.
Cross-cutting concerns should be delivered as capabilities, not duplicated as code.

With Blueprint Platform:

• Architecture is generated once
• Runtime behavior is standardized via shared libraries / BOMs
• Capabilities are centrally versioned and opt-in
• Upgrades happen in one place, not across 50 microservices

This is why Blueprint is not a template collection.

It is architecture as an executable product —
where behavior is shared, aligned, and evolves safely over time.

🧩 Same simplicity — stronger 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 and test) with verified bootstrapping
• Framework-free domain core by construction
• Profile-driven architecture selection (standard / hexagonal)
• Optional architecture guardrails via generated ArchUnit tests
  (enabled with --guardrails 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 evaluated and verified at build time as part of the project output.

Codegen Blueprint turns architectural intent into generated, executable rules that are evaluated during the build.

With strict guardrails enabled:

• architectural boundaries are translated into ArchUnit rules
• violations fail mvn verify deterministically
• drift surfaces early, while context is still fresh

👉 See the full, reproducible walkthrough:
Executable Architecture Proof

Architecture isn’t only drawn — it executes here.

Hexagonal Architecture is not a stylistic preference in Codegen Blueprint.
It is a structural foundation that keeps architectural intent intact as systems evolve.

Generate once.
Evolve across frameworks, runtimes, and languages — without rewriting the core.

Spring Boot is the first delivery adapter — not the foundation.

📌 If you want to explore the architecture more deeply, these documents provide progressively stronger levels of clarity, guarantees, and collaboration context:

• 📜 Architecture Guardrails Rulebook
  A complete reference of the architecture rules the engine can generate,
  explaining what can be validated, how boundaries are interpreted,
  and when different rule sets apply.
  (Conceptual and technical reference — not a GA guarantee)
  → Architecture Guardrails Rulebook

• 🔒 Executable Architecture Contract — 1.0.0 GA
  The authoritative contract defining what Codegen Blueprint 1.0.0 GA guarantees
  at generation and build time — no assumptions, no ambiguity.
  (If it’s not listed here, it is intentionally not guaranteed in GA)
  → Executable Architecture Contract — 1.0.0 GA

• 🧭 How to Explore This Codebase (Hexagonal Guide)
  A practical guide to understanding ports, adapters, boundaries,
  and how profile-driven execution shapes the system.
  → Hexagonal Architecture Guide

• 🧠 Architecture Governance & AI Collaboration Protocol
  Describes how architectural decisions are made visible, reviewed,
  and kept consistent in AI-assisted and multi-contributor environments.
  → 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, observable, and scalable enterprise development.

Unlike traditional generators that simply scaffold code, Blueprint Platform focuses on making architectural intent explicit and testable, from the moment a project is generated.

It 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.)
• Make architectural boundaries visible and verifiable through generated structure and optional guardrails
  (e.g. hexagonal boundaries, naming consistency, test-ready layouts)

As the platform evolves, additional modules will complement codegen-blueprint with:

• Ready-to-use, behavior-driven shared 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.

The domain stays clean — ports define intent, adapters handle the outside world.

domain       // business logic only
application  // orchestrates ports
adapter     // inbound/outbound driven by use cases
bootstrap   // Spring wiring + config

• No Spring annotations inside the domain
• Hexagonal from day zero — when opted‑in
• Flexible to evolve with future profiles (CQRS, Layered…)

📌 main branch reflects the upcoming 1.0.0 GA.

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, explicit, and testable.

Architectural guardrail artifacts are generated as part of the output — not hard-wired into the engine.

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 checks (ArchUnit tests)
  (enabled via --guardrails basic|strict)
• README + project documentation
• Filesystem writer for artifact creation

The domain depends on nothing — adapters depend 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 \
  --guardrails strict \
  --sample-code basic \
  --dependency web \
  --target-dir /path/to/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.

--dependency is repeatable. Multiple aliases may be specified:

--dependency web --dependency actuator --dependency data_jpa

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 guardrails in Codegen Blueprint are opt-in and designed to create a fast, explicit feedback loop during development — while context is still fresh.

They do not replace design decisions or reviews; they make architectural boundaries visible, testable, and hard to miss.

Default vs Recommended

• Default guardrails mode is basic to lower adoption friction.
• strict is recommended when architectural boundaries must be enforced as a hard, build-time contract.
• Selecting none is an explicit opt-out and should be a conscious exception.

When enabled, guardrails are generated as executable ArchUnit tests and evaluated automatically during:

mvn verify

Violations fail the build deterministically, without starting the application and without relying on runtime checks.

• Codegen Blueprint does not generate cross-cutting behavior (security, logging, observability, etc.)
• Those concerns are intended to be delivered and governed via shared libraries in later Blueprint Platform phases
• Generated projects are intentionally minimal, stable, and architecture-first by design

Codegen Blueprint optimizes for long-term architectural integrity,
not short-term scaffolding volume or feature breadth.

This section documents what Codegen Blueprint produces today —
no demos, no aspirational features, 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 verify

This runs the full build lifecycle, including unit tests, integration tests, and architecture rules for the generator itself.

The GitHub Actions workflow executes a selective JDK matrix designed to balance:

• contract-level confidence (exhaustive checks on the GA target JDK)
• forward compatibility (early smoke detection on the next JDK)

Rather than duplicating all checks across all JDKs, the pipeline is intentionally asymmetric.

This reflects the core principle:

Architectural guarantees are validated exhaustively on the GA baseline, while newer JDKs are used only to detect early breakage — not to multiply CI cost.

On Java 21 only, the pipeline validates the generator itself:

• ✔ Unit tests
• ✔ Integration tests
• ✔ Internal architectural rules (ArchUnit)
• ✔ Coverage aggregation (JaCoCo)
• ✔ Coverage upload (Codecov)

This defines the authoritative GA contract for the Codegen Blueprint engine.

The generator codebase is not validated against Java 25. Java 21 is the sole supported and guaranteed runtime for the generator itself.

On Java 21, the CI generates and verifies six real projects:

• ✔ hexagonal + guardrails basic + sample basic
• ✔ standard + guardrails basic + sample basic
• ✔ hexagonal + guardrails strict + sample basic
• ✔ standard + guardrails strict + sample basic
• ✔ hexagonal + guardrails strict + no sample (canary)
• ✔ standard + guardrails strict + no sample (canary)

These combinations validate:

• layout differences (hexagonal vs standard)
• guardrails strength (basic vs strict)
• sample presence vs absence

Together, they define the 1.0.0 GA architectural contract surface.

On Java 25, the CI runs exactly one generated-project verification:

• ✔ hexagonal + guardrails strict + sample basic

This scenario is intentionally chosen because it:

• exercises the strictest guardrails
• includes real generated application code
• represents the highest architectural sensitivity

If this passes, confidence is high that:

• the generator output remains compatible with the next JDK
• no immediate forward-compatibility breakage has been introduced

Java 25 is not a supported runtime for the generator itself. It is used strictly as a forward-compatibility signal for generated output.

Checkout repository
→ Java 21:
     Build & test generator (mvn clean verify)
     Generate & verify 6 projects
       - hex  + basic  + sample
       - std  + basic  + sample
       - hex  + strict + sample
       - std  + strict + sample
       - hex  + strict + no-sample  (canary)
       - std  + strict + no-sample  (canary)
     Upload coverage reports
→ Java 25:
     Build generator JAR (tests skipped)
     Generate & verify 1 project
       - hex + strict + sample (forward smoke)

The pipeline includes:

• JaCoCo — unit + integration test coverage (Java 21 only)
• CodeQL — static security analysis
• Codecov — aggregated coverage reporting (Java 21 only)

Coverage reflects the generator engine. Generated projects are validated via successful build and guardrails execution, not via coverage metrics.

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:

• architectural layouts
• guardrails modes
• sample presence
• GA and next-generation JDKs

Codegen Blueprint treats architecture as a continuously verified contract — not a one-time scaffolding decision.

If the architecture drifts, the build tells you immediately.

Architecture should execute, not merely be drawn.
And it should remain observable and verifiable — even 6, 12, 24 months later.

Blueprint Platform =
🔹 Architecture-as-a-Product
🔹 Capabilities delivered via libraries and governance
🔹 Consistency that survives time and team changes

From Day Zero to Production — architecture remains intentional, testable, and continuously evaluated.

Blueprint evolves in intentional layers — to protect its core promise and avoid premature surface expansion.

Each phase builds on proven contracts and executable proof, not assumptions.

1. Strengthen the contract & proof
   (determinism, architecture guardrails, reproducible demos)
2. Add new delivery surfaces
   (CLI today → REST tomorrow) without changing the core engine
3. Introduce capabilities via libraries + governance
   (standardize behavior, don’t copy-paste it)
4. Expand profiles cautiously
   (Gradle/Kotlin/etc. increase surface area — scheduled after proof maturity)

📌 Ordering matters.
Capabilities and profiles are introduced only after architectural intent is proven executable.

This phase establishes the executable architectural foundation.

• Hexagonal / Standard (Layered) project generation (opt-in)
• Architecture guardrails via generated ArchUnit checks
  (none | basic | strict)
• CLI-driven, profile-based generation
  (Spring Boot · Maven · Java 21)
• Framework-free domain core by construction
• End-to-end buildable output evaluated in CI
  (generated projects verified with mvn verify)

📌 1.0.0 GA Objective → Zero-drift architectural foundations + executable proof

This phase expands access, not responsibility.

The core engine remains unchanged.

• REST inbound adapter
  (same architecture engine, new entry point)
• Interactive onboarding / configuration UX
  (still contract-first)
• Safer defaults and clearer intent capture
  (without widening the domain surface)

📌 Goal → expand accessibility without rewriting the core

This phase operates at the Blueprint Platform level,
not inside the generator itself.

Cross-cutting concerns are not generated as boilerplate code.
They are delivered as versioned capabilities, governed and upgraded consistently across services.

codegen-blueprint acts as the entry point and wiring engine, enabling teams to adopt, configure, and govern these capabilities — not to implement them.

Planned capability areas include:

• 🔐 Security capability
  (OAuth2 / Keycloak)
• 🔍 Observability capability
  (tracing, logs, metrics)
• 📡 Resilience capability
  (retries, timeouts, policies)
• 🏛️ Architecture policy packs
  (versioned guardrails rulesets applied consistently across services)
• 🧩 Optional enterprise service kits
  (API / Domain / Infra)
• 🔁 Generics-aware OpenAPI clients
  (separate Blueprint module)

📌 Goal → consistent behavior, architectural boundaries, and upgrades
in one place — not duplicated across services

Profiles accelerate adoption but increase surface area
(templates, tests, compatibility, support).

They are introduced only after architectural contracts and governance mature.

• Gradle support (profile)
• Kotlin support
  (higher surface area than Gradle)
• Quarkus and future stack profiles
• Visual UI — configure → generate → download
• Governance at scale
  (drift detection & remediation ideas)
• Platform telemetry for architecture health (opt-in)

📌 Goal → expand stacks after proof and contracts are stable

📌 Community-driven priorities:
🔗 Participate via GitHub Discussions

📌 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 →

• 🔗 GitHub Discussions
• 🔗 GitHub Issues

If this project saves your team time or headaches, please consider starring the repository — it genuinely helps with visibility and long‑term sustainability.

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