django-erd-studio 1.1.5

Interactive ER Diagram Workbench for Django

Django ERD Studio

An interactive, premium web-based Entity-Relationship Diagram (ERD) workbench for Django projects. Introspect and visualize your Django database models and their complex relationships in a beautiful, responsive canvas.

---

✨ Key Features (Fully Implemented)

1. High-Performance Introspection

• Deep Django Introspection: Automatically scans your installed apps and models, extracting database fields and complex relationships (ForeignKey, OneToOneField, ManyToManyField).

2. Premium Vector Visuals & Canvas

• Collision-Free Theme Colors: Mapped distinct aesthetic colors for core Django applications with a deterministic hashing fallback to ensure newly created apps get unique, gorgeous colors.
• Natural Full-Height Cards: Table cards scale dynamically to show their full field list, eliminating annoying vertical scrollbars and ensuring relationship handles line up with micro-pixel accuracy.
• Unclipped Handles: Main containers are set to visible overflow, showing Primary Key (PK), Foreign Key (FK), Many-to-Many (M2M), and One-to-One (O2O) connector circles as beautiful, uncropped full circles.
• Interactive Relationship Edges: Hover and click on connection lines to view interactive details such as Type, Source/Target, and related_name properties.
• Dynamic Layout Switching: Toggle the canvas flow between Horizontal (Left-to-Right) and Vertical (Top-to-Bottom) directions dynamically, auto-arranging nodes using Dagre and persisting your preference in localStorage.
• Live Search Navigation: Quickly find specific tables by name or parent app with an interactive search bar that pans and zooms directly to the matched node.

3. Professional HD Export Engine (PNG & PDF)

• Retina-Grade Clarity: Renders the inner React Flow viewport at a native scale(1) transform with a 2x pixel ratio, capturing vector-sharp, clear text and arrowheads under close-up zooming.
• Dynamic Orientation Matching: Automatically detects your diagram's aspect ratio and chooses between Portrait or Landscape PDF page orientation to fit your layout.
• Standard A4 Mobile-Ready PDF: Scales the high-definition canvas to center and fit perfectly inside standard A4 document bounds. Color-fills the entire standard page with a solid dark-theme color (#111827) so aspect-ratio letterboxing blends seamlessly with zero white borders.
• PDF Auto-Fit on Open: Configures opening catalog metadata (setDisplayMode('fullpage')) so that modern PDF readers automatically fit the entire diagram to the screen on open—completely avoiding initial scrollbars!
• 95% File Size Optimization: Bypasses slow stylesheet font scanning (skipFonts: true) and processes images using high-efficiency JPEG compression (0.95 quality). This slashes exported PDF sizes by over 95% (typically from 10MB+ down to just 300KB - 500KB) while maintaining perfect text and path sharpness!

4. Smart Local State Persistence & Server Resilience

• Position Lock: Drag and arrange tables on your canvas—the coordinates are automatically saved to localStorage so your custom layouts are preserved across refreshes.
• Cache-Busting Backend: Pre-configured Flask servers serve static resources with explicit Cache-Control: no-store headers, completely eliminating aggressive browser cache locks during local development.
• Conflict-Free Port Binding: Auto-detects port conflicts (if the default port 8765 is already occupied) and increments ports dynamically up to 10 times to secure an available server binding.

5. Developer Diagnostics & Layout Tools

• Interactive Stats Dashboard: Toggle a dedicated panel to view metrics such as total models, unique apps, relations, and a complete, sorted breakdown of active Django field types.
• System App Filtering: Suppresses internal system/contrib apps (like auth, admin, contenttypes, sessions) to keep the diagram layout developer-focused and noise-free.

---

Technology Stack

Backend (Python)

• Django (>= 3.2): For database model introspection and project-wide metadata management.
• Flask (>= 2.0): Acts as a lightweight API server bridging the Django context and the web browser.
• LibCST (>= 1.0): Concrete Syntax Tree parser included in the backend package for AST parsing and code analysis.

Frontend (JavaScript/React)

• Vite: Rapid asset building and development hot-reloading.
• React (v19): The core UI component library.
• ReactFlow (v11): The interactive canvas engine handling nodes, handles, connections, zoom, and minimap.
• Dagre (v0.8): Organizes node coordinates programmatically using Directed Acyclic Graph layouts.
• html-to-image & jsPDF: Replaced obsolete rendering engines to support native SVG <marker> definitions (arrowheads) and high-efficiency standard PDF/JPEG rendering.

---

Getting Started

1. Installation

Install the package directly into your active Django environment:

pip install django-erd-studio

2. Register the App

Add django_erd_studio to your project's INSTALLED_APPS inside settings.py:

INSTALLED_APPS = [
    # ...
    'django_erd_studio',
]

3. Run the Workbench!

You can launch the workbench in two ways:

Option A: Standalone CLI Command (No Django registration required!)

Run the standalone runner from your Django project root (where manage.py resides):

django-erd

(If DJANGO_SETTINGS_MODULE is not set in your environment, the CLI will ask you to enter it, e.g. myproject.settings)

Option B: Django Management Command

If you registered the app in INSTALLED_APPS, launch it using:

python manage.py erd_studio

In either case, the server will start locally at http://127.0.0.1:8765 (or a fallback port if occupied) and automatically open the web portal in your browser!

---

Deployment & Clean Building

This repository is structured according to python packaging best practices. The backend code (django_erd_studio/) and frontend workspace (frontend/) are perfectly isolated, and Git is protected via a robust .gitignore file.

To compile optimized production assets and package your project for PyPI distribution:

1. Rebuild Frontend Static Assets:

   cd frontend
   npm run build
   

2. Generate Clean Package Wheels:

   cd ..
   python -m build
   

   (Generates a highly optimized, lightweight ~390 KB wheel inside dist/ containing only the backend server and minified Web UI, completely excluding raw React code and test environments).