From b4e219f4701a23b98a2daf14f185c3b493ab2bfe Mon Sep 17 00:00:00 2001 From: Daniel Imbert Date: Mon, 2 Feb 2026 19:50:03 -0600 Subject: [PATCH] Refresh README documentation --- README.md | 159 +++++++++++++++++++----------------------------------- 1 file changed, 56 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 6c04fd8..fba9c86 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,27 @@ # AppMakeup โ€” Core V4 (Closed) -## ๐Ÿš€ What is AppMakeup? +**AppMakeup** is a Kotlin Multiplatform desktop application that lets teams **model architecture visually** and **generate deterministic project structures and code** aligned with Clean Architecture. -**AppMakeup** is a desktop application built with **Kotlin Multiplatform** and **Compose Desktop** that allows you to **model application architecture visually** and **generate deterministic project structures and code** following Clean Architecture principles. +> **Not an AI tool.** AppMakeup does not infer business logic or make architectural decisions. +> It is a **deterministic architecture compiler**: you declare the architecture, AppMakeup materializes it safely. -AppMakeup is **not an AI tool**. - -It does **not**: -- infer business logic -- guess architecture decisions -- generate behavior automatically +--- -Instead, AppMakeup is a **deterministic architecture compiler**. +## โœจ Highlights -> You declare architecture. AppMakeup materializes it safely. +- Architecture-first workflow +- Deterministic generation (no magic) +- Strict validation before export +- Dry-run previews of the generation plan and files +- Clean Architecture separation (Domain / Application / Infrastructure / Presentation) --- -## ๐Ÿง  Core Philosophy (Unchanged) +## ๐Ÿง  Core Philosophy - Architecture first, code second - Structure before implementation - Predictability over magic -- Deterministic generation - Explicit contracts and layers - No filesystem access from UI - No domain logic in presentation @@ -30,110 +29,72 @@ Instead, AppMakeup is a **deterministic architecture compiler**. --- -## โœ… Current State โ€” **Core V4 (Closed & Stable)** +## โœ… Current State โ€” Core V4 (Closed & Stable) -Core V4 is now **feature-complete and closed**. +Core V4 is **feature-complete and closed**. +It delivers the **first full generation-capable core**, with: -It represents the **first full generation-capable core**, where AppMakeup moves from *structure modeling* to **real, validated code generation** while preserving strict architectural guarantees. - -Core V4 builds on Core V2 and Core V3 concepts but introduces a **generation pipeline**, **planning stage**, and **dry-run previews**. +- A deterministic pipeline +- A planning stage +- True dry-run previews --- -## โœจ What Core V4 Includes - -### ๐Ÿงญ Project Lifecycle +## ๐Ÿงญ What Core V4 Includes +### Project Lifecycle - Create new projects - Open existing projects - Persist and validate projects on disk - Versioned project format - Recent projects registry ---- - -### ๐Ÿงฉ Architecture Modeling - -- Features -- Domain entities -- Entity properties +### Architecture Modeling +- Features and layers +- Domain entities and properties - Identifier enforcement -- Layer selection per feature -- Validation before generation - -Invalid states are **prevented at editor level**. +- Validation before generation + *Invalid states are prevented at the editor level.* --- -### ๐Ÿงช Generation Pipeline (Core V4) +## ๐Ÿงช Generation Pipeline (5 Stages) -Core V4 introduces a **5-stage deterministic pipeline**: - -1. **ValidationStage** - - Entity rules - - Feature rules - - Architecture constraints - -2. **PlanningStage** - - Decides what layers will be generated - - Domain / Data / Repositories / Mappers - - Fully testable and previewable - -3. **GenerationStage** - - Layer generators - - Templates - - No filesystem access - -4. **WritingStage** - - Real filesystem writer - - Dry-run writer (preview mode) - -5. **ReportingStage** - - CLI / Table / JSON output +1. **ValidationStage** + Entity rules ยท Feature rules ยท Architecture constraints +2. **PlanningStage** + Determines which layers apply (Domain / Data / Repos / Mappers) +3. **GenerationStage** + Layer generators + templates (no filesystem access) +4. **WritingStage** + Real writer + dry-run writer +5. **ReportingStage** + CLI / Table / JSON output --- -### ๐Ÿงช Dry-Run Mode - -Core V4 supports **true dry-run execution**: +## ๐Ÿ”Ž Preview & Dry-Run -- No files are written -- Generated artifacts are collected -- Output paths are simulated +### Dry-Run Mode +- No files written +- Artifacts collected in memory +- Output paths simulated - Safe to run repeatedly -Used for: -- UI preview -- Tests -- Validation before export - ---- - -### ๐Ÿงฉ Generation Plan Preview (UI) - -Before exporting, users can see: - +### Generation Plan Preview (UI) - Which layers will be generated - Whether repositories/mappers apply - Why a layer is skipped -- Validation errors per feature - -This makes generation **explainable**, not magical. - ---- +- Per-feature validation errors -### ๐Ÿงพ Files Preview (Dry-Run Visual) - -The UI shows: +### Files Preview - Exact files that would be generated - Relative paths - Per-feature grouping -Nothing is written unless explicitly exported. - --- -### ๐Ÿ—๏ธ Internal Architecture (Clean Architecture) +## ๐Ÿ—๏ธ Internal Architecture (Clean Architecture) **Domain** - Core models @@ -148,7 +109,7 @@ Nothing is written unless explicitly exported. **Infrastructure** - Filesystem - Exporters -- Pipelines wiring (Koin) +- Pipeline wiring (Koin) **Presentation** - Compose Desktop UI @@ -160,7 +121,6 @@ Nothing is written unless explicitly exported. ## ๐Ÿงช Testing & Quality Core V4 is heavily tested: - - Pipeline unit tests - Dry-run generation tests - Failure-path tests @@ -170,27 +130,21 @@ Generation is **100% testable without filesystem**. --- -## ๐Ÿšซ What Core V4 Does NOT Do - -By design, Core V4 does **not**: +## ๐Ÿšซ Out of Scope (by design) -- generate UI screens -- generate ViewModels -- guess repository contracts -- auto-migrate projects -- act as an IDE -- include undo/redo (yet) +Core V4 does **not**: +- Generate UI screens or ViewModels +- Guess repository contracts +- Auto-migrate projects +- Act as an IDE +- Include undo/redo (yet) --- -## ๐Ÿ”ฎ What Comes Next โ€” **Core V5 (Planned)** - -Core V5 will focus on **advanced modeling and extensibility**: - -### Planned features +## ๐Ÿ”ฎ Whatโ€™s Next โ€” Core V5 (Planned) - RepositoryContract editor (visual CRUD modeling) -- Explicit Mapper contracts +- Explicit mapper contracts - Multi-platform generators (Android / KMP / Backend) - Plugin system - Template customization @@ -198,11 +152,11 @@ Core V5 will focus on **advanced modeling and extensibility**: - Project migrations - Export profiles -Core V5 will **not break Core V4 projects**. +> Core V5 will **not break Core V4 projects**. --- -## ๐Ÿ–ฅ๏ธ Running the project +## ๐Ÿ–ฅ๏ธ Running the Project ### Desktop (JVM) @@ -215,7 +169,6 @@ Core V5 will **not break Core V4 projects**. ## ๐Ÿค Final Notes Core V4 marks a **major milestone**: - - Architecture is explicit - Generation is deterministic - Previews are safe