/architecture-docs

name: architecture-docs
description: "Usar para documentar la arquitectura del sistema. Activar ante: documentar arquitectura, diagrama del sistema, como funciona el proyecto, vision general tecnica"

Documentar arquitectura del sistema

Resumen

Este skill genera documentación arquitectónica que permite a cualquier desarrollador nuevo entender cómo funciona el sistema sin necesidad de leer todo el código. Cubre la visión general, los componentes principales, los flujos de datos, las dependencias externas y los enlaces a las decisiones arquitectónicas (ADRs) que explican el por qué de cada elección.

La documentación arquitectónica es un mapa del sistema: no necesita cubrir cada detalle, pero debe permitir orientarse y saber dónde buscar.

Proceso

1. **Redactar la visión general.** En 2-3 párrafos, explicar:

• Qué es el sistema y qué problema resuelve.
• A quién va dirigido (usuarios, otros servicios, el equipo interno).
• Qué principios de diseño guían la arquitectura.

2. **Documentar los componentes principales.** Para cada componente significativo:

• Nombre y propósito.
• Responsabilidades (qué hace y qué no hace).
• Tecnologías que usa.
• Interfaces públicas (cómo se comunica con otros componentes).
• Ubicación en el código (directorio o módulo).

3. **Generar diagrama de componentes con Mermaid.** Un diagrama vale más que mil palabras, pero solo si es claro:

   graph TD
     subgraph Frontend
       A[SPA React]
     end
     subgraph Backend
       B[API REST]
       C[Worker Jobs]
     end
     subgraph Datos
       D[(PostgreSQL)]
       E[(Redis Cache)]
     end
     A -->|HTTP/JSON| B
     B --> D
     B --> E
     B -->|Encola| C
     C --> D

Mantener el diagrama simple. Si es demasiado complejo, dividir en múltiples diagramas por dominio.

4. **Documentar los flujos de datos principales.** Para los 2-3 flujos más importantes del sistema, generar diagramas de secuencia que muestren cómo se mueven los datos entre componentes:

   sequenceDiagram
     participant U as Usuario
     participant F as Frontend
     participant A as API
     participant D as DB
     U->>F: Acción del usuario
     F->>A: Request HTTP
     A->>D: Query
     D-->>A: Resultado
     A-->>F: Response JSON
     F-->>U: Actualiza interfaz

5. **Listar dependencias externas.** Servicios de terceros de los que depende el sistema:

• Nombre del servicio.
• Para qué se usa.
• Qué pasa si no está disponible (fallback, degradación, fallo total).
• Enlace a su documentación.

6. **Enlazar decisiones arquitectónicas.** Referenciar los ADRs relevantes que explican por qué se tomaron las decisiones de diseño. Si no hay ADRs, considerar crearlos con el skill `write-adr`.

7. **Incluir instrucciones de desarrollo.** Cómo levantar el entorno de desarrollo:

• Requisitos previos (versiones de lenguaje, herramientas).
• Pasos para arrancar el proyecto desde cero.
• Cómo ejecutar tests.
• Variables de entorno necesarias.

Criterios de éxito

• La visión general explica qué es el sistema y para qué sirve en 2-3 párrafos.
• Cada componente principal está documentado con propósito, responsabilidades e interfaces.
• Hay al menos un diagrama de componentes y un diagrama de secuencia en Mermaid.
• Las dependencias externas están listadas con su impacto en caso de fallo.
• Las decisiones arquitectónicas están referenciadas o documentadas.
• Las instrucciones de desarrollo permiten a un nuevo miembro del equipo arrancar el proyecto.