Clasificación de Servicios

Resumen Ejecutivo

Este modelo define la taxonomía oficial de servicios en HERA para garantizar una arquitectura escalable y gobernable.

• Estandarización Estratégica: Organiza el ecosistema en 4 capas (Experience, Domain, Integration, Platform) y 13 categorías, alineando el desarrollo con los objetivos de negocio.
• Eficiencia en el Diseño: Proporciona un árbol de decisión y reglas de oro (Golden Rules) que reducen la ambigüedad en la creación de nuevos servicios.
• Trazabilidad Total: Establece una convención de nombramiento unificada que conecta GitLab, SonarQube y Kubernetes, facilitando la observabilidad y el mantenimiento a escala.

Estándar complementario

El naming de repo <tipo>-<detalle> definido en esta página se propaga a todas las capas de configuración del servicio: K8s deployment, K8s Secret, GCP Secret Manager, env vars del pod. Ver el modelo Context-Aware Naming de 5 capas en Estándares de Configuración para entender cómo la taxonomía de servicios se propaga a la capa de configuración.

Todo servicio desplegado en HERA tiene una capa y una categoría oficial asignada. Esta página define el modelo de 4 capas, las 13 categorías, el decision tree, las golden rules, la convención de naming y la trazabilidad entre GitLab, SonarQube y Kubernetes. Consulta esta referencia antes de crear cualquier servicio nuevo.

---

1. Modelo Conceptual: Las 4 Capas Estratégicas

Antes de pensar en categorías individuales, todo servicio debe ubicarse en una de cuatro capas que reflejan su propósito estratégico en el ecosistema:

Modelo de 4 Capas Estratégicas — HERA

Cada servicio en HERA pertenece a una de estas 4 capas. La capa define su propósito, sus límites y quién lo opera.

Cliente final (Web · Mobile · Partner)

↓

1

Experience Layer

Adapta y orquesta para el usuario final

frontend bff experience

↓

2

Domain Layer

Lógica de negocio y datos del producto

backend (domain) data cms

↓ ↑

3

Integration Layer

Conexión con sistemas externos y procesamiento async

integration event worker

↓ ↑

Sistemas externos · SAP · CRM · Payments · Marketplaces

4

Platform Layer (Transversal)

Servicios reutilizables consumidos por todas las capas anteriores

platform edge infra docs

Mensaje clave Cada servicio en HERA pertenece a una sola capa. La capa define su propósito, sus límites y quién lo opera.

Propósito de cada capa

Capa	Propósito	Quién la opera	Pregunta clave
1. Experience Layer	Adapta y orquesta para el usuario final	Equipos de producto + Frontend devs	”¿Qué necesita ver el cliente?“
2. Domain Layer	Lógica de negocio y datos del producto	Equipos de producto + Backend devs	”¿Cuáles son las reglas del negocio?“
3. Integration Layer	Conecta con sistemas externos y procesa async	Platform Engineers + Backend devs	”¿Cómo hablamos con el mundo exterior?“
4. Platform Layer	Servicios reutilizables consumidos por todas las capas	Platform Engineers (equipo HERA)	“¿Qué necesita reutilizarse en toda la organización?”

¿Por qué 4 capas?

Las 4 capas son una abstracción estratégica para comunicación ejecutiva y razonamiento arquitectónico. Cuando un dev pregunta “¿dónde pongo esta lógica?”, la respuesta empieza por identificar la capa correcta — luego se elige la categoría dentro de esa capa.

---

2. Las 13 Categorías Oficiales de HERA

Capa	Categoría	Propósito	Ejemplo canónico
Experience	frontend	App que el usuario final ve y toca	frontend-web-store
Experience	bff	Backend optimizado para un canal específico	bff-mobile-app
Experience	experience	Orquestación avanzada por journey de negocio	experience-checkout-journey
Domain	backend	Lógica de negocio central — Domain Service	backend-checkout-service
Domain	data	Exposición de datos read-heavy	data-catalog-search
Domain	cms	Gestión de contenido editorial	cms-corporate-site
Integration	integration	Conexión a sistemas externos	integration-sap-orders
Integration	event	Productores y consumidores reactivos	event-consumer-orders
Integration	worker	Procesamiento asíncrono batch/cron	worker-loyalty-points
Platform	platform	Servicios reutilizables (auth, notifs)	platform-auth-service
Platform	edge	API Gateway, Ingress, entrada al sistema	edge-apigee-config
Platform	infra	Infrastructure as Code	infra-terraform-modules
Platform	docs	Repositorios de documentación	docs-architecture-decisions

Una sola fuente de verdad

Esta página es la referencia única para clasificar servicios en HERA. Si la categoría que necesitas no está aquí, abre un ticket en BMC para que el equipo de Arquitectura evalúe agregarla — no inventes una nueva categoría sin proceso.

Ejemplos de Naming por Categoria

Convencion HERA: <tipo>-<detalle> en kebab-case

frontend Experience

frontend-web-storefrontend-mobile-appfrontend-b2b-portalfrontend-internal-admin

