Versión: 1.0
Fecha: 29 de Diciembre, 2025
Estado: DOCUMENTO DE ANÁLISIS
Arquitecto: Carlos Alberto Torres Camargo
Has recibido DOS propuestas aparentemente contradictorias:
Tu pregunta legítima: ¿Cuál es la correcta? ¿Por qué tanto proceso manual si se puede automatizar?
Razón: Estás en Fase 0 (Arquitectura), aún no tienes ni un microservicio de negocio en producción. Implementar Backstage ahora es sobre-ingeniería prematura.
Propuesta B:
Crear un portal donde el desarrollador genera el microservicio con un clic, sin intervención del arquitecto.
Mi Análisis:
| Aspecto | Ventajas | Desventajas | Recomendación |
|---|---|---|---|
| Madurez tecnológica | ✅ Backstage es maduro (usado por Spotify, Netflix) | ❌ Requiere equipo DevOps dedicado | ⏸️ POSPONER a Fase 2 |
| Complejidad setup | ✅ Democratiza la creación de servicios | ❌ Setup inicial: 2-4 semanas | ⏸️ POSPONER a Fase 2 |
| ROI | ✅ Excelente si tienes 50+ microservicios | ❌ Overkill para 5-10 microservicios | ⏸️ POSPONER a Fase 2 |
| Gobernanza | ❌ Requiere proceso maduro ANTES de automatizar | ❌ Riesgo de "microservicios zombies" | ⛔ NO implementar aún |
Decisión: ⏸️ POSPONER hasta Fase 2 (cuando tengas 10+ microservicios en producción y el proceso manual esté depurado).
Alternativa HOY (Fase 0-1):
# Script simple (1 hora de desarrollo)
#!/bin/bash
# create-nebula-service.sh
SERVICE_NAME=$1
echo "🚀 Generando microservicio ${SERVICE_NAME}..."
# 1. Generar con arquetipo
mvn archetype:generate \
-DarchetypeGroupId=com.catcsoft.simappe \
-DarchetypeArtifactId=SimappeArchetype \
-DarchetypeVersion=2.0.0-SNAPSHOTS \
-DgroupId=com.centrica.nebula \
-DartifactId=${SERVICE_NAME} \
-DinteractiveMode=false
cd ${SERVICE_NAME}
# 2. Inicializar Git
git init
git add .
git commit -m "chore: generar ${SERVICE_NAME} con SimappeArchetype"
# 3. Crear repo en GitHub (usando GitHub CLI)
gh repo create centrica/${SERVICE_NAME} --private --source=. --remote=origin --push
# 4. Crear rama develop
git checkout -b develop
git push -u origin develop
echo "✅ Microservicio creado: https://github.com/centrica/${SERVICE_NAME}"
echo "📋 Próximo paso: El arquitecto debe crear Jenkinsfile y documentación"
Tiempo de desarrollo: 1 hora
Ahorro por microservicio: 30 minutos
ROI: Positivo desde el primer uso
Propuesta B:
El arquitecto define
openapi.yaml, ese es el contrato, no documentos Word/Markdown.
Mi Análisis:
✅ 100% DE ACUERDO. Esto es una BEST PRACTICE que debes implementar INMEDIATAMENTE.
Por qué es superior:
| Enfoque | Docs Markdown | OpenAPI YAML |
|---|---|---|
| Actualización | ❌ Manual, se desactualiza | ✅ Generado del código (SpringDoc) |
| Versionado | ❌ Difícil | ✅ Git + tags |
| Generación cliente | ❌ Desarrollador copia a mano | ✅ openapi-generator automático |
| Validación | ❌ No hay | ✅ Validadores automáticos |
| Testing | ❌ No hay | ✅ Contract Testing (Pact) |
Implementación INMEDIATA (Sin Backstage):
# /nebula-contracts/payroll/v1/openapi.yaml
openapi: 3.0.0
info:
title: Nebula Payroll API
version: 1.0.0
paths:
/api/v1/payroll/employees:
get:
summary: Listar empleados
responses:
"200":
description: OK
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/EmpleadoDto"
components:
schemas:
EmpleadoDto:
type: object
properties:
id:
type: integer
nombre:
type: string
salarioBase:
type: number
# En pipeline CI/CD
openapi-generator-cli validate -i openapi.yaml
# Automático en su pipeline
openapi-generator-cli generate \
-i ../nebula-contracts/payroll/v1/openapi.yaml \
-g typescript-angular \
-o src/app/core/services/payroll-client
Tiempo de setup: 1 día
Ahorro por microservicio: 2-3 días (re-trabajo por desalineación backend/frontend)
ROI: ✅ IMPLEMENTAR YA
Actualización de mi documento:
Cambiar Fase 3 (Documentación) de:
- ### 6.1. Documentation Pack
- **El Arquitecto crea un "paquete de documentación" para el equipo:**
- #### Archivo 2: `CONTRATOS_API.md`
+ ### 6.1. Contract-First con OpenAPI
+ **El Arquitecto define el contrato OpenAPI ANTES del desarrollo:**
+ #### Archivo: `openapi.yaml` (en repo /nebula-contracts)
Propuesta B:
Para desarrollo local, usar
mvn installen lugar de pasar por Nexus cada vez.
Mi Análisis:
✅ 100% DE ACUERDO. Esto es SENTIDO COMÚN y debes documentarlo en el proceso.
Flujo Refinado:
Documentar en FLUJO_DESARROLLO_NEBULA.md:
## Desarrollo Local de CentricaModel
### Opción 1: Desarrollo Local (RECOMENDADO para features en progreso)
```bash
# Terminal 1: CentricaModel
cd CentricaModel
mvn clean install -DskipTests
# Terminal 2: Microservicio
cd nebula-payroll
mvn clean package
# Automáticamente tomará la versión de ~/.m2/repository
```
Solo cuando el PR de CentricaModel fue aprobado y mergeado, se publica a Nexus.
**Tiempo de implementación:** 10 minutos (solo documentar)
**Ahorro:** 50% del tiempo de desarrollo con DTOs
**ROI:** ✅ **IMPLEMENTAR YA**
---
### 3.4. "ADRs Vinculados a JIRA"
**Propuesta B:**
> Vincular ADRs a tickets de JIRA automáticamente.
**Mi Análisis:**
⚠️ **ÚTIL PERO NO PRIORITARIO**.
**Por qué NO es prioritario:**
1. Los ADRs son **decisiones arquitectónicas de alto nivel**, no están 1:1 con tickets de JIRA
2. Un ADR puede afectar a 10+ tickets
3. La vinculación manual (poner `Refs: ADR-010` en el commit) es suficiente
**Implementación SI decides hacerlo:**
```bash
# Git hook pre-commit
#!/bin/bash
# .git/hooks/commit-msg
COMMIT_MSG_FILE=$1
COMMIT_MSG=$(cat $COMMIT_MSG_FILE)
# Extraer ADR del mensaje
ADR=$(echo "$COMMIT_MSG" | grep -oP 'Refs: ADR-\d+')
if [ -n "$ADR" ]; then
# Vincular a JIRA usando API
JIRA_KEY=$(git branch --show-current | grep -oP 'NEB-\d+')
if [ -n "$JIRA_KEY" ]; then
curl -X POST https://jira.centrica.com/rest/api/2/issue/${JIRA_KEY}/remotelink \
-H "Authorization: Bearer ${JIRA_TOKEN}" \
-d "{\"object\": {\"url\": \"https://github.com/centrica/Documentation/blob/main/ADRs/${ADR}.md\"}}"
fi
fi
Tiempo de implementación: 2-3 horas
Ahorro: Marginal (trazabilidad mejorada)
ROI: ⏸️ POSPONER a Fase 2
Propuesta B:
Implementar tests automáticos que validen el patrón
Controller -> Service -> Component -> Repository.
Mi Análisis:
✅ EXCELENTE IDEA. IMPLEMENTAR EN SPRINT 1.1 (después de tener el primer microservicio funcionando).
Valor:
Implementación:
// En SimappeCommons (para reutilizar en todos los microservicios)
// src/test/java/com/catcsoft/simappe/archunit/SimappeArchitectureRules.java
@AnalyzeClasses(packages = "com.centrica.nebula")
public class SimappeArchitectureRules {
// REGLA 1: Controllers NO deben acceder a Repositories directamente
@ArchTest
static final ArchRule controllers_must_not_access_repositories =
noClasses()
.that().resideInAPackage("..controller..")
.should().accessClassesThat().resideInAPackage("..repository..");
// REGLA 2: Components DEBEN tener @ConnectionContext
@ArchTest
static final ArchRule components_must_have_connection_context =
classes()
.that().resideInAPackage("..component..")
.and().areNotInterfaces()
.should().beAnnotatedWith(ConnectionContext.class);
// REGLA 3: Entities DEBEN extender BusinessBaseEntity
@ArchTest
static final ArchRule entities_must_extend_base =
classes()
.that().resideInAPackage("..entity..")
.and().areAnnotatedWith(Entity.class)
.should().beAssignableTo(BusinessBaseEntity.class);
// REGLA 4: Services NO deben tener lógica de negocio (solo orquestación)
@ArchTest
static final ArchRule services_should_only_call_components =
classes()
.that().resideInAPackage("..service..")
.should().onlyAccessClassesThat()
.resideInAnyPackage("..component..", "..service..", "java..", "org.springframework..");
// REGLA 5: DTOs deben estar en CentricaModel, NO en microservicios
@ArchTest
static final ArchRule no_dtos_in_microservices =
noClasses()
.that().resideInAPackage("com.centrica.nebula..")
.should().haveSimpleNameEndingWith("Dto");
}
Configuración en el Microservicio Cliente (Centrica):
// nebula-payroll/src/test/java/com/centrica/nebula/payroll/ArchitectureTest.java
@AnalyzeClasses(packages = "com.centrica.nebula.payroll")
public class ArchitectureTest extends SimappeArchitectureRules {
// Hereda TODAS las reglas genéricas de SimappeCommons
/**
* REGLA ESPECÍFICA DE CENTRICA:
* DTOs deben estar en CentricaModel, NO en microservicios
*/
@ArchTest
static final ArchRule no_dtos_in_microservices =
noClasses()
.that().resideInAPackage("com.centrica.nebula..")
.should().haveSimpleNameEndingWith("Dto")
.because("Los DTOs deben estar en la biblioteca compartida CentricaModel");
/**
* REGLA ESPECÍFICA DE CENTRICA:
* No usar clases deprecated de versiones anteriores
*/
@ArchTest
static final ArchRule no_deprecated_classes =
noClasses()
.should().dependOnClassesThat().areAnnotatedWith(Deprecated.class)
.because("Evitar uso de APIs deprecadas");
}
Ejemplo para OTRO cliente (ej. Acme Corp):
// acme-erp/src/test/java/com/acme/erp/ArchitectureTest.java
@AnalyzeClasses(packages = "com.acme.erp")
public class ArchitectureTest extends SimappeArchitectureRules {
// Hereda las mismas reglas genéricas de SimappeCommons
/**
* REGLA ESPECÍFICA DE ACME:
* DTOs deben estar en AcmeModel
*/
@ArchTest
static final ArchRule no_dtos_in_microservices =
noClasses()
.that().resideInAPackage("com.acme.erp..")
.should().haveSimpleNameEndingWith("Dto")
.because("Los DTOs deben estar en AcmeModel");
}
Ventajas de esta arquitectura:
✅ SimappeCommons es 100% agnóstico del cliente
✅ Reglas genéricas se reutilizan para todos los clientes (Centrica, Acme, etc.)
✅ Cada cliente define sus reglas específicas en su propio test
✅ No viola la arquitectura de separación Simappe/Cliente
En CI/CD (Jenkinsfile):
stage('Architecture Tests') {
steps {
sh 'mvn test -Dtest=ArchitectureTest'
}
}
Tiempo de implementación: 1 día (crear reglas en SimappeCommons)
Ahorro: 80% del tiempo de code review arquitectónico
ROI: ✅ IMPLEMENTAR EN SPRINT 1.1
Estado: Arquitectura completa, 0 microservicios de negocio en producción.
Tareas:
Automatizaciones a implementar:
create-nebula-service.sh (1 hora) ← HACER YAmvn install local (10 min) ← HACER YADuración: 1 semana
Meta: 3-5 microservicios en producción (accounting, billing, inventory, payroll, treasury).
Proceso: MANUAL con scripts de soporte.
Automatizaciones a agregar:
ArchUnit en SimappeCommons (1 día) ← Sprint 1.1
Generación automática de Jenkinsfile (2 días) ← Sprint 1.2
# create-nebula-service.sh (mejorado)
# Genera Jenkinsfile completo a partir de template
Portal de Documentación Centralizado (3 días) ← Sprint 1.3
Duración: 3 meses
Automatización: 30% (scripts + ArchUnit + portal docs)
Tiempo del arquitecto por microservicio: 6-7 días (vs. 8-9 inicial)
Meta: 10-15 microservicios en producción.
Proceso: SEMI-AUTOMÁTICO.
Automatizaciones a agregar:
Backstage (Internal Developer Platform) (4 semanas) ← Sprint 2.1-2.4
Contract Testing Automático (1 semana) ← Sprint 2.5
Terraform para Infraestructura (2 semanas) ← Sprint 2.6-2.7
Duración: 3 meses
Automatización: 60% (Backstage + infra as code)
Tiempo del arquitecto por microservicio: 3-4 días
Meta: 20+ microservicios, 100+ developers.
Proceso: SELF-SERVICE con governance.
Automatizaciones:
Duración: Ongoing
Automatización: 80%
Tiempo del arquitecto por microservicio: 1-2 días (solo aprobaciones y validaciones críticas)
| Criterio | Fase 0-1 (Manual) | Fase 2 (Semi-Auto) | Fase 3-4 (Self-Service) |
|---|---|---|---|
| Tiempo arquitecto/microservicio | 8-9 días | 3-4 días | 1-2 días |
| Costo de setup | $0 | $50K USD (Backstage + DevOps) | $150K USD (plataforma completa) |
| Break-even | - | 10 microservicios | 25 microservicios |
| Control de calidad | ✅ Alto (manual) | ✅ Alto (ArchUnit + Aprobaciones) | ⚠️ Medio (requiere madurez) |
| Riesgo de "microservicios zombies" | ✅ Bajo | ⚠️ Medio | ❌ Alto (si no hay gobernanza) |
| Velocidad de creación | 🐌 Lenta | 🚗 Moderada | 🚀 Rápida |
| Adecuado para equipo junior | ✅ Sí (mucha guía) | ✅ Sí (ArchUnit valida) | ❌ No (requiere experiencia) |
FASE 0-1 (HOY): MANUAL + Scripts Simples
├─ Script create-nebula-service.sh ✅
├─ Contract-First con OpenAPI ✅
├─ ArchUnit en Sprint 1.1 ✅
└─ Portal Docs en Sprint 1.3 ✅
FASE 2 (Junio 2025): Evaluar Backstage
└─ Solo si tienes 10+ microservicios y equipo DevOps dedicado
FASE 3-4 (2026): Self-Service Completo
└─ Solo si tienes 20+ microservicios y proceso maduro
Respuesta: Es INTENCIONAL para Fase 0-1.
Razones:
Calidad sobre velocidad: Aún estás definiendo los patrones. Si automatizas antes de tener el patrón correcto, automáticas la mediocridad.
Aprendizaje del equipo: El proceso manual fuerza a los desarrolladores a entender el "por qué", no solo el "cómo".
Flexibilidad: En Fase 0-1, los requerimientos cambian. Un proceso automatizado rígido es contraproducente.
Gobernanza: Con equipo junior o en formación, el control manual previene errores costosos.
Analogía: No compras una fábrica automatizada de autos si solo vas a producir 5 prototipos. Primero haces los 5 a mano, perfeccionas el diseño, LUEGO automatizas.
Respuesta: La propuesta B tiene razón sobre el destino, pero está equivocado sobre el timing.
Backstage es el futuro de Nebula, pero NO es el presente.
Evidencia:
| Empresa | Microservicios al adoptar Backstage | Equipo DevOps |
|---|---|---|
| Spotify | 1200+ | 15 personas |
| Netflix | 800+ | 20 personas |
| Booking.com | 2000+ | 30 personas |
| Centrica (hoy) | 0 | ¿? |
Conclusión: Implementar Backstage HOY es como comprar un avión comercial para aprender a volar.
Trigger points:
✅ Tienes 10+ microservicios en producción
✅ Creas 1+ microservicio nuevo por mes
✅ Tienes equipo DevOps dedicado (2+ personas)
✅ El proceso manual está DEPURADO (sabes exactamente qué automatizar)
✅ El costo del arquitecto manual supera el costo de Backstage
Para Centrica: Probablemente Junio-Julio 2026 (final de Fase 1, inicio de Fase 2).
PROCESO_ARQUITECTO_DESARROLLO.md (30 min)Cambios:
# Fase 3: Documentación
- #### Archivo 2: `CONTRATOS_API.md`
+ #### Archivo 1: `openapi.yaml` (Contract-First)
+ **Definir el contrato OpenAPI ANTES del desarrollo**
# Agregar sección:
+ ### 6.4. Script de Automatización
+ **Usar `create-nebula-service.sh` para reducir tareas repetitivas**
create-nebula-service.sh (1 hora)Ubicación: /workspace/centrica-scripts/create-nebula-service.sh
Contenido: Ver código en sección 3.1 de este documento.
FLUJO_DESARROLLO_NEBULA.md (15 min)Agregar sección:
## Desarrollo Local Rápido
Para evitar el ciclo "modificar CentricaModel → Nexus → esperar 10 min":
```bash
# Terminal 1: CentricaModel
cd CentricaModel
mvn clean install -DskipTests
# Terminal 2: Microservicio
cd nebula-payroll
mvn clean package # Usa ~/.m2/repository automáticamente
```
Solo publicas a Nexus cuando el PR es aprobado y mergeado.
#### 4. Crear Reglas ArchUnit en SimappeCommons (3 horas)
**Archivo:** `SimappeCommons/src/test/java/com/catcsoft/simappe/archunit/SimappeArchitectureRules.java`
**Contenido:** Ver código en sección 3.5 de este documento.
#### 5. Documentar Contrato OpenAPI de Ejemplo (1 hora)
**Ubicación:** `/nebula-contracts/template/openapi-template.yaml`
**Propósito:** Template para que desarrolladores copies y adapten.
---
## 8. CONCLUSIÓN
### Tu Confusión es Legítima
Estabas comparando **procesos de diferentes niveles de madurez** como si fueran mutuamente excluyentes.
### La Realidad
✅ **Fase 0-1 (HOY):** Proceso manual con scripts de soporte (mi documento)
✅ **Fase 2 (Junio 2025):** Semi-automatizado con Backstage
✅ **Fase 3-4 (2026):** Self-Service completo (propuesta B)
### Implementación Propuesta B: 20% Ahora, 80% Después
| Propuesta B | Implementar HOY | Implementar DESPUÉS |
|------------------|-----------------|---------------------|
| Self-Service Infrastructure | ❌ | ✅ Fase 2 (Junio 2026) |
| Contract-First OpenAPI | ✅ | - |
| mvn install local | ✅ | - |
| ADRs vinculados a JIRA | ❌ | ✅ Fase 2 (opcional) |
| ArchUnit | ✅ Sprint 1.1 | - |
### Próximo Paso
**Implementar las 5 tareas de la sección 7** (duración total: 1 día).
Esto te dará el **20% de automatización que necesitas HOY**, sin la sobrecarga del 80% que necesitarás DESPUÉS.
---
**Documento Aprobado - Listo para Implementación**
| Version | Fecha | Autor | Descripcion |
|---|---|---|---|
| 1.1.0 | 2026-03-04 | Carlos Torres | Revision, sanitizacion y publicacion en Wiki Arquitectura Centrica. |
| 1.0.0 | 2025-12-29 | Carlos Torres | Creacion del documento. |