Una arquitectura que només existeix al cap del seu autor és una arquitectura perduda. Documentar-la és allò que permet que l'equip l'entengui, que els nous membres s'incorporin ràpidament, que el negoci confiï en allò que es construeix i que les decisions sobrevisquin a la rotació de persones. Però documentar bé és difícil: els diagrames solen quedar obsolets, barrejar nivells de detall o resultar incomprensibles per a qui no els va dibuixar. En aquesta lliçó aprendràs dues eines fonamentals: el clàssic model de vistes 4+1 de Philippe Kruchten i, sobretot, el modern model C4 de Simon Brown, una manera senzilla i pragmàtica de diagramar arquitectures amb quatre nivells de zoom: Context, Contenidor, Component i Codi.

1. Per què documentar i per a qui
2. El model 4+1 de vistes
3. El model C4: la idea del zoom
4. Nivell 1: diagrama de Context
5. Nivell 2: diagrama de Contenidors
6. Nivell 3: diagrama de Components
7. Nivell 4: Codi
8. Bones pràctiques i eines

Documentar no és produir centenars de pàgines que ningú no llegirà. És comunicar de manera eficaç a diferents audiències. La regla principal: documenta just el necessari, per a una audiència concreta i amb un propòsit clar.

Un error clàssic és usar un únic diagrama gegant per a totes les audiències: acaba sent massa detallat per al negoci i massa superficial per al desenvolupador. La solució és oferir diferents vistes a diferents nivells.

Proposat per Philippe Kruchten el 1995, el model 4+1 parteix de la idea que cap vista única no captura tota l'arquitectura. Proposa quatre vistes més una de transversal.

Aquest diagrama Mermaid situa els escenaris al centre, connectats (amb ---, línies sense direcció) a les quatre vistes. La idea és que els casos d'ús clau "lliguen" i validen la resta de vistes: cada escenari important ha de poder recórrer-se a través de la vista lògica, de processos, de desenvolupament i física. El model 4+1 continua sent conceptualment valuós, però en la pràctica diària molts equips prefereixen avui el C4 per la seva senzillesa i el seu mapatge directe a com es construeix realment el programari.

El model C4, creat per Simon Brown, es basa en una analogia amb els mapes: igual que uses diferents nivells de zoom (món, país, ciutat, carrer), una arquitectura s'entén millor amb diferents nivells de detall. C4 defineix quatre nivells, cadascun un "zoom" sobre l'anterior:

Conceptes bàsics de C4:

• Persona: un usuari humà del sistema (client, administrador...).
• Sistema de programari: allò que construeixes (o un sistema extern amb què t'integres).
• Contenidor: no és necessàriament un contenidor Docker; és quelcom que s'executa i es desplega de manera independent: una aplicació web, una API, una base de dades, una single-page app, un broker.
• Component: una agrupació lògica de funcionalitat dins d'un contenidor.

Una regla d'or de C4: la majoria dels equips només necessiten els nivells 1 i 2 de manera habitual, i el 3 ocasionalment. El nivell 4 gairebé mai no es dibuixa a mà, perquè el genera l'IDE.

És el nivell més alt. Mostra el teu sistema com una sola caixa, envoltat dels seus usuaris i dels sistemes externs amb què es relaciona. El seu propòsit és que qualsevol, inclòs el negoci, entengui el panorama general.

Aquest diagrama de Context mostra una única caixa per a "Sistema de Banca en Línia", envoltada d'una persona (el Client) i dos sistemes externs (Email i Core Bancari). Les fletxes etiquetades descriuen què fa cada relació, no com. Fixa't que no apareix cap tecnologia ni detall intern: en aquest nivell només importa l'abast del sistema i les seves interaccions amb l'exterior. És el diagrama ideal per començar qualsevol conversa, també amb persones no tècniques.

Fem zoom dins del nostre sistema. Mostrem les unitats desplegables que el componen i com es comuniquen, indicant ja les tecnologies principals.

Aquí, dins del sistema de banca en línia veiem tres contenidors propis: una aplicació web single-page en React, una API en Java amb Spring Boot i una base de dades PostgreSQL; més el sistema extern (Core Bancari). Cada fletxa indica el protocol de comunicació (HTTPS, JSON, SQL). Aquest nivell és el més útil en el dia a dia tècnic: mostra d'una ullada l'arquitectura de desplegament, les tecnologies escollides i els fluxos de comunicació. Recorda: "contenidor" aquí significa unitat desplegable, no necessàriament un contenidor Docker.

Ara fem zoom dins d'un únic contenidor —per exemple, l'API de Banca— per veure com s'organitza internament en components.

Aquest diagrama usa un subgraph per representar les fronteres de l'API de Banca i mostra tres components interns: el controlador REST que rep les peticions, el servei que conté la lògica de negoci i el repositori que accedeix a les dades. És la clàssica separació en capes (presentació, negoci, dades) dins d'un contenidor. Aquest nivell és valuós perquè els desenvolupadors entenguin l'estructura interna, però convé dibuixar-lo només per als contenidors no trivials, no per a tots.

L'últim nivell detalla com s'implementa un component concret, normalment amb un diagrama de classes UML. A la pràctica, gairebé mai no es dibuixa a mà: el genera automàticament l'IDE o eines de documentació, perquè canvia constantment i mantenir-lo manualment és feina perduda.

Aquest codi mostra com es materialitza el component "Servei de Transferències" en classes concretes. La recomanació de C4 és no dibuixar aquest nivell manualment: si necessites veure'l, deixa que el teu IDE generi el diagrama de classes a partir del codi real. Mantenir diagrames de codi a mà és la causa número u de documentació obsoleta.

Resum de les notacions i pràctiques recomanades per C4:

• Cada diagrama, autoexplicatiu: amb títol, llegenda i elements clarament etiquetats.
• Etiqueta les relacions: descriu què fa cada fletxa i, si escau, amb quina tecnologia/protocol.
• Un nivell per diagrama: no barregis context amb codi.
• No abusis del nivell 3 ni del 4: dibuixa només allò que aporta valor.
• Documentació com a codi (diagrams as code): defineix els diagrames en text per versionar-los al costat del codi i evitar que quedin obsolets.

Eines habituals:

Exemple del mateix diagrama de context en PlantUML amb l'extensió C4:

Aquest fragment PlantUML usa la llibreria oficial C4_Context. Les macros Person, System i System_Ext (sistema extern) creen els elements amb el seu nom i descripció, i Rel defineix les relacions etiquetades. L'avantatge davant de Mermaid és que PlantUML amb C4 coneix la semàntica del model (distingeix persones de sistemes, interns d'externs) i aplica un estil coherent automàticament. En ser text, es versiona al costat del codi i es regenera sense esforç.

