El diagrama de Contexto de Sistema es el nivel 1 del modelo C4 -- el diagrama de arquitectura más importante que tu equipo puede crear. Esta guía explica qué debe contener un diagrama de contexto C4, recorre un ejemplo completo de diagrama de contexto y muestra cómo crear uno manualmente o generarlo a partir de tu código.

Diagrama de Contexto de Sistema C4: guía completa con ejemplos

Si solo vas a dibujar un único diagrama de arquitectura, que sea un diagrama de Contexto de Sistema. Es el punto de entrada del modelo C4, el diagrama que cualquier persona interesada puede leer sin formación previa, y la forma más rápida de sacar a la luz desacuerdos sobre lo que tu sistema realmente hace.

Y sin embargo, la mayoría de los equipos lo hacen mal. Lo llenan de bases de datos, microservicios y clústeres de Kubernetes hasta que el diagrama de "contexto" se convierte en un mapa de infraestructura ilegible. O lo omiten por completo y saltan directamente a un diagrama de Contenedores, dejando a las personas no técnicas sin nada que puedan entender.

Esta guía es un análisis a fondo del nivel 1 del modelo C4: qué es un diagrama de contexto de sistema, qué debe contener exactamente (y qué no), un ejemplo completo resuelto, los errores que arruinan la mayoría de los diagramas de contexto, y un proceso paso a paso para crear uno -- a mano o generado a partir de tu base de código. Si el modelo C4 en sí es nuevo para ti, empieza por nuestra guía completa del modelo C4 y luego vuelve aquí.

¿Qué es un diagrama de Contexto de Sistema?

Un diagrama de Contexto de Sistema es el primero y de más alto nivel del modelo C4. Muestra un sistema de software como una única caja y responde a una sola pregunta: ¿cómo encaja este sistema en su entorno?

Como dice la definición del glosario, el diagrama de Contexto de Sistema se centra en las personas y los sistemas externos que interactúan con el sistema descrito, omitiendo deliberadamente su estructura interna. Su objetivo es establecer el alcance: quién usa el sistema, de qué sistemas depende y qué sistemas dependen de él.

En un diagrama de contexto aparecen tres tipos de elementos, y solo tres:

Tu sistema de software -- una caja, en el centro. No sus servicios, no sus bases de datos. Una caja.
Personas -- los usuarios, roles o personas-tipo que interactúan con el sistema. Un "Cliente", un "Administrador", un "Agente de Soporte".
Sistemas de software externos -- los sistemas con los que el tuyo se comunica pero que tu equipo no posee: una pasarela de pago, un proveedor de correo, un ERP heredado, un proveedor de identidad.

Lo que los conecta son las relaciones: flechas etiquetadas que describen quién hace qué. "Realiza pedidos mediante", "Envía solicitudes de pago a", "Recibe actualizaciones de envío de".

Ese es todo el vocabulario. Cajas para el sistema, las personas y los sistemas externos; flechas para las relaciones. La disciplina del diagrama proviene de lo que dejas fuera.

¿Quién es la audiencia?

El diagrama de Contexto de Sistema es único entre los cuatro niveles del C4 porque está pensado para todo el mundo -- incluidas personas que nunca leerán una línea de código:

Personas no técnicas. Un product manager, un CEO o un responsable de cumplimiento puede mirar un diagrama de contexto y entender el propósito del sistema, sus usuarios y sus dependencias de terceros en menos de un minuto.
Nuevos miembros del equipo. Antes de que un nuevo ingeniero aprenda tu estructura de carpetas, debería aprender el límite de tu sistema. El diagrama de contexto es la primera diapositiva del onboarding.
Arquitectos y revisores de seguridad. Cada flecha que cruza el límite del sistema es un punto de integración, un flujo de datos y una posible superficie de ataque. Las revisiones de seguridad y cumplimiento a menudo empiezan aquí.
Otros equipos. Cuando otro equipo pregunta "¿tu sistema llama directamente a la API de facturación?", el diagrama de contexto responde sin necesidad de una reunión.

Por eso las decisiones tecnológicas no tienen cabida aquí. En el momento en que escribes "PostgreSQL" o "Kafka" en un diagrama de contexto, has reducido la audiencia a ingenieros -- y para eso tienes el diagrama de Contenedores.

Qué debe contener un diagrama de contexto (y qué no)

Incluir

El sistema en cuestión -- exactamente una caja, claramente nombrada.
Cada categoría de usuario -- no personas individuales, sino roles o personas-tipo. Si los clientes y el personal de almacén usan el sistema de forma distinta, son dos cajas-persona separadas.
Cada dependencia de sistema externo -- incluidas las que das por sentadas: el servicio de correo, el proveedor de identidad, la plataforma de analítica, el stack de monitorización si es arquitectónicamente relevante.
Sistemas que dependen de ti -- si el sistema de un socio consume tu API, debe figurar en el diagrama con la flecha apuntando hacia ti.
Relaciones etiquetadas -- cada flecha necesita una frase verbal. Una flecha sin etiqueta es un signo de interrogación.

Excluir

Contenedores -- nada de aplicaciones web, servicios de API, bases de datos ni colas de mensajes. Eso es el nivel 2.
Decisiones tecnológicas -- nada de "React", "Go" ni "PostgreSQL". Un diagrama de contexto debería sobrevivir a una reescritura completa de tu stack sin cambiar.
Estructura interna de sistemas externos -- Stripe es una caja, no un diagrama de la arquitectura de Stripe.
Detalles de infraestructura y despliegue -- nada de regiones, clústeres ni balanceadores de carga.
Funcionalidades individuales -- el diagrama muestra relaciones, no una lista de funcionalidades.

Una prueba sencilla: si eliminar un elemento no cambiaría quién interactúa con el sistema ni qué sistemas externos toca, ese elemento no pertenece al nivel 1.

Un ejemplo completo de diagrama de contexto: plataforma de pagos en línea

Veámoslo con un ejemplo realista. Imagina que estás documentando PayFlow, una plataforma de pagos en línea que permite a los comercios aceptar pagos con tarjeta en sus sitios web.

Paso 1: nombra el sistema

Una caja en el centro: Plataforma de Pagos PayFlow. Dale una descripción de una línea: "Permite a los comercios aceptar y gestionar pagos con tarjeta en línea."

Paso 2: identifica las personas

¿Quién interactúa con PayFlow, y en qué rol?

Comercio -- un propietario de negocio que configura las páginas de pago, consulta las transacciones y emite reembolsos.
Cliente Final -- un comprador que paga una compra a través de un checkout de PayFlow.
Agente de Soporte -- personal interno que investiga transacciones en disputa.

Paso 3: identifica los sistemas externos

¿De qué depende PayFlow, y qué depende de PayFlow?

Redes de Tarjetas / Banco Adquirente -- autoriza y liquida las transacciones con tarjeta.
Servicio de Detección de Fraude -- puntúa las transacciones según su riesgo de fraude.
Servicio de Correo -- envía recibos y notificaciones.
Proveedor de Identidad -- gestiona el inicio de sesión único de los comercios.
Sitio de E-Commerce del Comercio -- el propio sitio web del comercio, que integra el checkout de PayFlow y consume la API de PayFlow.
Plataforma de Contabilidad -- recibe informes de liquidación para la contabilidad del comercio.

Paso 4: dibuja las relaciones

La lista completa de elementos y relaciones se ve así:

People:
  [Merchant]          --> [PayFlow] : Configures payments, views transactions, issues refunds
  [End Customer]      --> [PayFlow] : Pays for purchases via hosted checkout
  [Support Agent]     --> [PayFlow] : Investigates and resolves disputes

External systems:
  [Merchant E-Commerce Site] --> [PayFlow] : Initiates payments via API, embeds checkout
  [PayFlow] --> [Card Networks / Acquiring Bank] : Authorizes and settles card transactions
  [PayFlow] --> [Fraud Detection Service] : Requests risk scores for transactions
  [PayFlow] --> [Email Service] : Sends receipts and payment notifications
  [PayFlow] --> [Identity Provider] : Delegates merchant authentication
  [PayFlow] --> [Accounting Platform] : Exports settlement reports

Diez elementos en total: un sistema, tres personas, seis sistemas externos. Cada flecha tiene una frase verbal. No se menciona ningún servicio, base de datos, cola ni lenguaje -- y aun así, cualquiera que lea este diagrama entiende qué es PayFlow, quién lo usa y de qué depende.

Fíjate en lo que este diagrama hace inmediatamente visible:

Superficie de cumplimiento. Las redes de tarjetas y la detección de fraude en el diagrama le indican a un revisor de seguridad exactamente por dónde fluyen los datos relevantes para PCI.
Riesgo de proveedores. Seis dependencias externas, cada una un posible punto de fallo o de negociación contractual.
Límite bidireccional. El sitio de e-commerce del comercio llama hacia dentro de PayFlow -- el sistema no es solo un consumidor de otros servicios, también es una dependencia para alguien más.

Ese es el tipo de conversación que un diagrama de contexto está hecho para iniciar.

Errores comunes en los diagramas de Contexto de Sistema

Error 1: demasiado detalle

El fallo más habitual. El diagrama empieza limpio, luego alguien añade "solo la base de datos principal", después el API gateway, luego los tres microservicios principales, y en cuestión de un mes es un diagrama de Contenedores disfrazado con el nombre de un diagrama de contexto. La solución es implacable: tu sistema es una caja. Si sientes el impulso de mostrar internos, esa es la señal para crear un diagrama de Contenedores como una vista separada y enlazada -- no para sobrecargar este.

Error 2: dependencias externas que faltan

Los equipos olvidan con regularidad las dependencias que consideran aburridas: el proveedor de correo, la pasarela de SMS, el proveedor de identidad, la CDN, el servicio de feature flags. Pero las dependencias "aburridas" causan caídas reales y dependencia real de proveedores. Recorre tus archivos de configuración y tus variables de entorno -- cada clave de API suele corresponder a un sistema externo que pertenece al diagrama.

Error 3: mezclar niveles de abstracción

Un diagrama que muestra "Cliente → App Web → API de Pedidos → PostgreSQL → Stripe" mezcla una persona, dos contenedores, una base de datos y un sistema externo en una sola vista plana. Quien lo lee no puede saber dónde está el límite de tu sistema. Cada diagrama C4 debe vivir en exactamente un nivel de zoom; todo el sentido de la jerarquía del modelo C4 es que haces zoom entre diagramas, nunca dentro de uno.

Error 4: relaciones sin etiquetar o vagas

"Usa" no es una etiqueta de relación -- todo "usa" todo. Escribe lo que de verdad ocurre: "Envía pedidos mediante", "Recibe eventos de webhook de", "Se autentica contra". Las etiquetas son donde vive la mayor parte de la información del diagrama.

Error 5: dibujarlo una vez y no actualizarlo nunca

Un diagrama de contexto de 2023 que todavía muestra el CRM heredado que migraste el año pasado induce a error de forma activa. Los diagramas de contexto cambian con menos frecuencia que los de niveles inferiores, pero cambian -- cada nueva integración con un proveedor, cada API de socio descontinuada. Trata el diagrama como documentación viva, no como un artefacto de arranque.

Cómo crear un diagrama de Contexto de Sistema: paso a paso

El enfoque manual

Nombra y describe el sistema. Una frase: ¿qué hace y para quién?
Lista los roles de usuario. Haz una lluvia de ideas de cada persona-tipo distinta que interactúa con el sistema. Fusiona los roles que interactúan de forma idéntica; separa los que no.
Lista los sistemas externos. Repasa las integraciones, las claves de API, los webhooks, las exportaciones programadas. Incluye los sistemas que te llaman, no solo los que tú llamas.
Dibuja las relaciones. Una flecha por cada interacción significativa, cada una etiquetada con una frase verbal. La dirección sigue la iniciativa: ¿quién inicia la interacción?
Revísalo con el equipo. Este es el paso de mayor valor. Una revisión de 30 minutos saca a la luz desacuerdos de forma fiable: "espera, ¿todavía llamamos a ese servicio?", "¿desde cuándo los socios pegan directamente a nuestra API?". Esos debates son el entregable.
Publícalo donde la gente lo encuentre -- no enterrado en una página de wiki que nadie visita.

Cualquier herramienta sirve para el dibujo en sí: una pizarra, diagrams.net, Structurizr, PlantUML con extensiones C4. El cuello de botella nunca fue el dibujo -- son los pasos 2, 3 y 5, y mantener el resultado preciso con el tiempo.

El enfoque automatizado: generar diagramas de contexto con Archyl

