# django-lumen

Visualize your Django models as an interactive ERD diagram in the browser. No external diagram library — the diagram is pure vanilla JS + SVG rendered at request time from the live Django model registry.

## Requirements

- Python 3.10+
- Django 3.2+

## Installation

```bash
pip install django-lumen
```

## Setup

1. Add `django_lumen` to `INSTALLED_APPS`:

```python
# settings.py
INSTALLED_APPS = [
    ...
    "django_lumen",
]
```

2. Mount the URLs in your root `urls.py`:

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

urlpatterns = [
    ...
    path("lumen/", include("django_lumen.urls")),
]
```

3. Run migrations:

```bash
python manage.py migrate
```

4. Start the development server and open [http://localhost:8000/lumen/](http://localhost:8000/lumen/).

## Access control

The diagram is only accessible to users with `is_active = True` **and** `is_staff = True`. Other users are redirected to the login page.

## App filter

The sidebar lists every app present in the diagram. Clicking an app name filters the diagram to show only models belonging to that app plus any models they have direct relations to. Click again to deselect. Multiple apps can be selected at once — when no app is selected, all models are shown.

Right-clicking an app name marks it as excluded (shown in red with strikethrough). Excluded apps are completely hidden from the diagram and the preference is saved automatically. Right-click again to un-exclude.

## Settings

Each staff user has their own saved preferences, accessible via the **Settings** link in the diagram header. The settings page provides three sections:

**Managed tables** — when enabled, models with `managed = False` in their `Meta` class are hidden from the diagram.

**Show inheritance** — when enabled, each model box displays its parent class(es) below the model name. The default Django base (`models.Model`) is not shown — only custom application-level parents are displayed.

**Excluded models** — a list of regex patterns matched against model names. Any model whose name matches at least one pattern is hidden. Patterns use Python `re.search`, so use `^`/`$` to anchor. Examples: `^Historical`, `Log$`, `Audit`.

**Excluded apps** — checkboxes to permanently hide entire apps from the diagram. The following apps are hidden by default: `auth`, `admin`, `sessions`, `contenttypes`, `django_lumen`. Users can also right-click an app chip in the sidebar to exclude it directly from the diagram view.
