Diagramación
Resumen
Crea diagramas técnicos claros y mantenibles usando sintaxis Mermaid. Esta habilidad cubre diagramas de arquitectura, diagramas de secuencia, diagramas entidad-relación, diagramas de flujo y diagramas de estado para documentar sistemas de software.
Instrucciones
1. Elige el tipo de diagrama adecuado
| Tipo de Diagrama | Úsalo cuando |
|---|---|
| Arquitectura/C4 | Se muestra la estructura y componentes del sistema |
| Secuencia | Se muestran interacciones a lo largo del tiempo |
| ERD | Se muestran modelos de datos y relaciones |
| Diagrama de flujo | Se muestra lógica de decisión y procesos |
| Estado | Se muestran transiciones de estado |
2. Principios generales de Mermaid
- Mantén los diagramas enfocados en un solo concepto
- Usa convenciones de nomenclatura consistentes
- Agrega etiquetas descriptivas a las relaciones
- Limita la complejidad (divide diagramas grandes)
- Usa comentarios para documentación
Mejores prácticas
- Simplicidad: Un diagrama, un concepto
- Consistencia: Misma nomenclatura en diagramas relacionados
- Legibilidad: Flujo de izquierda a derecha o de arriba a abajo
- Etiquetas: Siempre etiqueta relaciones y transiciones
- Contexto: Incluye un título y una breve descripción
Ejemplos
Diagramas de arquitectura (Modelo C4)
Diagrama de contexto (Nivel 1)
C4Context
title Diagrama de Contexto del Sistema para Plataforma de Comercio Electrónico
Person(cliente, "Cliente", "Un usuario que compra productos")
Person(admin, "Administrador", "Gestiona productos y pedidos")
System(ecommerce, "Plataforma de Comercio Electrónico", "Permite a los clientes navegar y comprar productos")
System_Ext(pago, "Pasarela de Pago", "Procesa los pagos")
System_Ext(envios, "Proveedor de Envíos", "Gestiona la logística de pedidos")
System_Ext(email, "Servicio de Correo", "Envía notificaciones")
Rel(cliente, ecommerce, "Navega, compra")
Rel(admin, ecommerce, "Gestiona")
Rel(ecommerce, pago, "Procesa pagos")
Rel(ecommerce, envios, "Crea envíos")
Rel(ecommerce, email, "Envía correos")
Diagrama de contenedores (Nivel 2)
C4Container
title Diagrama de Contenedores para Plataforma de Comercio Electrónico
Person(cliente, "Cliente")
Container_Boundary(ecommerce, "Plataforma de Comercio Electrónico") {
Container(web, "Aplicación Web", "React", "Interfaz de usuario orientada al cliente")
Container(api, "API Gateway", "Node.js", "API REST")
Container(carrito, "Servicio de Carrito", "Node.js", "Gestión del carrito de compras")
Container(catalogo, "Servicio de Catálogo", "Python", "Catálogo de productos")
Container(pedido, "Servicio de Pedidos", "Java", "Procesamiento de pedidos")
ContainerDb(db, "Base de Datos", "PostgreSQL", "Almacena todos los datos")
ContainerQueue(cola, "Cola de Mensajes", "RabbitMQ", "Mensajería asíncrona")
}
Rel(cliente, web, "Usa", "HTTPS")
Rel(web, api, "Llama", "JSON/HTTPS")
Rel(api, carrito, "Enruta a")
Rel(api, catalogo, "Enruta a")
Rel(api, pedido, "Enruta a")
Rel(carrito, db, "Lee/escribe")
Rel(catalogo, db, "Lee")
Rel(pedido, db, "Lee/escribe")
Rel(pedido, cola, "Publica eventos")
Diagrama de componentes (Nivel 3)
flowchart TB
subgraph "Servicio de Pedidos"
controller[Controlador de Pedidos]
service[Servicio de Pedidos]
repo[Repositorio de Pedidos]
validator[Validador de Pedidos]
publisher[Publicador de Eventos]
end
subgraph "Externo"
db[(PostgreSQL)]
cola[RabbitMQ]
end
controller --> service
service --> validator
service --> repo
service --> publisher
repo --> db
publisher --> cola
Diagramas de secuencia
Flujo básico de solicitud
sequenceDiagram
autonumber
participant C as Cliente
participant G as API Gateway
participant A as Servicio de Autenticación
participant S as Servicio
participant D as Base de Datos
C->>G: POST /api/recurso
G->>A: Validar token
A-->>G: Token válido
G->>S: Reenviar solicitud
S->>D: Consultar datos
D-->>S: Devolver resultados
S-->>G: Respuesta (200 OK)
G-->>C: Respuesta con datos
Flujo de manejo de errores
sequenceDiagram
participant C as Cliente
participant S as Servicio
participant D as Base de Datos
C->>S: POST /api/usuarios
S->>S: Validar entrada
alt Validación falla
S-->>C: 400 Solicitud Incorrecta
else Validación pasa
S->>D: INSERT usuario
alt Error de base de datos
D-->>S: Violación de restricción
S-->>C: 409 Conflicto
else Éxito
D-->>S: Usuario creado
S-->>C: 201 Creado
end
end
Procesamiento asíncrono
sequenceDiagram
participant C as Cliente
participant API as API
participant Q as Cola
participant W as Trabajador
participant N as Notificación
C->>API: Enviar trabajo
API->>Q: Poner en cola trabajo
API-->>C: 202 Aceptado (ID de trabajo)
Note over Q,W: Procesamiento asíncrono
Q->>W: Sacar de cola trabajo
W->>W: Procesar trabajo
W->>N: Enviar notificación
N-->>C: Notificación de trabajo completado
Diagramas entidad-relación
ERD básico
erDiagram
USUARIO ||--o{ PEDIDO : realiza
USUARIO {
uuid id PK
string email UK
string nombre
timestamp creado_en
}
PEDIDO ||--|{ LINEA_PEDIDO : contiene
PEDIDO {
uuid id PK
uuid usuario_id FK
decimal total
string estado
timestamp creado_en
}
LINEA_PEDIDO }|--|| PRODUCTO : referencia
LINEA_PEDIDO {
uuid id PK
uuid pedido_id FK
uuid producto_id FK
int cantidad
decimal precio
}
PRODUCTO ||--o{ PRODUCTO_CATEGORIA : "pertenece a"
PRODUCTO {
uuid id PK
string nombre
text descripcion
decimal precio
int stock
}
CATEGORIA ||--o{ PRODUCTO_CATEGORIA : contiene
CATEGORIA {
uuid id PK
string nombre
uuid padre_id FK
}
PRODUCTO_CATEGORIA {
uuid producto_id PK,FK
uuid categoria_id PK,FK
}
ERD con relaciones explicadas
erDiagram
CLIENTE ||--o{ PEDIDO : "realiza (1:N)"
PEDIDO ||--|{ LINEA_PEDIDO : "contiene (1:N, obligatorio)"
PRODUCTO ||--o{ LINEA_PEDIDO : "aparece en (1:N)"
CLIENTE }|--|| DIRECCION : "tiene facturación (N:1, obligatorio)"
CLIENTE }o--o{ DIRECCION : "tiene envío (N:N)"
Notación de relaciones:
||exactamente unoo|cero o uno}|uno o más}ocero o más
Diagramas de flujo
Lógica de decisión
flowchart TD
A[Inicio: Inicio de sesión de usuario] --> B{¿Credenciales válidas?}
B -->|Sí| C{¿2FA habilitado?}
B -->|No| D[Mostrar mensaje de error]
D --> A
C -->|Sí| E[Enviar código 2FA]
E --> F{¿Código válido?}
F -->|Sí| G[Crear sesión]
F -->|No| H{¿Intentos < 3?}
H -->|Sí| E
H -->|No| I[Bloquear cuenta]
C -->|No| G
G --> J[Redirigir al panel]
J --> K[Fin]
I --> K
Flujo de proceso
flowchart LR
subgraph "Pipeline de CI"
A[Enviar Código] --> B[Ejecutar Pruebas]
B --> C{¿Pruebas pasan?}
C -->|Sí| D[Construir Imagen]
C -->|No| E[Notificar al Desarrollador]
D --> F[Enviar al Registro]
end
subgraph "Pipeline de CD"
F --> G[Desplegar en Staging]
G --> H[Ejecutar Pruebas E2E]
H --> I{¿Pruebas pasan?}
I -->|Sí| J[Desplegar en Producción]
I -->|No| K[Rollback]
end
Diagramas de estado
Máquina de estado de pedido
stateDiagram-v2
[*] --> Borrador: Crear pedido
Borrador --> Pendiente: Enviar
Borrador --> Cancelado: Cancelar
Pendiente --> Confirmado: Pago recibido
Pendiente --> Cancelado: Pago fallido
Pendiente --> Cancelado: Tiempo agotado (24h)
Confirmado --> Procesando: Iniciar cumplimiento
Confirmado --> Cancelado: Cancelación por cliente
Procesando --> Enviado: Enviar pedido
Procesando --> Cancelado: Sin stock
Enviado --> Entregado: Entrega confirmada
Enviado --> Devuelto: Devolución iniciada
Entregado --> Devuelto: Devolución solicitada
Entregado --> [*]: Completado
Devuelto --> Reembolsado: Procesar reembolso
Reembolsado --> [*]: Completado
Cancelado --> [*]: Completado
Máquina de estado de conexión
stateDiagram-v2
[*] --> Desconectado
Desconectado --> Conectando: connect()
Conectando --> Conectado: éxito
Conectando --> Desconectado: fallo
Conectado --> Desconectado: disconnect()
Conectado --> Reconectando: conexión perdida
Reconectando --> Conectado: éxito
Reconectando --> Desconectado: máximo de reintentos
note right of Reconectando
Retroceso exponencial
Máximo 5 reintentos
end note
Diagramas de clase
classDiagram
class Repositorio~T~ {
<<interfaz>>
+findById(id: string) T
+findAll() Lista~T~
+save(entity: T) T
+delete(id: string) void
}
class RepositorioUsuario {
-db: BaseDeDatos
+findById(id: string) Usuario
+findAll() Lista~Usuario~
+save(entity: Usuario) Usuario
+delete(id: string) void
+findByEmail(email: string) Usuario
}
class Usuario {
+id: string
+email: string
+nombre: string
+creadoEn: Fecha
+validar() booleano
}
Repositorio~T~ <|.. RepositorioUsuario
RepositorioUsuario --> Usuario