django-dynamic-nav 0.1.0__py3-none-any.whl

django_dynamic_nav-0.1.0.dist-info/METADATA

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: django-dynamic-nav
+Version: 0.1.0
+Summary: Permissioned, dynamic navigation tree for Django REST Framework: Menu > SubMenu > Page > Widget, with group/role-based access control.
+Author: Chetan Pawar
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: Django>=3.2
+Requires-Dist: djangorestframework>=3.12
+
+# dynamic_nav
+
+A standalone Django REST Framework app for a **permissioned, dynamic
+navigation tree**: `Menu` → `SubMenu` → `Page` → `Widget`, where every
+level can be granted to a Django `Group` for specific actions (`view`,
+`update`, `create`, `delete`, `export`).
+
+This is a separate app from `dynamic_ui` (the form builder) - it's a
+different concept (navigation/dashboard structure + RBAC) rather than
+form fields, so it doesn't reuse `UIField`.
+
+## Install
+
+Add to `INSTALLED_APPS` (needs `django.contrib.contenttypes` and
+`django.contrib.auth`, which are on by default in any Django project):
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django.contrib.contenttypes",
+    "django.contrib.auth",
+    "rest_framework",
+    "dynamic_nav",
+]
+```
+
+```python
+# project/urls.py
+urlpatterns = [
+    ...
+    path("api/nav/", include("dynamic_nav.urls")),
+]
+```
+
+```bash
+python manage.py migrate dynamic_nav
+```
+
+## Model
+
+```
+Menu
+ └─ SubMenu
+     └─ Page
+         └─ Widget (chart / graph / kpi / table / field / text / custom)
+```
+
+Each of the four models can have any number of `ItemPermission` rows,
+each granting a "grantee" (a `Group` by default, or your own `Role`/
+`SubRole` - see "Integrating your own Role/SubRole tables" below) an
+`action`:
+
+```python
+from django.contrib.auth.models import Group
+from dynamic_nav.models import Menu, ItemPermission, PermissionAction
+
+menu = Menu.objects.create(name="Analytics", slug="analytics")
+sales_team = Group.objects.create(name="SalesTeam")
+
+ItemPermission.grant(menu, sales_team, PermissionAction.VIEW)
+```
+
+Or just use the Django admin - every level (`Menu`, `SubMenu`, `Page`,
+`Widget`) has a "Permissions" inline where you pick a Group and an action
+directly on that item's edit page.
+
+**Important:** permissions are checked per-item, not cascaded
+automatically. If you want a group to see a `Page`, grant `view` on the
+`Menu`, `SubMenu`, and `Page` (and any `Widget`s) it belongs to - this
+keeps the model simple and lets you, e.g., grant view on a menu without
+exposing every submenu under it.
+
+Superusers automatically have every action on everything.
+
+## Custom table names
+
+By default: `dynamic_nav_menu`, `dynamic_nav_submenu`, `dynamic_nav_page`,
+`dynamic_nav_widget`, `dynamic_nav_itempermission`. Override any of them
+in `settings.py`:
+
+```python
+DYNAMIC_NAV_TABLE_NAMES = {
+    "Menu": "nav_menus",
+    "SubMenu": "nav_submenus",
+    "Page": "nav_pages",
+    "Widget": "nav_widgets",
+    "ItemPermission": "nav_item_permissions",
+}
+```
+
+Any model you don't list keeps its default name. Then:
+
+```bash
+python manage.py makemigrations dynamic_nav
+python manage.py migrate dynamic_nav
+```
+
+`makemigrations` detects the rename against the shipped `0001_initial`
+migration and generates the `AlterModelTable` migration for you.
+
+## Integrating your own Role/SubRole tables
+
+`ItemPermission`'s "who" side is a generic FK (called the **grantee**), not
+a hardcoded link to Django's `Group`. That means you can grant permissions
+to a `Group`, your own `Role`, your own `SubRole`, a `Team` - any model
+instance with a primary key - without forking this package.
+
+**1. Point dynamic_nav at a function that resolves a User into their grantees.**
+
+```python
+# myapp/permissions.py
+def get_user_grantees(user):
+    """Return every grantee (Group, Role, SubRole, ...) this user should
+    be checked against. dynamic_nav unions permissions across all of them."""
+    if not user or not user.is_authenticated:
+        return []
+    grantees = list(user.groups.all())          # keep using Groups too, if you want
+    profile = getattr(user, "profile", None)     # however your project links User -> Role/SubRole
+    if profile:
+        if profile.role_id:
+            grantees.append(profile.role)
+        if profile.subrole_id:
+            grantees.append(profile.subrole)
+    return grantees
+```
+
+```python
+# settings.py
+DYNAMIC_NAV_GRANTEE_RESOLVER = "myapp.permissions.get_user_grantees"
+```
+
+If you don't set this, it defaults to just `user.groups.all()` - existing
+Group-based setups keep working unchanged.
+
+**2. Grant permissions to a Role or SubRole exactly like you would a Group,**
+using the `ItemPermission.grant()` helper (works with any grantee type):
+
+```python
+from dynamic_nav.models import Menu, ItemPermission, PermissionAction
+from myapp.models import Role, SubRole
+
+sales_manager = SubRole.objects.get(name="SalesManager")
+menu = Menu.objects.get(slug="dashboard")
+
+ItemPermission.grant(menu, sales_manager, PermissionAction.VIEW)
+```
+
+**3. That's it.** `MenuTreeView` / `PageDetailView` call your resolver
+automatically via `PermissionResolver`, so a user with `subrole=SalesManager`
+now sees exactly what that SubRole is granted - and you can still mix in
+plain `Group`-based grants for anything not yet migrated to your Role
+system, since `ItemPermission` doesn't care which type of grantee it's
+looking at.
+
+**Admin note:** the "Permissions" inline on each item's admin page now
+shows a content-type dropdown + a raw grantee id (since Django admin has
+no built-in widget for an arbitrary second generic FK). If you want a
+nicer picker restricted to just Group/Role/SubRole with autocomplete by
+name, write a custom `ModelForm` for `ItemPermissionInline` in your own
+`admin.py` that swaps `grantee_object_id` for a `ModelChoiceField` filtered
+by the selected `grantee_content_type` - happy to build that out if useful.
+
+## Finding out what a Role/SubRole/Group can access (or who can access an item)
+
+`item.permissions.all()` gives you raw `ItemPermission` rows for one item,
+but going the *other* direction - "what can this Role access" - needs a
+grantee-side lookup, since the grantee is a generic FK this app doesn't
+index on your model. Two helpers cover both directions:
+
+```python
+from dynamic_nav.permissions import list_for_grantee, list_for_item
+
+# "What can this SubRole access, and with which actions?"
+for entry in list_for_grantee(sales_manager_subrole):
+    print(entry["item"], entry["actions"])
+# <Menu: Dashboard> ['view']
+# <Page: Dashboard / Sales / Revenue> ['view']
+# <Widget: Dashboard / Sales / Revenue / Monthly Revenue> ['update', 'view']
+
+# "Who can access this Widget, and with which actions?"
+for entry in list_for_item(monthly_revenue_widget):
+    print(entry["grantee"], entry["actions"])
+# <SubRole: Manager / SalesManager> ['update', 'view']
+```
+
+Each entry groups all actions for the same item/grantee into one row (a
+Role granted both `view` and `update` on the same Widget shows up once,
+not twice).
+
+There's also `ItemPermission.for_grantee(grantee)` / `.for_item(item)` if
+you want the raw, ungrouped queryset instead (e.g. to `.delete()` a whole
+set of grants at once), and `ItemPermission.revoke(item, grantee, action)`
+to undo a single `grant()` call.
+
+**In the admin:** grants also show up in their own top-level "Item
+permissions" list (not just as inlines on each Menu/SubMenu/Page/Widget),
+filterable by action and by grantee type - so you can filter down to
+"everything granted to a SubRole" or "everything granted on Widgets" from
+one screen.
+
+## API
+
+### `GET /api/nav/menus/`
+
+Returns the full tree, pruned to only the menus/submenus/pages/widgets
+the requesting user's groups have `view` on. Every node includes a
+`permissions` list of the actions that user has on it:
+
+```json
+[
+  {
+    "name": "Analytics",
+    "slug": "analytics",
+    "icon": "bar-chart",
+    "order": 0,
+    "permissions": ["view"],
+    "submenus": [
+      {
+        "name": "Sales",
+        "slug": "sales",
+        "permissions": ["view"],
+        "pages": [
+          {
+            "name": "Sales Overview",
+            "slug": "sales-overview",
+            "layout": null,
+            "permissions": ["view"],
+            "widgets": [
+              {
+                "name": "Revenue Trend",
+                "widget_type": "chart",
+                "config": {"chart_type": "line", "endpoint": "/api/data/revenue"},
+                "permissions": ["view"]
+              },
+              {
+                "name": "Total Deals",
+                "widget_type": "kpi",
+                "config": {"endpoint": "/api/data/deals-count"},
+                "permissions": ["view", "update"]
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+The frontend uses `permissions` on each node to decide what to render -
+e.g. only show an "Edit" button on "Total Deals" for users whose list
+includes `"update"`.
+
+### `GET /api/nav/pages/<slug>/`
+
+Returns one page (with its permission-filtered widgets). Returns `403` if
+the user's groups don't grant `view` on that page, even if they can see
+its parent menu/submenu.
+
+## Widget `config`
+
+`config` is a free-form JSON field - this app only stores/serves it, it
+doesn't fetch chart data itself. Put whatever your frontend needs there,
+e.g.:
+
+```json
+{"chart_type": "line", "endpoint": "/api/data/revenue", "refresh_seconds": 60}
+```
+
+## Performance note
+
+`MenuTreeView` and `PageDetailView` use `PermissionResolver.preload()` to
+fetch all relevant `ItemPermission` rows in one query per model (4 queries
+total for a whole tree, regardless of its size) rather than querying
+per-node, and reuse `prefetch_related` caches when walking children - so
+response time doesn't degrade as the tree grows.

django_dynamic_nav-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+dynamic_nav/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+dynamic_nav/admin.py,sha256=SUq5NRcyyI9sDZW2dwM8zveuZ9pcEAMmCq2jtfGAmdI,2698
+dynamic_nav/apps.py,sha256=pbTPr2bwfvOyAJjok_Ssfo8TnhUlhQ_t9AQLpUc99IQ,193
+dynamic_nav/models.py,sha256=C3y7i2DyCIcmw15-fEnl7Klr_uG0iMtSpGvfe6XYugc,7988
+dynamic_nav/permissions.py,sha256=BsyeMZlVEG2Ec2PupROyT9wB0whuMfXTEhBEuUwoyXM,5581
+dynamic_nav/serializers.py,sha256=UHlaEbIBMfCM_MPf_tdGHltlRQr7hZSfgo5VLT7BMvg,2582
+dynamic_nav/urls.py,sha256=ie2OvTd9OqBGvPg8Azu3iPwikYX9GLf802Kq6y04MnI,263
+dynamic_nav/views.py,sha256=lTqbm7iT_8VQb-wK2phmNKRZtGqUI7bWZ4gHhMqbOhU,2935
+dynamic_nav/migrations/0001_initial.py,sha256=mJNfJofI-hK6kmTp_SMvne6xpLhsQ7g-tLVxQE7U9iE,5523
+dynamic_nav/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_dynamic_nav-0.1.0.dist-info/METADATA,sha256=y11QCtTyAO_szdQej4ZCUNG3sbBbq7F3Mur59LwL2jA,9924
+django_dynamic_nav-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+django_dynamic_nav-0.1.0.dist-info/top_level.txt,sha256=GFjxsOrpgmHPG0VXtdJwDiV0n9eqoqQMBUeAy2od_PM,12
+django_dynamic_nav-0.1.0.dist-info/RECORD,,

django_dynamic_nav-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_dynamic_nav-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dynamic_nav

dynamic_nav/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

dynamic_nav/admin.py

@@ -0,0 +1,82 @@
+from django.contrib import admin
+from django.contrib.contenttypes.admin import GenericTabularInline
+
+from .models import ItemPermission, Menu, Page, SubMenu, Widget
+
+
+class ItemPermissionInline(GenericTabularInline):
+    """
+    Assign permissions directly on a Menu/SubMenu/Page/Widget's edit page.
+    The "target" side (content_type/object_id) is handled automatically by
+    GenericTabularInline. The "grantee" side is a *second*, independent
+    generic FK (grantee_content_type/grantee_object_id) - the admin has no
+    built-in widget for picking an arbitrary model's instance by name, so
+    you pick the content type (e.g. "group" or "role") and type in its id.
+    For nicer UX, swap grantee_object_id for a custom form field/autocomplete
+    scoped to your Role/SubRole models - see README.md.
+    """
+
+    model = ItemPermission
+    extra = 1
+    fields = ("grantee_content_type", "grantee_object_id", "action")
+
+
+class WidgetInline(admin.TabularInline):
+    model = Widget
+    extra = 1
+    fields = ("order", "name", "widget_type", "is_active")
+
+
+class PageInline(admin.StackedInline):
+    model = Page
+    extra = 1
+    show_change_link = True
+
+
+class SubMenuInline(admin.StackedInline):
+    model = SubMenu
+    extra = 1
+    show_change_link = True
+
+
+@admin.register(Menu)
+class MenuAdmin(admin.ModelAdmin):
+    list_display = ("name", "slug", "order", "is_active")
+    prepopulated_fields = {"slug": ("name",)}
+    inlines = [SubMenuInline, ItemPermissionInline]
+
+
+@admin.register(SubMenu)
+class SubMenuAdmin(admin.ModelAdmin):
+    list_display = ("menu", "name", "slug", "order", "is_active")
+    list_filter = ("menu",)
+    prepopulated_fields = {"slug": ("name",)}
+    inlines = [PageInline, ItemPermissionInline]
+
+
+@admin.register(Page)
+class PageAdmin(admin.ModelAdmin):
+    list_display = ("submenu", "name", "slug", "order", "is_active")
+    list_filter = ("submenu__menu", "submenu")
+    prepopulated_fields = {"slug": ("name",)}
+    inlines = [WidgetInline, ItemPermissionInline]
+
+
+@admin.register(ItemPermission)
+class ItemPermissionAdmin(admin.ModelAdmin):
+    """
+    Standalone list of every grant, independent of the inlines on each
+    item's own admin page - useful for answering "what can this Role
+    access" or "who can access this Widget" by filtering.
+    """
+
+    list_display = ("content_object", "grantee", "action")
+    list_filter = ("action", "content_type", "grantee_content_type")
+    search_fields = ("object_id", "grantee_object_id")
+
+
+@admin.register(Widget)
+class WidgetAdmin(admin.ModelAdmin):
+    list_display = ("page", "name", "widget_type", "order", "is_active")
+    list_filter = ("widget_type", "page")
+    inlines = [ItemPermissionInline]

dynamic_nav/apps.py

@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class DynamicNavConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "dynamic_nav"
+    verbose_name = "Dynamic Navigation"

dynamic_nav/migrations/0001_initial.py

@@ -0,0 +1,103 @@
+# Generated by Django 6.1.1 on 2026-09-08 11:19
+
+import django.db.models.deletion
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('contenttypes', '0002_remove_content_type_name'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Menu',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100)),
+                ('slug', models.SlugField(max_length=100, unique=True)),
+                ('icon', models.CharField(blank=True, help_text='Optional icon name for the frontend.', max_length=100)),
+                ('order', models.PositiveIntegerField(default=0)),
+                ('is_active', models.BooleanField(default=True)),
+            ],
+            options={
+                'db_table': 'dynamic_nav_menu',
+                'ordering': ['order', 'id'],
+            },
+        ),
+        migrations.CreateModel(
+            name='SubMenu',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100)),
+                ('slug', models.SlugField(max_length=100)),
+                ('icon', models.CharField(blank=True, max_length=100)),
+                ('order', models.PositiveIntegerField(default=0)),
+                ('is_active', models.BooleanField(default=True)),
+                ('menu', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='submenus', to='dynamic_nav.menu')),
+            ],
+            options={
+                'db_table': 'dynamic_nav_submenu',
+                'ordering': ['order', 'id'],
+            },
+        ),
+        migrations.CreateModel(
+            name='Page',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100)),
+                ('slug', models.SlugField(max_length=100)),
+                ('order', models.PositiveIntegerField(default=0)),
+                ('is_active', models.BooleanField(default=True)),
+                ('layout', models.JSONField(blank=True, help_text='Optional grid/layout config for the frontend.', null=True)),
+                ('submenu', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='pages', to='dynamic_nav.submenu')),
+            ],
+            options={
+                'db_table': 'dynamic_nav_page',
+                'ordering': ['order', 'id'],
+            },
+        ),
+        migrations.CreateModel(
+            name='Widget',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100)),
+                ('widget_type', models.CharField(choices=[('chart', 'Chart'), ('graph', 'Graph'), ('kpi', 'KPI'), ('table', 'Table'), ('field', 'Field'), ('text', 'Text'), ('custom', 'Custom')], max_length=20)),
+                ('order', models.PositiveIntegerField(default=0)),
+                ('is_active', models.BooleanField(default=True)),
+                ('config', models.JSONField(blank=True, help_text='Frontend-specific config: chart type, data source endpoint, columns, etc.', null=True)),
+                ('page', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='widgets', to='dynamic_nav.page')),
+            ],
+            options={
+                'db_table': 'dynamic_nav_widget',
+                'ordering': ['order', 'id'],
+            },
+        ),
+        migrations.CreateModel(
+            name='ItemPermission',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('object_id', models.PositiveIntegerField()),
+                ('grantee_object_id', models.PositiveIntegerField()),
+                ('action', models.CharField(choices=[('view', 'View'), ('update', 'Update'), ('create', 'Create'), ('delete', 'Delete'), ('export', 'Export')], max_length=20)),
+                ('content_type', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='+', to='contenttypes.contenttype')),
+                ('grantee_content_type', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='+', to='contenttypes.contenttype')),
+            ],
+            options={
+                'db_table': 'dynamic_nav_itempermission',
+                'indexes': [models.Index(fields=['content_type', 'object_id'], name='dynamic_nav_content_b9e6a1_idx'), models.Index(fields=['grantee_content_type', 'grantee_object_id'], name='dynamic_nav_grantee_2c978a_idx')],
+                'constraints': [models.UniqueConstraint(fields=('content_type', 'object_id', 'grantee_content_type', 'grantee_object_id', 'action'), name='unique_grantee_action_per_nav_item')],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name='submenu',
+            constraint=models.UniqueConstraint(fields=('menu', 'slug'), name='unique_submenu_slug_per_menu'),
+        ),
+        migrations.AddConstraint(
+            model_name='page',
+            constraint=models.UniqueConstraint(fields=('submenu', 'slug'), name='unique_page_slug_per_submenu'),
+        ),
+    ]

