====== 03 - Diagramas C4 ======

El modelo **C4** describe la arquitectura de un sistema en cuatro niveles: **Contexto**, **Contenedores**, **Componentes** y **Código**. Cada nivel responde a una pregunta distinta y tiene distinta audiencia.

===== 1. Los cuatro niveles =====

^ Nivel ^ Pregunta ^ Audiencia ^
| **Contexto** | ¿Cómo se relaciona el sistema con personas y sistemas externos? | Cualquier interesado |
| **Contenedores** | ¿Qué aplicaciones y almacenes forman el sistema? | Técnicos y arquitectos |
| **Componentes** | ¿Qué módulos componen cada contenedor? | Desarrolladores |
| **Código** | ¿Cómo se organizan las clases? | Desarrolladores del componente |

Los tres primeros son los más usados; el nivel de código es esencialmente el diagrama de clases del tema anterior.

===== 2. Elementos =====

  * **Persona:** usuario del sistema.
  * **Sistema de software:** el conjunto completo; en el nivel de contexto es la caja mayor.
  * **Contenedor:** unidad ejecutable o almacén de datos: aplicación web, API, base de datos, cola de mensajes.
  * **Componente:** módulo con responsabilidad dentro de un contenedor.
  * **Relación:** conecta elementos, normalmente con su tecnología y protocolo (HTTP, JDBC...).

===== 3. Contexto =====

<sxh java>
@startuml
!include <C4/C4_Context>

Person(student, "Estudiante", "Consulta el catálogo")
System(biblioteca, "Sistema de biblioteca", "Gestiona libros y préstamos")

Rel(student, biblioteca, "Usa", "HTTPS")
@enduml
</sxh>

El nivel de contexto no entra en detalles internos: solo muestra el sistema, sus usuarios y los sistemas externos con los que habla.

===== 4. Contenedores =====

<sxh java>
@startuml
!include <C4/C4_Container>

Person(student, "Estudiante", "Consulta el catálogo")
System_Boundary(c1, "Sistema de biblioteca") {
  Container(spa, "Aplicación web", "TypeScript", "Interfaz del usuario")
  Container(api, "API REST", "Java, Spring Boot", "Expone la lógica")
  ContainerDb(db, "Base de datos", "MariaDB", "Guarda libros y préstamos")
}

Rel(student, spa, "Usa", "HTTPS")
Rel(spa, api, "Llama a", "HTTPS/JSON")
Rel(api, db, "Lee y escribe", "JDBC")
@enduml
</sxh>

Aquí aparecen las tecnologías y los protocolos. Para el monolito por capas que se construye en 1.º, el diagrama de contenedores muestra aplicación, API y base de datos.

===== 5. Componentes =====

<sxh java>
@startuml
!include <C4/C4_Component>

Component(ctrl, "Controller", "Recibe peticiones HTTP")
Component(svc, "Service", "Reglas de negocio")
Component(repo, "Repository", "Acceso a datos")

Rel(ctrl, svc, "invoca")
Rel(svc, repo, "usa")
@enduml
</sxh>

El nivel de componentes muestra la organización interna de un contenedor, por ejemplo las capas del monolito.

===== 6. Cuándo usar cada nivel =====

^ Situación ^ Diagrama ^
| Explicar el sistema a alguien nuevo | Contexto |
| Decidir tecnologías o despliegue | Contenedores |
| Planificar el código de un módulo | Componentes |
| Diseñar o revisar clases | Código (diagrama de clases) |

<note tip>No hay que dibujar los cuatro niveles siempre: se elige el nivel que responde a la pregunta que se quiere contestar. Mantener los diagramas actualizados importa más que el detalle.</note>