Generate Er Diagram

Generating Entity-Relationship (ER) Diagrams

This skill allows agents to automatically generate clean, structured Entity-Relationship (ER) diagrams from one or more Cortex data products. The diagrams represent data models, primary keys, and relationships inferred from the data product's manifest, annotations, and definitions.

Core Operating Behaviors

When asked to generate an ER diagram for a data product:

1. Establish Output Format (CRITICAL):

   • You MUST check if the user has specified the desired format for the ER diagram (e.g., dot, mermaid, draw.io, or all).
   • If the format is not specified, you MUST explicitly ask the user:

     "Which format would you like to use for the ER diagram?

     1. Mermaid diagram (.mmd) - Best for quick markdown integration (also creates a .md file for immediate visual preview)
     2. Graphviz dot notation (.dot) - Best for custom graph rendering
     3. draw.io XML (.drawio) - Best for importing directly into draw.io as an interactive layout
     4. All formats - Generates Mermaid, DOT, and draw.io diagrams concurrently"

   • Wait for the user's choice before executing the generator.

2. Locate target data product:

   • Determine the name or folder of the data product to analyze. If it is not specified, look inside src/data_modules/<namespace>/<source>/products/ for available products.

3. Execute the generator script:

   • Use the virtualenv Python interpreter to run the tool:

     cortex-framework-core/.venv/bin/python external-skills/.agents/skills/generate_er_diagram/scripts/generate_er_diagram.py -p <data_product_path_or_name> -f <mermaid|dot|drawio> [options]
     

   • Optional Flags:
     • --include-siblings: Include sibling data products in the same namespace to map cross-product relationships. (Disabled by default to prevent oversized diagrams).
     • --all-foundation-fields: Render all fields for foundation tables (by default only keys and relationship-participating fields are shown to avoid clutter).
     • --all-data-product-fields: Render all fields for data product tables (by default only keys and relationship-participating fields are shown to avoid clutter).
   • Note: If the user selects All formats, execute the generator command three times sequentially, once for each format option (mermaid, dot, drawio).

4. Confirm Output:

   • The tool will write the output file directly in the data product's directory alongside the data product itself, named <type>_erd.<ext>.
   • Note: When generating in mermaid format, the tool will also automatically output a <type>_erd.md preview file wrapping the Mermaid diagram in a Markdown code block for immediate visual rendering in your editor or viewer's Markdown preview.
   • Present the generated diagram content (especially for mermaid) to the user, along with the path to the saved file(s).

Supported Diagram Formats

• Mermaid (mermaid, .mmd): A clean text-based diagramming language that renders automatically in markdown previews (such as GitHub, VS Code, or Gemini). Excellent for code-first documentation.
• Graphviz DOT (dot, .dot): A powerful, declarative graph description language using HTML-like table labels. Ideal for complex hierarchical visualizations.
• draw.io XML (drawio, .drawio): An uncompressed mxGraph XML file ready to be imported into draw.io or diagram.net for further manual layout styling and interactive editing.

Quick Start / Manual Execution

To manually run the ER diagram generator from the workspace root:

# For Mermaid (default fields)
cortex-framework-core/.venv/bin/python external-skills/.agents/skills/generate_er_diagram/scripts/generate_er_diagram.py -p <type> -f mermaid

# For Graphviz DOT (with all foundation fields)
cortex-framework-core/.venv/bin/python external-skills/.agents/skills/generate_er_diagram/scripts/generate_er_diagram.py -p <type> -f dot --all-foundation-fields

# For draw.io XML (including sibling data products)
cortex-framework-core/.venv/bin/python external-skills/.agents/skills/generate_er_diagram/scripts/generate_er_diagram.py -p <type> -f drawio --include-siblings