dynamic_nav/models.py

@@ -0,0 +1,221 @@
+from django.conf import settings
+from django.contrib.contenttypes.fields import GenericForeignKey, GenericRelation
+from django.contrib.contenttypes.models import ContentType
+from django.db import models
+
+# Lets a project override this app's table names without forking it:
+#   DYNAMIC_NAV_TABLE_NAMES = {"Menu": "nav_menus", "Widget": "nav_widgets"}
+# in settings.py. Any model not listed keeps its default dynamic_nav_* name.
+# See the "Custom table names" section in README.md for the migration step
+# this requires.
+_TABLE_OVERRIDES = getattr(settings, "DYNAMIC_NAV_TABLE_NAMES", {})
+
+
+def _table(model_name, default_table):
+    return _TABLE_OVERRIDES.get(model_name, default_table)
+
+
+class PermissionAction(models.TextChoices):
+    VIEW = "view", "View"
+    UPDATE = "update", "Update"
+    CREATE = "create", "Create"
+    DELETE = "delete", "Delete"
+    EXPORT = "export", "Export"
+
+
+class ItemPermission(models.Model):
+    """
+    Grants a "grantee" the ability to perform an action (view/update/
+    create/delete/export) on a navigation item.
+
+    Both sides are generic FKs:
+    - the target (content_type/object_id) is a Menu, SubMenu, Page, or Widget.
+    - the grantee (grantee_content_type/grantee_object_id) is *any* model
+      with a primary key: Django's built-in Group, or your own Role,
+      SubRole, Team, whatever your project already has. This app doesn't
+      need to know its shape - see permissions.py and the "Integrating
+      your own Role/SubRole tables" section in README.md for how a User
+      gets resolved into a set of grantees.
+    """
+
+    content_type = models.ForeignKey(
+        ContentType, on_delete=models.CASCADE, related_name="+"
+    )
+    object_id = models.PositiveIntegerField()
+    content_object = GenericForeignKey("content_type", "object_id")
+
+    grantee_content_type = models.ForeignKey(
+        ContentType, on_delete=models.CASCADE, related_name="+"
+    )
+    grantee_object_id = models.PositiveIntegerField()
+    grantee = GenericForeignKey("grantee_content_type", "grantee_object_id")
+
+    action = models.CharField(max_length=20, choices=PermissionAction.choices)
+
+    class Meta:
+        db_table = _table("ItemPermission", "dynamic_nav_itempermission")
+        constraints = [
+            models.UniqueConstraint(
+                fields=[
+                    "content_type",
+                    "object_id",
+                    "grantee_content_type",
+                    "grantee_object_id",
+                    "action",
+                ],
+                name="unique_grantee_action_per_nav_item",
+            )
+        ]
+        indexes = [
+            models.Index(fields=["content_type", "object_id"]),
+            models.Index(fields=["grantee_content_type", "grantee_object_id"]),
+        ]
+
+    def __str__(self):
+        return f"{self.grantee} can {self.action} {self.content_object}"
+
+    @classmethod
+    def grant(cls, item, grantee, action):
+        """
+        Convenience for `ItemPermission.grant(menu, some_role, PermissionAction.VIEW)`
+        - works for a Group, a Role, a SubRole, or anything else with a pk.
+        Idempotent: granting the same thing twice is a no-op.
+        """
+        return cls.objects.get_or_create(
+            content_type=ContentType.objects.get_for_model(item),
+            object_id=item.pk,
+            grantee_content_type=ContentType.objects.get_for_model(grantee),
+            grantee_object_id=grantee.pk,
+            action=action,
+        )[0]
+
+    @classmethod
+    def revoke(cls, item, grantee, action):
+        """Undo a grant() call. Silently no-ops if it wasn't granted."""
+        cls.objects.filter(
+            content_type=ContentType.objects.get_for_model(item),
+            object_id=item.pk,
+            grantee_content_type=ContentType.objects.get_for_model(grantee),
+            grantee_object_id=grantee.pk,
+            action=action,
+        ).delete()
+
+    @classmethod
+    def for_grantee(cls, grantee):
+        """
+        All ItemPermission rows for one grantee (a specific Role, SubRole,
+        Group, ...) - i.e. "what can this Role/SubRole access, and with
+        which actions". Returns a queryset; use list_for_grantee() below
+        for a readable summary instead of raw rows.
+        """
+        return cls.objects.filter(
+            grantee_content_type=ContentType.objects.get_for_model(grantee),
+            grantee_object_id=grantee.pk,
+        )
+
+    @classmethod
+    def for_item(cls, item):
+        """All ItemPermission rows granted on one item (a specific Menu,
+        SubMenu, Page, or Widget) - i.e. "who can access this, and how"."""
+        return cls.objects.filter(
+            content_type=ContentType.objects.get_for_model(item),
+            object_id=item.pk,
+        )
+
+
+class PermissionedItemMixin(models.Model):
+    """Reverse generic relation so `item.permissions.all()` works and
+    deleting an item cleans up its ItemPermission rows automatically."""
+
+    permissions = GenericRelation(ItemPermission)
+
+    class Meta:
+        abstract = True
+
+
+class Menu(PermissionedItemMixin):
+    name = models.CharField(max_length=100)
+    slug = models.SlugField(unique=True, max_length=100)
+    icon = models.CharField(max_length=100, blank=True, help_text="Optional icon name for the frontend.")
+    order = models.PositiveIntegerField(default=0)
+    is_active = models.BooleanField(default=True)
+
+    class Meta:
+        db_table = _table("Menu", "dynamic_nav_menu")
+        ordering = ["order", "id"]
+
+    def __str__(self):
+        return self.name
+
+
+class SubMenu(PermissionedItemMixin):
+    menu = models.ForeignKey(Menu, related_name="submenus", on_delete=models.CASCADE)
+    name = models.CharField(max_length=100)
+    slug = models.SlugField(max_length=100)
+    icon = models.CharField(max_length=100, blank=True)
+    order = models.PositiveIntegerField(default=0)
+    is_active = models.BooleanField(default=True)
+
+    class Meta:
+        db_table = _table("SubMenu", "dynamic_nav_submenu")
+        ordering = ["order", "id"]
+        constraints = [
+            models.UniqueConstraint(
+                fields=["menu", "slug"], name="unique_submenu_slug_per_menu"
+            )
+        ]
+
+    def __str__(self):
+        return f"{self.menu.name} / {self.name}"
+
+
+class Page(PermissionedItemMixin):
+    submenu = models.ForeignKey(SubMenu, related_name="pages", on_delete=models.CASCADE)
+    name = models.CharField(max_length=100)
+    slug = models.SlugField(max_length=100)
+    order = models.PositiveIntegerField(default=0)
+    is_active = models.BooleanField(default=True)
+    layout = models.JSONField(
+        blank=True, null=True, help_text="Optional grid/layout config for the frontend."
+    )
+
+    class Meta:
+        db_table = _table("Page", "dynamic_nav_page")
+        ordering = ["order", "id"]
+        constraints = [
+            models.UniqueConstraint(
+                fields=["submenu", "slug"], name="unique_page_slug_per_submenu"
+            )
+        ]
+
+    def __str__(self):
+        return f"{self.submenu} / {self.name}"
+
+
+class Widget(PermissionedItemMixin):
+    class WidgetType(models.TextChoices):
+        CHART = "chart", "Chart"
+        GRAPH = "graph", "Graph"
+        KPI = "kpi", "KPI"
+        TABLE = "table", "Table"
+        FIELD = "field", "Field"
+        TEXT = "text", "Text"
+        CUSTOM = "custom", "Custom"
+
+    page = models.ForeignKey(Page, related_name="widgets", on_delete=models.CASCADE)
+    name = models.CharField(max_length=100)
+    widget_type = models.CharField(max_length=20, choices=WidgetType.choices)
+    order = models.PositiveIntegerField(default=0)
+    is_active = models.BooleanField(default=True)
+    config = models.JSONField(
+        blank=True,
+        null=True,
+        help_text="Frontend-specific config: chart type, data source endpoint, columns, etc.",
+    )
+
+    class Meta:
+        db_table = _table("Widget", "dynamic_nav_widget")
+        ordering = ["order", "id"]
+
+    def __str__(self):
+        return f"{self.page} / {self.name}"