bff Experience

bff-web-storebff-mobile-appbff-b2b-portal

experience Experience

experience-checkout-journeyexperience-customer-onboardingexperience-product-return

backend Domain

backend-checkout-servicebackend-inventory-servicebackend-loyalty-enginebackend-pricing-service

data Domain

data-catalog-searchdata-product-recommendationsdata-customer-360

cms Domain

cms-corporate-sitecms-marketing-contentcms-product-stories

integration Integration

integration-sap-ordersintegration-stripe-paymentsintegration-salesforce-crm

event Integration

event-consumer-ordersevent-handler-inventoryevent-dispatcher-notifications

worker Integration

worker-loyalty-pointsworker-sap-exportworker-reports-generator

platform Platform

platform-auth-serviceplatform-notificationsplatform-feature-flags

edge Platform

edge-apigee-configedge-ingress-rulesedge-cloud-armor-policies

infra Platform

infra-terraform-modulesinfra-helm-checkoutinfra-k8s-base

Mensaje clave Cada servicio HERA sigue la convencion <tipo>-<detalle> en kebab-case. El prefijo de tipo siempre va primero. No repetir el producto (la jerarquia del grupo GitLab ya lo provee). Sin clasificacion, no se crea el repo.

---

2.1 frontend

Capa: Experience Layer

Qué es: Aplicación que el usuario final consume directamente (web SPA, web SSR, app móvil nativa, app de escritorio).

Cuándo usarla

• Necesitas renderizar una interfaz de usuario en navegador o dispositivo
• El servicio tiene estado de UI, no estado de negocio
• Consume APIs vía HTTP/GraphQL

Cuándo NO usarla

• Si el servicio solo expone datos → es data o backend
• Si orquesta múltiples APIs sin renderizar UI → es bff o experience

Ejemplos canónicos

frontend-web-store          # Next.js SSR para tienda
frontend-mobile-app         # React Native
frontend-b2b-portal         # SPA del portal de proveedores
frontend-internal-admin     # Admin interno

Beneficios

• Separación clara entre UI y lógica de negocio
• Despliegue independiente del backend
• Escalado horizontal del rendering según tráfico
• A/B testing y feature flags sin tocar el backend
• Equipos frontend autónomos

Stack típico y operación

Aspecto	Detalle
Lenguaje	TypeScript / JavaScript
Frameworks	Next.js, Astro, Vite + React, React Native
Pipeline	Golden Pipeline
Imagen base	hera/node-golden:20-alpine
Criticidad típica	Alta (es la cara del negocio)
SLO sugerido	99.9% uptime, P95 TTFB < 800ms
Observabilidad clave	Web Vitals, error rate del cliente, latencia de TTFB

---

2.2 bff (Backend For Frontend)

Capa: Experience Layer

Qué es: Backend optimizado para un canal específico (web, móvil, partner). Agrega, filtra y transforma datos de servicios backend y data para entregar al frontend exactamente lo que necesita en una sola llamada.

Cuándo usarla

• Tienes múltiples canales con necesidades diferentes (web rica, móvil ligera, API pública)
• El frontend necesita datos de 3 o más servicios backend para una sola pantalla
• Quieres versionar la API del cliente independientemente del core
• Necesitas aplicar reglas de presentación (formato de fechas, locale, layouts)

Cuándo NO usarla

• Tienes un solo canal y un solo backend → es overhead innecesario
• El BFF tendría lógica de negocio pesada → eso pertenece al backend
• Solo agrega un endpoint a una llamada → no justifica un servicio separado
• Es orquestación de un journey completo (checkout, onboarding) → es experience

Ejemplos canónicos

bff-web-store               # BFF para frontend web
bff-mobile-app              # BFF optimizado para móvil (payloads ligeros)
bff-b2b-portal              # BFF para portal de proveedores

Beneficios

• Menos llamadas desde el frontend — el BFF agrega N llamadas en una sola respuesta
• Mejor performance percibida — menos round trips, payload optimizado por canal
• Desacoplamiento frontend/backend — el frontend evoluciona sin tocar servicios core
• Control de seguridad centralizado — autenticación y autorización en el borde
• Versionado independiente — el BFF web puede ir en v3 mientras el móvil sigue en v2

Stack típico y operación

Aspecto	Detalle
Lenguaje	Node.js (más común), Java, .NET
Frameworks	Express, Fastify, NestJS, Spring Boot
Pipeline	Golden Pipeline
Criticidad típica	Alta (bloquea el frontend si falla)
SLO sugerido	99.9% uptime, P95 < 300ms
Observabilidad clave	Latencia P95, error rate por endpoint, fan-out a backends

Regla del BFF Ligero

Un BFF debe ser ligero. Su trabajo es orquestar y adaptar — no implementar reglas de negocio. Si tu BFF tiene validaciones complejas, cálculos o reglas que aplicarían igual desde otro canal, esa lógica pertenece a un backend (Domain Service) o platform.

---

2.3 experience (Experience Service)

Capa: Experience Layer

