josevelazcoh/erdalchemy

1. Purpose and top-level flow

This repository is a self-contained ERD generator for SQLAlchemy 2.0 models. The main pipeline is: take a DeclarativeBase, introspect tables and foreign keys, build an internal schema graph, lay it out, route edges, and export the result as interactive HTML or static image formats.

2. Primary entry points

There are two user-facing entry points:

- the Python API exposed from sqlalchemy_erd via generate_erd(...)

- the CLI in src/sqlalchemy_erd/cli.py, which loads a target base class from a module path like myapp.models:Base

Both paths converge into the same core generation pipeline.

3. Schema introspection boundary

introspect.py is the boundary between SQLAlchemy models and the renderer. It reads mapped tables, columns, schemas, and foreign-key relationships from the provided declarative base and turns them into the repository’s internal graph representation. This is where multi-schema support and table/column filtering are applied.

4. Internal model and serialization

serialization.py appears to define the portable data shape used across the rest of the pipeline. That matters because the layout and rendering subsystems should not depend directly on SQLAlchemy objects; they consume a normalized schema graph instead.

5. Layout subsystem

The layout layer is split into selectable strategies:

- layered.py for the default hierarchical FK-driven layout

- force.py for force-directed placement

- star.py for hub-and-spoke or disconnected schemas

- layout_select.py chooses the strategy

- layout.py provides shared layout primitives/data structures

This is the main architectural decision point for how tables are positioned on the canvas.

6. Edge routing subsystem

edge_routing.py handles orthogonal routing of foreign-key edges so connectors avoid cutting through table cards. This is separate from node placement, which is important for diagram readability: layout decides where tables sit, routing decides how relationships are drawn between them.

7. Rendering and export

Rendering is split from layout:

- renderer.py / render.py are the core rendering layer

- html_renderer.py generates the interactive browser-based output

- export.py manages output formats such as HTML, SVG, PNG, and PDF

The README indicates PNG/PDF need an optional dependency, so static image export is an add-on boundary rather than a hard runtime dependency.

8. Theming and presentation

theme.py controls visual styling, including built-in themes and per-table color overrides. This is the presentation layer that sits on top of the structural diagram, allowing the same schema graph to be rendered with different visual identities.

9. Interactive HTML as a first-class output

The flagship output is the interactive HTML diagram: draggable cards, hover highlighting, and routed connectors. That makes the browser output the most feature-rich artifact, while SVG/PNG/PDF are simpler export targets derived from the same underlying diagram model.

10. Filtering and scale management

The repo supports regex-based include/exclude filtering for tables and columns, which is an important scaling mechanism for large schemas. This likely happens before layout so the graph size is reduced early and all downstream steps work on a smaller subgraph.

11. Examples as architecture references

The examples/ directory is not just demos; it demonstrates the major schema shapes the system is designed to handle:

- simple blog/ecommerce chains

- N:N association tables

- 1:1 and 1:N relationships

- multi-schema cross-schema foreign keys

- larger showcase graphs

These examples show the intended input diversity and validate the layout strategies.

12. Repo constraints and runtime boundary

The project emphasizes “zero dependencies beyond SQLAlchemy” for core use, with optional extras for richer exports. That constraint strongly shapes the architecture: introspection, layout, routing, and HTML generation are all implemented inside the package rather than delegated to heavier external graphing libraries.