# 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

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

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

### 2. Crear Nuevo Proyecto

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

### 3. Validar Configuracion

```bash
# 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.

```yaml
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.

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

### databases.registry.yml

Registro de bases de datos y roles.

```yaml
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)

```yaml
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

```bash
./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

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

### Docker

```bash
# 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

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

### Service Descriptor invalido

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

### Red Docker no existe

```bash
./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