Arquitectura como código: modelo C4, DSL y navegación para agentes de IAA fondo · digest del 7 de noviembre
Modelo isométrico multinivel C4 formado por cuatro plataformas de cristal flotantes Context, Containers, Components y Code que emergen de un archivo Structurizr DSL.
A fondo6 secciones≈ 16 min

Arquitectura como código: modelo C4, DSL y navegación para agentes de IA

Recuerda cómo suele ser una reunión de arquitectura en un equipo de producto promedio. Alguien abre una pizarra online en Miro o Confluence donde hay dibujados una quincena de rectángulos de colores con etiquetas como «Servicio de autenticación», «Bus de datos» y «Backend». Las flechas apuntan en todas direcciones a la vez: unas muestran llamadas de red, otras flujo de datos y otras dependencias de despliegue. A la pregunta «¿Y qué hay dentro del servicio de autenticación?», el tech lead suspira y dice: «Ahí hay legado en Express, la mitad se reescribió en Go, en el esquema no sale, hay que mirarlo en producción».

Tres meses después el proyecto crece, aparecen nuevos microservicios y el viejo dibujo se convierte en un monumento histórico que nadie necesita. Los desarrolladores dejan de mirar la documentación porque miente, y las decisiones de arquitectura se toman «sobre la marcha» directamente en las ramas del repositorio.

A principios de los años 2000 se intentó combatir este problema con el estándar UML (Unified Modeling Language), creado por el consorcio OMG. Pero la complejidad académica de UML, con sus catorce tipos de diagramas y sus estrictas notaciones de flechas, se asfixió en la era Agile: los equipos simplemente no daban abasto para actualizar documentos tan pesados. El arquitecto británico Simon Brown propuso una salida genial por su simplicidad: el modelo C4, inspirado en el principio de zoom de los mapas geográficos de Google Maps.

Y hoy este enfoque vive un segundo nacimiento gracias al paradigma Architecture as Code (AaC) y al lenguaje Structurizr DSL. En una serie de profundas investigaciones y charlas, el ingeniero ucraniano Timur Shemsedinov mostró cómo C4 resuelve un problema radicalmente nuevo de 2026: se convierte en un sistema de coordenadas estructurado para agentes de IA (Claude, Cursor, Copilot, Windsurf), salvando a los equipos del consumo explosivo de tokens y de las alucinaciones arquitectónicas.

Analicemos esta mecánica multicapa desde sus abstracciones fundamentales hasta el código práctico y la integración con redes neuronales.

De la burocracia de UML a la escala de Google Maps: orígenes del modelo C4

Para apreciar la elegancia de C4, hay que volver por un segundo a la época de RUP (Rational Unified Process) de finales de los años 1990. El paradigma de ingeniería de aquellos años exigía «diseñarlo todo hasta la última línea antes del primer código». Los analistas pasaban meses dibujando paquetes completos de UML: Use Case Diagrams, Sequence Diagrams, Component Diagrams, Deployment Diagrams.

Pero cuando la industria pasó a los sprints de dos semanas, la entrega continua y los microservicios, en UML afloraron tres vicios sistémicos:

  1. Excesivo academicismo: En lugar de responder a la pregunta «cómo entregar un pedido», los ingenieros en las revisiones discutían sobre la diferencia entre asociación, agregación y composición en un diagrama de clases.
  2. Falta de una jerarquía transversal única: En UML no había ninguna regla estándar para vincular un objetivo de negocio general de la empresa con una base de datos concreta. Los diagramas existían de forma aislada, sin formar un sistema coherente.
  3. Incomprensibilidad para los stakeholders: Un product manager que miraba un UML Deployment Diagram con puertos y artefactos no entendía absolutamente nada, y un desarrollador que miraba un diagrama de casos de uso no veía el stack tecnológico.

Simon Brown se fijó en una analogía sencilla: ¿cómo se orienta una persona en el mundo físico? Abres Google Maps en el smartphone. En la primera pantalla ves continentes y países. Eso permite entender en qué punto del globo nos encontramos. Haces zoom y aparecen las fronteras de las regiones, las grandes ciudades y las autopistas. Un poco más de zoom y ves las calles, los números de las casas y los giros.

