🚀 SnapAdmin — Declarative Django Admin & API

Define your model fields once — get a feature-rich Django admin, a REST API with Swagger docs, a GraphQL API, and optional Elasticsearch search. Every surface can be switched on or off with a single setting, and expensive ?search= queries are routed to Elasticsearch automatically when a model is mirrored there — plain listings stay on the database.

📚 Full Documentation — configuration guide, API reference, examples 📦 Django Packages — compare SnapAdmin against other Django admin packages 📝 Changelog · 🔒 Security policy

⚡ The Core Idea — 3 Steps, Full Stack

# 1. Define a model
from snapadmin import fields as snap, models as snap_models

class Product(snap_models.SnapModel):
    name      = snap.SnapCharField(max_length=200, searchable=True, show_in_list=True)
    price     = snap.SnapDecimalField(max_digits=10, decimal_places=2, filterable=True)
    available = snap.SnapBooleanField(default=True, filterable=True)

    # Optional: mirror to Elasticsearch, auto-delete after a year
    # es_storage_mode = snap_models.EsStorageMode.DUAL
    # data_retention_days = 365

# 2. settings.py — every surface is a toggle
SNAPADMIN_REST_API_ENABLED = True
SNAPADMIN_GRAPHQL_ENABLED  = True
SNAPADMIN_SWAGGER_ENABLED  = True

# 3. admin.py
from snapadmin.models import SnapModel
SnapModel.register_all_admins()

That's it — you get an Unfold-themed admin with filters, badges and change logging, /api/product/ CRUD with Swagger docs, an allDemoProducts GraphQL field, and typo-tolerant search when Elasticsearch is on.

→ Field types · SnapModel reference · Admin registration

👀 What You'll See

These screens come from the bundled demo, not the package — they illustrate what SnapAdmin generates for your models.

┌────────────────────────────────────────────────────────────┐
│  SnapAdmin                           🔍 Search...    admin ▾│
├──────────────┬─────────────────────────────────────────────┤
│  DEMO APP    │  Products                         + Add     │
│  Categories  │ ┌──────────────────────────────────────────┐│
│  Tags        │ │ Name            Price  In Stock  Category ││
│  Products    │ │ Premium Laptop  $249   ● Active   Audio   ││
│  Customers   │ │ Ergonomic Mouse $89    ● Active   Access. ││
│  Orders      │ │ USB-C Hub       $49    ○ Out      Electr. ││
│  Audit Logs  │ └──────────────────────────────────────────┘│
│  SYSTEM      │  Sidebar filters: Price range │ Available   │
│  Dashboard   │                   Category    │             │
└──────────────┴─────────────────────────────────────────────┘

Also generated: Swagger UI at /api/docs/, a GraphQL playground at /api/graphql/, and a system dashboard at /admin/snapadmin/dashboard/ showing per-model row counts, storage modes and scheduled jobs.

📦 Installation

pip install django-snapadmin

Requires Python ≥ 3.10 and Django ≥ 5.2. The package is beta — the public API is stabilising but may still change before 0.1.0 stable, so pin an exact version in production.

Add the stack to INSTALLED_APPS — order matters, unfold must precede django.contrib.admin:

INSTALLED_APPS = [
    "unfold", "unfold.contrib.filters", "unfold.contrib.forms", "unfold.contrib.inlines",
    "django.contrib.admin", "django.contrib.auth", "django.contrib.contenttypes",
    "django.contrib.sessions", "django.contrib.messages", "django.contrib.staticfiles",
    "rest_framework", "drf_spectacular", "django_filters", "graphene_django", "snapadmin",
    # your apps …
]

Installing SnapAdmin pulls in django-unfold, djangorestframework, drf-spectacular, django-filter and graphene-django automatically — you only list them.

Optional extras

The base install is self-contained and carries only permissive licences (MIT/BSD/Apache), so it is safe for commercial and proprietary use. Opt into the rest:

→ Full installation guide — compatibility matrix, extras gotchas, and the licensing notes for [wysiwyg] and MySQL drivers.

✨ Features

Admin

