Metadata-Version: 2.4
Name: django-erd-studio
Version: 1.1.5
Summary: Interactive ER Diagram Workbench for Django
Author: Johnweslee
Project-URL: Homepage, https://github.com/JohnWeslee97/django-erd-studio
Project-URL: Repository, https://github.com/JohnWeslee97/django-erd-studio
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: Django>=3.2
Requires-Dist: Flask>=2.0
Requires-Dist: libcst>=1.0

# 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:
```bash
pip install django-erd-studio
```

### 2. Register the App
Add `django_erd_studio` to your project's `INSTALLED_APPS` inside `settings.py`:
```python
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):
```bash
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:
```bash
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**:
    ```bash
    cd frontend
    npm run build
    ```
2.  **Generate Clean Package Wheels**:
    ```bash
    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).*
