Feature: Use mermaidjs for sequence diagrams?

[hanzalahwaheed]

Now that we have mermaidjs support, maybe some of the sequence diagrams can be visualised better with these as mermaid has native support for sequence diagrams.

Advantages of mermaidjs over raw images/SVGs (for sequence diagrams):

1. Mermaid diagrams are much easier to maintain since they are written in plain text, whereas SVGs require manual editing or regenerating from external tools.

2. Contributors can update Mermaid diagrams directly in the Markdown files, which lowers the barrier to contribution compared to editing and exporting SVG files.

3. Changes to Mermaid diagrams are clearly visible in Git diffs, while SVG diffs are mostly coordinate and XML changes that are hard to review.

4. Mermaid removes the need to manage separate static image files, keeping the diagrams co-located with the documentation and simplifying the repository structure.

5. Hugo and GitHub both support Mermaid well, so diagrams render automatically without requiring additional export steps or asset handling.

6. Require separate SVGs for Dark mode (noticed this when I pasted the SVG here).

Created a quick POC to for the maintainers to consider.

Reference: https://precice.org/couple-your-code-coupling-flow.html

SVG

mermaidjs render

sequenceDiagram
    participant FluidSolver
    participant SolidSolver

    Note over FluidSolver,SolidSolver: Initialization
    FluidSolver->>FluidSolver: precice.initialize()
    SolidSolver->>SolidSolver: precice.initialize()

    SolidSolver->>FluidSolver: send mesh (SolidMesh)
    FluidSolver->>FluidSolver: receive mesh

    loop Coupling timestep

        Note over FluidSolver: Solve fluid timestep
        FluidSolver->>FluidSolver: solveTimeStep(...)
        FluidSolver->>FluidSolver: precice.advance()

        Note over FluidSolver: Map write Forces\nFluidMesh → SolidMesh
        FluidSolver->>SolidSolver: send Forces

        Note over SolidSolver: Waiting for Forces
        SolidSolver->>SolidSolver: receive Forces
        SolidSolver->>SolidSolver: solveTimeStep(...)
        SolidSolver->>SolidSolver: precice.advance()

        SolidSolver->>FluidSolver: send Displacements

        Note over FluidSolver: receive Displacements
        FluidSolver->>FluidSolver: Map read Displacements\nSolidMesh → FluidMesh

    end

    Note over FluidSolver,SolidSolver: Finalization
    FluidSolver->>FluidSolver: precice.finalize()
    SolidSolver->>SolidSolver: precice.finalize()

Loading

[hanzalahwaheed]

@MakisH
This can be a nice addition to future-proof the sequence diagrams when we migrate or maybe add a Dark mode for the docs. Please do tell if I should pursue this as a PR.

[precice-bot]

This issue has been mentioned on preCICE Forum on Discourse. There might be relevant details there:

https://precice.discourse.group/t/gsoc-2026-introduction-hanzalah-waheed/2745/5

[MakisH]

This has already been addressed by #726. No reason to keep the issue open specifically for the sequence diagrams, there is a PR.