workspace-v1/control-plane/README.md

Control Plane - Workspace v1

Version: 2.0.0 Fecha: 2025-12-18

---

Descripcion

El Control Plane es la capa de governance del workspace. Contiene toda la configuracion centralizada, directivas, perfiles de agentes y herramientas de desarrollo.

---

Estructura

control-plane/
|
+-- registries/              # Fuente de verdad
|     +-- ports.registry.yml
|     +-- domains.registry.yml
|     +-- databases.registry.yml
|
+-- manifests/               # Configuracion de repos
|     +-- repos.manifest.yml
|     +-- environments.manifest.yml
|
+-- orchestration/           # Sistema SIMCO/NEXUS
|     +-- agents/
|     |     +-- ALIASES.yml
|     |     +-- perfiles/
|     +-- directivas/
|     |     +-- simco/
|     |     +-- principios/
|     +-- templates/
|     +-- checklists/
|
+-- devtools/                # Herramientas
      +-- scripts/
      |     +-- validation/
      |     +-- bootstrap/
      +-- docker/
      |     +-- traefik/
      |     +-- networks/
      |     +-- templates/
      +-- configs/

---

Quick Start

1. Inicializar Workspace

# Crear redes Docker
./devtools/docker/networks/create-networks.sh

# O inicializar todo
./devtools/scripts/bootstrap/init-workspace.sh

2. Crear Nuevo Proyecto

./devtools/scripts/bootstrap/init-project.sh mi-proyecto

3. Validar Configuracion

# Validar todo
./devtools/scripts/validation/validate-all.sh

# Validar puertos
./devtools/scripts/validation/validate-ports.sh .

# Validar service descriptors
./devtools/scripts/validation/validate-service-descriptors.sh .

---

Registries

ports.registry.yml

Registro central de puertos por proyecto/servicio.

projects:
  gamilit:
    services:
      api:
        internal: 3000
        protocol: "http"
        healthcheck: "/health"

Regla fundamental: Solo Traefik expone puertos publicos (80, 443).

domains.registry.yml

Registro de dominios para Traefik.

projects:
  gamilit:
    domains:
      api: "api.gamilit.localhost"
      web: "gamilit.localhost"

databases.registry.yml

Registro de bases de datos y roles.

databases:
  gamilit:
    host: "postgres"
    port: 5432
    database: "gamilit_db"
    roles:
      owner: "gamilit_owner"
      runtime: "gamilit_app"

---

Sistema SIMCO

Directivas Principales

Directiva	Proposito
SIMCO-INICIALIZACION	Protocolo CCA de inicio
SIMCO-CREAR	Creacion de componentes
SIMCO-VALIDAR	Validacion pre-commit
SIMCO-DOCUMENTAR	Standards de documentacion
SIMCO-SERVICE-DESCRIPTOR	Uso de descriptores
SIMCO-DEVOPS	Operaciones e infraestructura

Directivas por Rol

Directiva	Agente
SIMCO-BACKEND	Backend-Agent
SIMCO-FRONTEND	Frontend-Agent
SIMCO-DDL	Database-Agent
SIMCO-ARQUITECTURA	Tech-Leader
SIMCO-NIVELES	Workspace-Manager
SIMCO-PROPAGACION	Workspace-Manager

---

Sistema NEXUS (Agentes)

Agentes Disponibles

Agente	Alias	Rol
NEXUS-BACKEND	backend-agent	APIs y logica
NEXUS-FRONTEND	frontend-agent	Interfaces UI
NEXUS-DATABASE	database-agent	Schemas y datos
NEXUS-DEVOPS	devops-agent	Infraestructura
NEXUS-QA	qa-agent	Testing
NEXUS-SECURITY	security-agent	Seguridad
NEXUS-ML	ml-agent	Machine Learning
NEXUS-TECH-LEADER	tech-leader	Arquitectura
NEXUS-WORKSPACE	workspace-agent	Organizacion
NEXUS-DOCS	docs-agent	Documentacion

Inicializacion de Agente (Protocolo CCA)

1. Cargar perfil desde ALIASES.yml
2. Cargar registries relevantes
3. Cargar directivas aplicables
4. Verificar service.descriptor.yml
5. Ejecutar tarea

---

DevTools

Scripts de Validacion

./devtools/scripts/validation/validate-all.sh
./devtools/scripts/validation/validate-ports.sh /path/to/project
./devtools/scripts/validation/validate-service-descriptors.sh /path/to/project

Scripts de Bootstrap

./devtools/scripts/bootstrap/init-workspace.sh
./devtools/scripts/bootstrap/init-project.sh PROJECT_NAME

Docker

# Iniciar Traefik
cd devtools/docker/traefik
docker-compose -f docker-compose.traefik.yml up -d

# Crear redes
./devtools/docker/networks/create-networks.sh
./devtools/docker/networks/create-networks.sh --list

---

Arquitectura de 3 Capas

+------------------+
|  CONTROL PLANE   |  <- Governance (este repo)
|  - Registries    |
|  - Orchestration |
|  - DevTools      |
+------------------+
        |
        v
+------------------+
|  PRODUCT REPOS   |  <- Codigo de productos
|  - gamilit       |
|  - erp-suite     |
|  - trading       |
|  - betting       |
+------------------+
        |
        v
+------------------+
|  SHARED REPOS    |  <- Recursos compartidos
|  - libs          |
|  - infra         |
|  - knowledge-base|
+------------------+

---

URLs de Desarrollo

Servicio	URL
Traefik Dashboard	http://traefik.localhost:8080
Gamilit API	http://api.gamilit.localhost
Gamilit Web	http://gamilit.localhost
ERP Core API	http://api.erp.localhost
ERP Core Web	http://erp.localhost

---

Principios Clave

1. Registry First: Todo puerto/dominio/BD debe estar registrado
2. Descriptor First: Crear service.descriptor.yml antes del codigo
3. Validacion Continua: Ejecutar validaciones antes de commit
4. Aislamiento: Cada proyecto en su red Docker
5. Traefik Only: Solo puertos 80/443 publicos

---

Mantenimiento

Agregar Nuevo Proyecto

1. Agregar a registries/ports.registry.yml
2. Agregar a registries/domains.registry.yml
3. Agregar a registries/databases.registry.yml (si aplica)
4. Agregar a manifests/repos.manifest.yml
5. Ejecutar validate-all.sh

Actualizar Puerto

1. Verificar que nuevo puerto no esta en uso
2. Actualizar ports.registry.yml
3. Actualizar service.descriptor.yml del servicio
4. Actualizar docker-compose.yml del proyecto
5. Ejecutar validate-ports.sh

---

Troubleshooting

Puerto en uso

./devtools/scripts/validation/validate-ports.sh .
lsof -i :3000

Service Descriptor invalido

./devtools/scripts/validation/validate-service-descriptors.sh .

Red Docker no existe

./devtools/docker/networks/create-networks.sh
./devtools/docker/networks/create-networks.sh --list

---

Changelog

v2.0.0 (2025-12-18)

• Sistema de registries centralizado
• Perfiles de agentes con registry awareness
• Directivas SIMCO v2.0
• Scripts de validacion y bootstrap
• Templates de Docker Compose
• Configuracion completa de Traefik
• Sistema de redes Docker

v1.0.0 (Original)

• Version inicial

---

Mantenido por: Tech-Leader + DevOps-Agent Ultima actualizacion: 2025-12-18