CommunityImagengithub.com

diagramas-c4

Se activa al crear, revisar, actualizar o explicar diagramas de arquitectura de software que utilizan el modelo C4 (Contexto del Sistema Nivel 1, Contenedor Nivel 2, Componente Nivel 3, Código Nivel 4, Diagramas de Paisaje del Sistema, Dinámicos o de Despliegue), especialmente en Markdown/Mermaid.

¿Qué es diagramas-c4?

Este skill proporciona una guía completa y práctica para modelar arquitectura de software utilizando el modelo C4 de Simon Brown. Define las cuatro abstracciones fundamentales (Persona, Sistema de Software, Contenedor y Componente) con reglas estrictas para evitar mezclar niveles y garantizar la claridad en los diagramas. Incluye un catálogo detallado de diagramas recomendados (Contexto, Contenedor, Componente, Código, Paisaje del Sistema, Dinámicos y de Despliegue), así como patrones de modelado especializados para colas, tópicos y microservicios. La documentación también especifica convenciones de notación estándar, como el uso obligatorio de leyendas, flechas unidireccionales con verbos activos y tecnología explícita, y proporciona plantillas listas para usar en Mermaid (principalmente con diagramas de flujo) adaptadas para su visualización en Markdown. Es ideal para ingenieros que necesitan documentar, revisar o explicar arquitectura de manera consistente y profesional.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fsodano/writing-skills/tree/HEAD/skills/c4-diagrams

Installed? Explore more Imagen skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Diagramas C4

Fuente: el modelo C4 oficial en https://c4model.com/. Aplica estas reglas cada vez que dibujes, revises o expliques un diagrama C4. Carga también el skill de escritura cuando la salida incluya prosa (ADR, documentos, descripciones de PR).

1. Propósito

C4 es un conjunto de "mapas de tu código" en cuatro niveles de zoom: Contexto, Contenedores, Componentes, Código. Simon Brown lo creó, inspirado en UML y el modelo de vistas 4+1, para reemplazar los diagramas ad hoc de cajas y líneas. Fallos típicos que soluciona: sin leyenda, abstracciones mezcladas, flechas sin etiqueta, tecnología ausente y etiquetas vagas como "lógica de negocio".

C4 es independiente de la notación y de las herramientas. Las abstracciones y las reglas que se indican a continuación son lo que importa; las formas no.

2. Abstracciones

Jerarquía: Persona -> Sistema de Software -> Contenedor -> Componente -> Código. Cada nivel se acerca a un elemento del nivel superior.

AbstracciónDefiniciónEjemplos
PersonaUn usuario humano, actor, rol o persona del sistemaCliente, Agente de Soporte, Administrador
Sistema de SoftwareNivel más alto de abstracción; aporta valor a los usuarios. Normalmente es propiedad de un solo equipo y lo construye. No es un dominio de producto, contexto delimitado, tribu o squadPlataforma de Ticketing, Sistema de Pagos
ContenedorUna aplicación o almacén de datos que se ejecuta/despliega de forma independiente dentro de un sistema de softwareAplicación web del lado del servidor, SPA, aplicación de escritorio, aplicación móvil, función serverless, aplicación por lotes/consola, API de microservicio, esquema de base de datos, almacenamiento S3/blob, CDN, sistema de archivos, script de shell
ComponenteUna agrupación de funcionalidad relacionada detrás de una interfaz bien definida, dentro de un contenedor. No se puede desplegar por separado: todos los componentes de un contenedor comparten un espacio de procesoOrderController, PaymentService, EmailSender
CódigoClases, interfaces, funciones o tablas de base de datos dentro de un componenteclass OrderValidator, tabla orders

Reglas de los contenedores (Preguntas frecuentes de C4)

  • Un contenedor C4 no es Docker. Es una aplicación o almacén de datos ejecutable/desplegable, independientemente del empaquetado.
  • Una aplicación HTML renderizada en el servidor es 1 contenedor. Un servidor más un SPA o cliente móvil son 2 contenedores que se comunican a través de una API remota.
  • Los JAR, DLL, assemblies y módulos no son contenedores. Organizan el código dentro de un contenedor.
  • Los servicios de datos gestionados (S3, RDS, CDN) son contenedores dentro del límite de tu sistema cuando tú posees o controlas los buckets o esquemas. No son sistemas externos.

Reglas de los componentes

  • Un componente no es una carpeta, paquete o JAR. Es una agrupación funcional con una interfaz.
  • Los componentes no se pueden desplegar de forma independiente. Si se despliega por separado, es un contenedor.

