django-schematic

If this is useful to you, a star helps others find it.

Interactive schema visualization for Django projects.

See all your models, fields, and relationships as an interactive, force-directed graph — directly in your browser. Zero Node.js required at runtime.

Features

• Export/Import view state as a PNG with location/canvas placement data.
• Export/Import view state as JSON
• Clean JSON API endpoint (GET /schema/api/)
• Force-directed layout with physics settle animation (drag-to-pin support)
• Hierarchical layout via dagre
• Click to expand/collapse field lists per model
• App-based color coding
• Show/hide models and apps via sidebar
• Django 5.x + Python 3.12+ only

Live Demo

• Live Demo
• CI/CD Pipeline Demo (YouTube) — auto-regenerating schema PNGs when models change

Visualize

Frontend Stack

Aspect	Technology
Framework	React 18
Language	TypeScript
Graph Visualization	React Flow (@xyflow/react 12)
Layout Engines	d3-force + dagre + ELK (3 options)
UI / Styling	TailwindCSS 4
State Management	Zustand 5
Bundler	Vite 6
Type Safety	Full TypeScript
Testing	Vitest + ESLint
CDN Dependencies	None (all bundled)
Package Manager	npm

Exported PNG file with embedded config data

This is an example output PNG file, that can be re-imported into django-schematic

Quick Start

pip install django-schematic

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "schematic",
]

Add to urls.py:

from django.urls import include, path

urlpatterns = [
    ...
    path("schema/", include("schematic.urls")),
]

Visit http://localhost:8000/schema/ — your model graph will be there.

Security

The viewer is only accessible when DEBUG = True. In production (DEBUG = False) both the HTML view and the API return 404, making the URL appear non-existent.

To expose the viewer in production behind your own auth layer, set the visible option to a callable:

SCHEMATIC = {
    "visible": lambda request: request.user.is_staff,
}

Configuration

# settings.py (all optional — these are the defaults)
SCHEMATIC = {
    "visible": lambda request: settings.DEBUG,  # or any callable, or True/False
    "include_apps": [],           # empty = all apps
    "exclude_apps": ["admin", "contenttypes", "sessions", "auth"],
    "exclude_models": {},         # {"myapp": ["InternalModel"]}
    "include_abstract": False,
    "include_proxy": True,
    "suppress_through_m2m": False,
}

suppress_through_m2m

When a ManyToManyField uses an explicit through model, Django draws two layers of relationships: the FK edges from the through table to each side, and a direct logical M2M edge on the model that declares the field. With suppress_through_m2m = False (the default) both are shown.

Set suppress_through_m2m = True to hide the redundant logical M2M edge and keep only the FK edges through the junction table — useful when the through model carries extra fields and you want the graph to reflect the true database structure.

Explicit through models are also tagged through in the graph and shown with a through badge in the node header, making them easy to identify regardless of this setting.

API

The schema is also available as JSON:

GET /schema/api/
GET /schema/api/?apps=myapp,otherapp

CI/CD Pipeline (optional)

update_diagrams is a management command that re-renders your PNG schema diagrams automatically when models change. See README.setting-up-CI.md for setup instructions.

Development

# Backend
pip install -e ".[dev]"
pytest

# Frontend
cd ui
npm install
npm run dev   # Vite dev server with HMR
npm run build # Outputs to schematic/static/schematic/

License

MIT