El modelo C4 trasladó esta óptica multinivel a la ingeniería del software. Brown definió cuatro niveles estrictos de abstracción:

  • Context (Contexto del sistema);
  • Containers (Contenedores);
  • Components (Componentes);
  • Code (Código).

Cada nivel responde a la pregunta de una audiencia estrictamente definida y recorta el ruido técnico innecesario a esa escala.

Cuatro niveles de abstracción de C4: Context, Containers, Components, Code

Diseccionemos en detalle cada una de las cuatro capas del modelo.

1. Nivel 1: Contexto del sistema (System Context Diagram)

Es la vista a vista de pájaro. En el centro del esquema se sitúa el sistema de software objetivo como una única caja negra. Alrededor se representan las entidades externas: usuarios (actores, roles) y sistemas externos con los que interactúa (pasarelas de pago, CRM, proveedores de correo, registros estatales).

La gran regla de hierro del primer nivel: ningún detalle técnico. Aquí está terminantemente prohibido escribir «PostgreSQL», «Kafka», «gRPC», «Go» o «Linux». Solo roles de negocio y la esencia de los datos transferidos: «El comprador realiza un pedido», «El servicio de pagos realiza el cobro». Este diagrama debe entenderlo a primera vista el director general de la empresa, un inversor y un nuevo becario en su primer día de onboarding.

2. Nivel 2: Contenedores (Container Diagram)

Damos el primer paso de zoom y «miramos dentro» del sistema de software. Y aquí es fundamental no caer en una trampa terminológica: en el modelo C4 un «contenedor» no es un contenedor Docker ni un Pod de Kubernetes.

Para Simon Brown, un contenedor es cualquier unidad de software desplegable o ejecutable de forma independiente que almacena datos o ejecuta código:

  • Una Single Page Application cliente en el navegador (React, Vite);
  • Una aplicación móvil (iOS / Android en Flutter);
  • Un microservicio de API en el servidor (Go, Node.js o Java);
  • Una base de datos relacional (PostgreSQL);
  • Un bróker de mensajes distribuido (Apache Kafka);
  • Un almacenamiento de objetos (MinIO / S3).

El diagrama de contenedores es el plano de trabajo favorito de arquitectos, ingenieros DevOps y desarrolladores backend. Muestra la topología de alto nivel: qué servicios existen, de qué se encarga cada uno, con qué tecnologías están construidos (por ejemplo, NestJS / TypeScript, PostgreSQL 16) y mediante qué protocolos se comunican (JSON/HTTPS, gRPC, Kafka Protocol).

3. Nivel 3: Componentes (Component Diagram)

El siguiente nivel de acercamiento: tomamos un contenedor concreto (por ejemplo, el servicio de API de pedidos) y desglosamos su estructura interna en módulos lógicos y componentes: controladores, servicios de lógica de negocio, adaptadores de integraciones externas, repositorios de acceso a datos.

Aquí reside una recomendación crucial de Brown: no hay que dibujar diagramas de componentes para cada servicio de la empresa. Si un servicio es un simple módulo CRUD de 500 líneas, modelar sus componentes es una pérdida de tiempo. El diagrama de componentes se crea únicamente para servicios arquitectónicamente complejos, de alta carga o no triviales, donde importa fijar la separación de capas de arquitectura limpia o los patrones de tolerancia a fallos.

4. Nivel 4: Código (Code Diagram)

Es el nivel máximo de detalle: diagramas de clases UML o de entidades Entity-Relationship (ER) que muestran interfaces, métodos y dependencias en el código.

El consenso moderno de ingeniería es tajante: el nivel 4 no debe modelarse manualmente bajo ningún concepto. Las clases y las firmas de funciones cambian en cada commit. Mantener el código a mano en esquemas arquitectónicos queda obsoleto al instante. Si un diagrama de clases es realmente necesario, debe generarse automáticamente a partir del árbol AST mediante el compilador o las herramientas del IDE.

Architecture as Code: una única fuente de verdad basada en Structurizr DSL

