Skills/mcd-mld-designer/references/diagram-syntax.md

Mermaid Diagram Syntax Guide (Antigravity & VS Code Compatible)

Both Antigravity and Visual Studio Code (via Markdown preview extensions) natively render Mermaid diagrams. To avoid syntax or parsing errors, follow these strict templates.

---

1. MCD Diagram Template (flowchart LR or flowchart TD)

Merise MCDs represent Entities (rectangles) and Associations (rounded/ovals) connected by lines labeled with (min,max) cardinalities.

Syntax Guidelines

1. Always quote edge labels containing commas: ---|"1,N"| (unquoted commas can break Mermaid parsers).
2. Use <br/> for line breaks inside node labels.
3. Keep entity attributes clean with a separator (---).
4. Association nodes use double parentheses ((Name)) or stadium brackets ([Name]).

Code Example

flowchart LR
    %% ENTITIES
    CUSTOMER["CUSTOMER<br/>-------------------<br/>+ CUS_ID (Identifiant)<br/>- CUS_FIRST_NAME<br/>- CUS_LAST_NAME<br/>- CUS_EMAIL"]
    
    ORDER["ORDER<br/>-------------------<br/>+ ORD_ID (Identifiant)<br/>- ORD_DATE<br/>- ORD_TOTAL_AMOUNT"]
    
    PRODUCT["PRODUCT<br/>-------------------<br/>+ PRO_ID (Identifiant)<br/>- PRO_NAME<br/>- PRO_PRICE"]

    %% ASSOCIATIONS
    ASSOC_PASS(["PASSER / PLACE"])
    ASSOC_CONT(["CONTENIR / CONTAIN<br/>-------------------<br/>- ITE_QUANTITY<br/>- ITE_UNIT_PRICE"])

    %% CARDINALITIES
    CUSTOMER ---|"0,N"| ASSOC_PASS
    ASSOC_PASS ---|"1,1"| ORDER

    ORDER ---|"1,N"| ASSOC_CONT
    ASSOC_CONT ---|"0,N"| PRODUCT

    %% STYLING
    classDef entity fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#01579b;
    classDef assoc fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100;
    class CUSTOMER,ORDER,PRODUCT entity;
    class ASSOC_PASS,ASSOC_CONT assoc;

---

2. MLD Diagram Template (erDiagram)

Merise MLDs represent normalized relational tables with explicit types, primary keys (PK), and foreign keys (FK).

Syntax Guidelines

1. In Mermaid erDiagram, data types must be single tokens without spaces (e.g. VARCHAR, INT, DECIMAL, TIMESTAMP, BOOLEAN). Do not write VARCHAR(100) directly in the type position if your renderer strictly checks tokens; use VARCHAR or VARCHAR_100.
2. Always assign PK and FK flags.
3. Relationship lines indicate relational cardinality (Crow's Foot notation):
   • ||--o{: Exactly one to zero or many (1 to 0..N)
   • ||--|{: Exactly one to one or many (1 to 1..N)
   • |o--o{: Zero or one to zero or many (0..1 to 0..N)
   • ||--||: Exactly one to exactly one (1 to 1)

Code Example

erDiagram
    ECO_CUSTOMER {
        INT CUS_ID PK
        VARCHAR CUS_FIRST_NAME
        VARCHAR CUS_LAST_NAME
        VARCHAR CUS_EMAIL
        TIMESTAMP CUS_CREATED_AT
    }

    ECO_ORDER {
        INT ORD_ID PK
        INT ORD_CUS_ID FK "References ECO_CUSTOMER"
        TIMESTAMP ORD_DATE
        DECIMAL ORD_TOTAL_AMOUNT
        VARCHAR ORD_STATUS
    }

    ECO_PRODUCT {
        INT PRO_ID PK
        VARCHAR PRO_NAME
        DECIMAL PRO_PRICE
        INT PRO_STOCK_QUANTITY
    }

    ECO_ORDER_ITEM {
        INT ITE_ORD_ID PK,FK "References ECO_ORDER"
        INT ITE_PRO_ID PK,FK "References ECO_PRODUCT"
        INT ITE_QUANTITY
        DECIMAL ITE_UNIT_PRICE
    }

    ECO_CUSTOMER ||--o{ ECO_ORDER : "places"
    ECO_ORDER ||--|{ ECO_ORDER_ITEM : "contains"
    ECO_PRODUCT ||--o{ ECO_ORDER_ITEM : "ordered_in"

---

3. Markdown Formatting in db/mcd.md and db/mld.md

• Enclose every diagram inside triple backticks with mermaid:

  ```mermaid
  flowchart LR
  ...
  ```
  

• Never mix raw HTML script tags; use native Markdown and Mermaid notation.