Skip to main content

Diagrames d’arquitectura

Aquest document explica on i com gestionem els diagrames de l’arquitectura de LDP (Line Dance Platform).

L’objectiu és:

  • tenir tots els diagrames versionats al repo,
  • poder-los editar fàcilment (Draw.io, Mermaid, PlantUML…),
  • enllaçar-los des de la documentació de Docusaurus.

1. Ubicació dels diagrames​

Hi ha dos llocs principals:

  1. Fitxers font (editable)

    • Carpeta suggerida: docs-web/static/diagrams/src/
    • Formats típics:
      • .drawio (diagrames editables amb Draw.io),
      • .puml (PlantUML),
      • .mmd (Mermaid),
      • altres formats editables que es decideixin.

  2. Exports per a la web

    • Carpeta suggerida: docs-web/static/diagrams/export/
    • Formats:
      • .png / .svg generats a partir dels fitxers font.

Els documents de Docusaurus no haurien de contenir imatges “manuals” fora d’aquest esquema, per poder regenerar fàcilment els diagrames.

2. Tipus de diagrames​

2.1. C4 – Vista alta​

Diagrames de tipus C4 Model per explicar:

  • Context: qui interactua amb LDP (usuari final, professor, organitzador, APIs externes…).
  • Containers: backend, frontend, app mòbil, BD, sistemes externs.
  • Components (opcional, quan calgui): parts internes del backend o del frontend.

Fitxers suggerits:

  • architecture_c4_context.drawio
  • architecture_c4_containers.drawio

Es referencien des d’architecture/architecture-overview.md.

2.2. ERD – Model de dades​

Diagrames de model relacional de la BD:

  • entitats principals (dances, songs, choreographers, events, venues, locations…),
  • relacions i cardinalitats,
  • camps clau i FKs importants.

Fitxers suggerits:

  • db_erd_core.drawio – model de dades principal,
  • db_erd_import_staging.drawio – model per al sistema d’import.

Es referencien des d’architecture/db-redesign-plan.md.

2.3. Fluxos i seqüències​

Per funcionalitats concretes:

  • Sistema d’importació: des del CSV/API fins a import_staging i publicació.
  • Ownership requests: flux CLAIM / TRANSFER amb Admin i usuaris.
  • Events wizard: passos de l’assistent d’alta/modificació d’esdeveniments.

Fitxers suggerits:

  • flow_import_system.mmd (Mermaid),
  • sequence_ownership_request.puml (PlantUML).

Es referencien des dels docs d’arquitectura corresponents.

3. Estàndards de nomenclatura​

Per facilitar la cerca dins del repo:

  • Prefixar pel domini:
    • architecture_*, db_*, flow_*, sequence_*, ui_*, etc.
  • Utilitzar snake_case i noms descriptius:
    • db_events_classes_locations.drawio,
    • flow_import_csv_to_staging.mmd.

Evitar noms genèrics com diagram1.png, untitled.puml, etc.

4. Ús de Mermaid a Docusaurus​

Per diagrames senzills, es pot utilitzar Mermaid directament al .md.

Exemple:

flowchart LR
  A[CSV] --> B[Import service]
  B --> C[import_staging]
  C --> D[Admin review]
  D --> E[Publish to domain tables]

Recomanacions:

  • Utilitzar Mermaid per diagrames simples i textuals.
  • Reservar Draw.io / PlantUML per diagrames complexos o més visuals.

5. Flux de treball recomanat​

  1. Crear o editar el diagrama al format font (.drawio, .puml, .mmd, etc.).
  2. Exportar-lo a .png o .svg a static/diagrams/export/.
  3. Referenciar la imatge des del .md, per exemple:
![C4 Containers](../../static/diagrams/export/architecture_c4_containers.png)
  1. Fer commit tant del fitxer font com de l’export.
  2. Si hi ha un canvi rellevant de model o arquitectura:
    • Actualitzar també els docs relacionats (architecture-overview, db-redesign-plan, etc.).

6. Responsabilitats​

Arquitectura / Data Steward​

  • mantenir els diagrames de model de dades i C4,
  • garantir que no es queden desactualitzats.

Desenvolupament​

  • proposar nous diagrames quan apareguin funcionalitats complexes,
  • actualitzar diagrames de flux quan es canviïn processos.

Aquest document pot anar evolucionant a mesura que es vagin afegint nous tipus de diagrames o eines.
L’important és centralitzar i documentar sempre on es troben i com s’han d’actualitzar.