de_DEen_USes_ESfa_IRfr_FRhi_IN

Acercándose al máximo: comprensión de los diagramas de código C4 – qué son, cuándo aportan valor y ejemplos prácticos de PlantUML

¿Qué es un diagrama de código C4?

El diagrama de código esNivel 4— el nivel más profundo y detallado en el modelo C4 de Simon Brown.

The Ultimate Guide to C4 Model Visualization with Visual Paradigm's AI Tools - ArchiMetric

Muestra:

  • Clases, interfaces, enums, registros, u otros constructos de nivel de código que implementan un componente específicocomponente (del Nivel 3).

  • Relaciones entre esas clases (herencia, composición, dependencia, realización de interfaces, etc.).

  • Elementos claveelementos de diseño tales como patrones aplicados dentro del componente (por ejemplo, repositorios, servicios, DTOs, entidades de dominio, fábricas).

En la práctica, este nivel casi siempre es undiagrama de clases UML (o una variante simplificada) centrado en un componente (o muy pocos).

Aclaración importante:

  • El Nivel 4 esno sobre todo el código base.

  • No esno necesario para mostrar cada clase.

  • Mapea solo la estructura esencial necesario para entender cómo se construye en realidad un componente complejo o crítico.

  • La recomendación oficial de C4: idealmente generada automáticamente a partir del código fuente (mediante herramientas como Doxygen, Javadoc + complementos UML, yWorks, Structurizr, CodeSee, etc.) en lugar de dibujada a mano.

Cuándo crear un diagrama de código

Crea diagramas de nivel 4 con moderación — solo en estas situaciones:

  • El componente es altamente complejo, crítico para la misión, o difícil de entender a partir del código fuente solo (por ejemplo, lógica de dominio compleja, uso intensivo de patrones de diseño, flujos criptográficos, máquinas de estado, código heredado plagado de deuda técnica).

  • Estás trabajando en un industria altamente regulada (finanzas, salud, aeroespacial, defensa) donde los auditores o equipos de cumplimiento exigen un mapeo explícito desde arquitectura → diseño → implementación.

  • Durante refactorización importante, estrangular un componente heredado, o introducir un nuevo patrón arquitectónico (hexagonal, limpio, corte vertical, agregados de DDD) — las vistas antes/después ayudan a comunicar el cambio.

  • Integración de desarrolladores senior o arquitectosquienes necesitan comprender rápidamente la estructura interna no obvia de un fragmento de código de alto riesgo.

  • Ya has invertido en generación automáticaherramientas — por lo tanto, mantener el Nivel 4 cuesta casi nada.

  • El equipo ha acordado que «documentación viviente»a nivel de clase es valioso para este subsistema específico.

No crees diagramas de Nivel 4 cuando:

  • La estructura de componentes es evidente por un buen nombre, tamaño pequeño o código limpio (la mayoría de los microservicios modernos caen aquí).

  • Ya tienes buenas pruebas unitarias/integración, interfaces claras, y comentarios explicativos.

  • La mayoría del equipo puede navegar por el código fácilmente.

  • El costo de mantenimiento supera el beneficio (los diagramas de clases dibujados a mano envejecen muy rápidamente).

Simon Brown y la mayoría de los profesionales enfatizan: La mayoría de los equipos nunca necesitan el Nivel 4. Niveles 1 + 2cubren del 80 al 90 % de las necesidades de comunicación; Nivel 3maneja la mayor parte del resto. El Nivel 4 es la excepción, no la regla.

¿Por qué usar diagramas de código? (Cuando aportan valor)

  • Puente entre arquitectura ↔ implementación— Muestra cómo los componentes de alto nivel se realizan realmente en código.

  • Aclarar el diseño interno complejo— Exponen el uso de patrones (Estrategia, Fábrica, Decorador, Repositorio), violaciones de capas, acoplamiento fuerte o modelado inteligente del dominio.

  • Apoyar auditorías y cumplimiento — Demuestra que las decisiones arquitectónicas se siguen hasta el código.

  • Ayudar a las discusiones de refactorización y migración — Las estructuras de clases antes/después hacen que las propuestas sean tangibles.

  • Reducir el conocimiento tribal — Ayuda a los nuevos contratos senior a entender las partes no triviales más rápido que leyendo todos los archivos de origen.

  • Las versiones generadas automáticamente se convierten en ‘documentos vivos’ — Si hay herramientas disponibles, permanecen precisas con casi ningún esfuerzo.