Qué es: Servicio que orquesta un journey completo de negocio (no un canal). Agrupa múltiples servicios backend, data y platform para entregar una experiencia end-to-end del usuario, independiente del canal por el que entre.

Diferencia con BFF

Aspecto	BFF	Experience Service
Propósito	Optimización por canal	Orquestación de journey de negocio
Ejemplo	”Datos para móvil vs web"	"Todo el flujo de checkout o de onboarding”
Cambia con	El cliente (canal)	El proceso de negocio
Owner típico	Equipo frontend del canal	Equipo de producto/journey
Reusable cross-canal	No (uno por canal)	Sí (lo consumen múltiples BFFs)

Cuándo usarla

• Tienes un journey complejo que toca 5+ servicios (checkout, onboarding, devolución)
• El journey es igual o muy similar entre canales (web y móvil hacen lo mismo)
• Quieres encapsular la lógica del proceso en un solo lugar
• Múltiples BFFs consumirían exactamente la misma orquestación

Cuándo NO usarla

• Es solo agregación técnica → es bff
• El journey tiene reglas de negocio puras sin orquestación → es backend
• Solo lo usa un canal → puede vivir en el BFF de ese canal

Ejemplos canónicos

experience-checkout-journey       # Journey completo de checkout
experience-customer-onboarding    # Alta de cliente end-to-end
experience-product-return         # Proceso de devolución
experience-loyalty-redemption     # Canje de puntos

Beneficios

• Encapsulamiento del journey — un cambio de proceso se hace en un solo lugar
• Reusabilidad cross-canal — múltiples BFFs consumen el mismo Experience Service
• Visibilidad end-to-end del proceso de negocio
• Testing del journey completo centralizado
• Observabilidad del proceso (métricas de cada paso del journey)

Stack típico y operación

Aspecto	Detalle
Lenguaje	Java, .NET, Node.js
Frameworks	Spring Boot, NestJS
Pipeline	Golden Pipeline
Patrones útiles	Saga, State Machine, Workflow Engine
Criticidad típica	Alta (bloquea journeys completos del negocio)
SLO sugerido	99.9% uptime, P95 según journey
Observabilidad clave	Métricas por paso del journey, conversion rate, drop-off points

---

2.4 backend (Domain Service)

Capa: Domain Layer

Qué es: Servicio que implementa lógica de negocio central y es propietario de un dominio o subdominio del producto. Es el corazón funcional del software. En arquitectura empresarial se conoce como Domain Service.

Backend = Domain Service

La categoría se llama backend por convención técnica, pero conceptualmente siempre es un Domain Service alineado con un bounded context de DDD.

Cuándo usarla

• Implementa reglas de negocio que son propias del producto (checkout, inventario, loyalty)
• Es propietario de los datos de su dominio
• Otros servicios lo consumen como source of truth de su dominio

Cuándo NO usarla

• Solo conecta a un sistema externo → es integration
• Solo expone datos sin lógica → es data
• Es reutilizable transversalmente (auth, notifs) → es platform
• Orquesta un journey end-to-end → es experience

Ejemplos canónicos

backend-checkout-service          # Procesamiento de orden de compra
backend-inventory-service         # Gestión de stock
backend-loyalty-engine            # Motor de puntos y recompensas
backend-pricing-service           # Cálculo de precios y promociones

Beneficios

• Bordes claros de dominio — cada servicio tiene una responsabilidad
• Escalado independiente — el inventario escala distinto al checkout
• Despliegue independiente — un cambio en pricing no toca checkout
• Equipos autónomos — un equipo dueño por servicio
• Source of truth clara para auditoría y compliance

Stack típico y operación

Aspecto	Detalle
Lenguaje	Java, .NET, Node.js, Python
Frameworks	Spring Boot, ASP.NET Core, NestJS, FastAPI
Pipeline	Golden Pipeline
Acceso a datos	Sí — propietario de tablas en Cloud SQL
Criticidad típica	Alta
SLO sugerido	99.95% uptime, P95 < 500ms
Observabilidad clave	Latencia de operaciones de negocio, error rate, throughput

---

2.5 data

Capa: Domain Layer

Qué es: Servicio que expone datos para consumo de lectura intensiva (catálogos, búsquedas, reportes). No contiene lógica de negocio compleja — su valor está en cómo modela y entrega los datos.

Cuándo usarla

• Datos consultados por muchos clientes simultáneamente con queries complejas
• Necesitas caché agresivo, índices especializados o motores de búsqueda
• Los datos son denormalizados desde múltiples fuentes (proyecciones, vistas materializadas)
• El read pattern es muy distinto al write pattern (CQRS)

Cuándo NO usarla

• Solo es CRUD básico de un dominio → vive en el backend propietario
• Tiene reglas de negocio complejas → es backend

Ejemplos canónicos

data-catalog-search          # Catálogo con búsqueda y facetas (Elasticsearch)
data-product-recommendations # Recomendaciones personalizadas
data-sales-reporting         # Reportes de ventas pre-calculados
data-customer-360            # Vista 360 del cliente

