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) 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.
- Java 21
- Maven 3.9+
- macOS / Linux / WSL (the proof runner is a shell script)
Goal: see GREEN → RED → GREEN using build-time architecture guardrails (strict mode).
No app startup required. Guardrails run during
mvn verifyand fail the build deterministically on boundary violations.
git clone https://github.com/blueprint-platform/codegen-blueprint.git && cd codegen-blueprintmvn -q clean packagecd docs/demo
chmod +x ./proof/proof-runner.sh
CODEGEN_JAR="$(ls -1 ../../target/codegen-blueprint-*.jar | head -n 1)" ./proof/proof-runner.sh- ✅ A project is generated with strict guardrails
- ✅
mvn verifypasses (baseline) - ❌ An intentional architectural boundary violation is introduced
- ❌
mvn verifyfails deterministically with a generated ArchUnit rule - ✅ The violation is reverted and the build returns to green
Executable evidence bundle (screenshots, exact failures, and proof artifacts):
👉 Executable Architecture Proof
- 🤔 Should you clone this repository?
- 🛡 1.0.0 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.0 Release Scope
- 🔌 Inbound & Outbound Adapters
- 🔄 CLI Usage (Spring Boot)
- 🧪 Testing & CI (This Repository)
- 🚀 Vision & Roadmap
- 🤝 Contributing
- ⭐ Support
- 🛡 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.
Every project generated by Codegen Blueprint 1.0.0 includes executable architecture guardrails — enabled by default (basic), with explicit opt-out (--guardrails none).
- Guardrails are generated ArchUnit rules evaluated at build time (
mvn verify). - Boundary violations fail the build deterministically, while context is still fresh.
- Guardrails are mode-based (
basic/strict): selecting the mode is explicit; disabling is explicit. - The goal is not restriction — it’s protecting architectural intent as the system evolves.
GA contract source of truth
The guarantee surface is defined exclusively by the
Executable Architecture Contract — 1.0.0 GA.
If it’s not listed there, it’s not guaranteed.
A CLI-driven, profile-based, architecture-aware project generator that produces buildable output with configurable architecture guardrails.
📌 Current GA profile: springboot-maven-java
Generated projects: Spring Boot 3.5 (default) or 3.4 · Java 21 (GA baseline) · Maven 3.9+
It delivers:
- Deterministic, single-module project generation
- Clean
main/testsource layout with verified bootstrapping - Layout options: standard (layered) / hexagonal (ports & adapters)
- Guardrails via generated ArchUnit tests (default:
--guardrails basic; options:none|basic|strict) - Maven wrapper + build baseline +
application.yml - Optional basic sample code (standard + hexagonal)
This diagram summarizes who benefits, what the engine provides, and what teams get in return.
| Role | What it unlocks |
|---|---|
| Platform Engineering | Org-wide standards made explicit and verifiable |
| Lead Architects | Guardrails contracts made observable |
| Developers | Less debate, faster feedback loops |
| New Team Members | Architecture learning curve reduced by structure |
📘 Canonical platform specification
The canonical definition of Architecture as a Product is defined at the platform level.
→ Architecture as a Product — Platform Specification
This repository provides executable proof of that specification, with the Spring Boot · Maven · Java profile as its current implementation.
Architecture here is not merely described — it is generated, evaluated, and verified.
Codegen Blueprint (the generator itself) is built using Hexagonal Architecture — not as a stylistic choice, but as a structural guarantee for long-term evolution.
The engine is intentionally designed to:
- remain independent of frameworks and build tools,
- stay stable as delivery surfaces evolve (CLI today, REST tomorrow),
- evolve without rewriting the core.
Generate once.
Evolve across frameworks, runtimes, and languages — without rewriting the core.
At the center of the engine, use cases and domain logic define the contract. All interaction with the outside world happens through explicit ports, implemented by replaceable adapters at the edges.
This ensures a clear separation of responsibilities: the core decides what happens, adapters decide how it is triggered or materialized.
Spring Boot is the first delivery adapter, not the foundation. The engine itself remains framework-agnostic by construction.
This section describes the generator architecture (engine).
Generated project layouts (standard/hexagonal) are explained in the CLI Usage (Spring Boot) section below.
(GA contract → rulebook → guide → collaboration)
-
🔒 Executable Architecture Contract — 1.0.0 GA — source of truth for all GA guarantees
Executable Architecture Contract — 1.0.0 GA -
📜 Architecture Guardrails Rulebook — guardrails semantics and rule vocabulary (not a GA guarantee)
Architecture Guardrails Rulebook -
🧭 Hexagonal Architecture Guide — ports, adapters, and boundary navigation
Hexagonal Architecture Guide -
🧠 Architecture Governance & AI Protocol — decision-making & AI collaboration rules
Architecture Governance & AI Protocol
Codegen Blueprint does not optimize for scaffolding speed, template count, or framework convenience.
It optimizes for architectural continuity — keeping boundaries explicit, observable, and verifiable as systems, teams, and pressure evolve.
The focus is after generation:
- boundaries remain explicit
- drift becomes observable at build time (
mvn verify) - the domain stays framework-free by construction
So early architectural decisions remain enforceable — not aspirational.
| Focus area | Traditional project generators | Codegen Blueprint |
|---|---|---|
| Primary goal | Fast project start | Architectural continuity |
| Architecture boundaries | Implicit or documented | Executable & verified |
| Drift detection | Manual (reviews, discipline) | Build-time feedback |
| Domain isolation | Optional / framework-led | By construction |
| Long-term evolution strategy | Out of scope | First-class concern |
Boundaries stay enforced by the build — not by memory or review culture.
It doesn’t try to make starting easy — it makes staying correct unavoidable.
A reproducible walkthrough that demonstrates GREEN → RED → GREEN purely through build‑time guardrails:
👉 Executable Architecture Proof
Versions represent architectural and compatibility contracts, not feature counts.
- Breaking changes are introduced only in major versions.
- Determinism, structure, and guardrails guarantees are intentional and protected starting from 1.0.0 GA.
Codegen Blueprint is intentionally constrained by design. Some things are out of scope — not by accident, but to protect architectural integrity.
Most generators generate code for cross-cutting concerns. That approach does not scale.
Codegen Blueprint makes a deliberate distinction:
| Approach | What happens | Long-term effect |
|---|---|---|
| Generate code | Copies security/logging/error handling into each service | ❌ Drift, copy-paste, painful upgrades |
| Deliver as capabilities | Centralized, versioned, opt-in behavior via shared libraries | ✔ Consistency, easier upgrades, alignment |
Not everything should be generated. Cross-cutting concerns should be delivered as capabilities, not duplicated as code.
codegen-blueprint is the first foundational module of the Blueprint Platform — an ecosystem designed to keep architecture explicit, testable, and evolvable.
🔗 Learn more at the Blueprint Platform GitHub organization
📌 The
mainbranch reflects the 1.0.0 GA line.
The following guarantees define the 1.0.0 GA contract surface.
| Guarantee | Description |
|---|---|
| Deterministic project generation | The same inputs produce the same structure and files. |
| CLI-driven generation | The CLI is the source of truth—no UI-only behavior or hidden defaults. |
| Layout options | Standard (layered) and Hexagonal (ports & adapters) layouts can be generated on demand. |
| Architecture guardrails | Generated ArchUnit rules (default: basic; opt-out: none; strict supported). |
| Test-ready output | Generated projects are designed to pass mvn verify on the GA baseline. |
| Profile-driven stack selection | Technology choices are expressed via profiles (not ad-hoc flags). |
| Framework-free domain core | No Spring dependencies or annotations in the domain. |
GA target
The 1.0.0 GA profile targets Spring Boot 3.4 / 3.5, Java 21, and Maven. The generator runtime baseline is Java 21. Generated output may target newer JDKs (e.g., Java 25), but that is not part of the GA contract.
Adapters drive interactions into and out of the core—keeping domain logic isolated, explicit, and testable.
| Adapter | Status | Description |
|---|---|---|
| CLI | ✔ GA Ready | Primary driver to generate projects via command line. |
| REST | 🚧 Planned | Future interactive generation + onboarding UX. |
Architecture guardrails are generated as output artifacts—not hard-wired into the engine.
The generator produces everything required to build → run → extend a real service:
-
Maven POM + Maven Wrapper
-
Main & test source structure
-
Domain + Application + Adapter layout
-
Application configuration (
application.yml) -
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 that materializes generated artifacts
The core remains clean: domain depends on nothing; adapters depend on the domain.
This section documents the current CLI contract for Codegen Blueprint 1.0.0. It reflects the actual generated output—no aspirational flags or placeholder examples.
How to run the CLI
Codegen Blueprint is a Spring Boot executable JAR. The CLI is activated via
--cli, then the subcommand (e.g.springboot) and its options follow.Example pattern:
java -jar <jar> --cli springboot <options...>
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/outputTip: If you built locally, the typical path is:
java -jar target/codegen-blueprint-1.0.0.jar --cli springboot ...
| Option | Required | Default | Description |
|---|---|---|---|
--group-id |
✔ | – | Maven groupId. |
--artifact-id |
✔ | – | Maven artifactId (also becomes the output folder name). |
--name |
✔ | – | Human-readable project name. |
--description |
✔ | – | Project description (min 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 |
Generated project Java version: 21, 25 — GA target: 21. |
--boot |
✖ | 3.5 |
Generated project Spring Boot version: 3.4, 3.5 — (GA baseline: 3.5) |
--layout |
✖ | standard |
Project layout: standard or hexagonal. |
--guardrails |
✖ | basic |
Guardrails mode: none, basic, strict (default: basic; opt-out: none). |
--sample-code |
✖ | none |
Sample code level: none, basic. |
--dependency |
✖ | – | Dependency alias (repeatable; controlled set). |
--target-dir |
✖ | . |
Target directory for generated output. |
Dependency aliases are intentionally constrained and mapped internally to well-known Spring Boot starters. This prevents uncontrolled dependency sprawl and keeps generated projects aligned with the architecture-first intent.
Available aliases in 1.0.0:
web
data_jpa
validation
actuator
security
devtools
- Unknown aliases fail fast during CLI execution.
--dependencyis repeatable, e.g.:
--dependency web --dependency actuator --dependency data_jpaCodegen 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/...
The output is:
- buildable (
mvn verify) - testable (unit + integration baseline)
- architecture-aware by construction
standard layout (layered packages)
controller/
service/
repository/
domain/
config/
hexagonal layout (ports & adapters)
domain/
application/
adapter/
bootstrap/
Guardrails are opt-in and create a fast, explicit feedback loop while context is still fresh. They don’t replace design decisions or reviews—they make boundaries visible, testable, and hard to miss.
| Mode | Intent & Behavior |
|---|---|
basic |
Default (1.0.0 GA). Designed for adoption. Enforces core boundaries without being overly restrictive. |
strict |
Recommended for proof-grade, fail-fast validation. Enforces stricter dependency and boundary rules. |
none |
Explicit opt-out only. Intended for special cases; not recommended for regular use. |
Default vs recommended
- Default is
basicto reduce adoption friction.strictis recommended when boundaries must be enforced as a hard, build-time contract.noneshould be a conscious exception.
When enabled, guardrails are generated as executable ArchUnit tests and evaluated during:
mvn verifyViolations fail the build deterministically, without application startup and without runtime checks.
- Codegen Blueprint does not generate cross-cutting runtime 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.
This section 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 verifyRuns unit + integration tests and internal architecture rules for the generator.
GitHub Actions validates the GA baseline exhaustively, and uses a single forward-compat smoke to detect early breakage.
| JDK | Purpose | What runs |
|---|---|---|
| Java 21 | GA baseline (supported) | Full generator verification + generated-project verification matrix |
| Java 25 | Forward-compat signal | One generated-project smoke scenario (strict guardrails + sample) |
Notes:
- The generator runtime baseline is Java 21.
- Generated projects are validated by actually building them (
mvn verify) in CI.
- CodeQL — security/static analysis
- JaCoCo + Codecov — coverage for the generator codebase (Java 21)
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 remain observable and verifiable 6, 12, 24 months later.
Blueprint Platform exists to keep architecture explicit, testable, and evolvable across teams and time.
- Architecture as a product (structure + guardrails as an executable outcome)
- Capabilities delivered via libraries + governance (not copied boilerplate)
- Consistency that survives scale (onboarding, upgrades, standards)
From Day Zero to Production — architecture stays intentional, testable, and continuously evaluated.
This roadmap expresses direction and intent, not contractual guarantees.
Blueprint evolves in intentional layers to protect its core promise:
- Prove the contract (determinism, guardrails, reproducible proof)
- Add new delivery surfaces (CLI → REST) without changing the core engine
- Deliver cross-cutting capabilities via versioned libraries + governance (no boilerplate generation)
- Expand stacks cautiously only after the proof and contracts mature
📌 Ordering matters: capabilities and stack expansion come after the architecture contract is proven executable.
- Deterministic generation + executable guardrails (
none | basic | strict) - Standard / Hexagonal layouts (opt-in) + framework-free domain
- CI validates real generated projects (
mvn verify)
- REST inbound adapter + interactive onboarding/config UX
(same engine, new entry point — domain surface unchanged)
- Versioned capabilities (libraries/BOMs + governance): security, observability, resilience, policy packs
- OpenAPI clients as a separate Blueprint module
- Gradle, Kotlin, additional frameworks/stacks, broader governance ideas
(introduced only after contracts and proof maturity)
Community-driven priorities happen in Discussions:
🔗 Participate via GitHub Discussions
For detailed scope and guarantees, see the Executable Architecture Contract — 1.0.0 GA and the Release Discipline policy docs.
| Without Blueprint | With Blueprint |
|---|---|
| Architecture drifts silently | Guardrails make drift visible (build-time) |
| Boilerplate spreads across services | Capabilities delivered via versioned libraries |
| Onboarding takes weeks | Day-zero structure + executable contracts |
| Standards depend on discipline | Standards become observable by construction |
The platform evolves → projects stay clean → org-wide consistency holds.
Blueprint Platform isn’t “just code generation” — it’s strategic architectural continuity.
Contributions are welcome — especially around:
- Architecture and guardrails improvements
- Profile expansion (adapters, stacks)
- Templates and documentation
Start here:
- 🔗 GitHub Discussions — ideas, proposals, design review
- 🔗 GitHub Issues — bugs, actionable tasks
Community feedback and real-world usage help shape the Blueprint Platform’s direction.
If you’re using codegen-blueprint, sharing experiences or participating in discussions is the most valuable form of support.
Barış Saylı — Creator & Maintainer
- GitHub: https://github.com/bsayli
- LinkedIn: https://www.linkedin.com/in/bsayli
- Medium: https://medium.com/@baris.sayli
MIT — see LICENSE.
