This document provides an end-to-end GREEN → RED → GREEN proof that Codegen Blueprint guardrails are generated and enforced at build time.
- If you want the fastest, deterministic proof: start with Fast Proof (Console-First).
- If you want human-readable evidence (screenshots + rule + failure output): continue with the High-Resolution Walkthrough.
- Fast Proof (Console-First)
- What this proves
- Proof Flow (High-Level)
- Proof Output (Persistent, Inspectable Artifacts)
- What each artifact means
- Why this matters
- Notes
- High-Resolution Walkthrough (Manual Proof)
- Part I — Hexagonal Architecture (Ports & Adapters)
- Part II — Standard (Layered) Architecture
- Final Proof Outcome
- Why this matters
🔎 Prefer visuals instead of running the build?
→ Jump to the High-Resolution Walkthrough (Manual Proof)
→ Back to Table of Contents
Execution precondition
This proof assumes you are running from a local clone of the
codegen-blueprintrepository and have already built the generator JAR. This section documents the verification protocol only. Building the generator itself is outside the scope of this walkthrough.
If you want to see the GREEN → RED → GREEN proof (strict architecture guardrails)
purely via the console — no screenshots, no explanations, just deterministic build output — run:
# From the repository root
cd docs/demo
chmod +x ./proof/proof-runner.sh
CODEGEN_JAR="$(ls -1 ../../target/codegen-blueprint-*.jar | head -n 1)" ./proof/proof-runner.shThe command exits with a non-zero code on any contract violation or unexpected behavior and prints a concise, step-by-step execution status to the console.
This single command demonstrates — end to end — that Codegen Blueprint can:
- generate a real project with strict architecture guardrails
- evaluate those guardrails at build time (
mvn verify) - fail the build deterministically when a boundary is violated
- return to green immediately once the violation is removed
- No application run (no
spring-boot:run, nojava -jar) - No runtime enforcement — guardrails are evaluated at build time
- No custom test framework beyond standard JUnit + ArchUnit
Architecture is evaluated by the build itself.
The script executes the following sequence for both Hexagonal and Standard (Layered) architectures:
Generate project
→ mvn verify (GREEN)
→ inject boundary violation
→ mvn verify (RED)
→ revert violation
→ mvn verify (GREEN)
This is performed for real generated code, not mocks, examples, or pre‑canned test fixtures.
In addition to console output, each run produces a durable proof bundle under the repository:
docs/demo/proof-output/
Each execution creates a timestamped run directory:
docs/demo/proof-output/
└── 20260104-180325/
├── logs/
│ ├── HEX_baseline.log
│ ├── HEX_violation.log
│ ├── HEX_fixed.log
│ ├── STD_baseline.log
│ ├── STD_schema_violation.log
│ ├── STD_schema_fixed.log
│ ├── STD_violation.log
│ └── STD_fixed.log
├── excerpts/
│ ├── HEX_violation.excerpt.txt
│ ├── STD_schema_violation.excerpt.txt
│ └── STD_violation.excerpt.txt
├── env.txt
└── proof-summary.txt
- Full, raw build output (
mvn verify) for each proof step - Contains complete ArchUnit failure messages and stack traces
- Suitable for deep inspection, CI attachments, or audits
- Focused slices extracted from logs
- Centered around ArchUnit / guardrails violations
- Designed for fast human review without scanning full logs
Captured execution context, including:
- OS and shell
- Java version
- Maven version
- Codegen Blueprint JAR path
- Timestamp of the run
This ensures the proof is reproducible and attributable.
A machine‑readable and human‑readable execution ledger:
- ordered proof steps
- PASS / EXPECTED_FAIL / UNEXPECTED_PASS statuses
- exact log and excerpt file references
- final proof result
This file is the primary evidence ledger that the proof executed as intended.
Console output proves something happened.
The proof-output directory proves:
- what happened
- where it failed
- why it failed
- that it recovered deterministically
This transforms guardrails from:
“trust me, it works”
into:
inspectable, replayable, build‑time evidence.
- Each run is append‑only; older runs are preserved unless manually removed
- For deeper inspection of generated projects, run with:
KEEP_WORK_DIR=1 ./proof-runner.shThis is not documentation. This is not a convention.
This is architecture enforced, evaluated, and proven at build time.
The remainder of this document is the high‑resolution proof — the human‑readable version of the console‑first proof:
-
screenshots of the generated structure
-
the exact minimal code change that introduces the violation (same as the script injects)
-
the precise generated ArchUnit rule that fails
-
the proof artifacts showing why it failed:
- console output
proof-output/logs and excerpts
This is intentional.
Executable architecture is only convincing when failure is observable and explainable — not just asserted.
This is not a diagram. This is not a convention. This is architecture evaluated at build time.
⚡ Want the fastest possible proof?
→ Jump to Fast Proof (Console-First)
→ Back to Table of Contents
This walkthrough proves a single, concrete claim:
When strict guardrails mode is enabled, architectural boundaries become executable rules that are evaluated during the build.
Specifically, it demonstrates that:
- Codegen Blueprint generates projects with explicit architectural models (Hexagonal or Standard / Layered).
- With
--guardrails strict, those models are translated into generated ArchUnit rules. - Any architectural violation causes
mvn verifyto fail immediately — with deterministic evidence.
- A build-time architecture proof
- A demonstration of guardrails rules produced by the generator
- Deterministic failures when architectural boundaries are violated
- A comparison across two different architectural models
- A runtime demo
- A Spring Boot feature showcase
- An ArchUnit tutorial
- A style guide
No manual app server is started.
The proof is driven by mvn verify
To reproduce this walkthrough, you need:
- Codegen Blueprint 1.0.0 (or later)
- A project generated via the CLI
- Architecture guardrails enabled in
strictmode - The generated guardrails rules left unchanged (no manual edits)
No runtime configuration or external infrastructure is required.
All validations happen at build time via mvn verify.
Every case follows the same proof protocol:
Generate project
→ mvn verify (GREEN)
→ inject boundary violation
→ mvn verify (RED)
→ revert violation
→ mvn verify (GREEN)
Each case uses three screenshots to make the proof observable:
- Baseline (GREEN) — clean dependency direction
- Violation (RED trigger) — the exact forbidden dependency introduced
- Failure (RED evidence) — the ArchUnit rule and failure output
You will end up with 3 cases × 3 images = 9 images.
This case matches the proof-runner failure:
- Test:
HexagonalStrictPortsIsolationTest.adapters_must_not_depend_on_application_implementation - Violation:
adapter..depends on an application implementation (application.usecase..) instead ofapplication.port..
Generate the project:
java -jar codegen-blueprint-1.0.0.jar \
--cli springboot \
--group-id io.github.blueprintplatform \
--artifact-id greeting-hex \
--name "Greeting" \
--description "Proof: hexagonal strict guardrails" \
--package-name io.github.blueprintplatform.greeting \
--layout hexagonal \
--guardrails strict \
--sample-code basic \
--dependency webStrict guardrails mode is enabled from the start. All architectural rules are generated from profiles, not handwritten.
Inbound adapters depend only on application ports.
Adapter → Port → Use Case → Domain
Case 1 — Baseline (GREEN): inbound adapter depends only on an application port
This snapshot shows the initial generated state of a hexagonal project with strict guardrails enabled. No architectural violation has been introduced at this point.
Introduce a deliberate violation by making the controller depend on an application implementation
(e.g., ...application.usecase.GetGreetingHandler) instead of the port.
This is illegal in strict hex guardrails:
Adapters may depend only on
application.port..— not application implementations.
Case 1 — Violation: inbound adapter depends on an application implementation (port bypass)
Run the exact same build again:
mvn verifyThe build fails deterministically.
Case 1 — Failure: generated ArchUnit rule detects adapter → application implementation dependency
Console evidence (proof-runner aligned):
Rule: no classes in ..adapter.. should depend on classes in application but not ports (outside '.port.')
Violation:
Field <...GreetingController.__archViolation> has type <...GetGreetingHandler>
Test:
HexagonalStrictPortsIsolationTest.adapters_must_not_depend_on_application_implementation
This case matches the proof-runner failure:
- Test:
StandardStrictLayerDependencyRulesTest.controllers_must_not_depend_on_repositories - Violation:
controller..depends onrepository..
Generate the project:
java -jar codegen-blueprint-1.0.0.jar \
--cli springboot \
--group-id io.github.blueprintplatform \
--artifact-id greeting-standard \
--name "Greeting" \
--description "Proof: standard strict guardrails" \
--package-name io.github.blueprintplatform.greeting \
--layout standard \
--guardrails strict \
--sample-code basic \
--dependency webIn the standard model, controllers must remain delivery-only and must not depend on repositories.
Case 2 — Baseline (GREEN): controller does not depend on repository
This snapshot represents the initial generated structure of a standard layered project. At this stage, no forbidden dependency exists.
Introduce a deliberate violation by injecting/calling a repository from a controller.
But architecturally it is illegal:
Controllers must not depend on repositories.
Case 2 — Violation: controller directly depends on repository (repository bypass)
Run:
mvn verifyThe build fails deterministically.
Case 2 — Failure: generated ArchUnit rule detects controller → repository dependency
Console evidence (proof-runner aligned):
Rule: no classes in ..controller.. should depend on classes in ..repository..
Violation:
Field <...GreetingController.__archViolation> has type <...LoggingGreetingAuditRepository>
Test:
StandardStrictLayerDependencyRulesTest.controllers_must_not_depend_on_repositories
This case matches your schema experiment:
- Test:
StandardPackageSchemaSanityTest.each_standard_bounded_context_must_contain_required_canonical_families - Violation: canonical family
controlleris missing because you renamed it (e.g.,controller→controllers).
A detected bounded context root must contain all required canonical families:
controllerservicedomain
Case 3 — Baseline (GREEN): standard schema contains controller/service/domain
This snapshot shows the unaltered, generated package schema before any canonical family is renamed or removed.
Introduce the deliberate schema violation by renaming the canonical package family:
...controller...→...controllers...
This is illegal because the guardrails schema sanity test requires the canonical families to exist.
Case 3 — Violation: canonical family 'controller' is missing due to rename
Run:
mvn verifyThe build fails deterministically.
Case 3 — Failure: schema sanity test fails (required canonical families missing)
Console evidence (aligned to your output):
STANDARD package schema integrity failure under base scope 'io.github.blueprintplatform.greeting.bp.sample
Required canonical families: [controller, service, domain]
Violations:
- context: io.github.blueprintplatform.greeting.bp.sample
present: controller ❌, service ✅, domain ✅
missing: controller
Test:
StandardPackageSchemaSanityTest.each_standard_bounded_context_must_contain_required_canonical_families
Different architectures. Different rules. Same outcome.
- Hexagonal validates ports & adapter isolation
- Standard validates layered dependency direction
- Standard also validates schema integrity (canonical families)
- All are evaluated automatically at build time
- All surface drift by breaking the build deterministically with explicit evidence
No documentation is consulted at evaluation time. No conventions are trusted.
This is the practical difference between:
- Documented architecture — can be ignored
- Executable architecture — cannot be ignored
With Codegen Blueprint:
- Architecture is generated once
- Guardrails are executable
- Drift is detected immediately
If a rule is violated, the build fails fast with explicit feedback.
No assumptions. No hidden conventions. No silent drift.
That is Architecture as a Product — observable, repeatable, and evaluated at build time.
This walkthrough focused on proving guardrails — not on showcasing generated artifacts.
If you want to see what actual projects generated by Codegen Blueprint look like, including:
- the exact
README.mdfiles written into generated projects - how architecture, guardrails, and sample code are explained to developers
- what a team receives after generation
see:
-
📘 Generated Project README Previews — real, generated README outputs shipped with projects
These READMEs are real generator output, not examples.
They represent the human-facing expression of the same architecture contract that is evaluated and verified throughout this walkthrough.