Beneficios

• Performance optimizada para consultas intensivas
• Escalado horizontal independiente de los servicios transaccionales
• Caché especializado sin contaminar el modelo transaccional
• Múltiples consumidores sin acoplar al backend de origen
• Read replicas y motores de búsqueda específicos

Stack típico y operación

Aspecto	Detalle
Lenguaje	Node.js, Java, Python, Go
Frameworks	Express, Spring, FastAPI
Storage típico	Read replicas de Cloud SQL, BigQuery, Elasticsearch, Redis
Pipeline	Golden Pipeline
Acceso a datos	Solo lectura — los datos vienen de eventos o ETL desde el backend propietario
Criticidad típica	Media-Alta
SLO sugerido	99.9% uptime, P95 < 200ms
Observabilidad clave	Cache hit rate, latencia de query, freshness de datos

---

2.6 cms

Capa: Domain Layer

Qué es: Servicio especializado en gestión de contenido editorial (textos, imágenes, banners, campañas). Generalmente es un Headless CMS que expone contenido vía API a frontends.

Cuándo usarla

• El contenido lo edita gente de negocio o marketing, no devs
• Necesitas versionado de contenido, workflow de aprobación, programación de publicaciones
• Múltiples frontends consumen el mismo contenido (web, móvil, kioscos)

Cuándo NO usarla

• El “contenido” son datos transaccionales (productos, precios) → es data o backend
• Solo necesitas un endpoint estático → no justifica un CMS

Ejemplos canónicos

cms-corporate-site         # CMS para sitio corporativo (Strapi)
cms-marketing-content      # Banners, landings, contenido de marketing
cms-product-stories        # Historias de producto multi-idioma

Beneficios

• Autonomía del negocio — marketing publica sin pasar por devs
• Workflow editorial — borradores, revisiones, programación
• Multi-canal — un solo contenido alimenta web, móvil y partners
• Versionado y rollback de contenido publicado
• Localización y soporte multi-idioma

Stack típico y operación

Aspecto	Detalle
Software típico	Strapi, Sanity, Contentful, Directus
Lenguaje	Node.js (Strapi, Sanity)
Pipeline	Golden Pipeline
Storage	PostgreSQL (Cloud SQL) + Cloud Storage para assets
Criticidad típica	Media-Alta
SLO sugerido	99.9% uptime
Observabilidad clave	Latencia de API de lectura, uptime del editor, errores de publicación

---

2.7 integration

Capa: Integration Layer

Qué es: Servicio cuya única responsabilidad es conectar HERA con un sistema externo (SAP, CRM, payment gateway, marketplace). Encapsula el protocolo, la autenticación y la traducción de modelos.

Anti-Corruption Layer (ACL)

Todo integration service debe implementar el patrón Anti-Corruption Layer: traduce el modelo del sistema externo al modelo interno de HERA, evitando que el “lenguaje” del legacy contamine el resto del ecosistema.

Cuándo usarla

• Necesitas hablar con un sistema fuera del ecosistema HERA
• Quieres aislar a los servicios de negocio de los detalles del sistema externo (SOAP, IDoc, archivos, formatos legacy)
• Necesitas resiliencia ante caídas o lentitud del sistema externo

Cuándo NO usarla

• La integración es trivial (una sola llamada HTTP) → puede vivir dentro del backend
• El sistema externo es de Grupo Herdez y ya tiene API moderna → llámalo directo

Ejemplos canónicos

integration-sap-orders            # Integración con SAP ERP
integration-salesforce-crm        # Sincronización con Salesforce CRM
integration-stripe-payments       # Gateway de pagos Stripe
integration-mlibre-marketplace    # Conector a Mercado Libre

Beneficios

• Aislamiento de sistemas legacy — el resto del ecosistema no conoce SOAP ni IDocs
• Resiliencia — circuit breakers, retries, timeouts en un solo lugar
• Traducción de modelos — el sistema externo cambia su contrato y solo tocas un servicio
• Auditabilidad — todas las llamadas al sistema externo pasan por aquí
• Rate limiting controlado — protege al sistema externo de saturación

Stack típico y operación

Aspecto	Detalle
Lenguaje	Java, .NET (común para sistemas enterprise)
Frameworks	Spring Integration, Apache Camel
Pipeline	Golden Pipeline
Patrones obligatorios	Circuit Breaker, Retry con Backoff, Timeout, ACL
Criticidad típica	Variable (depende del sistema externo)
SLO sugerido	99.5% uptime (limitado por el sistema externo)
Observabilidad clave	Tasa de éxito hacia el externo, latencia, errores por código

---

2.8 event

Capa: Integration Layer

Qué es: Servicio que reacciona a eventos publicados en un bus (Pub/Sub, Kafka). No expone APIs HTTP — su trigger es la llegada de mensajes.

Cuándo usarla

• Necesitas acoplamiento débil entre dominios (pedido creado → muchos servicios reaccionan)
• Quieres propagación de cambios sin que el origen sepa quién consume
• Tienes patrones event-driven o coreografía de servicios
• Procesamiento near-real-time (no es batch, no es síncrono)

