kiwi-tcms-admin-overlay

A Kiwi TCMS plugin that overlays a sophisticated admin shell on top of Django's stock admin — dashboard, command palette, smart sidebar grouping, contextual badges, and live notifications — without modifying Kiwi TCMS or any other plugin.

Screenshots

The overlay layered on a real Kiwi TCMS install:

Dashboard with categorised sidebar, hero, three cards (Quick stats / System health / Recent activity), and the plugin tile grid below
Same view zoomed on the cards — note the per-card monospace data, hairline grid, and the top-right ▤ ◐ ↻ action buttons
Notifications bell dropdown — per-user activity stream with read markers and the Mark all action
Recent activity card with long Django content-type pills wrapping cleanly inside the column
Stock Django changelist restyled — mono uppercase headers, hairline rules, hover paper-sunken; the trailing column shows the per-row badges (e.g. 45 pass · 9 fail on TestRun)

The full design preview is at docs/design-preview.html — open it in any browser to see every component at full fidelity, including the light/dark/system theme toggle, without spinning up Django.

Why

Kiwi's /admin/ is the stock Django admin (lightly skinned by Grappelli). Once several plugins are installed, the index becomes a flat alphabetic wall of model classes. There's no global search, no dashboard, no per-domain grouping, no contextual signal. This plugin enriches that experience without forking anything.

How it stays out of the way

• Pure additive. Composes the existing Django admin via response-rewriting middleware (the same pattern used by kiwitcms-review and kiwitcms-requirements). No AdminSite subclass. No template inheritance fights with Grappelli.
• No Kiwi changes. Drops in via the kiwitcms.plugins entry point.
• Easily disabled. Set KIWI_TCMS_ADMIN_OVERLAY = {"enabled": False} and the overlay deactivates without uninstall.
• No rebranding. "Kiwi TCMS" wordmark is preserved everywhere, per upstream license.

What it adds

Compatibility

Install (development)

pip install -e /path/to/kiwi-tcms-admin-overlay
./manage.py migrate kiwi_tcms_admin_overlay
./manage.py runserver

Visit /admin/ — the new shell renders. Stock admin pages still work.

Configure

Every option is optional. Defaults shown:

# settings.py (or local_settings.py)
KIWI_TCMS_ADMIN_OVERLAY = {
    "enabled": True,
    "categories": None,                  # None → use defaults; list → replace
    "category_overrides": {},            # surgical {"app_label": "category_key"}
    "dashboard_cache_seconds": 30,
    "notifications_poll_seconds": 60,
    "show_uncategorised_warning": True,
    "theme_default": "system",           # light | dark | system
}

Extending — for plugin authors

Three registries are available; call them from your own AppConfig.ready():

from kiwi_tcms_admin_overlay import (
    AdminCategory, register_category,
    Badge, register_badge,
    register_notification_source,
)

class MyPluginConfig(AppConfig):
    def ready(self):
        # Sidebar grouping
        register_category(AdminCategory(
            "my_domain", "My Domain", "fa-flask", 25,
            ("my_plugin_app",),
        ))

        # Per-row changelist badges
        def badge_provider(model, queryset):
            return {row.pk: [Badge("active", "pass")] for row in queryset.filter(active=True)}
        register_badge("my_plugin_app", "mything", badge_provider)

        # Notification source for the bell
        def notifs(request, limit):
            for item in MyNotification.objects.filter(user=request.user)[:limit]:
                yield {
                    "source": "my_plugin",
                    "key": str(item.pk),
                    "label": item.title,
                    "hint": "my_plugin.mything",
                    "verb": "needs review",
                    "actor": item.from_user.username,
                    "time": item.created_at.isoformat(),
                    "href": item.get_absolute_url(),
                }
        register_notification_source("my_plugin", notifs)

All registrations are app-startup-only; runtime mutation is rejected so per-user caches stay consistent.

Architecture

┌─────────────────────────────────────────────────────┐
│  Browser (admin page)                                │
│  ┌────────────────────────────────────────────────┐ │
│  │ overlay.css + shell.js + palette.js +          │ │
│  │ badges.js + notifications.js                   │ │
│  └────────────────────────────────────────────────┘ │
│                       ↕                              │
│  /admin_overlay/api/{dashboard,health,sidebar,…}/    │
└─────────────────────────────────────────────────────┘
                       ↕
┌─────────────────────────────────────────────────────┐
│  Django (your existing Kiwi install)                 │
│   • AdminOverlayMiddleware injects bundle into HTML  │
│   • ModelAdmin permissions gate every endpoint       │
│   • OverlayNotificationRead persists read markers    │
└─────────────────────────────────────────────────────┘

Testing

make test                 # full pytest suite (107 tests at 0.1.0)
make test-a11y            # contrast + accessibility-only (fast canary)
make lint                 # flake8 + pylint

The accessibility CI surface includes a contrast verifier that asserts every documented design-token pair meets WCAG AA in both light and dark mode. See docs/accessibility.md for the manual axe-core audit procedure.

Design preview

docs/design-preview.html is a single self-contained file demonstrating every UI component at full fidelity, with light/dark/system theme cycling. Open it in any browser without Django running.

Status

v0.1.0 — feature-complete, internal use only. PyPI publish on hold pending broader review.

License

GPL-2.0-or-later, matching Kiwi TCMS upstream.