workspace-v1/orchestration/directivas/simco/SIMCO-SERVICE-DESCRIPTOR.md

SIMCO-SERVICE-DESCRIPTOR: Directiva de Contratos de Servicio

Version: 1.0.0 Sistema: SIMCO v2 - Workspace v1 Responsable: Todos los agentes Fecha: 2025-12-18

---

PROPOSITO

El Service Descriptor (service.descriptor.yml) es el contrato universal que define completamente un servicio. Esta directiva establece cuando, como y por que usar service descriptors.

---

PRINCIPIO FUNDAMENTAL

Los agentes dejan de "inferir" y empiezan a "leer contrato".

Toda informacion sobre un servicio debe estar en su service.descriptor.yml

---

1. REGLA FUNDAMENTAL

TODO servicio DEBE tener un service.descriptor.yml en su raiz.

Ubicacion: {proyecto}/apps/{servicio}/service.descriptor.yml

Ejemplos:
- gamilit-platform/apps/backend/service.descriptor.yml
- gamilit-platform/apps/frontend/service.descriptor.yml
- erp-suite/apps/erp-core/backend/service.descriptor.yml
- erp-suite/apps/verticales/construccion/backend/service.descriptor.yml

---

2. CUANDO CREAR

2.1 Al crear nuevo servicio

TRIGGER: Creacion de nuevo backend, frontend, ML service, etc.

PASOS:
1. Crear carpeta del servicio
2. INMEDIATAMENTE crear service.descriptor.yml
3. Completar campos obligatorios
4. Verificar referencias a registries
5. Luego proceder con codigo

2.2 Al migrar servicio existente

TRIGGER: Migracion de workspace actual a workspace-v1

PASOS:
1. Analizar servicio existente
2. Identificar puerto, BD, dependencias
3. Verificar que esten en registries (o agregar)
4. Crear service.descriptor.yml con datos reales
5. Validar con validate-service-descriptors.sh

---

3. CAMPOS OBLIGATORIOS

3.1 Seccion service

service:
  name: "string"        # Nombre unico (kebab-case)
  type: "string"        # backend | frontend | database | ml | worker
  runtime: "string"     # node | python | go | static
  version: "string"     # SemVer (1.0.0)
  description: "string" # Descripcion breve
  owner_agent: "string" # NEXUS-BACKEND | NEXUS-FRONTEND | etc

3.2 Seccion repository

repository:
  name: "string"        # Nombre del repo
  path: "string"        # Path relativo al servicio
  main_branch: "string" # main | master

3.3 Seccion ports

ports:
  internal: number      # Puerto interno (3000, 3001, etc)
  registry_ref: "string" # Referencia al registry (projects.gamilit.api)
  protocol: "string"    # http | https | ws | grpc

3.4 Seccion environments

environments:
  deployed_to:          # Lista de ambientes
    - "local"
    - "development"
    - "production"
  default: "string"     # Ambiente por defecto

---

4. CAMPOS OPCIONALES

4.1 Seccion domains

domains:
  registry_ref: "string"  # Referencia a domains.registry
  overrides:              # Overrides por ambiente
    local: "string"
    development: "string"

4.2 Seccion database

database:
  registry_ref: "string"  # Referencia a databases.registry
  role: "string"          # runtime | migrator | owner
  schemas:
    - "string"            # Lista de schemas

4.3 Seccion healthcheck

healthcheck:
  path: "string"          # /health
  interval: "string"      # 30s
  timeout: "string"       # 5s
  retries: number         # 3

4.4 Seccion dependencies

dependencies:
  services:               # Otros servicios
    - name: "string"
      required: boolean
      healthcheck: "string"
  databases:
    - "string"            # Nombres de BD
  external:
    - name: "string"
      url: "string"
      required: boolean

4.5 Seccion ci

ci:
  pipeline: "string"      # Template de pipeline
  tests: boolean
  lint: boolean
  build: boolean
  docker: boolean
  docker_image: "string"
  docker_registry: "string"

---

5. WORKFLOW DE USO

5.1 Backend-Agent crea servicio

1. Recibe tarea de crear nuevo servicio
2. Verificar puerto disponible en ports.registry.yml
3. Si no disponible: Solicitar a DevOps-Agent
4. Crear service.descriptor.yml con:
   - service.* completado
   - ports.registry_ref apuntando al registro
   - database.registry_ref si usa BD