Cuándo NO usarla

• El procesamiento es periódico y no reactivo → es worker
• Necesitas respuesta sincrónica al productor → debe ser HTTP

Ejemplos canónicos

event-consumer-orders             # Reacciona a eventos de orden creada/cancelada
event-handler-inventory           # Actualiza stock al recibir eventos de venta
event-dispatcher-notifications    # Envía notifs al recibir eventos de negocio
event-collector-audit             # Persiste eventos para auditoría

Beneficios

• Acoplamiento débil entre dominios — el publisher no conoce a los consumers
• Escalabilidad natural — múltiples consumers procesan en paralelo
• Coreografía sobre orquestación — cada dominio reacciona autónomamente
• Reprocesamiento — eventos persistidos pueden replayed
• Auditoría completa del flujo de negocio

Stack típico y operación

Aspecto	Detalle
Lenguaje	Java, Node.js, Python, Go
Bus de eventos	Pub/Sub (estándar HERA), Kafka (casos especiales)
Pipeline	Golden Pipeline
Patrones obligatorios	Idempotencia, dead-letter queue, ordering si aplica
Criticidad típica	Alta
SLO sugerido	Lag < 1min, 99.9% mensajes procesados
Observabilidad clave	Lag del consumer, mensajes/segundo, errores por tipo de evento

---

2.9 worker

Capa: Integration Layer

Qué es: Servicio que ejecuta procesamiento asíncrono en background sin atender requests HTTP de usuarios. Procesa jobs programados (cron), batches o tareas encoladas.

Cuándo usarla

• Tareas que toman minutos u horas y no pueden bloquear una request HTTP
• Procesamiento periódico (cierre de día, recálculo de loyalty, sincronización nocturna)
• ETL entre sistemas
• Generación de reportes pesados, exportaciones masivas

Cuándo NO usarla

• La tarea debe responder en tiempo real → es un endpoint del backend
• Reacciona a un evento puntual del bus → es event

Ejemplos canónicos

worker-loyalty-points             # Recálculo nocturno de puntos
worker-sap-export                 # Exportación batch de órdenes a SAP
worker-inventory-sync             # Sincronización de stock con bodegas
worker-reports-generator          # Generación de PDFs de reportes

Beneficios

• Desacople de tiempos — el usuario no espera operaciones largas
• Resiliencia ante fallos — un job puede reintentarse sin afectar a usuarios
• Escalado por demanda — más workers cuando hay backlog
• Operaciones programadas controladas centralmente
• Procesamiento masivo sin saturar APIs de usuario

Stack típico y operación

Aspecto	Detalle
Lenguaje	Java, Python, Node.js, Go
Patrón típico	CronJob de Kubernetes, BullMQ, Celery, Quartz
Pipeline	Golden Pipeline
Healthcheck	Endpoint mínimo para liveness probe
Criticidad típica	Media
SLO sugerido	Job duration p95, success rate > 99%
Observabilidad clave	Job duration, success rate, backlog size, last run timestamp

---

2.10 platform

Capa: Platform Layer

Qué es: Servicio reutilizable transversalmente por múltiples productos del ecosistema HERA. Resuelve un problema común (autenticación, notificaciones, feature flags) para que cada equipo no lo reinvente.

Cuándo usarla

• La funcionalidad es necesaria por 3 o más productos del ecosistema
• Es agnóstica del dominio de negocio (auth no depende de qué vende cada tienda)
• Tiene un equipo o área dueña que la mantiene como producto interno

Cuándo NO usarla

• Solo lo usa un producto → es backend de ese producto
• Es lógica específica de un dominio de negocio → es backend
• Es entrada al sistema (API Gateway) → es edge

Ejemplos canónicos

platform-auth-service             # Autenticación y autorización corporativa
platform-notifications            # Envío de emails, SMS, push (multi-canal)
platform-feature-flags            # Toggles de features
platform-audit-logging            # Logging centralizado de eventos de negocio
platform-file-storage             # Subida y entrega de archivos

Beneficios

• DRY a nivel organización — no se reimplementa auth N veces
• Estándar único — todos los productos manejan auth igual
• Mantenimiento centralizado — security patches en un solo lugar
• Compliance simplificado — auditorías pasan por servicios conocidos
• Time to market acelerado — los productos heredan capacidades

Stack típico y operación

Aspecto	Detalle
Propietario	Equipo de Plataforma HERA
Lenguaje	Java, .NET, Go (priorizando estabilidad)
Pipeline	Golden Pipeline
SLO sugerido	99.95% uptime
Criticidad típica	Crítica (caída afecta a múltiples productos)
Observabilidad clave	SLOs estrictos, alertas con bajo umbral, runbooks completos

---

2.11 edge

Capa: Platform Layer

Qué es: Punto de entrada al sistema. Maneja routing, rate limiting, autenticación de borde, transformación de protocolos y políticas de tráfico. Es la primera línea de defensa antes de que un request toque cualquier servicio de negocio.

