Clean Architecture API - Multi-Módulo ✨

API REST para gestión de usuarios y autenticación implementada con Clean Architecture Multi-Módulo 100% PURA, Spring Boot 3.5.5+ y Java 21+.

🏗️ Arquitectura Multi-Módulo

El proyecto sigue el patrón de Clean Architecture con 4 módulos Maven separados:

• domain: Entidades puras, enums y repositorios (reglas de negocio) - 🔒 COMPLETAMENTE INDEPENDIENTE
• application: DTOs, servicios, queries y commands (casos de uso) - ✅ PURE POJOs - Solo depende de domain
• infrastructure: Seguridad, persistencia y configuración (adaptadores) - 🔧 Implementa interfaces de domain
• presentation: Controladores REST y endpoints (interfaz) - 🌐 Depende solo de application

Dependencias entre Módulos (Clean Architecture 100% PURA)

                    ┌─────────────────┐
                    │  PRESENTATION   │ ← Controladores REST
                    └─────────┬───────┘
                              │ ✅ Depende solo de
                              ▼
┌─────────────────┐ ┌─────────────────┐
│ INFRASTRUCTURE  │ │   APPLICATION   │ ← POJOs puros
│                 │ │                 │
│ • Spring Config │ │ • DTOs          │
│ • JPA Entities  │ │ • Services      │
│ • Security      │ │ • Commands      │
│ • Repositories  │ │ • Queries       │
└─────────┬───────┘ └─────────┬───────┘
          │                   │ ✅ Solo depende de
          │ ✅ Implementa     │
          │   interfaces      ▼
          └─────────────────→ ┌─────────────────┐
                              │     DOMAIN      │ ← Núcleo independiente
                              │                 │
                              │ • Entities      │
                              │ • Enums         │
                              │ • Interfaces    │
                              │ • Business Logic│
                              └─────────────────┘

🎯 Principios SOLID + Clean Architecture (100% Implementados)

• ✅ Dependency Inversion: Interfaces definidas en Domain, implementadas en Infrastructure
• ✅ Separation of Concerns: Cada capa tiene responsabilidades específicas y claras
• ✅ Domain Independence: Domain sin dependencias de frameworks (solo Lombok)
• ✅ Interface Segregation: Interfaces específicas por servicio y repositorio
• ✅ Framework Independence: Application layer sin dependencias de Spring
• ✅ Single Responsibility: Cada clase y módulo tiene una única razón para cambiar

🚀 Características

• ✅ Autenticación JWT con Spring Security
• ✅ Registro e inicio de sesión de usuarios
• ✅ Gestión de roles (USER, ADMIN)
• ✅ Validación de datos con Bean Validation
• ✅ Documentación API con Swagger/OpenAPI
• ✅ Múltiples perfiles (dev, test, staging, prod)
• ✅ Base de datos H2 (desarrollo) y PostgreSQL (producción)
• ✅ CORS configurado para desarrollo y producción
• ✅ Logging estructurado con diferentes niveles por perfil
• ✅ MapStruct para mapeo entre entidades de dominio y JPA
• ✅ Interfaces de servicios para inversión de dependencias
• ✅ Entidades de dominio puras sin anotaciones JPA
• ✅ Repositorios de dominio sin dependencias Spring

📋 Endpoints Disponibles

Públicos

• GET /api/public/welcome - Mensaje de bienvenida
• GET /api/public/health - Estado de la API
• GET /api/public/info - Información completa de la API

Autenticación

• POST /api/auth/signup - Registro de usuario
• POST /api/auth/login - Inicio de sesión
• POST /api/auth/validate - Validar token JWT
• POST /api/auth/refresh - Refrescar token JWT

Usuario (Requiere autenticación)

• GET /api/user/profile - Perfil del usuario autenticado
• GET /api/user/info - Información básica del usuario
• GET /api/user/has-role/{role} - Verificar rol específico

Documentación

• GET /swagger-ui.html - Interfaz de Swagger UI
• GET /v3/api-docs - Especificación OpenAPI

🛠️ Tecnologías

• Java 21+
• Spring Boot 3.5.5+
• Spring Security 6+
• Spring Data JPA
• JWT (jjwt 0.12.3)
• H2 Database (desarrollo)
• PostgreSQL (producción)
• Swagger/OpenAPI 3
• Lombok
• MapStruct 1.5.5 (mapeo entre capas)
• Maven Multi-Module

🚀 Inicio Rápido

Prerrequisitos

• Java 21+
• Maven 3.6+
• PostgreSQL (solo para producción)

1. Clonar el repositorio

git clone git@github.com:aruponse/java_clean_architecture.git
cd java_clean_architecture

2. Configurar variables de entorno

# Copiar archivo de ejemplo
cp env.example .env