Cuando los equipos empiezan a adoptar C4, el primer error suele ser intentar dibujar estos diagramas en editores gráficos como Draw.io, Lucidchart o Visio. Es un callejón sin salida.

Imagina que cambia el nombre de un microservicio o que la pasarela de pagos pasa de REST a gRPC. Si los esquemas están dibujados a mano, el arquitecto tiene que abrir el diagrama de contexto, el diagrama de contenedores, tres diagramas de componentes y reescribir manualmente el texto en los bloques gráficos. El factor humano es inevitable: en un esquema el servicio lleva el nombre nuevo, en otro queda el protocolo antiguo y en un tercero se olvidaron de borrar una flecha.

El paradigma Architecture as Code (AaC) traza una frontera fundamental entre el modelo del sistema y sus representaciones visuales (views).

El lenguaje Structurizr DSL, diseñado por Simon Brown, ofrece una sintaxis textual declarativa:

  1. En la raíz se declara el bloque workspace.
  2. Dentro del bloque model se crean una sola vez todos los actores, sistemas, contenedores y relaciones entre ellos.
  3. En el bloque views se declaran los diagramas: systemContext, container, component. El comando include * selecciona por sí mismo los elementos necesarios del modelo único, y el algoritmo autoLayout calcula automáticamente sus coordenadas en pantalla.

Si cambias la tecnología de un servicio en el bloque model, ese cambio se propaga al instante y sin tu intervención a todos los diagramas relacionados del proyecto.

Veamos un ejemplo completo del manifiesto arquitectónico de una tienda online:

workspace "Marketplace" "Modelo arquitectónico de los servicios de comercio electrónico" {

    model {
        customer = person "Comprador" "Usuario de la tienda online que elige productos"
        support = person "Operador de soporte" "Empleado del centro de atención"

        ecommerce = softwareSystem "Plataforma de compras" "Proporciona el escaparate, el procesamiento del carrito y el registro de pedidos" {
            webApp = container "Web SPA" "Interfaz en el navegador del cliente" "React, TypeScript"
            mobileApp = container "Aplicación móvil" "Cliente para iOS y Android" "Flutter"
            apiGateway = container "API Gateway" "Enrutamiento de llamadas y autenticación" "Envoy, Go"
            orderService = container "Servicio de pedidos" "Lógica de negocio de creación y cambio de estados" "Node.js, NestJS"
            paymentService = container "Servicio de pagos" "Interacción con bancos y fiscalización" "Go, gRPC"
            orderDb = container "Base de datos de pedidos" "Almacenamiento de pedidos e historial de transacciones" "PostgreSQL 16"
            eventBus = container "Bus de eventos" "Entrega asíncrona de eventos de dominio" "Apache Kafka"

            # Relaciones entre contenedores dentro del sistema
            webApp -> apiGateway "Envía peticiones API" "JSON/HTTPS"
            mobileApp -> apiGateway "Envía peticiones API" "JSON/HTTPS"
            apiGateway -> orderService "Enruta llamadas de pedidos" "gRPC"
            apiGateway -> paymentService "Enruta pagos" "gRPC"
            orderService -> orderDb "Lee y escribe datos" "TCP/SQL"
            orderService -> eventBus "Publica el evento OrderCreated" "Kafka Protocol"
            paymentService -> eventBus "Suscrito a eventos de pedidos" "Kafka Protocol"
        }

        bank = softwareSystem "Pasarela bancaria" "Procesamiento externo de tarjetas bancarias" "Sistema externo"

        # Interacciones externas
        customer -> webApp "Explora el catálogo y compra" "HTTPS"
        customer -> mobileApp "Usa la aplicación" "HTTPS"
        support -> webApp "Resuelve incidencias de pedidos" "HTTPS"
        paymentService -> bank "Inicia el cargo sin efectivo" "REST/HTTPS"
    }

    views {
        systemContext ecommerce "SystemContext" "Diagrama de contexto de la plataforma" {
            include *
            autoLayout lr
        }

        container ecommerce "Containers" "Topología de contenedores de la plataforma" {
            include *
            autoLayout tb
        }

        styles {
            element "Person" {
                shape Person
                background #08427b
                color #ffffff
            }
            element "Software System" {
                background #1168bd
                color #ffffff
            }
            element "Container" {
                background #438dd5
                color #ffffff
            }
            element "Database" {
                shape Cylinder
            }
        }
    }
}

