Metadata-Version: 2.4
Name: django-model-visualizer
Version: 0.1.0
Summary: Reusable Django app to visualize Django models and relationships
Author-email: Hossein Tajfirouz <hosseintajfirouz@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ht21992/django-model-visualizer
Project-URL: Repository, https://github.com/ht21992/django-model-visualizer
Project-URL: Issues, https://github.com/ht21992/django-model-visualizer/issues
Keywords: django,models,visualization,erd,schema
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Dynamic: license-file

# django-model-visualizer

Interactive visualization of Django models and their relationships.

`django-model-visualizer` is a reusable Django app that generates a visual graph of your project's models directly from Django's ORM metadata. It renders models as draggable cards and relationships as live connectors, making it easy to understand complex schemas.

The visualizer runs entirely inside your Django project and requires no external services.

---

# Features

- Automatic Django model discovery
- Visual graph of models and relationships
- Support for:
  - ForeignKey
  - OneToOneField
  - ManyToManyField
- Draggable model cards
- Zoom and pan canvas
- Relationship highlighting
- App filtering
- Optional inclusion of Django internal models
- JSON API for exporting schema metadata
- Management command for exporting schema graph
- Lightweight (vanilla JS, no frontend framework)

---

# Example Use Cases

- Understanding large Django schemas
- Exploring unfamiliar projects
- Architecture documentation
- Teaching Django ORM relationships
- Debugging model structures
- Visualizing complex SaaS schemas

---

# Installation

```bash
pip install django-model-visualizer
```

Add the app to your Django project.

### settings.py
```
INSTALLED_APPS = [
    # ...
    "model_visualizer",
]
```

Add the URL route.

### urls.py
```
from django.urls import include, path

urlpatterns = [
    path("viz/", include("model_visualizer.urls")),
]
```

⸻

# Usage

Start your Django server.

```
python manage.py runserver
```
Open the visualizer:

```
http://127.0.0.1:8000/viz/
```

You will see a graphical representation of your project’s models.

⸻

### Canvas Controls

- Action Result
- Drag model card Reposition model
- Drag empty space Pan canvas
- Mouse wheel Zoom
- Click model Highlight relationships
- Reset layout button Restore automatic layout


⸻

### Filtering Models

The sidebar allows filtering:

|  Option 	|  Description 	|
|---	|---	|
|   App label	|   Show models from a specific Django app	|
|   Include auto created models	|   Show M2M through tables	|
|   Include proxy models	|   Show Django proxy models	|
|    Include Django apps  |       Show admin/auth/contenttypes models |


** For most projects, leaving these unchecked gives a cleaner graph.

⸻

## JSON API

The visualizer exposes a schema API.

```
/viz/api/graph/
```

#### Example request:
```
/viz/api/graph/?app_label=library
```
#### Example response structure:

```
{
  "meta": {
    "model_count": 5,
    "edge_count": 6
  },
  "models": [
    {
      "id": "library.Book",
      "fields": [...]
    }
  ],
  "edges": [
    {
      "from": "library.Book",
      "to": "library.Author",
      "type": "fk"
    }
  ]
}
```

This API can be used to:
 - build custom schema tools
 - export architecture diagrams
 - integrate with documentation systems

⸻

## Management Command

Export the model graph as JSON.

```
python manage.py export_model_graph --output graph.json
```

Example with filtering:

```
python manage.py export_model_graph \
    --output graph.json \
    --app-label library
```

Options:

Argument Description
- output JSON output file
- app-label Filter by app
- include-auto-created Include M2M through models
- include-proxy Include proxy models
- include-django-apps Include Django internal apps


⸻

### How It Works

The package inspects Django’s app registry:

django.apps.apps.get_models()

For each model it extracts:
 - fields
 - field types
 - relationships
 - metadata

The data is returned via a JSON API and rendered with an SVG-based graph.

Edges are dynamically recalculated as models are dragged.

⸻

Development

Clone the repository:
```
git clone https://github.com/yourname/django-model-visualizer.git
cd django-model-visualizer
```
Create a virtual environment:
```
python -m venv venv
source venv/bin/activate
```
Install in editable mode:
```
pip install -e .
```
Run tests:
```
python -m tests.runtests
```

⸻

Project Structure
```
model_visualizer/
├── apps.py
├── forms.py
├── serializers.py
├── services.py
├── urls.py
├── views.py
├── templates/
│   └── model_visualizer/
│       └── index.html
├── static/
│   └── model_visualizer/
│       ├── app.js
│       └── styles.css
```


⸻

### Compatibility

Supported Python versions:
 - Python 3.10+
 - Python 3.11
 - Python 3.12

Supported Django versions:
 - Django 4.2
 - Django 5.x

⸻

Security

The visualizer exposes project structure.

* For production environments it is recommended to restrict access to staff users.

Example:

```
from django.contrib.admin.views.decorators import staff_member_required
```
⸻

License

MIT License

⸻

Author

Created by a Django developer for exploring complex ORM structures.

Contributions and improvements are welcome.
