---
name: diagrama-arquitectura
description: >
  Genera diagramas de arquitectura profesionales como archivos HTML auto-contenidos
  con gráficos SVG inline. Usar cuando se necesiten diagramas de sistema, infraestructura
  cloud, topología de red, flujos de seguridad, o cualquier diagrama técnico que muestre
  componentes y sus relaciones. Ideal para documentación, presentaciones y onboarding.
version: "1.0.0"
herramientasPermitidas: [Read, Grep]
user-invocable: false
license: MIT (basado en architecture-diagram-generator de Cocoon AI)
evolvable: true  # default para skill estandar
exclusiones:
  - "No cargar para diagramas de flujo de datos ETL o pipelines de datos — para diagramas de datos cargar `datos-etl` que incluye su propia notación de capas."
  - "No cargar para diagramas de entidad-relación de base de datos — para ER cargar `generacion-mermaid` con sintaxis erDiagram o `dbml-experto`."
  - "No cargar para wireframes o mockups de interfaz de usuario — para UI prototyping cargar `wireframes-flujos`."
  - "No cargar para diagramas de secuencia de API o flujos de autenticación en texto plano (Mermaid) — para diagramas Mermaid cargar `generacion-mermaid`."
---
# Diagrama de Arquitectura

Genera diagramas técnicos de arquitectura como archivos HTML standalone con SVG inline y CSS.
Basado en architecture-diagram-generator (MIT, Cocoon AI) — adaptado al sistema SWL.

## Cuándo NO cargar

- Los diagramas son de entidad-relación de base de datos: cargar `generacion-mermaid` (sintaxis `erDiagram`) o `dbml-experto`.
- Los diagramas son de flujo de datos ETL o pipelines de datos: `datos-etl` tiene su propia notación Medallion.
- Los diagramas son wireframes o mockups de UI: cargar `wireframes-flujos`.
- Los diagramas son de secuencia o flujo en texto Mermaid: cargar `generacion-mermaid`.

## Cuándo cargar

- El usuario pide un diagrama de arquitectura del proyecto
- `arquitecto-swl` necesita visualizar la arquitectura propuesta
- `documentador-swl` genera documentación visual
- `/swl:wiki` o `/swl:status dashboard` necesitan representación gráfica
- Cualquier tarea de RFC, ADR o propuesta arquitectónica

## Sistema de diseño

### Paleta semántica de colores

| Tipo de componente | Fill (rgba) | Stroke |
|-------------------|-------------|--------|
| Frontend | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) |
| Backend | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) |
| Base de datos | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) |
| Cloud/AWS/GCP/Azure | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) |
| Seguridad | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) |
| Bus de mensajes | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) |
| Externo/Genérico | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) |

### Tipografía

JetBrains Mono (monoespaciada, estética técnica):
```html
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
```

Tamaños: 12px nombres de componentes, 9px sub-etiquetas, 8px anotaciones, 7px etiquetas pequeñas.

### Elementos visuales

**Fondo:** `#020617` (slate-950) con patrón de grilla sutil:
```svg
<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
  <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
</pattern>
```

**Cajas de componentes:** Rectángulos redondeados (`rx="6"`) con stroke 1.5px, fills semi-transparentes.

**Grupos de seguridad:** Stroke punteado (`stroke-dasharray="4,4"`), fill transparente, color rose.

**Límites de región:** Stroke punteado largo (`stroke-dasharray="8,4"`), color amber, `rx="12"`.

**Flechas:** Marker SVG para puntas:
```svg
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
  <polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
</marker>
```

**Z-order de flechas:** Dibujar flechas temprano en el SVG (después de la grilla) para que queden detrás de componentes.

**Enmascarar flechas bajo fills transparentes:** Dado que las cajas usan fills semi-transparentes, las flechas se ven a través. Para enmascarar, dibujar un rect opaco (`fill="#0f172a"`) debajo del rect estilizado:
```svg
<!-- Fondo opaco para enmascarar flechas -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="#0f172a"/>
<!-- Componente estilizado encima -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
```

### Reglas de espaciado

**CRÍTICO:** Al apilar componentes verticalmente, asegurar espaciado correcto:

- **Altura estándar de componente:** 60px para servicios, 80-120px para componentes grandes
- **Gap vertical mínimo entre componentes:** 40px
- **Conectores inline (buses de mensajes):** Colocar EN el gap, sin solapar
- **Leyendas:** FUERA de todos los boundary boxes, al menos 20px debajo del más bajo
- **ViewBox SVG:** Extender si es necesario para acomodar leyendas

### Patrón de componente