Adaptación de la terminología

Los equipos pueden sustituir nombres idiomáticos del lenguaje (por ejemplo Módulo o Función en código funcional) cuando definen el término explícitamente en el diagrama o en su documentación. No inventes niveles de abstracción adicionales a menos que cada uno esté estrictamente definido.

3. Patrones de modelado especiales

Colas y tópicos

  • Incorrecto: un único "Bus de Mensajes" gigante en el centro con todos los servicios conectados (hub-and-spoke). Oculta quién produce y quién consume qué.
  • Opción 1 (preferida): modela cada cola o tópico como su propio contenedor (un almacén de datos de mensajes). Los productores escriben en él, los consumidores leen o se suscriben a él.
  • Opción 2: para acoplamiento directo punto a punto, omite la caja de la cola y etiqueta la relación "Publica eventos de pedido a través de Cola orders [AMQP]". Opcionalmente, estiliza estas líneas de forma diferente a las llamadas HTTP (explícalo en la leyenda).

Por ejemplo: Order API --"Publica OrderPlaced en [Kafka]"--> [(orders topic)] --"Lee OrderPlaced desde [Kafka]"--> Fulfilment Worker.

Microservicios (Regla de la Ley de Conway)

  • Un equipo posee todo el sistema de software: modela cada microservicio como un grupo de contenedores dentro del límite de ese sistema (contenedor de API más su propio contenedor de esquema de base de datos, o un único contenedor Lambda sin estado).
  • Equipos separados poseen cada servicio: promociona cada servicio de propiedad independiente a su propio Sistema de Software, cada uno con sus propios diagramas de Contexto del Sistema y de Contenedores. Indica la propiedad de la cola/tópico explícitamente a través de los límites del sistema.

4. Catálogo de diagramas

Niveles estáticos principales

NivelDiagramaRecomendadoAlcanceAudienciaMostrar / omitir
1Contexto del SistemaSí1 sistema de softwareTécnica y no técnicaPersonas y sistemas externos alrededor del sistema. Omitir tecnología y protocolos de bajo nivel
2ContenedorSí1 sistema de softwareTécnica, operacionesOpciones tecnológicas principales y protocolos entre procesos. Omitir clustering, balanceadores de carga, recuperación tras fallos
3ComponenteNo: solo cuando aporte valor claro, idealmente automatizado1 contenedorArquitectos, desarrolladoresComponentes dentro de un contenedor y sus interacciones
4CódigoNo: generar bajo demanda en el IDE1 componenteDesarrolladoresDiagrama de clases UML o DER

Diagramas de apoyo

DiagramaRecomendadoUso
Paisaje del SistemaSí, para organizaciones y carterasMapa empresarial o departamental de todos los sistemas y personas. Un diagrama de Contexto sin un sistema de enfoque único
DinámicoNo: usar con moderaciónColaboraciones complejas en tiempo de ejecución. Estilo de colaboración numerada o estilo de secuencia UML
DespliegueSí1 entorno (producción, staging, desarrollo). Nodos de despliegue anidados (físicos, VM, Docker, Kubernetes, runtime) que contienen instancias de sistema/contenedor, más nodos de infraestructura (DNS, balanceadores de carga, cortafuegos)

Compatibilidad

  • arc42: Contexto y Alcance -> L1; Nivel de Bloque de Construcción 1 -> L2; Nivel de Bloque de Construcción 2 -> L3; Nivel de Bloque de Construcción 3 -> L4.
  • UML: complementa C4 con diagramas UML de estado, secuencia y ERD para flujos de trabajo, máquinas de estado y modelos de datos.

Regla de escalado

Cuando un diagrama se satura, no metas docenas de cajas en un solo lienzo. Divide en el mismo nivel de abstracción por área de negocio, contexto delimitado, característica o enfoque de un solo servicio (el servicio central más sus vecinos entrantes y salientes).

5. Reglas de notación

Diagrama

  • El título indica el tipo de diagrama y el alcance: Diagrama de Contenedores para el Sistema de Pago.
  • Incluye siempre una clave/leyenda que explique formas, colores, bordes, tipos de línea, puntas de flecha y acrónimos.
  • Mantén una pureza estricta de abstracción: nunca mezcles niveles de abstracción (por ejemplo, no incluyas cajas de Componente dentro de un diagrama de Contenedores L2), y nunca pongas protocolos o pasos de implementación internos ([HTTPS], paquete enmascarado, tool_runner) dentro de un diagrama de Contexto del Sistema L1.
  • Al comparar arquitecturas competidoras o históricas, etiqueta los títulos de los límites explícitamente (Opción A (Reemplazada) vs. Opción B (Actual)) y actualiza todos los diagramas en el documento cada vez que los requisitos o supuestos cambien.