• Declarative list_display / search_fields / list_filter straight from field kwargs
• Unfold-themed responsive UI, colour-coded status badges, horizontal rows and tabs
• Date and numeric range filters; field-level change logging (old → new) with a history view
• Offline mode — per-model IndexedDB prefetch, real backend health checks, sync on reconnect

APIs

• REST CRUD for every SnapModel, with Swagger + ReDoc, filters derived from field types, and streaming/async export
• GraphQL schema generated from the same models, auth-enforced on every traversed relation
• API tokens hashed at rest (SHA-256), shown once, scoped per model — or plug in JWT/session/custom auth
• Privacy controls: api_exclude_fields, api_write_fields (mass-assignment guard), api_json_filters, PII masking

Elasticsearch

• Per-model DB_ONLY / DUAL / ES_ONLY storage modes with auto-derived index mappings
• Smart routing — ?search= on DUAL models runs fuzzy on ES; plain listings stay on SQL
• es_filter() structured term filters, es_aggregate() facets, es_scan() deep scan past the 10k window — each with a DB fallback when ES is off

Operations

• GDPR retention (data_retention_days) and an immutable audit trail
• Error monitoring — spike alerts + daily grouped email digests
• 3-2-1 database backups — local, network share, and offsite FTPS/SFTP
• Large-dataset tuning — auto list_select_related (no admin N+1), estimated counts, per-model paging
• Generic ETL — upsert_from_source() and stale_sync() with a max_fraction wipe guard
• Structured logging via structlog; i18n in 10 locales

Management commands: snapadmin_reindex, db_backup, send_error_digest, purge_expired_data.

⏱ Nothing runs on its own. SnapAdmin ships no daemon — the retention purge, digests and backups need a Celery Beat entry or a cron line. See Background tasks & scheduling.

⚙️ Configuration

Every surface is a plain Django setting; disabling one removes its URL routes entirely (404):

SNAPADMIN_REST_API_ENABLED  = True    # REST CRUD endpoints
SNAPADMIN_GRAPHQL_ENABLED   = True    # GraphQL endpoint
SNAPADMIN_SWAGGER_ENABLED   = True    # Swagger UI + ReDoc
SNAPADMIN_ES_QUERY_ROUTING  = True    # route ?search= on DUAL models to Elasticsearch
SNAPADMIN_GRAPHQL_REQUIRE_AUTH = True # auth + per-model perms on every resolver
SNAPADMIN_URL_PREFIX        = ""      # relocate the whole API surface

→ Full settings reference — every SNAPADMIN_* knob with its default, grouped by area.

🧩 Extending

SnapAdmin is meant to be customised, not forked:

• Add field types — subclass SnapField with your own admin introspection
• Extend a SnapModel — override save(), add managers, mix in your own behaviour
• Add or override REST endpoints — mount your router before SnapAdmin's
• Swap auth, permissions and the ES client — configuration, no code
• Override admin templates and the dashboard — standard Django template resolution

→ Extending & Overriding guide

🌟 Trying the Demo

The repository ships a runnable demo under demo/ — example models (Product, Customer, Order), a seeded database, and a Docker stack with PostgreSQL, Redis and Elasticsearch. It is not published to PyPI; only the top-level snapadmin/ package is.

git clone https://github.com/drofji/django-snapadmin.git
cd django-snapadmin
cp demo/dist.env demo/.env
docker compose -f demo/docker-compose.yml up --build

Then open http://localhost:8000/admin/ (admin / admin).

→ Demo guide — Traefik overlays with HTTPS, the Elasticsearch profile, manual setup without Docker, and the seed command.

📖 Documentation

Upgrading from drofji-automatically-django-admin? See the migration guide.

🔒 Security

API tokens are hashed at rest, rich-text HTML is sanitized before display, GraphQL enforces permissions on every traversed relation, and PII masking is available on both APIs. Report vulnerabilities privately — see SECURITY.md for the policy, the supported-versions row, and the production-hardening checklist.

Third-party dependency licences are inventoried in THIRD_PARTY_NOTICES.md.

🤝 Contributing

See CONTRIBUTING.md. The suite must stay green with 100% coverage on snapadmin/:

pytest

📜 License

MIT — see LICENSE.