Este archivo se guarda directamente en el repositorio del proyecto en la ruta docs/architecture/workspace.dsl. Pasa por control de versiones en Git, se revisa mediante Pull Request y cualquier cambio de arquitectura queda visible en un git diff estándar.

Ecosistema de herramientas: Structurizr Lite, exportación a Mermaid y CI/CD

Una descripción textual en código sería inútil si no pudiera mostrarse visualmente a las personas. En torno a Structurizr DSL ha madurado todo un ecosistema de utilidades:

1. Structurizr Lite

Es un servidor web compacto distribuido como contenedor Docker. Se lanza en la máquina local del desarrollador literalmente con un solo comando:

docker run -it --rm -p 8080:8080 -v $(pwd)/docs/architecture:/usr/local/structurizr structurizr/lite

Abres en el navegador http://localhost:8080 y obtienes un mapa interactivo completo del sistema. Puedes acercar la escala, hacer clic en los contenedores, resaltar relaciones y leer la documentación integrada. Al guardar el archivo workspace.dsl en el IDE, el navegador actualiza los diagramas al vuelo al instante.

2. Structurizr CLI y exportación multivendor

Si necesitas incrustar los esquemas en la documentación del proyecto en GitHub o en Confluence, la utilidad de consola structurizr-cli exporta el modelo único a cualquier sintaxis gráfica popular:

# Exportación de diagramas a formato Mermaid para un renderizado limpio en GitHub
structurizr-cli export -w docs/architecture/workspace.dsl -f mermaid -o docs/images/

# Exportación a C4-PlantUML para generar esquemas rasterizados
structurizr-cli export -w docs/architecture/workspace.dsl -f plantuml -o docs/images/

Una alternativa para equipos ya acostumbrados a PlantUML es usar la librería C4-PlantUML, donde una topología similar se declara mediante macros:

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

LAYOUT_WITH_LEGEND()

Person(customer, "Comprador", "Cliente del marketplace")
System_Boundary(c1, "Plataforma de compras") {
    Container(spa, "Web SPA", "React, TS", "Interfaz web cliente")
    Container(gateway, "API Gateway", "Go / Envoy", "Punto de entrada y autenticación")
    Container(orders, "Servicio de pedidos", "NestJS", "Lógica de negocio de pedidos")
    ContainerDb(db, "Base de pedidos", "PostgreSQL", "Almacenamiento relacional")
}

Rel(customer, spa, "Realiza el pedido", "HTTPS")
Rel(spa, gateway, "Peticiones API", "JSON/HTTPS")
Rel(gateway, orders, "Enrutamiento", "gRPC")
Rel(orders, db, "Lectura / escritura", "SQL")
@enduml
3. Linting arquitectónico en CI/CD

Lo mejor del enfoque Architecture as Code es la posibilidad de convertir la documentación arquitectónica en parte obligatoria del pipeline de integración continua. En GitHub Actions o GitLab CI se añade un paso de validación:

structurizr-cli validate -w docs/architecture/workspace.dsl

Si un desarrollador eliminó un servicio del código base pero olvidó reflejarlo en la arquitectura (o creó una dependencia circular), la compilación falla con error. La documentación deja de ser un peso muerto y se convierte en un contrato de ingeniería vivo.

Cuadrícula de coordenadas para agentes de IA: un grafo en lugar de contexto ciego

Y ahora veamos la aplicación más apasionante de los modelos C4, de la que habló Timur Shemsedinov. En 2026 el desarrollo de software se ha transformado de raíz: los programadores ya no escriben todo el código a mano, sino que delegan la implementación de funcionalidades a agentes autónomos de IA (Claude 3.7 Sonnet, OpenAI Codex, Cursor, Windsurf).

