eva4j 1.0.3 → 1.0.4

package/README.md

@@ -1,30 +1,156 @@
 # eva4j
 
-A powerful Node.js CLI for generating Spring Boot projects with modular architecture that enables efficient monolith-first development with seamless transition to microservices.
+> **A powerful Node.js CLI for generating Spring Boot projects with modular architecture that enables efficient monolith-first development with seamless transition to microservices.**
 
-## 🚀 Objetivo
+[![npm version](https://img.shields.io/npm/v/eva4j.svg)](https://www.npmjs.com/package/eva4j)
+[![License](https://img.shields.io/npm/l/eva4j.svg)](https://github.com/your-repo/eva4j/blob/main/LICENSE)
+[![Node Version](https://img.shields.io/node/v/eva4j.svg)](https://nodejs.org)
 
-**Acelerar el proceso de desarrollo de aplicaciones Spring Boot** mediante la automatización de tareas repetitivas y la generación de código siguiendo las mejores prácticas de arquitectura limpia, CQRS y microservicios.
+---
+
+## 🚀 What is eva4j?
+
+**eva4j accelerates Spring Boot development** by automating repetitive tasks and generating production-ready code following industry best practices for Clean Architecture, CQRS, and Microservices.
+
+### ⚡ Generate in Seconds, Not Hours
+
+```bash
+# Create a complete project
+eva4j create my-ecommerce
+cd my-ecommerce
+
+# Add a module
+eva4j add module product
 
-Eva4j elimina la complejidad inicial de configurar proyectos modulares, permitiendo a los desarrolladores enfocarse en la lógica de negocio desde el primer momento. Con comandos simples e interactivos, puedes:
+# Generate full CRUD from YAML
+eva4j g entities product
+
+# 🎉 Done! You have:
+# ✅ Domain entities with business logic
+# ✅ JPA repositories and mappers
+# ✅ CQRS commands and queries
+# ✅ REST API with pagination
+# ✅ Complete hexagonal architecture
+```
+
+---
+
+## 💎 Why eva4j?
+
+### The Problem
+
+Building Spring Boot applications with proper architecture requires:
+- ❌ Hours setting up project structure
+- ❌ Repetitive code for CRUD operations
+- ❌ Manual wiring of layers (domain, application, infrastructure)
+- ❌ Complex microservices infrastructure from day one
+- ❌ Risk of architectural inconsistencies
+
+### The Solution
+
+eva4j provides:
+- ✅ **Project in seconds** - Complete structure with one command
+- ✅ **YAML-driven development** - Define domain model, generate 90% of code
+- ✅ **Automatic layer wiring** - Domain, application, infrastructure pre-connected
+- ✅ **Modular monolith first** - Simple development, microservices ready
+- ✅ **Architectural consistency** - Same patterns across all modules
+
+---
 
-- ⚡ **Crear proyectos completos** en segundos con toda la estructura arquitectónica definida
-- 🎯 **Generar módulos de dominio** con capas hexagonales pre-configuradas
-- 🔄 **Implementar CQRS** sin código repetitivo (commands, queries, handlers)
-- 📦 **Agregar integraciones** (Kafka, HTTP clients) con configuración automática
-- 🚢 **Extraer microservicios** de tu monolito cuando sea necesario, sin reescribir código
+## 🎯 Key Benefits & Impact
 
-### 💡 Sin Infraestructura Compleja
+### 1. **Massive Time Savings**
 
-**Desarrollo simplificado:** No necesitas orquestar múltiples servicios, bases de datos distribuidas, ni configurar service mesh desde el día uno.
+| Task | Without eva4j | With eva4j | Time Saved |
+|------|---------------|------------|------------|
+| Project setup | 2-4 hours | 30 seconds | **99%** |
+| Module creation | 1-2 hours | 15 seconds | **99%** |
+| Entity + CRUD | 3-6 hours | 1 minute | **98%** |
+| HTTP integration | 1-2 hours | 30 seconds | **99%** |
+| Kafka setup | 2-3 hours | 30 seconds | **99%** |
 
-- 📁 **Un solo repositorio** - todo tu código en un lugar
-- 🖥️ **Un solo servidor** - despliega una aplicación en desarrollo para validar cambios
-- 🐛 **Debug simple** - breakpoints que funcionan en todo el flujo
-- ⚡ **Startup rápido** - segundos, no minutos
-- 🧪 **Testing integrado** - prueba interacciones entre módulos sin Docker Compose
+**Total saved per module: 7-15 hours** → Invest in business logic instead!
 
-**Resultado:** Reduce días de configuración inicial a minutos, mantén consistencia arquitectónica en todo el proyecto, y escala desde desarrollo rápido hasta producción distribuida.
+### 2. **Quality & Consistency**
+
+- ✅ **Clean/Hexagonal Architecture** - Enforced by design
+- ✅ **CQRS Pattern** - Write and read operations properly separated
+- ✅ **Domain-Driven Design** - Entities, Value Objects, Aggregates
+- ✅ **Best Practices** - Industry-standard patterns built-in
+- ✅ **No Architectural Drift** - All modules follow same structure
+
+### 3. **Developer Experience**
+
+- ✅ **Simple Learning Curve** - YAML + CLI commands
+- ✅ **Interactive Prompts** - Guided project creation
+- ✅ **Clear Documentation** - Every command fully documented
+- ✅ **Rich Examples** - 10+ YAML examples included
+- ✅ **Fast Feedback** - Generate, run, test in seconds
+
+### 4. **Pragmatic Microservices**
+
+#### Start Simple (Modular Monolith)
+- 📁 **Single repository** - All code in one place
+- 🖥️ **Single application** - Deploy and debug easily
+- 🐛 **Simple debugging** - Breakpoints work across modules
+- ⚡ **Fast startup** - Seconds, not minutes
+- 🧪 **Integrated testing** - Test module interactions without Docker
+
+#### Scale When Needed (Microservices)
+- 🚀 **Extract modules** - One command to microservice
+- 🔄 **Zero rewrite** - Same code structure
+- 📦 **Independent deployment** - Deploy modules separately
+- 🎯 **Gradual migration** - Extract only what you need
+- 🏗️ **Same architecture** - Familiar structure everywhere
+
+---
+
+## 🏆 Real-World Impact
+
+### Typical Project Timeline Comparison
+
+**Traditional Approach:**
+```
+Week 1-2:  Project setup, architecture decisions
+Week 3-4:  First module implementation
+Week 5-6:  Second module, refactor patterns
+Week 7-8:  Third module, stabilize architecture
+Week 9+:   Business logic finally starts
+```
+
+**With eva4j:**
+```
+Day 1:     Project setup, 3 modules created, CRUD working
+Week 1:    Business logic implementation
+Week 2:    Testing and refinement
+Week 3+:   More features, not more infrastructure
+```
+
+**Result: Ship in 1/3 of the time** while maintaining higher quality standards.
+
+---
+
+## 💡 Development Philosophy
+
+### Without Complex Infrastructure
+
+You **don't need** from day one:
+- ❌ Multiple services running
+- ❌ Distributed databases
+- ❌ Service mesh
+- ❌ Complex orchestration
+- ❌ Microservices overhead
+
+Instead, you **get**:
+- ✅ **Single application** - Simple to develop and debug
+- ✅ **Module boundaries** - Enforced by Spring Modulith
+- ✅ **Clean architecture** - Ready for extraction
+- ✅ **Fast iteration** - Change multiple modules instantly
+- ✅ **Microservices ready** - Extract when business requires it
+
+### Result
+
+**Reduce setup time from days to minutes**, maintain architectural consistency, and scale from rapid development to distributed production when actually needed.
 
 ## 🎯 Philosophy: Modular Monolith to Microservices
 
@@ -84,7 +210,104 @@ npm link
 
 ---
 
-## 📚 Commands Reference
+## 📚 Complete Documentation
+
+### 📖 Command Reference
+
+All commands are fully documented with examples, use cases, and best practices:
+
+**[📑 Complete Commands Index](docs/commands/INDEX.md)** - Full documentation hub
+
+#### Quick Links to Most Used Commands
+
+| Command | Purpose | Documentation |
+|---------|---------|---------------|
+| `create` | Create new project | [📖 CREATE.md](docs/commands/CREATE.md) |
+| `add module` | Add domain module | [📖 ADD_MODULE.md](docs/commands/ADD_MODULE.md) |
+| `g entities` | Generate from YAML | [📖 GENERATE_ENTITIES.md](docs/commands/GENERATE_ENTITIES.md) |
+| `g usecase` | Create use case | [📖 GENERATE_USECASE.md](docs/commands/GENERATE_USECASE.md) |
+| `g resource` | Generate REST API | [📖 GENERATE_RESOURCE.md](docs/commands/GENERATE_RESOURCE.md) |
+| `g http` | HTTP client | [📖 GENERATE_HTTP_EXCHANGE.md](docs/commands/GENERATE_HTTP_EXCHANGE.md) |
+| `g kafka-event` | Kafka events | [📖 GENERATE_KAFKA_EVENT.md](docs/commands/GENERATE_KAFKA_EVENT.md) |
+| `detach` | Extract microservice | [📖 DETACH.md](docs/commands/DETACH.md) |
+
+### 📘 Additional Resources
+
+- **[DOMAIN_YAML_GUIDE.md](DOMAIN_YAML_GUIDE.md)** - Complete YAML syntax reference
+- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Command cheat sheet  
+- **[examples/](examples/)** - 10+ YAML examples for different scenarios
+
+---
+
+## 📚 Commands Documentation
+
+Eva4j provides a comprehensive set of commands for different stages of development. Each command has detailed documentation with examples and best practices.
+
+### Core Commands
+
+| Command | Description | Documentation |
+|---------|-------------|---------------|
+| **create** | Create a new Spring Boot project with modular architecture | [📖 CREATE.md](docs/commands/CREATE.md) |
+| **add module** | Add a new domain module with hexagonal architecture | [📖 ADD_MODULE.md](docs/commands/ADD_MODULE.md) |
+| **detach** | Extract a module into an independent microservice | [📖 DETACH.md](docs/commands/DETACH.md) |
+
+### Code Generation Commands
+
+| Command | Description | Documentation |
+|---------|-------------|---------------|
+| **generate entities** (g entities) | Generate complete domain model from YAML | [📖 GENERATE_ENTITIES.md](docs/commands/GENERATE_ENTITIES.md) |
+| **generate usecase** (g usecase) | Create CQRS commands or queries | [📖 GENERATE_USECASE.md](docs/commands/GENERATE_USECASE.md) |
+| **generate resource** (g resource) | Generate REST controller with CRUD endpoints | [📖 GENERATE_RESOURCE.md](docs/commands/GENERATE_RESOURCE.md) |
+| **generate record** (g record) | Create Java Record for DTOs | [📖 GENERATE_RECORD.md](docs/commands/GENERATE_RECORD.md) |
+
+### Integration Commands
+
+| Command | Description | Documentation |
+|---------|-------------|---------------|
+| **generate http-exchange** (g http) | Create HTTP client with OpenFeign | [📖 GENERATE_HTTP_EXCHANGE.md](docs/commands/GENERATE_HTTP_EXCHANGE.md) |
+| **generate kafka-event** (g kafka-event) | Setup Kafka event publishing | [📖 GENERATE_KAFKA_EVENT.md](docs/commands/GENERATE_KAFKA_EVENT.md) |
+| **generate kafka-listener** (g kafka-listener) | Create Kafka event consumer | Coming soon |
+| **add kafka-client** | Add Kafka dependencies to module | Coming soon |
+
+### Quick Start Example
+
+```bash
+# 1. Create project
+eva4j create my-ecommerce
+cd my-ecommerce
+
+# 2. Start development services
+docker-compose up -d
+
+# 3. Add modules
+eva4j add module product
+eva4j add module order
+eva4j add module customer
+
+# 4. Generate entities from YAML
+eva4j g entities product
+
+# 5. Run application
+./gradlew bootRun
+```
+
+### Command Aliases
+
+For faster development, most generate commands have short aliases:
+
+```bash
+eva4j g entities <name>        # generate entities
+eva4j g usecase <name>         # generate usecase  
+eva4j g resource <name>        # generate resource
+eva4j g record <name>          # generate record
+eva4j g http <name>            # generate http-exchange
+eva4j g kafka-event <name>     # generate kafka-event
+eva4j g kafka-listener <name>  # generate kafka-listener
+```
+
+---
+
+## 📖 Detailed Command Reference
 
 ### 1. `create` - Create New Project
 
@@ -94,106 +317,147 @@ Initialize a new Spring Boot project with modular architecture.
 eva4j create <project-name>
 ```
 
-**Interactive Prompts:**
-- Artifact ID (default: project name)
-- Group ID (default: com.example)
-- Java version: 21, 22, or 23
-- Spring Boot version
-- Database type: postgresql, mysql, h2
-- Author name
+Creates a production-ready Spring Boot project with:
+- ✅ Modular architecture (Spring Modulith)
+- ✅ Multi-environment configuration (local, dev, test, prod)
+- ✅ Docker Compose with database and Kafka
+- ✅ Gradle build with all necessary dependencies
+- ✅ Hexagonal architecture structure
 
-**Generated Structure:**
-```
-my-project/
-├── build.gradle              # Gradle build with Spring Modulith
-├── settings.gradle
-├── .eva4j.json              # Project configuration
-├── docker-compose.yml       # Database container
-└── src/
-    ├── main/
-    │   ├── java/.../
-    │   │   └── Application.java
-    │   └── resources/
-    │       ├── application.yml
-    │       ├── application-local.yml
-    │       ├── application-develop.yml
-    │       ├── application-test.yml
-    │       └── application-production.yml
-    └── test/
+**[📖 Full Documentation](docs/commands/CREATE.md)**
+
+---
+
+### 2. `add module` - Add Domain Module
+
+Add a domain module following hexagonal architecture.
+
+```bash
+eva4j add module <module-name>
 ```
 
-**Example:**
+Generates a complete module with:
+- ✅ Domain layer (entities, value objects, repositories)
+- ✅ Application layer (commands, queries, handlers, DTOs)
+- ✅ Infrastructure layer (JPA, REST controllers)
+- ✅ CQRS pattern ready
+- ✅ Spring Modulith boundaries validated
+
+**[📖 Full Documentation](docs/commands/ADD_MODULE.md)**
+
+---
+
+### 3. `generate entities` - Generate Domain Model
+
+Generate complete domain implementation from YAML definition.
+
 ```bash
-eva4j create my-shop
-cd my-shop
+eva4j generate entities <aggregate-name>
+eva4j g entities <aggregate-name>    # Short alias
 ```
 
+Creates from a YAML file:
+- ✅ Domain entities and value objects
+- ✅ JPA entities and repositories
+- ✅ CRUD commands and queries
+- ✅ Command/Query handlers
+- ✅ DTOs and mappers
+- ✅ REST controller
+
+**[📖 Full Documentation](docs/commands/GENERATE_ENTITIES.md)**
+
+**Example YAML:** See [examples/](examples/) directory for complete examples.
+
 ---
 
-### 2. `add module` - Add Domain Module
+### 4. Other Commands
+
+For complete documentation on all commands, see:
 
-Add a domain module following Spring Modulith architecture.
+- **[generate usecase](docs/commands/GENERATE_USECASE.md)** - Create individual CQRS use cases
+- **[generate resource](docs/commands/GENERATE_RESOURCE.md)** - Generate REST controllers
+- **[generate record](docs/commands/GENERATE_RECORD.md)** - Create Java Records
+- **[generate http-exchange](docs/commands/GENERATE_HTTP_EXCHANGE.md)** - HTTP client integration
+- **[generate kafka-event](docs/commands/GENERATE_KAFKA_EVENT.md)** - Kafka event publishing
+- **[detach](docs/commands/DETACH.md)** - Extract module to microservice
+
+---
+
+## 🎯 Common Workflows
+
+### Workflow 1: Create CRUD Module
 
 ```bash
-eva4j add module [module-name]
+# 1. Add module
+eva4j add module product
+
+# 2. Create YAML definition
+# Edit examples/product.yaml
+
+# 3. Generate entities
+eva4j g entities product
+
+# 4. Run and test
+./gradlew bootRun
 ```
 
-**Interactive Prompts:**
-- Module name (if not provided)
-- Enable soft delete? (createdAt/deletedAt fields)
-- Enable audit fields? (createdAt/updatedAt)
-
-**Generated Module Structure:**
-```
-src/main/java/.../user/
-├── package-info.java        # @ApplicationModule annotation
-├── application/
-│   ├── commands/           # CQRS commands
-│   ├── queries/            # CQRS queries
-│   ├── usecases/           # Command/Query handlers
-│   ├── dtos/               # Response DTOs
-│   ├── events/             # Domain events
-│   ├── mappers/            # Entity-DTO mappers
-│   └── ports/              # Output ports (interfaces)
-├── domain/
-│   ├── models/
-│   │   ├── entities/       # Domain entities
-│   │   └── valueObjects/   # Value objects
-│   ├── repositories/       # Repository interfaces
-│   └── services/           # Domain services
-└── infrastructure/
-    ├── adapters/           # Port implementations
-    ├── database/           # JPA repositories
-    └── rest/
-        ├── controllers/    # REST controllers
-        └── validators/     # Request validators
-```
-
-**Auto-Generated Shared Module (First Module Only):**
-```
-src/main/java/.../shared/
-├── domain/
-│   ├── annotations/        # @DomainComponent, @ApplicationComponent
-│   ├── customExceptions/   # DomainException, EntityNotFoundException
-│   ├── errorMessage/       # ErrorMessage
-│   └── interfaces/         # BaseEntity, AuditableEntity
-└── infrastructure/
-    ├── configurations/     # SwaggerConfig, JacksonConfig
-    ├── eventEnvelope/      # EventEnvelope wrapper
-    ├── filters/            # Request/Response logging
-    └── handlerException/   # Global exception handler
+### Workflow 2: Add Custom Use Cases
+
+```bash
+# Generate additional commands
+eva4j g usecase UpdateProductPrice --type command
+eva4j g usecase DeactivateProduct --type command
+
+# Generate custom queries
+eva4j g usecase SearchProductsByCategory --type query
+eva4j g usecase GetLowStockProducts --type query
 ```
 
-**Examples:**
+### Workflow 3: Integrate External Service
+
 ```bash
-eva4j add module user
-eva4j add module product
-eva4j add module order
+# Create HTTP client
+eva4j g http PaymentGateway
+
+# Configure in application.yml
+# Implement client methods
+# Use in domain through ports
+```
+
+### Workflow 4: Event-Driven Communication
+
+```bash
+# Publish events
+eva4j g kafka-event OrderCreated
+
+# Consume events in another module
+eva4j g kafka-listener OrderCreated
+```
+
+### Workflow 5: Extract to Microservice
+
+```bash
+# When module is mature and needs independence
+eva4j detach order
+
+# Result: order-service/ as standalone application
 ```
 
 ---
 
-### 3. `add kafka-client` - Add Kafka Support
+## 🎓 Additional Resources
+
+- **[DOMAIN_YAML_GUIDE.md](DOMAIN_YAML_GUIDE.md)** - Complete YAML syntax reference
+- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Command cheat sheet
+- **[examples/](examples/)** - YAML examples for different scenarios
+
+---
+
+### 3. Legacy Reference (Deprecated Section)
+
+For backward compatibility, here's the old reference format:
+
+### `add kafka-client` - Add Kafka Support
 
 Install Kafka dependencies and configuration.