• El "diagrama plat d'espaguetis". Un sol diagrama amb tot barrejat no comunica res. Separa per nivells i audiències.
• Diagrames sense llegenda ni etiquetes. Si les caixes i fletxes no s'expliquen, cada lector interpreta el que vol. Etiqueta-ho tot.
• Documentació que envelleix. Els diagrames dibuixats a mà queden obsolets de seguida. Usa diagrams as code i genera el nivell de codi automàticament.
• Excés de detall. No dibuixis els nivells 3 i 4 per a tot. La majoria d'equips viu feliç amb els nivells 1 i 2.
• Consell: comença sempre pel Context. En qualsevol conversa d'arquitectura, arrenca amb el diagrama de context; alinea tothom abans de baixar al detall.

Exercici 1. Associa cada element amb el seu nivell C4: (a) "una base de dades Redis"; (b) "el client i el sistema de pagament extern"; (c) "la classe ServeiComandes"; (d) "el controlador, el servei i el repositori dins de l'API".

Exercici 2. Dibuixa (en Mermaid o PlantUML) un diagrama de Context per a un sistema de gestió d'una biblioteca, amb almenys una persona i un sistema extern.

Exercici 3. Explica per què C4 recomana no dibuixar el nivell de Codi manualment i quina alternativa proposa.

Solució 1. (a) Contenidor (nivell 2): una base de dades és una unitat desplegable. (b) Context (nivell 1): persones i sistemes externs. (c) Codi (nivell 4): una classe concreta. (d) Component (nivell 3): agrupacions lògiques dins d'un contenidor.

Solució 2. Exemple en Mermaid:

Aquest diagrama de Context mostra dues persones (Soci i Bibliotecari), el sistema propi i un sistema extern d'Email, amb relacions etiquetades que descriuen què fa cada interacció, sense entrar en tecnologies ni en l'estructura interna.

Solució 3. Perquè el codi canvia contínuament i mantenir a mà un diagrama de classes el converteix ràpidament en documentació obsoleta i poc fiable, cosa que genera més confusió que ajuda. L'alternativa que proposa C4 és generar aquest nivell automàticament des del mateix codi (amb l'IDE o eines de documentació) quan realment es necessiti, en lloc de dibuixar-lo manualment.

Has après per què i per a qui es documenta una arquitectura, el clàssic model de vistes 4+1 i, en profunditat, el model C4 amb els seus quatre nivells de zoom (Context, Contenidor, Component i Codi), a més de les pràctiques i eines per mantenir la documentació viva mitjançant diagrams as code. Amb això tanques el Mòdul 1, Fonaments de l'Arquitectura d'Aplicacions: ja saps què és l'arquitectura i els seus àmbits, qui és l'arquitecte, com s'especifiquen els atributs de qualitat, com es prenen i documenten les decisions amb els seus trade-offs, i com comunicar-ho tot amb claredat. Sobre aquests fonaments, els mòduls següents aprofundiran en els estils i patrons arquitectònics concrets amb què materialitzar aquestes idees.