5. Validar descriptor
6. Proceder con implementacion

5.2 Frontend-Agent crea servicio

1. Recibe tarea de crear frontend
2. Verificar puerto disponible
3. Identificar backend del que depende
4. Crear service.descriptor.yml con:
   - dependencies.services incluyendo backend
   - domains.registry_ref configurado
5. Validar y proceder

5.3 DevOps-Agent hace deployment

1. Recibe solicitud de deployment
2. Leer service.descriptor.yml
3. Validar contra registries
4. Leer ci.* para configurar pipeline
5. Ejecutar pipeline segun flags
6. Si todo OK: Deploy

---

6. VALIDACION

6.1 Validacion Manual

# Validar un proyecto
./control-plane/devtools/scripts/validation/validate-service-descriptors.sh ./mi-proyecto/

# Salida esperada:
# Validando: ./mi-proyecto/apps/backend/service.descriptor.yml
#   [OK] YAML valido
#   [OK] Todos los campos obligatorios presentes
#   [OK] Referencias a registries validas

6.2 Validacion en CI

# En pipeline de CI:
- name: Validate Service Descriptors
  run: |
    ./control-plane/devtools/scripts/validation/validate-service-descriptors.sh .    

6.3 Errores Comunes

Error	Causa	Solucion
"Campo obligatorio faltante"	Falta service.name, etc	Completar campo
"YAML invalido"	Sintaxis incorrecta	Verificar indentacion
"registry_ref no existe"	Referencia a puerto no registrado	Agregar a registry primero
"Puerto no coincide"	internal != registry	Sincronizar valores

---

7. CUANDO ACTUALIZAR

7.1 Cambio de Puerto

1. Verificar nuevo puerto disponible en registry
2. Actualizar ports.registry.yml
3. Actualizar service.descriptor.yml ports.internal
4. Actualizar docker-compose.yml
5. Validar

7.2 Cambio de BD

1. Verificar nueva BD en databases.registry.yml
2. Actualizar service.descriptor.yml database.registry_ref
3. Actualizar variables de entorno
4. Validar

7.3 Nueva Dependencia

1. Identificar servicio del que se depende
2. Agregar a dependencies.services
3. Agregar healthcheck del servicio
4. Actualizar docker-compose depends_on

7.4 Cualquier Cambio

SIEMPRE:
1. Actualizar metadata.updated con fecha actual
2. Incrementar service.version si es cambio significativo
3. Ejecutar validacion

---

8. TEMPLATE

Ver template completo en:

control-plane/orchestration/templates/service-descriptor/SERVICE-DESCRIPTOR-TEMPLATE.yml

Ejemplo Minimo (Backend)

service:
  name: "mi-api"
  type: "backend"
  runtime: "node"
  version: "1.0.0"
  description: "API de mi servicio"
  owner_agent: "NEXUS-BACKEND"

repository:
  name: "mi-proyecto"
  path: "apps/backend"
  main_branch: "main"

ports:
  internal: 3000
  registry_ref: "projects.mi_proyecto.api"
  protocol: "http"

environments:
  deployed_to: ["local", "development", "production"]
  default: "local"

healthcheck:
  path: "/health"

ci:
  tests: true
  build: true
  docker: true

Ejemplo Minimo (Frontend)

service:
  name: "mi-web"
  type: "frontend"
  runtime: "static"
  version: "1.0.0"
  description: "Frontend web"
  owner_agent: "NEXUS-FRONTEND"

repository:
  name: "mi-proyecto"
  path: "apps/frontend"
  main_branch: "main"

ports:
  internal: 3001
  registry_ref: "projects.mi_proyecto.web"
  protocol: "http"

environments:
  deployed_to: ["local", "development", "production"]
  default: "local"

dependencies:
  services:
    - name: "mi-api"
      required: true

ci:
  build: true
  docker: true

---

9. INTEGRACION CON SIMCO

Referencias desde otras directivas

SIMCO-INICIALIZACION:
  - Cargar service.descriptor.yml como parte del contexto

SIMCO-CREAR:
  - Crear service.descriptor.yml ANTES de crear codigo

SIMCO-VALIDAR:
  - Incluir validacion de service.descriptor.yml

SIMCO-DEVOPS:
  - Leer service.descriptor.yml para deployment

---

Directiva mantenida por: Tech-Leader Ultima actualizacion: 2025-12-18