Cómo crear un diagrama de código excelente (paso a paso + mejores prácticas)

  1. Elige UN componente — Generalmente desde un diagrama de nivel 3 donde la complejidad interna justifica el acercamiento.

  2. Decide: dibujado a mano o generado?

    • Dibujado a mano → solo para talleres, propuestas o áreas demasiado desordenadas para herramientas automáticas.

    • Generado → preferido (PlantUML aún se puede usar para estilizar/ajustar la salida).

  3. Enfócate en lo esencial — Muestra:

    • Clases/interfaces clave

    • Relaciones importantes (→ dependencia, — composición, <| realización, ^ herencia)

    • Agregados, entidades, objetos de valor (estilo DDD)

    • Patrones críticos o anti-patrones que deseas resaltar

  4. Manténlo pequeño — Máximo 8–15 clases. Si es más grande → divídelo en diagramas enfocados (por ejemplo, ‘rebanada de autenticación’, ‘entidades de procesamiento de pedidos’).

  5. Mejores prácticas

    • Prefiere generación automática cuando sea posible (menos obsolescencia).

    • Usa sintaxis classDiagram de PlantUML sintaxis — limpia y versionable.

    • Añade notas para decisiones no obvias (por ejemplo, “Utiliza un modelo de dominio anémico – refactorización planeada”).

    • Evita mostrar todo — omite getters/setters triviales, clases de utilidad.

    • Almacena en el repositorio → trata como código (confirma los archivos .puml cerca del componente).

    • Úsalo con moderación — uno por componente complejo, no por microservicio.

    • Combínalo con vistas dinámicas (secuencia/collaboración) si el flujo en tiempo de ejecución es más importante que la estructura estática.

Ejemplo de PlantUML – Componente de Autenticación (extensión de estilo Big Bank plc)

Aquí tienes un ejemplo real de nivel 4 que se enfoca en el Componente de Seguridad / Autenticación de los diagramas de aplicación de API anteriores.

@startuml
título Diagrama de código C4 Nivel 4: Autenticación dentro de la Aplicación de API

skinparam monochrome verdadero
skinparam shadowing falso
skinparam class {
  BackgroundColor Blanco
  BorderColor Negro
  ArrowColor Negro
}

clase abstracta AuthenticationProvider {
  + authenticate(credentials): Authentication
}

class JwtAuthenticationProvider {
  - tokenProvider: JwtTokenProvider
  - userDetailsService: UserDetailsService
  + authenticate(credentials): Authentication
}

class JwtTokenProvider {
  - secretKey: String
  - validityInMilliseconds: long
  + generateToken(userDetails): String
  + validateToken(token): boolean
  + getUsernameFromToken(token): String
}

interfaz UserDetailsService {
  + loadUserByUsername(username): UserDetails
}

class DatabaseUserDetailsService {
  - userRepository: UserRepository
  + loadUserByUsername(username): UserDetails
}

class UserRepository {
  + findByUsername(username): Optional<User>
}

class User {
  - username: String
  - passwordHash: String
  - roles: Set<Role>
}

class JwtAuthenticationToken << (T,orchid) Authentication >> {
  - principal: UserDetails
  - credentials: Object
  - authorities: Collection<GrantedAuthority>
}

' Relaciones
JwtAuthenticationProvider -arriba-> JwtTokenProvider : utiliza
JwtAuthenticationProvider -arriba-> UserDetailsService : utiliza
DatabaseUserDetailsService .arriba.|> UserDetailsService
DatabaseUserDetailsService --> UserRepository : utiliza
UserRepository --> User : devuelve

JwtAuthenticationToken .arriba.|> Authentication

nota a la derecha de JwtAuthenticationProvider
  Flujo principal de autenticación para sesiones sin estado basadas en JWT
fin nota

nota abajo de JwtTokenProvider
  Firma y verifica JWTs usando HS512
fin nota

@enduml

Este pequeño diagrama:

  • Se enfoca únicamente en los internos de la autenticación

  • Muestra las clases clave, interfaces y dependencias

  • Destaca patrones (proveedor, repositorio)

  • Utiliza notas para contexto

Pégalo en cualquier renderizador de PlantUML — personalízalo para tu dominio (por ejemplo, reemplaza JWT con OAuth2, agrega clases de MFA, etc.).

Recordatorio resumen: El nivel 4 es potente pero raro. Úsalo intencionalmente, prefiere la generación automática, y nunca permitas que se convierta en trabajo tedioso. La mayor parte del valor en C4 proviene de los niveles 1 a 3. ¡Feliz modelado (selectivo)!

Recurso