dynamic_nav/permissions.py

@@ -0,0 +1,151 @@
+from collections import defaultdict
+
+from django.conf import settings
+from django.contrib.contenttypes.models import ContentType
+from django.db.models import Q
+from django.utils.module_loading import import_string
+
+from .models import ItemPermission, PermissionAction
+
+ALL_ACTIONS = {choice.value for choice in PermissionAction}
+
+
+def default_get_user_grantees(user):
+    """
+    Default grantee resolver: just the user's Django Groups.
+
+    Override via settings:
+        DYNAMIC_NAV_GRANTEE_RESOLVER = "myapp.permissions.get_user_grantees"
+
+    Your resolver receives the User and returns a list of model instances
+    - any mix of Group, your Role, your SubRole, a Team, etc. Each must
+    just be a normal model instance with a pk; this app never needs to
+    know their shape.
+    """
+    if not user or not user.is_authenticated:
+        return []
+    return list(user.groups.all())
+
+
+def get_user_grantees(user):
+    path = getattr(settings, "DYNAMIC_NAV_GRANTEE_RESOLVER", None)
+    resolver = import_string(path) if path else default_get_user_grantees
+    return resolver(user)
+
+
+def list_for_grantee(grantee):
+    """
+    Human-readable summary of everything one Role/SubRole/Group can access.
+
+    Returns a list of {"item": <Menu|SubMenu|Page|Widget instance>,
+    "actions": ["view", "update", ...]}, one entry per item, actions sorted
+    and grouped (so a Role granted both view and update on the same Widget
+    shows up once, not as two rows).
+
+    >>> for entry in list_for_grantee(sales_manager_subrole):
+    ...     print(entry["item"], entry["actions"])
+    Dashboard ['view']
+    Dashboard / Sales / Revenue ['view']
+    Dashboard / Sales / Revenue / Monthly Revenue ['update', 'view']
+    """
+    rows = ItemPermission.for_grantee(grantee).select_related("content_type")
+    grouped = defaultdict(list)
+    items = {}
+    for row in rows:
+        key = (row.content_type_id, row.object_id)
+        grouped[key].append(row.action)
+        if key not in items:
+            items[key] = row.content_object
+    return [
+        {"item": items[key], "actions": sorted(actions)}
+        for key, actions in grouped.items()
+    ]
+
+
+def list_for_item(item):
+    """
+    Human-readable summary of everyone who can access one item.
+
+    Returns a list of {"grantee": <Group|Role|SubRole instance>,
+    "actions": [...]}, same grouping behaviour as list_for_grantee().
+    """
+    rows = ItemPermission.for_item(item).select_related("grantee_content_type")
+    grouped = defaultdict(list)
+    grantees = {}
+    for row in rows:
+        key = (row.grantee_content_type_id, row.grantee_object_id)
+        grouped[key].append(row.action)
+        if key not in grantees:
+            grantees[key] = row.grantee
+    return [
+        {"grantee": grantees[key], "actions": sorted(actions)}
+        for key, actions in grouped.items()
+    ]
+
+
+class PermissionResolver:
+    """
+    Batch-loads ItemPermission rows for a set of objects against the
+    current user's grantees (Groups, Roles, SubRoles, or whatever your
+    DYNAMIC_NAV_GRANTEE_RESOLVER returns), so checking permissions across
+    a whole menu tree costs a handful of queries (one per model preloaded)
+    instead of one per node.
+
+    Usage:
+        resolver = PermissionResolver(request.user)
+        resolver.preload(Menu, menus)
+        resolver.preload(SubMenu, submenus)
+        ...
+        resolver.can(some_menu, PermissionAction.VIEW)
+        resolver.actions_for(some_menu)  # -> {"view", "update"}
+    """
+
+    def __init__(self, user):
+        self.user = user
+        self.is_superuser = bool(user and user.is_authenticated and user.is_superuser)
+
+        # (content_type_id, object_id) for every grantee this user has -
+        # e.g. their Groups AND their Role AND their SubRole all at once.
+        self._grantee_keys = []
+        if not self.is_superuser:
+            for grantee in get_user_grantees(user):
+                ct = ContentType.objects.get_for_model(type(grantee))
+                self._grantee_keys.append((ct.id, grantee.pk))
+
+        self._map = {}  # {(content_type_id, object_id): {actions}}
+
+    def _grantee_q(self):
+        """One Q object covering all grantee types at once, e.g.
+        (grantee_ct=Group AND grantee_id IN [1,2]) OR (grantee_ct=Role AND grantee_id IN [5])."""
+        by_ct = defaultdict(list)
+        for ct_id, obj_id in self._grantee_keys:
+            by_ct[ct_id].append(obj_id)
+        q = Q()
+        for ct_id, ids in by_ct.items():
+            q |= Q(grantee_content_type_id=ct_id, grantee_object_id__in=ids)
+        return q
+
+    def preload(self, model, objects):
+        """Fetch permissions for a batch of instances of one model in a single query."""
+        if self.is_superuser or not self._grantee_keys:
+            return
+        ids = [obj.pk for obj in objects]
+        if not ids:
+            return
+        content_type = ContentType.objects.get_for_model(model)
+        rows = ItemPermission.objects.filter(
+            self._grantee_q(), content_type=content_type, object_id__in=ids
+        ).values_list("object_id", "action")
+        for object_id, action in rows:
+            self._map.setdefault((content_type.id, object_id), set()).add(action)
+
+    def actions_for(self, obj) -> set:
+        if self.is_superuser:
+            return set(ALL_ACTIONS)
+        if not self._grantee_keys:
+            return set()
+        content_type = ContentType.objects.get_for_model(obj)
+        return self._map.get((content_type.id, obj.pk), set())
+
+    def can(self, obj, action: str) -> bool:
+        return action in self.actions_for(obj)