Elemento

  • Nombre, tipo de elemento explícito (Persona, Sistema de Software, Contenedor, Componente, Base de Datos, Nodo de Despliegue) y una descripción concisa de la responsabilidad.
  • Tecnología explícita en cada contenedor, componente y nodo de despliegue.

Relación

  • Solo flechas unidireccionales. Nunca <-->. Si los datos fluyen en ambas direcciones, muestra la dirección del iniciador y describe la respuesta en la etiqueta.
  • Etiquetas con verbos activos específicos. Nunca un simple "Usa". Escribe Envía pedidos a, Lee mapa de asientos de.
  • Protocolo/tecnología en las relaciones entre contenedores: [JSON/HTTPS], [SQL], [gRPC], [AMQP].

6. Mermaid en Markdown

Usa por defecto flowchart (flowchart TB o LR), no el C4Context/C4Container nativo de Mermaid. La sintaxis C4 nativa es experimental y a menudo falla al renderizarse en los visores de Markdown. Emítela solo si el usuario lo solicita explícitamente y confirma que el renderizador lo soporta.

Convenciones para flowchart:

  • Usa subgraph para el límite del sistema (Contenedores/Componentes) o nodos de despliegue.
  • Usa [(...)] para bases de datos, almacenes de datos, colas y tópicos.
  • Etiquetas HTML entre comillas: "<b>Nombre</b><br/>«Contenedor: Tecnología»<br/>Responsabilidad breve".
  • Flechas con etiquetas entre comillas: A -->|"Acción [Protocolo]"| B.
  • Un classDef por tipo de elemento, aplicado de forma consistente.
  • Se requiere un Legend subgraph compacto (nodos no conectados, anclado en la parte inferior con un enlace invisible bottomNode ~~~ Legend cuando Dagre lo coloca arriba) siempre que se usen colores, formas cilíndricas o múltiples estilos de línea; coloca un título como encabezado o en una línea Title: ... directamente sobre el bloque de código.
  • Diagramas dinámicos: sequenceDiagram, o un flowchart con etiquetas de flecha numeradas (1. Envía pedido [JSON/HTTPS]).
  • Diagramas de despliegue: subgraphs anidados en un flowchart.
  • Pon siempre entre comillas las etiquetas que contengan paréntesis, corchetes o dos puntos.
  • Nunca pongas punto y coma (;) sin escapar dentro de las etiquetas de sequenceDiagram o stateDiagram-v2 (Mermaid trata ; como terminador de sentencia y divide el texto restante en estados falsos o errores de análisis); envuelve los bloques Note largos en sequenceDiagram con <br/> para que el texto nunca se corte en el borde del viewport.

Plantilla: L1 Contexto del Sistema

Título: Diagrama de Contexto del Sistema para Plataforma de Ticketing

flowchart TB
    customer["<b>Cliente</b><br/>«Persona»<br/>Compra entradas para eventos"]
    ticketing["<b>Plataforma de Ticketing</b><br/>«Sistema de Software»<br/>Permite a los clientes explorar eventos y comprar entradas"]
    payments["<b>Proveedor de Pagos</b><br/>«Sistema de Software, externo»<br/>Cobra tarjetas"]
    email["<b>Servicio de Correo</b><br/>«Sistema de Software, externo»<br/>Entrega correos de confirmación"]

    customer -->|"Explora eventos y compra entradas usando"| ticketing
    ticketing -->|"Solicita cargos a tarjeta a"| payments
    ticketing -->|"Envía correos de confirmación usando"| email
    email -->|"Entrega correos de confirmación a"| customer

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef system fill:#1168bd,stroke:#0b4884,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class customer person
    class ticketing system
    class payments,email external

    subgraph Leyenda
        direction LR
        l1["Persona"]:::person
        l2["Sistema de Software (en alcance)"]:::system
        l3["Sistema de Software (externo)"]:::external
    end

Plantilla: L2 Contenedor (con contenedor de cola)

Título: Diagrama de Contenedores para Plataforma de Ticketing

