Diagrammi C4 in Confluence

Un diagramma C4 descrive il software a un livello di dettaglio scelto: contesto, container, componenti o deployment.

Ultimo aggiornamento

Quando usarlo

Usa un diagramma C4 quando lettori diversi hanno bisogno di profondità diverse. La vista di contesto mostra utenti e sistemi vicini a chiunque; le viste dei container e dei componenti scendono di un livello per chi lo costruisce. Ogni elemento ha un nome, una tecnologia e una breve descrizione.

Esempio

Questo è il codice del modello System context: utenti, piattaforma e sistemi esterni in una vista C4.

C4Context
  title System context for a SaaS platform
  Person(customer, "Customer", "Manages a subscription and its billing")
  Person(admin, "Administrator", "Configures tenants, users and plans")
  Enterprise_Boundary(company, "Company") {
    System(platform, "SaaS platform", "Serves customers and administrators")
  }
  System_Ext(payments, "Payment provider", "Charges cards and issues refunds")
  System_Ext(email, "Email service", "Delivers transactional email")
  System_Ext(idp, "Identity provider", "Authenticates users with single sign-on")
  Rel(customer, platform, "Uses", "HTTPS")
  Rel(admin, platform, "Manages", "HTTPS")
  Rel(customer, idp, "Signs in", "OpenID Connect")
  Rel(platform, idp, "Verifies tokens", "OpenID Connect")
  Rel(platform, payments, "Charges cards", "REST / JSON")
  Rel(platform, email, "Sends email", "SMTP")
  UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Vellnar Diagrams lo disegna così:

Cambia una riga e il diagramma cambia con lei. A nessuno serve il file originale del disegno, perché non esiste: il codice è il diagramma.

Aggiungerlo a una pagina di Confluence

  1. Modifica una pagina di Confluence e scrivi /mermaid dove vuoi il diagramma.
  2. Seleziona Mermaid diagram. Si apre l’editor con l’elenco dei modelli.
  3. Scegli un modello, oppure Start blank e incolla il codice qui sopra. L’anteprima segue ogni tasto.
  4. Scegli Save. Il diagramma compare nella pagina.

La documentazione spiega l’editor, le impostazioni e le esportazioni.

Modelli

Il pulsante Templates dell’editor ha 2 modelli pronti per questo tipo:

  • System context: Utenti, piattaforma e sistemi esterni in una vista C4.
  • Event streaming: Un topic partizionato, i suoi gruppi di consumer, un topic dead-letter e uno schema registry.

Sintassi

Il codice inizia con C4Context. La documentazione di Mermaid (in inglese) descrive ogni elemento della sintassi. Vellnar Diagrams lo disegna con Mermaid 12.3; se una riga ha un errore, l’editor segna la riga e tiene a schermo l’ultimo diagramma valido.

Altro

  • Mermaid in Confluence: come funzionano i diagrammi scritti come codice in una pagina, e tutti i tipi di diagramma.
  • Sicurezza: l’app non chiede nessun permesso e non manda nulla fuori da Atlassian.