Diferencia con platform

Aspecto	platform	edge
Posición	Interno, llamado por otros servicios	Externo, primer salto desde el cliente
Ejemplos	auth, notifications, logging	API Gateway, Ingress, WAF
Owner típico	Platform Engineering	Platform Engineering + Security
Cambia con	Necesidades de negocio	Topología de red, seguridad

Cuándo usarla

• Necesitas un API Gateway (Apigee, Kong, GCP API Gateway)
• Configuración de Ingress de Kubernetes específica del producto
• WAF rules custom (Cloud Armor)
• GraphQL Gateway unificado

Cuándo NO usarla

• Es lógica de aplicación → es backend
• Es infraestructura genérica → es infra
• Es un servicio reutilizable interno → es platform

Ejemplos canónicos

edge-apigee-config                # Configuración de Apigee API Gateway
edge-ingress-rules                # Ingress controllers de Kubernetes
edge-cloud-armor-policies         # Reglas WAF Cloud Armor
edge-graphql-gateway              # Gateway GraphQL unificado

Beneficios

• Centralización del borde — todas las políticas de entrada en un solo lugar
• Defensa en profundidad — primera línea antes de los servicios
• Transformación de protocolos — REST a GraphQL, HTTP a gRPC
• Rate limiting global y throttling
• Observabilidad de tráfico desde el primer hop

Stack típico y operación

Aspecto	Detalle
Software típico	Apigee, Kong, GCP API Gateway, Istio Gateway
Configuración	YAML / declarativa
Pipeline	Golden Pipeline — variante base-edge.yml
Owner	Platform Engineering + Security
Criticidad típica	Crítica (todo pasa por aquí)
SLO sugerido	99.99% uptime, latencia añadida < 50ms
Observabilidad clave	Latencia agregada, RPS por endpoint, rate limit hits, errores 4xx/5xx

---

2.12 infra

Capa: Platform Layer

Qué es: Repositorio que contiene Infrastructure as Code — Terraform, Helm charts, manifiestos Kubernetes — para aprovisionar y configurar la infraestructura cloud.

Cuándo usarla

• Necesitas crear o modificar recursos en GCP (Cloud SQL, GKE namespaces, buckets, networking)
• Defines la configuración de despliegue del producto en Kubernetes
• Contiene módulos Terraform reutilizables

Cuándo NO usarla

• Es código de aplicación que corre en runtime → es otro tipo de servicio
• Es configuración de pipeline (.gitlab-ci.yml) → vive con el código del servicio
• Es configuración de API Gateway → es edge

Ejemplos canónicos

infra-terraform-modules           # Módulos Terraform compartidos
infra-helm-checkout               # Helm chart de un servicio backend
infra-k8s-base                    # Manifiestos base de Kubernetes

Beneficios

• Reproducibilidad — el ambiente DEV es idéntico al PRD
• Auditoría — cada cambio de infra pasa por MR y review
• Versionado — rollback de infraestructura es trivial
• Drift detection — Terraform plan detecta cambios manuales
• Documentación viva — el código ES la documentación de la infra

Stack típico y operación

Aspecto	Detalle
Herramientas	Terraform, Helm, kubectl, kustomize
Pipeline	Golden Pipeline — variante base-infra.yml
State storage	GCS bucket centralizado con locking
Criticidad típica	Alta
Observabilidad clave	Drift de Terraform, éxito de plans/applies

Regla de oro de IaC

Cero cambios manuales en la consola de GCP para producción. Si cambia infra, cambia código en este repo.

---

2.13 docs

Capa: Platform Layer

Qué es: Repositorio dedicado a documentación — ADRs, guías técnicas, runbooks, contratos de API, especificaciones de negocio.

Cuándo usarla

• Documentación que vive más allá del README
• Necesitas versionar documentación junto con cambios de producto
• Contiene ADRs (Architecture Decision Records) o RFCs

Cuándo NO usarla

• Solo necesitas un README → vive en el repo del servicio
• Es documentación de plataforma → vive en platform/docs/

Ejemplos canónicos

docs-architecture-decisions       # ADRs de arquitectura
docs-runbooks-sre                 # Runbooks operacionales
docs-product-specs                # Especificaciones de producto

Stack típico

Aspecto	Detalle
Formato	Markdown / MDX
Render	Astro + Starlight, Docusaurus, MkDocs
Pipeline	Golden Pipeline — variante base-docs.yml
Criticidad típica	Baja (no afecta runtime)

---

3. Decision Tree — Cuándo usar cada categoría

Cuando no sepas qué categoría usar, sigue este árbol de decisión en orden:

Decision Tree por Caso

Sigue el caso que mejor describa tu escenario para encontrar la categoria correcta

1 UI para el usuario final

Renderiza UI al usuario final?

SI frontend

NO continuar

2 Frontend necesita datos de varios servicios

Consume multiples APIs backend en una vista?

SI

Journey completo de negocio?

SI experience

NO bff

