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

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.