# Editar variables según tu entorno
nano .env

3. Ejecutar la aplicación

Desarrollo (H2 Database)

mvn spring-boot:run -Dspring-boot.run.profiles=dev

Producción (PostgreSQL)

mvn spring-boot:run -Dspring-boot.run.profiles=prod

4. Acceder a la documentación

• Swagger UI: http://localhost:8080/swagger-ui.html
• H2 Console (dev): http://localhost:8080/h2-console

🔧 Configuración

Perfiles de Spring

Desarrollo (dev)

• Base de datos: H2 (memoria)
• Logging: DEBUG
• H2 Console: Habilitada
• Swagger: Habilitado

Pruebas (test)

• Base de datos: H2 (memoria)
• Logging: INFO/WARN
• H2 Console: Deshabilitada

Staging (staging)

• Base de datos: Configurable por variables de entorno
• Logging: INFO
• Swagger: Habilitado

Producción (prod)

• Base de datos: PostgreSQL
• Logging: WARN
• Swagger: Deshabilitado (configurable)

Variables de Entorno

Variable	Descripción	Valor por defecto
SERVER_PORT	Puerto del servidor	8080
JWT_SECRET	Clave secreta para JWT	(requerido en prod)
JWT_EXPIRATION	Expiración del token (ms)	86400000
DB_URL	URL de la base de datos	jdbc:h2:mem:testdb
DB_USERNAME	Usuario de la base de datos	sa
DB_PASSWORD	Contraseña de la base de datos	(vacío)
CORS_ALLOWED_ORIGINS	Orígenes CORS permitidos	*

📝 Uso de la API

Adicional a la suite de test swagger implementada en el proyecto se agrega una suite de pruebas para importarse en Postman lista para ejecutar.

1. Registro de usuario

curl -X POST http://localhost:8080/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario",
    "email": "usuario@example.com",
    "password": "password123",
    "firstName": "Juan",
    "lastName": "Pérez"
  }'

2. Inicio de sesión

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "usernameOrEmail": "usuario",
    "password": "password123"
  }'

3. Acceder a perfil (con token)

curl -X GET http://localhost:8080/api/user/profile \
  -H "Authorization: Bearer <tu-token-jwt>"

🧪 Pruebas

# Ejecutar todas las pruebas
mvn test

# Ejecutar pruebas con perfil específico
mvn test -Dspring.profiles.active=test

📁 Estructura del Proyecto Multi-Módulo

clean_architecture/
├── pom.xml                        # POM padre con módulos
├── domain/                        # Módulo de dominio (INDEPENDIENTE)
│   ├── pom.xml
│   └── src/main/java/com/api/cleanarch/domain/
│       ├── enums/                 # Enumeraciones puras
│       ├── model/                 # Entidades puras (sin JPA)
│       ├── repository/            # Interfaces de repositorio (sin Spring)
│       └── service/               # Interfaces de servicios
├── application/                   # Módulo de aplicación
│   ├── pom.xml
│   └── src/main/java/com/api/cleanarch/application/
│       ├── dto/                   # DTOs
│       ├── mappers/               # Mappers (MapStruct)
│       ├── service/               # Servicios e interfaces
│       ├── queries/               # Consultas (CQRS)
│       └── commands/              # Comandos (CQRS)
├── infrastructure/                # Módulo de infraestructura
│   ├── pom.xml
│   ├── src/main/java/com/api/cleanarch/infrastructure/
│   │   ├── security/              # Configuración de seguridad
│   │   ├── persistence/           # Implementación de repositorios
│   │   │   ├── entity/            # Entidades JPA
│   │   │   ├── mapper/            # Mappers MapStruct
│   │   │   └── *RepositoryImpl.java # Implementaciones
│   │   └── config/                # Configuraciones
│   └── src/main/resources/
│       ├── application.properties
│       ├── application-dev.properties
│       ├── application-test.properties
│       ├── application-staging.properties
│       └── application-prod.properties
├── presentation/                  # Módulo de presentación
│   ├── pom.xml
│   ├── src/main/java/com/api/cleanarch/presentation/
│   │   ├── controller/            # Controladores REST
│   │   └── ApiApplication.java    # Clase principal
│   └── src/test/java/com/api/cleanarch/presentation/
│       └── controller/            # Pruebas unitarias
├── env.example                    # Variables de entorno de ejemplo
└── Clean_Architecture_API_Postman_Collection.json   # Colección Postman para pruebas de la API (Lista para importar)

Compilación y Ejecución

# Compilar todos los módulos
mvn clean compile

# Ejecutar la aplicación (desde el módulo presentation)
mvn spring-boot:run -pl presentation

# Ejecutar pruebas
mvn test

# Compilar e instalar en repositorio local
mvn clean install