```svg
<rect x="X" y="Y" width="W" height="H" rx="6" fill="FILL_COLOR" stroke="STROKE_COLOR" stroke-width="1.5"/>
<text x="CENTER_X" y="Y+20" fill="white" font-size="11" font-weight="600" text-anchor="middle">ETIQUETA</text>
<text x="CENTER_X" y="Y+36" fill="#94a3b8" font-size="9" text-anchor="middle">sub-etiqueta</text>
```

### Estructura del layout

1. **Encabezado** — Título con punto pulsante, subtítulo
2. **Diagrama SVG principal** — Contenido en tarjeta con borde redondeado
3. **Tarjetas de resumen** — Grid de 3 tarjetas debajo con detalles clave
4. **Pie** — Línea de metadatos mínima

## Template

Usar y personalizar el template en `assets/template.html`. Puntos de personalización:

1. Actualizar `<title>` y texto del encabezado
2. Modificar dimensiones del viewBox SVG si es necesario (default: `1000 x 680`)
3. Agregar/quitar/reposicionar cajas de componentes
4. Dibujar flechas de conexión entre componentes
5. Actualizar las tres tarjetas de resumen
6. Actualizar metadatos del pie

## Salida

Siempre producir un archivo `.html` auto-contenido con:
- CSS embebido (sin hojas de estilo externas excepto Google Fonts)
- SVG inline (sin imágenes externas)
- Sin JavaScript requerido (animaciones puras CSS)

El archivo debe renderizar correctamente al abrirlo directamente en cualquier navegador moderno.

## Flujo de uso en swl-ses

```
1. arquitecto-swl analiza el codebase → genera descripción textual de la arquitectura
2. Se carga Skill("diagrama-arquitectura")
3. Se genera HTML personalizado a partir del template + descripción
4. Se guarda en .planning/diagramas/ o docs/ del proyecto
5. Se actualiza en cada fase de verificación si hay cambios estructurales
```

## Casos de uso

- **Documentación de proyecto:** Diagrama visual para README o wiki
- **Propuesta arquitectónica:** Visualizar RFC o ADR antes de implementar
- **Onboarding:** Mostrar a nuevos desarrolladores cómo se conectan los componentes
- **Revisión de arquitectura:** Validar visualmente que el diseño cumpla requisitos
- **Presentaciones:** Diagrama profesional sin depender de herramientas externas (Lucidchart, Draw.io)

## Gotchas / Errores comunes no obvios

**Las flechas de conexión se ven a través de los componentes porque los fills son semi-transparentes**: cuando las flechas se dibujan en el SVG después de las cajas, se ven detrás de los fills transparentes y el diagrama parece correcto en el SVG editor, pero en el browser la línea atraviesa visualmente la caja. Causa: el orden de elementos SVG determina el z-order — los elementos dibujados después están "encima". Fix: dibujar todas las flechas **antes** de las cajas en el SVG (justo después del patrón de grilla). Además, para cada caja, agregar un `<rect>` opaco (`fill="#0f172a"`) detrás del `<rect>` con fill semitransparente para enmascarar las líneas que pasan por debajo.

**El viewBox del SVG es muy pequeño y las leyendas o etiquetas largas se recortan fuera del área visible**: si el diagrama tiene más componentes de los previstos, o los nombres son más largos que los del template, los elementos se solapan o quedan fuera del borde derecho/inferior del SVG. Causa: el viewBox por defecto `0 0 1000 680` es un punto de partida, no un límite flexible. Fix: calcular el espacio necesario antes de definir el viewBox. La leyenda debe quedar al menos 20px debajo del componente más bajo. Si el diagrama crece, extender el viewBox verticalmente: `0 0 1000 800` o más.

**Los textos centrados en componentes se desplazan cuando los nombres tienen acento o caracteres Unicode**: `text-anchor="middle"` en SVG calcula el centro basado en el ancho visual del texto, pero algunos navegadores calculan el ancho de manera diferente para caracteres no ASCII. Causa: SVG delega el cálculo de ancho de texto al motor de renderizado del navegador, que puede diferir entre Chrome, Firefox y Safari para caracteres especiales. Fix: para garantizar consistencia, usar nombres de componentes en inglés o en formato `Servicio: Nombre` donde el componente crítico es la palabra en inglés. Si se necesitan nombres en español, verificar el diagrama en Chrome y Firefox antes de publicarlo.

**El archivo HTML generado no renderiza correctamente al compartirlo por correo o subirlo a Confluence**: algunos sistemas de correo y wikis sanitizan el HTML y eliminan etiquetas `<svg>` o atributos inline de estilo. Causa: el HTML auto-contenido con SVG inline es correcto en el browser, pero los sanitizadores de contenido de Confluence/Outlook remueven elementos SVG por política de seguridad. Fix: para compartir en estas plataformas, renderizar el HTML en un browser y hacer captura de pantalla como PNG, o usar el comando de exportación de Confluence que soporta SVG como adjunto separado.
