Skip to content

Commit bc70588

Browse files
bsaylibsayli
committed
docs: refine README wording for clarity and GA contract alignment
1 parent 7666315 commit bc70588

1 file changed

Lines changed: 50 additions & 35 deletions

File tree

‎README.md‎

Lines changed: 50 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,11 @@
2424
* A new developer (or a rushed change) shipped code into the **wrong layer** — and the only “rule” was tribal knowledge.
2525
* Reviews turned into **“is this the right boundary?”** debates — because nothing was **executable**.
2626

27-
Codegen Blueprint exists for that exact moment: when architecture needs to become **observable**, not aspirational.
27+
Codegen Blueprint exists for that exact moment:
28+
when architecture needs to become **observable and testable** — not aspirational.
2829

29-
> This separation keeps the core engine isolated from technology choices
30-
> and enables future stack expansion **without changing the engine’s architectural contract**.
30+
It is designed for teams who care about **architectural integrity over time**,
31+
and want boundaries that remain **visible and verifiable** as systems, teams, and pressure evolve.
3132

3233
---
3334

@@ -97,7 +98,7 @@ Full walkthrough (screenshots + exact failures):
9798
* 🧾 [Project history (short)](#-project-history-short)
9899
* 🧭 [Architecture as an executable product](#-architecture-as-an-executable-product)
99100
* 🎯 [Who is this for?](#-who-is-this-for)
100-
* 🥇 [What makes it different?](#-what-makes-it-different)
101+
* 🥇 [What makes Codegen Blueprint different?](#-what-makes-codegen-blueprint-different)
101102
* 🧩 [Generate vs deliver capabilities (cross-cutting concerns)](#-generate-vs-deliver-capabilities-cross-cutting-concerns)
102103
* 🧩 [Part of the Blueprint Platform](#-part-of-the-blueprint-platform)
103104
* 🧭 [1.0.0 Release Scope](#-100-release-scope)
@@ -126,7 +127,7 @@ It turns architectural intent into **executable guardrails** with **fast, determ
126127

127128
### 🚫 Not the best fit
128129

129-
* You only want a quick starter template (use Spring Initializr).
130+
* You only need a quick starter template without build-time guardrails.
130131
* You expect cross‑cutting runtime behavior (security/logging/etc.) to be generated as boilerplate.
131132

132133
---
@@ -155,8 +156,6 @@ A **CLI-driven**, **profile-based**, **architecture-aware** project generator th
155156
📌 Current GA profile: **springboot-maven-java**
156157

157158
> Generated projects: Spring Boot **3.5 (default)** or **3.4** · Java **21 (GA baseline)** · Maven **3.9+**
158-
>
159-
> Generated output may target newer JDKs (e.g., **Java 25**), but that is **not** part of the GA contract.
160159
161160
It delivers:
162161

@@ -174,18 +173,23 @@ It delivers:
174173
Architecture isn’t only drawn — it **executes** here.
175174

176175
Codegen Blueprint (the generator itself) is built with **Hexagonal Architecture** — not as a stylistic preference,
177-
but as a **structural foundation** that keeps the core stable as delivery surfaces evolve.
176+
but as a **structural foundation** that keeps the core engine isolated from technology choices
177+
and stable as delivery surfaces evolve.
178178

179179
> Generate once.
180180
> Evolve across frameworks, runtimes, and languages — **without rewriting the core**.
181181
182-
> This section covers the generator’s architecture (the engine). For generated project layouts (`standard` / `hexagonal`), see the CLI section.
182+
This separation allows the engine to preserve its architectural contract
183+
while enabling future stack expansion through replaceable adapters.
184+
185+
> This section covers the generator’s architecture (the engine itself).
186+
> For generated project layouts (`standard` / `hexagonal`), see the CLI documentation.
183187
184-
Spring Boot is the first delivery adapter — not the foundation.
188+
Spring Boot is the **first delivery adapter** — not the foundation.
185189

186190
### Architecture docs (from capability → GA contract → guide → collaboration)
187191

188-
* 📜 **Architecture Guardrails Rulebook** — full rule surface the engine can generate *(capability reference; not a GA guarantee)*
192+
* 📜 **Architecture Guardrails Rulebook** — full guardrails semantics and rule vocabulary *(descriptive reference; not a GA guarantee)*
189193

190194
→ [Architecture Guardrails Rulebook](docs/architecture/architecture-guardrails-rulebook.md)
191195

@@ -269,15 +273,26 @@ Codegen Blueprint targets what happens **after** generation:
269273

270274
---
271275

272-
## 🥇 What makes it different?
276+
## 🥇 What makes Codegen Blueprint different?
277+
278+
Codegen Blueprint does **not** compete on scaffolding speed, template volume,
279+
or framework convenience.
280+
281+
Its focus is **architectural continuity** —
282+
making architectural boundaries **explicit, observable, and verifiable**
283+
as systems evolve over time.
284+
285+
| Focus area | Traditional project generators | Codegen Blueprint |
286+
| ---------------------------- | ------------------------------ | ----------------- |
287+
| Primary goal | Fast project start | Architectural continuity |
288+
| Architecture boundaries | Implicit or documented | **Executable & verified** |
289+
| Drift detection | Manual (reviews, discipline) | **Build-time feedback** |
290+
| Domain isolation | Optional / framework-led | **By construction** |
291+
| Long-term evolution strategy | Out of scope | **First-class concern** |
273292

274-
| Capability focus | Spring Initializr / JHipster | Codegen Blueprint |
275-
| ------------------------ | ---------------------------- | ----------------- |
276-
| Folder scaffolding | ✔ | ✔ |
277-
| Architecture guardrails | ⚠️ | **✔** |
278-
| Framework-free domain | ❌ | **✔** |
279-
| Profile-driven evolution | ⚠️ | **✔** |
280-
| Anti-drift roadmap | ❌ | **✔** |
293+
Codegen Blueprint exists for teams who have already felt the cost of
294+
silent architecture drift — and want boundaries that remain
295+
**visible and testable**, not dependent on tribal knowledge or reviews.
281296

282297
---
283298

@@ -403,22 +418,22 @@ java -jar codegen-blueprint-1.0.0.jar \
403418

404419
### Available Options (`springboot`)
405420

406-
| Option | Required | Default | Description |
407-
| ---------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------- |
408-
| `--group-id` | ✔ | – | Maven `groupId`. |
409-
| `--artifact-id` | ✔ | – | Maven `artifactId` (also becomes the output folder name). |
410-
| `--name` | ✔ | – | Human-readable project name. |
411-
| `--description` | ✔ | – | Project description (**min 10 characters**). |
412-
| `--package-name` | ✔ | – | Base Java package name. |
413-
| `--build-tool` | ✖ | `maven` | Build tool (**currently only** `maven`). |
414-
| `--language` | ✖ | `java` | Programming language (**currently only** `java`). |
415-
| `--java` | ✖ | `21` | **Generated project** Java version: `21`, `25` — **GA target: 21**. |
416-
| `--boot` | ✖ | `3.5` | **Generated project** Spring Boot version: `3.4`, `3.5` — **GA baseline: 3.5** (3.4 supported). |
417-
| `--layout` | ✖ | `standard` | Project layout: `standard` or `hexagonal`. |
418-
| `--guardrails` | ✖ | `basic` | Guardrails mode: `none`, `basic`, `strict` (**default: basic; opt-out: none**). |
419-
| `--sample-code` | ✖ | `none` | Sample code level: `none`, `basic`. |
420-
| `--dependency` | ✖ | – | Dependency alias (repeatable; controlled set). |
421-
| `--target-dir` | ✖ | `.` | Target directory for generated output. |
421+
| Option | Required | Default | Description |
422+
| ---------------- | -------- | ---------- |---------------------------------------------------------------------------------|
423+
| `--group-id` | ✔ | – | Maven `groupId`. |
424+
| `--artifact-id` | ✔ | – | Maven `artifactId` (also becomes the output folder name). |
425+
| `--name` | ✔ | – | Human-readable project name. |
426+
| `--description` | ✔ | – | Project description (**min 10 characters**). |
427+
| `--package-name` | ✔ | – | Base Java package name. |
428+
| `--build-tool` | ✖ | `maven` | Build tool (**currently only** `maven`). |
429+
| `--language` | ✖ | `java` | Programming language (**currently only** `java`). |
430+
| `--java` | ✖ | `21` | **Generated project** Java version: `21`, `25` — **GA target: 21**. |
431+
| `--boot` | ✖ | `3.5` | **Generated project** Spring Boot version: `3.4`, `3.5` — (GA baseline: `3.5`) |
432+
| `--layout` | ✖ | `standard` | Project layout: `standard` or `hexagonal`. |
433+
| `--guardrails` | ✖ | `basic` | Guardrails mode: `none`, `basic`, `strict` (**default: basic; opt-out: none**). |
434+
| `--sample-code` | ✖ | `none` | Sample code level: `none`, `basic`. |
435+
| `--dependency` | ✖ | – | Dependency alias (repeatable; controlled set). |
436+
| `--target-dir` | ✖ | `.` | Target directory for generated output. |
422437

423438
---
424439

0 commit comments

Comments
 (0)