dynamic_nav/serializers.py

@@ -0,0 +1,77 @@
+from rest_framework import serializers
+
+from .models import Menu, Page, SubMenu, Widget
+from .permissions import PermissionAction
+
+
+class WidgetSerializer(serializers.ModelSerializer):
+    permissions = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Widget
+        fields = ["name", "widget_type", "order", "config", "permissions"]
+
+    def get_permissions(self, obj):
+        return sorted(self.context["resolver"].actions_for(obj))
+
+
+class PageSerializer(serializers.ModelSerializer):
+    widgets = serializers.SerializerMethodField()
+    permissions = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Page
+        fields = ["name", "slug", "order", "layout", "widgets", "permissions"]
+
+    def get_widgets(self, obj):
+        resolver = self.context["resolver"]
+        # obj.widgets.all() reuses the prefetch cache set up by the view -
+        # no extra query here.
+        visible = [
+            w for w in obj.widgets.all()
+            if w.is_active and resolver.can(w, PermissionAction.VIEW)
+        ]
+        return WidgetSerializer(visible, many=True, context=self.context).data
+
+    def get_permissions(self, obj):
+        return sorted(self.context["resolver"].actions_for(obj))
+
+
+class SubMenuSerializer(serializers.ModelSerializer):
+    pages = serializers.SerializerMethodField()
+    permissions = serializers.SerializerMethodField()
+
+    class Meta:
+        model = SubMenu
+        fields = ["name", "slug", "icon", "order", "pages", "permissions"]
+
+    def get_pages(self, obj):
+        resolver = self.context["resolver"]
+        visible = [
+            p for p in obj.pages.all()
+            if p.is_active and resolver.can(p, PermissionAction.VIEW)
+        ]
+        return PageSerializer(visible, many=True, context=self.context).data
+
+    def get_permissions(self, obj):
+        return sorted(self.context["resolver"].actions_for(obj))
+
+
+class MenuSerializer(serializers.ModelSerializer):
+    submenus = serializers.SerializerMethodField()
+    permissions = serializers.SerializerMethodField()
+
+    class Meta:
+        model = Menu
+        fields = ["name", "slug", "icon", "order", "submenus", "permissions"]
+
+    def get_submenus(self, obj):
+        resolver = self.context["resolver"]
+        visible = [
+            sm for sm in obj.submenus.all()
+            if sm.is_active and resolver.can(sm, PermissionAction.VIEW)
+        ]
+        return SubMenuSerializer(visible, many=True, context=self.context).data
+
+    def get_permissions(self, obj):
+        return sorted(self.context["resolver"].actions_for(obj))