flowchart TB
    customer["<b>Cliente</b><br/>«Persona»<br/>Compra entradas para eventos"]
    payments["<b>Proveedor de Pagos</b><br/>«Sistema de Software, externo»<br/>Cobra tarjetas"]

    subgraph boundary["Plataforma de Ticketing [Sistema de Software]"]
        spa["<b>Web App</b><br/>«Contenedor: React SPA»<br/>Exploración de eventos y UI de pago"]
        api["<b>API de Pedidos</b><br/>«Contenedor: Java, Spring Boot»<br/>Valida y coloca pedidos"]
        db[("<b>DB de Pedidos</b><br/>«Contenedor: PostgreSQL»<br/>Almacena pedidos y entradas")]
        topic[("<b>tópico de pedidos</b><br/>«Contenedor: tópico Kafka»<br/>Eventos OrderPlaced")]
        worker["<b>Trabajador de Cumplimiento</b><br/>«Contenedor: Python»<br/>Emite entradas y envía correos"]
    end

    customer -->|"Explora y compra usando [HTTPS]"| spa
    spa -->|"Envía pedidos a [JSON/HTTPS]"| api
    api -->|"Escribe pedidos en [SQL/TCP]"| db
    api -->|"Publica OrderPlaced en [Kafka]"| topic
    worker -->|"Lee OrderPlaced desde [Kafka]"| topic
    worker -->|"Actualiza estado de entrada en [SQL/TCP]"| db
    api -->|"Solicita cargos a tarjeta a [JSON/HTTPS]"| payments

    classDef person fill:#08427b,stroke:#052e56,color:#fff
    classDef container fill:#438dd5,stroke:#2e6295,color:#fff
    classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
    classDef external fill:#999,stroke:#6b6b6b,color:#fff
    class customer person
    class spa,api,worker container
    class db,topic store
    class payments external

    subgraph Leyenda
        direction LR
        l1["Persona"]:::person
        l2["Contenedor"]:::container
        l3[("Almacén de datos / cola / tópico")]:::store
        l4["Sistema externo"]:::external
    end

Nota de leyenda: las flechas apuntan desde el iniciador al destino. La etiqueta indica la acción y [protocolo].

Plantilla: Despliegue

Título: Diagrama de Despliegue para Plataforma de Ticketing (Producción)

flowchart TB
    users["<b>Navegador del cliente</b><br/>«Nodo de Despliegue: Chrome»"]

    subgraph aws["AWS «Nodo de Despliegue: Cloud, us-east-1»"]
        dns["<b>Route 53</b><br/>«Nodo de Infraestructura: DNS»"]
        lb["<b>Balanceador de Carga</b><br/>«Nodo de Infraestructura: ALB»"]
        subgraph eks["EKS «Nodo de Despliegue: clúster Kubernetes»"]
            subgraph pod["pod order-api «Nodo de Despliegue: Docker, x3»"]
                api["<b>API de Pedidos</b><br/>«Instancia de Contenedor: Java, Spring Boot»"]
            end
        end
        subgraph rds["RDS «Nodo de Despliegue: PostgreSQL 16»"]
            db[("<b>DB de Pedidos</b><br/>«Instancia de Contenedor: esquema PostgreSQL»")]
        end
    end

    users -->|"Resuelve nombre de host usando [DNS]"| dns
    users -->|"Envía solicitudes a [HTTPS]"| lb
    lb -->|"Reenvía solicitudes a [HTTP]"| api
    api -->|"Lee y escribe pedidos en [SQL/TCP]"| db

Agrega un subgraph de Leyenda si usas colores o estilos más allá de los predeterminados.

Plantilla: Dinámico (Secuencia)

Título: Diagrama dinámico (estilo secuencia) para Pago de Pedido en Plataforma de Ticketing

sequenceDiagram
    autonumber
    actor customer as Cliente
    participant spa as Web App (React SPA)
    participant api as API de Pedidos (Spring Boot)
    participant payments as Proveedor de Pagos
    participant db as DB de Pedidos (PostgreSQL)
    participant topic as tópico de pedidos (Kafka)

    customer->>spa: Hace clic en "Realizar Pedido"
    spa->>api: POST /orders [JSON/HTTPS]
    api->>payments: Cobra tarjeta [JSON/HTTPS]
    payments-->>api: Pago autorizado
    api->>db: Inserta fila de pedido [SQL/TCP]
    api->>topic: Publica OrderPlaced [Kafka]
    api-->>spa: 201 Creado (confirmación de pedido)
    spa-->>customer: Muestra recibo de pedido

Mantén las etiquetas de los participantes y mensajes de sequenceDiagram libres de barras inclinadas no escapadas, punto y coma (;, que Mermaid analiza como terminadores de sentencia), o saltos de línea sin procesar para máxima compatibilidad con visores de Markdown.

7. Diagramas

...

[truncado para traducción]

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills relacionados