NO consumo directo

3 Logica de negocio

Reglas de negocio complejas y dueno de datos?

SI

Agnostico del dominio?

SI platform

NO backend

NO

Solo read-heavy?

SI data

NO

Contenido editorial?

SI cms

NO revisar

4 Conectar con sistema externo

Sistema externo a Grupo Herdez?

SI integration (con ACL)

NO backend

5 Procesamiento asincrono

Es procesamiento async?

SI

Reactivo a eventos del bus?

SI event

NO

Batch/cron?

SI worker

NO revisar

NO backend sincrono

6 Borde del sistema

Punto de entrada (API GW, Ingress, WAF)?

SI edge

NO

IaC (Terraform, Helm)?

SI infra

NO

Solo documentacion?

SI docs

NO revisar

Por que NO repetir el producto

El producto ya esta en la jerarquia del grupo GitLab

grupo-herdez/ products/ ecommerce/ tienda-herdez/ v2-partner-beta/ backend-checkout-service

ya provee el contexto

Estrategia de Namespaces de Kubernetes

Cada producto tiene un unico namespace en GKE con todos sus servicios dentro

GKE Cluster

tienda-herdez/

frontend frontend-web-store

bff bff-mobile-app

bff bff-web-store

experience experience-checkout-journey

backend backend-checkout-service

backend backend-inventory-service

data data-catalog-search

cms cms-marketing-content

integration integration-sap-orders

event event-consumer-orders

worker worker-loyalty-points

Mensaje clave 6 casos de uso comunes con su categoría recomendada. Consulta el árbol antes de crear un servicio.

---

4. Golden Rules de HERA

Estas 8 reglas son obligatorias y no negociables. Aplican a todo servicio que se construye y despliega en HERA:

Regla 1 — Frontend con múltiples backends DEBE tener un BFF

Todo frontend que cumpla al menos uno de estos criterios DEBE tener un BFF:

• (a) Consume 3 o más servicios backend en una sola vista
• (b) Requiere agregación o transformación específica del canal (móvil necesita payload distinto a web)
• (c) Tiene SLA de latencia agresivo (P95 < 500ms con backends remotos)
• (d) Necesita centralizar autenticación/autorización del lado del servidor
• (e) El frontend tiene cadencia de versionado más rápida que los backends que consume

Frontends que NO cumplen ninguno de estos criterios pueden llamar directamente a las APIs si los endpoints son estables, públicos y versionados.

Regla 2 — Toda lógica de negocio vive en Domain Services (backend)

Ni el frontend, ni el BFF, ni el integration pueden contener reglas de negocio. La lógica vive en el backend propietario del dominio. Esto evita la duplicación, los bugs de inconsistencia entre canales y las complicaciones durante auditorías de compliance.

Regla 3 — Toda integración externa va en integration con ACL

No se permite que un backend o frontend llame directamente a SAP, CRM o payment gateways. Todas las integraciones externas pasan por un servicio integration que implementa el patrón Anti-Corruption Layer.

Regla 4 — Todo proceso async se desacopla en event o worker

Si una tarea no es inmediata, no bloquees al usuario. Reactiva (event) si responde a un mensaje del bus, batch (worker) si es periódica o programada. Nunca metas un sleep de 30 segundos en un endpoint HTTP.

Regla 5 — Servicios usados por 3+ productos van en platform

Si tu equipo está reimplementando autenticación, notificaciones o logging, detente. Esa funcionalidad ya debe existir como platform service. Si no existe, propón crearla — no la metas en tu backend.

Regla 6 — Naming obligatorio según convención HERA

Todo repo sigue el formato <tipo>-<detalle>. Ver Convención de Naming más abajo. Ningún repo se crea sin nombre conforme.

Regla 7 — Clasificación obligatoria

Todo servicio tiene service_type declarado en su service-manifest.yml, con uno de los 13 valores oficiales. Sin clasificación no se crea el repo en GitLab.

Regla 8 — Registro en inventario HERA obligatorio

Todo servicio se registra en el catálogo de servicios HERA con su metadata: dueño, criticidad, dependencias, SLO.

---

5. Convención de Naming

Formato general

<tipo>-<detalle>

Donde:

• <tipo> es uno de los 13 valores oficiales (frontend, bff, experience, backend, data, cms, integration, event, worker, platform, edge, infra, docs)
• <detalle> describe la función específica del servicio en kebab-case

Por qué NO repetir el producto

El producto ya está en la jerarquía del grupo GitLab:

Si nombras el repo backend-tienda-herdez-checkout-service, repites “tienda-herdez” innecesariamente. Esto se llama redundancia con el contexto.

Ejemplos correctos por categoría