dynamic_nav/urls.py

@@ -0,0 +1,10 @@
+from django.urls import path
+
+from .views import MenuTreeView, PageDetailView
+
+app_name = "dynamic_nav"
+
+urlpatterns = [
+    path("menus/", MenuTreeView.as_view(), name="menu-tree"),
+    path("pages/<slug:slug>/", PageDetailView.as_view(), name="page-detail"),
+]

dynamic_nav/views.py

@@ -0,0 +1,83 @@
+from rest_framework.exceptions import PermissionDenied
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from .models import Menu, Page, SubMenu, Widget
+from .permissions import PermissionResolver
+from .serializers import MenuSerializer, PageSerializer
+from .models import PermissionAction
+
+
+class MenuTreeView(APIView):
+    """
+    GET /menus/
+
+    Returns the full navigation tree - menus, submenus, pages, widgets -
+    pruned to only what the requesting user's groups grant 'view' on.
+    Each node also carries a `permissions` list (e.g. ["view", "update"])
+    so the frontend can show/hide edit affordances without another call.
+    """
+
+    permission_classes = [IsAuthenticated]
+
+    def get(self, request):
+        menus = list(
+            Menu.objects.filter(is_active=True).prefetch_related(
+                "submenus__pages__widgets"
+            )
+        )
+
+        # Flatten the tree once so each model's permissions can be
+        # preloaded in a single query, instead of one query per node.
+        submenus, pages, widgets = [], [], []
+        for menu in menus:
+            for submenu in menu.submenus.all():
+                submenus.append(submenu)
+                for page in submenu.pages.all():
+                    pages.append(page)
+                    widgets.extend(page.widgets.all())
+
+        resolver = PermissionResolver(request.user)
+        resolver.preload(Menu, menus)
+        resolver.preload(SubMenu, submenus)
+        resolver.preload(Page, pages)
+        resolver.preload(Widget, widgets)
+
+        visible_menus = [m for m in menus if resolver.can(m, PermissionAction.VIEW)]
+        serializer = MenuSerializer(
+            visible_menus, many=True, context={"request": request, "resolver": resolver}
+        )
+        return Response(serializer.data)
+
+
+class PageDetailView(APIView):
+    """
+    GET /pages/<slug>/
+
+    Returns a single page and its permission-filtered widgets. Raises 403
+    if the requesting user's groups don't grant 'view' on the page itself.
+    """
+
+    permission_classes = [IsAuthenticated]
+
+    def get(self, request, slug):
+        try:
+            page = Page.objects.select_related("submenu__menu").prefetch_related(
+                "widgets"
+            ).get(slug=slug, is_active=True)
+        except Page.DoesNotExist:
+            return Response({"detail": "Page not found."}, status=404)
+
+        resolver = PermissionResolver(request.user)
+        resolver.preload(Page, [page])
+        if not resolver.can(page, PermissionAction.VIEW):
+            raise PermissionDenied("You do not have permission to view this page.")
+
+        widgets = list(page.widgets.all())
+        resolver.preload(Widget, widgets)
+
+        serializer = PageSerializer(
+            page, context={"request": request, "resolver": resolver}
+        )
+        return Response(serializer.data)