Skip to content

feat(library): add Entity-Relationship diagrams (Chen and crow's-foot notations)#776

Draft
FelixTJDietrich wants to merge 15 commits into
mainfrom
entity-relationship-diagram-production
Draft

feat(library): add Entity-Relationship diagrams (Chen and crow's-foot notations)#776
FelixTJDietrich wants to merge 15 commits into
mainfrom
entity-relationship-diagram-production

Conversation

@FelixTJDietrich

@FelixTJDietrich FelixTJDietrich commented Jun 20, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds Entity-Relationship diagram support to Apollon, covering the two notations people actually use — shipped as two separate diagram types because they don't share a model:

  • Entity-Relationship (Chen) — the academic notation taught in DB courses: entities (rectangles, double for weak), relationships (diamonds, double for identifying), and attributes as ellipses (key = underline, partial-key = dashed underline, multivalued = double ellipse, derived = dashed ellipse). Connectors carry a cardinality label with presets for both the Chen ratio (1/N/M) and (min,max), plus a participation toggle (total = double line).
  • Entity-Relationship (Crow's Foot) — the Mermaid / Information-Engineering notation every modern DB tool uses (dbdiagram, DrawSQL, Mermaid erDiagram): entities are structured tables whose columns each carry a name, data type and key role — a PK/FK/UK key gutter, the column name, and an aligned data-type column, with subtle row dividers. Each column is individually themeable (fill/text colour), and all colours flow through the same getCustomColorsFromData path as the class diagram, so theming behaves identically across diagram types. They are related by straight lines with crow's-foot cardinality markers at each end (zero/one/many) and solid (identifying) / dashed (non-identifying) lines. The column layout follows Mermaid's erDiagram / DBML and the classic ER convention of underlining the primary key.

Context: this started from issue #751 (Chen notation). The natural follow-up question was "why doesn't this look like Mermaid's ERD?" — because Mermaid uses crow's-foot, a genuinely different notation (relationships are line-markers, not diamonds; attributes are table rows, not ellipses). Rather than force one model to serve both, Apollon now offers both as first-class types.

Release note

You can now create Entity-Relationship diagrams in both Chen notation (entities, relationships, attributes with key/multivalued/derived decorations) and crow's-foot / Mermaid-style notation (entity tables with crow's-foot cardinality markers).

Implementation notes

  • Follows the existing per-diagram pattern (PetriNet/Flowchart/Sfc): each type registers its node/edge types through the shared registries, palette, popovers and generated JSON schema. No new framework.
  • Chen: three node types (erEntity/erRelationship/erAttribute) + two edge types; a small pure classifyErConnection gates structurally valid connections and auto-picks connector vs. link.
  • Crow's foot: one entity node (erCfEntity) whose columns are a structured ErCfColumn { name, type?, keys?: (PK|FK|UK)[] } model, rendered by a 3-cell row renderer (ErCfRowSection: key gutter | name | type, with the data type aligned in its own column and row dividers drawn from the entity's themeable stroke colour) and edited by a structured column editor (ErCfColumnList) that also exposes a per-column fill/text colour control mirroring the class attribute editor and edited by a dedicated structured column editor (ErCfColumnList: name + type inputs, PK/FK/UK selector, drag-to-reorder). The relationship edge (ErCfRelationship) draws composite end markers via ErCrowsFootMarker (min = bar/ring, max = bar/foot, ordered outward per the IE standard); crow's-foot edges are straight-only so the markers stay attached, and Swap-Ends carries the directional cardinalities.
  • Export-safe SVG throughout (plain line/circle/polygon/rect, var(--apollon-background) for open shapes), so PNG/PDF export via resvg renders correctly.

Steps for testing

  1. pnpm dev → playground → pick Entity-Relationship (Chen) or Entity-Relationship (Crow's Foot) from the dropdown (or New diagram → Structural).
  2. Chen: drag Entity / Weak Entity / Relationship / Identifying / Attribute / Key Attribute; connect entity→relationship → cardinality connector; set a ratio then a (min,max) preset; toggle participation (Total = double line). Connect attribute→entity → link; entity→entity is rejected.
  3. Crow's foot: drag Entity tables, edit their columns, connect two entities → a relationship; open its popover and set source/target cardinality + the identifying toggle (solid ↔ dashed); confirm the crow's-foot markers update.
  4. Export SVG/PNG/PDF and confirm shapes/markers/labels render.
  5. Automated: cd library && pnpm test (Chen + crow's-foot unit tests; full suite green) and the Playwright e2e/visual specs.

Visual baselines for the new ER snapshots are generated in the pinned Playwright container (mcr.microsoft.com/playwright:v1.59.1-noble) via Update Visual Baselines, so they match CI exactly.

Two unrelated infra fixes are included because they fix pre-existing breakage on main that blocks every PR's CI (droppable if fixed independently): style: formats two files left unformatted by #645; ci: fixes the Update-Visual-Baselines workflow's commit step (it set -o pipefail under dash, so it could regenerate baselines but never commit them).

Screenshots / screencasts

Entity-Relationship (Chen) — full notation, weak entity + identifying relationship, key/multivalued/derived attributes:

Chen ER overview

Entity-Relationship (Crow's Foot) — structured tables (key gutter, name, aligned types, themeable per column), solid/dashed relationships, crow's-foot markers:

Crow's-foot ER overview

Structured column editor (name + type + PK/FK/UK + per-column colour):

Crow's-foot column editor

Editing cardinality — Chen connector (ratio / min,max presets) and crow's-foot relationship (per-end cardinality + identifying toggle):

Chen cardinality popover
Crow's-foot relationship popover

Checklist

  • Linked to a related issue (if applicable) — closes Entity-Relationship (Chen) notation as a render flavor for class diagrams #751
  • Added a changeset whose summary is written in the user's voice
  • PR title's Conventional Commit type (feat) matches the kind of change
  • Tests added or updated — Chen + crow's-foot unit tests, e2e spec, visual + SVG-export coverage
  • Documentation updated (if applicable) — docs/user/overview.md
  • Screenshots or screencasts attached

Add a standalone EntityRelationship diagram type that draws the full Chen
notation: strong/weak entities, regular/identifying relationships, and
attributes as ellipses with key, partial-key, multivalued and derived
decorations. Entity–relationship connectors carry a cardinality label
(free text with presets for Chen ratio and (min,max)) and a participation
toggle that renders total participation as a double line.

The connect flow only allows structurally valid Chen edges (entities link
to relationships, attributes hang off an owner) and picks the connector vs.
link edge type automatically, including on reconnection.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
These files fail `pnpm format:check` (prettier 3.4.2) on the current main
branch, which blocks the lint-and-format CI gate for every PR. They are
unrelated to the ER feature; this is a whitespace-only fix to unblock CI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Apollon Development Jun 20, 2026
@github-project-automation github-project-automation Bot moved this from Done to Backlog in Apollon Development Jun 20, 2026
The commit step set `-o pipefail` but ran under the container's default
dash shell, which dies on that bash-only option — so the workflow could
regenerate baselines but never commit them back. Pin the step to bash.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@FelixTJDietrich FelixTJDietrich force-pushed the entity-relationship-diagram-production branch from 43a6134 to b54f7e8 Compare June 20, 2026 18:24
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Apollon Development Jun 20, 2026
@github-project-automation github-project-automation Bot moved this from Done to Backlog in Apollon Development Jun 20, 2026
Add a second ER diagram type using the crow's-foot (Information
Engineering / Mermaid-style) notation: entity tables whose columns are
listed as rows, related by straight lines with crow's-foot cardinality
markers at each end (zero/one/many) and solid (identifying) or dashed
(non-identifying) lines. The entity reuses the class diagram's row
renderer and attribute editor; the composite end markers are a dedicated
SVG renderer.

The existing Chen ER type is relabelled "Entity-Relationship (Chen)" to
distinguish the two.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
FelixTJDietrich added a commit that referenced this pull request Jun 20, 2026
@FelixTJDietrich FelixTJDietrich changed the title feat(library): add Entity-Relationship (Chen) diagram type feat(library): add Entity-Relationship diagrams (Chen + crow's foot) Jun 20, 2026
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Apollon Development Jun 20, 2026
@github-project-automation github-project-automation Bot moved this from Done to Backlog in Apollon Development Jun 20, 2026
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Apollon Development Jun 20, 2026
@github-project-automation github-project-automation Bot moved this from Done to Backlog in Apollon Development Jun 20, 2026
FelixTJDietrich and others added 2 commits June 20, 2026 23:05
…r Swap

The shared Swap-Ends handler exchanges an edge's endpoints but not its data,
so swapping a crow's-foot relationship left the per-end cardinality markers on
the wrong entities (a "1 → 0..*" relationship silently became "0..* → 1").
Swap the directional cardinality data alongside the endpoints, scoped to the
crow's-foot popover so other edge types are untouched.

Also extract the edge's render logic (dashed/identifying, per-end marker
direction and cardinality defaults) into a pure `deriveErCfEdgeRender` so this
diagram type's defining behavior is unit-tested rather than only pixel-tested.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A crow's-foot / Information-Engineering ER entity is a table whose columns
each carry a name, data type and key role — the layout Mermaid `erDiagram`,
DBML and physical-ER tools all use. The previous implementation reused the
class diagram's single free-text row, so type/PK/FK were just typing
conventions baked into one opaque string.

Model each column as { name, type?, keys?: (PK|FK|UK)[] } and render the
entity as a real table: a key gutter (PK/FK/UK), a name column with the
primary key underlined, and a right-aligned data-type column. Replace the
reused class attribute editor with a structured column editor (name + type
inputs and a PK/FK/UK selector, drag to reorder).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Apollon Development Jun 21, 2026
@github-project-automation github-project-automation Bot moved this from Done to Backlog in Apollon Development Jun 21, 2026
FelixTJDietrich and others added 2 commits June 21, 2026 13:11
Make the crow's-foot entity read as a real database table and the column
editor look professional, following how Mermaid, dbdiagram and DrawSQL render
and edit ER tables.

Entity: shade the title band (var(--apollon-background-variant), honouring a
user fill), draw thin row dividers, and align the data type in a left-aligned
column right after the name (computed from the widest name) instead of
stranding it at the box edge with a large gap. Drop the redundant, geometry-
fragile primary-key underline — the PK/FK/UK gutter is the key signal.

Column editor: replace the three space-hogging PK/FK/UK toggle buttons with a
compact multi-select (so the row stays legible in the narrow popover), add
Name/Type/Key column labels, an empty state, and an inline "+ Add column" row.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Apollon Development Jun 21, 2026
@github-project-automation github-project-automation Bot moved this from Done to Backlog in Apollon Development Jun 21, 2026
Bring the crow's-foot entity in line with the shared theming system (traced
against the class diagram, the reference). Three consistency fixes:

- Per-column colour: each column now exposes a fill/text colour control in the
  editor (a paint-roller panel mirroring the class per-attribute editor). The
  renderer already read per-column colours, so columns were renderable but not
  settable — now they are individually themeable like class attributes.
- Header fill: derive the header fill from getCustomColorsFromData like every
  other entity, so the header default matches the rows (white) and the entity
  fill themes the header — instead of a bespoke grey band that bypassed the
  shared fallback and produced a two-tone default.
- Row dividers: draw inter-row rules from the entity's themeable strokeColor at
  low opacity, instead of a hard-coded grey chrome token, so they track a
  user-chosen border colour.

Chen ER nodes were traced and already follow the shared pattern — untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@FelixTJDietrich FelixTJDietrich changed the title feat(library): add Entity-Relationship diagrams (Chen + crow's foot) feat(library): add Entity-Relationship diagrams (Chen and crow's-foot notations) Jun 21, 2026
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Apollon Development Jun 21, 2026
@github-project-automation github-project-automation Bot moved this from Done to Backlog in Apollon Development Jun 21, 2026
Switch the crow's-foot relationship edge from straight to the class
diagram's step (orthogonal) routing by reusing useStepPathEdge and
StepEdgeBody — bringing bend points, midpoint dragging and reconnection
for free, and removing the bespoke BaseEdge/overlay/endpoint-marker
duplication.

deriveErCfEdgeRender now orients each crow's-foot marker along the
path's end segment (via getPathStartInfo/getPathEndInfo) instead of the
source→target vector, so the markers stay attached and correctly angled
when the edge bends. Falls back to the straight line before first layout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@FelixTJDietrich FelixTJDietrich marked this pull request as draft June 21, 2026 20:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

Entity-Relationship (Chen) notation as a render flavor for class diagrams

1 participant