Mapa-esquema topológico de Structurizr DSL con el que el agente de IA localiza con precisión los contenedores orderService y orderDb sorteando el resto del repositorio.

Con el crecimiento de las ventanas de contexto de las redes neuronales hasta cientos de miles y millones de tokens, en muchos desarrolladores surgió una ilusión peligrosa: «¿Para qué complicarse estructurando? Volquemos todo el monorrepositorio entero en el prompt y que la red neuronal se aclare sola!»

En la práctica, este enfoque acarrea consecuencias catastróficas:

  1. Callejón sin salida económico y latencia de respuesta: Pasar cientos de miles de tokens en cada paso del ciclo agéntico quema decenas de dólares por petición y obliga al desarrollador a esperar varios minutos por cada generación.
  2. Alucinaciones arquitectónicas y dilución de responsabilidades: Como ya analizamos en detalle en el artículo sobre sistemas de restricciones para asistentes de IA, los grandes modelos de lenguaje no poseen una comprensión innata de las fronteras arquitectónicas. Al ver todo el código sin mapa, el agente empieza a proponer soluciones que rompen la encapsulación: accede directamente a una base de datos ajena saltándose la API del servicio, duplica funciones auxiliares o mezcla la capa de presentación con la lógica de dominio.

El archivo arquitectónico de Structurizr DSL actúa para el agente de IA como un mapa topológico del metro.

En lugar de escanear gigabytes de código fuente, el agente lee en el primer paso un archivo DSL compacto de apenas 3–5 kilobytes. En un par de decenas de milisegundos el modelo obtiene un modelo mental completo del proyecto:

  • Qué servicios existen y cuáles son sus zonas claras de responsabilidad;
  • Qué tecnologías y frameworks se utilizan en cada contenedor;
  • Mediante qué protocolos y con qué garantías interactúan los nodos.

Al recibir una tarea del usuario (por ejemplo, «Añadir cupones de descuento al proceso de compra»), el agente deduce al instante a partir del grafo C4 Containers que los cambios afectan exclusivamente a los contenedores orderService y orderDb. El agente abre de forma dirigida únicamente el directorio apps/order-service, sin tocar millones de líneas en el resto del monorrepositorio. Esto reduce el consumo de tokens en un 80–90% y garantiza que la IA no rompa las convenciones arquitectónicas del equipo.

Límites de aplicabilidad, antipatrones y defensa contra la deriva arquitectónica

Como cualquier herramienta potente de ingeniería, el modelo C4 exige comprender con lucidez sus límites de aplicabilidad y protegerse de los errores típicos:

  • Antipatrón «Microgestión manual de clases»: Intentar describir componentes hasta el nivel de pequeños helpers y DTO convierte el DSL en una rutina insoportable. Mantén el modelo en el nivel de los grandes módulos arquitectónicos.
  • Antipatrón «Dibujos por dibujar»: Si el equipo dibuja C4 en pizarras online sin usar DSL, se pierden todas las ventajas del versionado, el renderizado y la integración con IA.
  • El problema de los procesos dinámicos: El modelo C4 transmite de maravilla la estructura estática de los sistemas, pero sirve poco para visualizar sagas distribuidas temporales complejas, colisiones paralelas y condiciones de carrera. Para esas tareas, los diagramas de secuencia (Sequence Diagrams) siguen siendo insustituibles y complementan perfectamente a C4 en la documentación.
  • Lucha contra la deriva arquitectónica (Architecture Drift): Para que el código no diverja del modelo con el tiempo, los equipos avanzados conectan tests de integridad arquitectónica (ArchUnit en el mundo JVM o ts-arch en TypeScript). Los tests analizan las importaciones reales en el repositorio y las contrastan con las flechas declaradas en workspace.dsl.

Como resultado, Architecture as Code deja de ser una aburrida obligación burocrática. Es un armazón vivo que permite a las personas y a la inteligencia artificial hablar un mismo idioma comprensible y construir sistemas digitales fiables y escalables.

Quiero un análisis detalladoLos votos ayudan a elegir qué analizar a fondo. Este material tiene 0 votos.
Fuentes · 4