Aquí es donde Archyl toma un camino distinto al de las herramientas de dibujo. En lugar de partir de un lienzo en blanco, conectas tus repositorios y ejecutas el descubrimiento por IA: Archyl analiza la estructura de tu código, tus archivos de configuración y tus grafos de dependencias, y luego propone un borrador de modelo C4 -- sistemas, dependencias externas, contenedores, componentes y las relaciones entre ellos. Revisas cada sugerencia, la aceptas o la ajustas, y la vista de Contexto de Sistema se renderiza automáticamente a partir del modelo.

Como el diagrama se genera a partir de un modelo en lugar de dibujarse a mano, se derivan dos cosas:

Los niveles se mantienen conectados. La caja del sistema en tu diagrama de contexto es la misma entidad en la que profundizas para la vista de contenedores. No hay desfase por copiar y pegar entre diagramas.
La obsolescencia se vuelve medible. La detección de drift de Archyl compara de forma continua tu arquitectura documentada con lo que existe de verdad en la base de código, así que cuando una integración se elimina o un servicio se renombra, te enteras por una puntuación de drift en lugar de por una nueva incorporación confundida.

Si prefieres documentación que viva en el control de versiones, Archyl también admite un flujo de Arquitectura como Código: define tu modelo C4 en YAML, confírmalo junto a tu código y deja que los diagramas se rendericen a partir de esa definición.

Del contexto a los contenedores

El diagrama de Contexto de Sistema establece el límite; el siguiente nivel abre la caja. Una vez que tu diagrama de contexto es estable, el siguiente paso natural es el diagrama de contenedores -- la vista de nivel 2 que muestra las unidades desplegables (aplicaciones web, APIs, bases de datos, brokers) dentro de tu sistema y cómo se comunican. Lo cubrimos en detalle en nuestra guía del diagrama de Contenedores C4.

La progresión importa. Los equipos que se saltan el diagrama de contexto y empiezan en el nivel 2 tienden a producir diagramas de contenedores con límites difusos -- sistemas externos mezclados con servicios internos, porque nadie acordó nunca dónde termina el sistema.

Preguntas frecuentes

¿Cuál es la diferencia entre un diagrama de Contexto de Sistema y un diagrama de Contenedores?

El diagrama de contexto (nivel 1) muestra tu sistema como una única caja y se centra en su entorno: usuarios y sistemas externos. El diagrama de contenedores (nivel 2) hace zoom dentro de esa caja para mostrar las unidades desplegables -- aplicaciones web, servicios, bases de datos -- y sus decisiones tecnológicas. El contexto responde a "¿con qué interactúa este sistema?"; los contenedores responden a "¿de qué está hecho este sistema?".

¿Cuántos elementos debe tener un diagrama de contexto?

No hay una regla estricta, pero la mayoría de los diagramas de contexto sanos tienen un sistema, de dos a cinco roles de usuario y de tres a diez sistemas externos. Si pasas de quince o veinte elementos, o bien el límite de tu sistema es demasiado amplio, o estás documentando un paisaje empresarial -- en cuyo caso el diagrama de Paisaje de Sistemas C4 (varios sistemas en una vista) encaja mejor.

¿Deben aparecer las bases de datos en un diagrama de Contexto de Sistema?

No -- siempre que la base de datos pertenezca a tu sistema, es un detalle interno y aparece en el nivel de contenedores. La excepción es una base de datos operada por otro equipo o proveedor desde la que tu sistema lee directamente; eso es, en la práctica, un sistema externo y puede aparecer como tal.

¿Es un diagrama de contexto C4 lo mismo que un diagrama de contexto UML o de flujo de datos?

Conceptualmente son primos -- la idea de un "diagrama de contexto" (un sistema, su entorno) es anterior a C4 y existe en el análisis estructurado y en la práctica de UML. La versión C4 se distingue por su lugar en una jerarquía: cada elemento que contiene puede descomponerse en el siguiente nivel inferior, lo que te da un mapa navegable en lugar de una imagen aislada.

¿Listo para crear tu diagrama de Contexto de Sistema? Prueba Archyl gratis y genera un modelo C4 directamente a partir de tus repositorios. O sigue leyendo: ¿Qué es el modelo C4? Guía completa | Guía del diagrama de Contenedores C4 | Diagrama de Contexto de Sistema en el glosario.

Diagrama de Contexto de Sistema C4: guía completa con ejemplos - Archyl Blog