Codegen Blueprint — Architecture-First Project Generator 🚀

🚀 Executable Architecture Generator — Enforced by Design. Scalable by Default.
🔗 Part of the Blueprint Platform → https://github.com/blueprint-platform

---

🧭 Architecture as a Product

Modern teams rarely struggle to start a service. They struggle to keep architecture consistent as they scale.

Most project generators create a folder structure and disappear. Codegen Blueprint codifies and executes architectural intent:

• Enforces boundaries — layered and/or Hexagonal
• Prevents silent architecture drift
• Protects the domain from frameworks
• Standardizes early decisions across teams

Executable Architecture — Delivered from day zero

Who benefits → Engine capabilities → What teams get

---

🎯 Who is this for?

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

---

🥇 What makes it different?

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	❌	✔

🧩 Same simplicity — better long‑term alignment

---

📑 Table of Contents

• ⚡ What is Codegen Blueprint (Today)?
• 🧭 1.0.0 Release Scope
• 🧱 Architecture Overview
• 🔌 Inbound & Outbound Adapters
• 🔄 CLI Usage
• 🧪 Testing & CI
• 🚀 Vision & Roadmap
• 🤝 Contributing
• ⭐ Support
• 🛡 License

---

⚡ What is Codegen Blueprint (Today)?

A CLI-driven, profile‑based, architecture‑aware project generator.

📌 Current profile: springboot‑maven‑java

Spring Boot 3.5+ · Java 21 · Maven — production‑ready baseline

Outputs include:

• Clean source layout (main + test)
• Domain isolation & enforcement
• Maven configuration & wrappers
• Application configuration
• Optional sample Hexagonal service

---

🧱 Architecture Overview

Architecture isn’t only drawn — it executes here ⬇

📌 Want the architectural deep dive?

• 🔒 Executable Architecture Scope (1.0.0 GA)
  Defines what is strictly enforced today and output guarantees
  → docs/architecture/executable-architecture-scope.md

---

• 🧭 How to Explore This Codebase (Hexagonal Guide)
  Understand ports/adapters, profiles, boundaries
  → docs/guides/how-to-explore-hexagonal-architecture.md

🧩 Part of the Blueprint Platform

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
adapters     // inbound/outbound driven by use cases
bootstrap    // Spring wiring + config

CLI → Use case layer → Domain → Artifacts → Spring Boot project

Guarantees

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

---

🧭 1.0.0 Release Scope

📌 main branch reflects the upcoming 1.0.0 GA.

Included — GA Ready

Feature	Status
CLI project generation	✔
Optional Hexagonal structure	✔
Spring Boot 3.5+ + Java 21 + Maven	✔
Main & Test entrypoints	✔
Build + config artifacts	✔
Optional greeting sample	✔
MIT License	✔

---

🔌 Inbound & Outbound Adapters

Adapters drive interactions in and out of the core domain — keeping domain logic isolated and testable.

Inbound (Delivery) — How requests enter

Adapter	Status	Description
CLI	✔ GA Ready	Primary driver to generate services via command-line
REST	🚧 Planned	Future interactive generation + developer onboarding UX

Outbound (Artifacts) — What the engine produces

Everything required to build → run → extend a real service:

• Maven POM + Wrapper
• Main & Test source structure
• Domain + Application + Adapter layout
• Application configuration (YAML)
• Optional Hexagonal sample slice
• README + project docs
• Filesystem writer for artifact creation

The domain depends on nothing — adapters depend on the domain.

---

🔄 CLI Usage

java -jar codegen-blueprint-1.0.0.jar \
  --cli \
  springboot \
  --group-id io.github.blueprintplatform.samples \
  --artifact-id greeting-service \
  --name "Greeting Service" \
  --package-name io.github.blueprintplatform.samples.greeting \
  --layout hexagonal \
  --sample-code basic \
  --dependency web \
  --dependency data_jpa \
  --target-dir /path/to/output

Output (simplified)

greeting-service/
 ├── pom.xml
 ├── src/main/java/.../GreetingServiceApplication.java
 ├── src/test/java/.../GreetingServiceApplicationTests.java
 ├── src/main/resources/application.yml
 └── .gitignore

Hexagonal with optional sample = ready‑to‑run REST service

---

🧪 Testing & CI

mvn verify

Includes:

• ✔ Unit + integration tests
• ✔ JaCoCo coverage
• ✔ CodeQL security analysis
• ✔ Codecov reporting

---

🚀 Vision & Roadmap

Architecture should execute, not merely be drawn.
And it should stay enforced — even 6, 12, 24 months later.

🌟 The Vision

Blueprint Platform =
🔹 Architecture-as-a-Product
🔹 Reusable Behavior Libraries
🔹 Enforced Consistency Across Teams

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

---

🎯 Roadmap

🔹 Phase 1 — Architecture-First Generation (Today)

• Hexagonal / Layered architecture enforcement
• 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

---

🔹 Phase 2 — Reusable Enterprise Behavior (In Progress)

• 🔐 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

---

🔹 Phase 3 — Ecosystem Expansion (Roadmap)

• 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: https://github.com/blueprint-platform/codegen-blueprint/discussions

---

🧩 Why this matters

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.

🤝 Contributing

We welcome:

• Architecture improvements
• Stack profiles & adapters
• Template & documentation enhancements

Start here → Discussions: https://github.com/blueprint-platform/codegen-blueprint/discussions

Issues: https://github.com/blueprint-platform/codegen-blueprint/issues

---

⭐ Support

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

---

🛡 License

MIT — free for commercial and personal use. See: LICENSE