Categoría	✅ Correcto	❌ Incorrecto
frontend	frontend-web-store	frontend-tienda-herdez-web
bff	bff-mobile-app	bff-tienda-mobile-app
experience	experience-checkout-journey	experience-tienda-checkout
backend	backend-checkout-service	backend-tienda-checkout-service
data	data-catalog-search	data-tienda-catalog
cms	cms-marketing-content	cms-tienda-marketing
integration	integration-sap-orders	sap-integration-tienda
event	event-consumer-orders	tienda-event-orders
worker	worker-loyalty-points	tienda-worker-loyalty
platform	platform-auth-service	auth-service-corporate
edge	edge-apigee-config	apigee-tienda-edge
infra	infra-terraform-modules	tienda-iac-modules
docs	docs-architecture-decisions	tienda-docs-adr

Regla de oro del naming

1. Prefijo de tipo siempre primero — facilita búsqueda en GitLab y identificación visual
2. No repetir el producto — la jerarquía del grupo ya lo provee
3. kebab-case obligatorio — sin guiones bajos, sin camelCase, sin mayúsculas
4. Descriptivo y específico — backend-checkout-service es mejor que backend-svc
5. Sin abreviaciones oscuras — auth sí, athsvc no

---

6. Trazabilidad: GitLab + SonarQube + Kubernetes

Las 13 categorías oficiales se propagan a través de toda la cadena de herramientas de HERA, garantizando trazabilidad multi-dimensional. La taxonomía declarada en el repo (dominio → producto → implementación → tipo + detalle) se convierte directamente en:

• El Project Key de SonarQube — documentado en Estructura de Repositorios — Convención de Project Key, se deriva de los atributos del product-manifest.yml.
• La estrategia de namespaces de Kubernetes — descrita abajo.

6.1 Estrategia de Namespaces de Kubernetes

Cada producto tiene un único namespace en GKE, con todos sus servicios dentro:

Reglas del namespace

Regla	Detalle
Nombre fijo	Coincide exactamente con el nombre del producto, sin prefijos (ej. tienda-herdez, sitio-donamaria, cms-corporativo). No incluye versión ni partner
Permanencia	El namespace sobrevive a cambios de versión y de partner
Separación de ambientes	El mismo nombre de namespace se replica en los clusters de DEV, QA y PRD, cada uno dentro de su GCP project correspondiente
Network policies	Cada namespace tiene policies que restringen el tráfico cross-namespace
RBAC	Permisos por namespace y por categoría de servicio

---

7. Anti-patterns Bloqueados en HERA

Estos patrones están explícitamente prohibidos y bloqueados en code review. Si los detectas, abre issue inmediato:

#	Anti-pattern	Por qué es malo	Qué hacer en su lugar
1	❌ Un solo backend gigante	Imposible de mantener, deploy lento, equipos bloqueados entre sí	Dividir por dominios en backend services
2	❌ Frontend llamando 10 APIs directo	Frágil, lento, frontend acoplado a la arquitectura interna	Crear un bff o experience service
3	❌ Lógica de negocio en BFF	El BFF se vuelve un mini-monolito; otros canales reimplementan	La lógica vive en backend o platform
4	❌ Repositorios sin clasificación	Imposible de buscar, sin pipeline correcto, sin SLOs	Asignar una de las 13 categorías oficiales antes de crear el repo
5	❌ APIs genéricas tipo api-general	Nombre que no comunica nada, terminan siendo basureros	Cada servicio tiene un dominio claro reflejado en su nombre
6	❌ Integración directa a SAP desde frontend	Acoplamiento total al legacy, sin ACL, sin auditoría	Usar integration service con ACL obligatorio
7	❌ Workers tratados como backends	SLOs incorrectos, sin monitoreo de backlog, fallos silenciosos	Usar la categoría worker con observabilidad adecuada
8	❌ Reinventar auth/notifs por producto	Inconsistencia, deuda técnica, deterioro del compliance	Usar los servicios platform existentes
9	❌ Llamadas síncronas donde aplicaría un evento	Fragilidad, cascadas de fallos, acoplamiento fuerte	Usar event services con Pub/Sub
10	❌ API Gateway mezclado con servicios de negocio	Confusión de responsabilidades, security misconfigurations	Separar en categoría edge
11	❌ Múltiples namespaces por producto en GKE	Permisos confusos, observabilidad fragmentada	Un solo namespace con el nombre del producto y todos sus servicios dentro
12	❌ Naming sin prefijo de tipo	Imposible saber qué es el servicio sin abrir el repo	Aplicar <tipo>-<detalle> siempre

---

8. Cómo se conecta esta clasificación con el resto de HERA

Aspecto	Documento relacionado
Cómo se nombra y crea el repo	Estructura de Repositorios
Qué pipeline ejecuta	GitLab Workflow
Qué patrón arquitectónico aplica	Patrones de Arquitectura
Quién es responsable de qué	Responsabilidad Compartida
Qué imagen base debe usar	Golden Images
Cómo se observa en producción	DevSecOps — Introducción

¿Es este contenido para ti?

Esta página es referencia obligatoria para Arquitectos, Tech Leads y todos los Equipos de Desarrollo. SRE y DevOps la usan para definir SLOs y pipelines. DBAs la usan para identificar quién accede a qué datos. Consulta los Roles y Responsabilidades para ver cuándo encaja en tu plan de lectura.