Skip to content

Emit Mermaid ERD for GitHub-rendered docs #10

Description

@KKranthi6881

Problem

DataLex already emits Markdown docs and has a React Flow studio, but a loaded DataLex project has no path to an ERD that renders inline on GitHub. The cleanest fix is Mermaid: GitHub renders ```mermaid blocks natively in Markdown, so an ERD emitted as Mermaid becomes a PR-reviewable artifact.

Goal

Add datalex emit erd --format mermaid <project> that walks the loaded DataLex project and writes one Mermaid erDiagram block per domain (or one combined block if the project has no domains), directly embeddable in docs.

Suggested approach

  1. Add an emitter module at packages/core_engine/src/datalex_core/emitters/mermaid_erd.py.
  2. Use the loader to get a DataLexProject; iterate entities + relationships.
  3. Render each entity as a Mermaid erDiagram entity block, cardinality-annotated relationships between them.
  4. Wire a new subcommand in packages/cli/src/datalex_cli/datalex_cli.py (e.g. datalex emit erd).
  5. Add a golden-file test with a small fixture project.
  6. Document in docs/cli.md; consider linking into the tutorial.

Acceptance criteria

  • datalex emit erd --format mermaid examples/jaffle_shop_demo/datalex-out produces valid Mermaid that renders on GitHub.
  • Cardinality notation is correct (||--o{, }o--||, etc.) based on each relationship's cardinality: field.
  • Unit test diffs against a golden .md file.

Why this is a good first issue

The emitter sits in a well-established module pattern (look at emitters/dbt.py for shape), touches only read-side APIs on the loader, and is trivially testable against a fixture. Great way to learn the loader internals.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions