🚀 SnapAdmin

Write your data model once. Get the admin panel, the REST API, the GraphQL endpoint and the search index — automatically.

📚 Documentation · 📦 Django Packages · 📝 Changelog · 🔒 Security · 🧭 llms.txt

Start where you are

Why this exists

Every internal tool needs the same four things: a screen where staff manage the data, an API for the mobile app, an API for the frontend team, and a search box. Today each one is written and maintained separately — four descriptions of the same data, four places to update when a field changes, four chances to leak a field you meant to keep private.

SnapAdmin generates all four from one description.

In one sentence for a decision maker: it turns weeks of internal-tool plumbing into a declaration your developers write once, and keeps the admin panel, the APIs and the search in sync automatically — so a field is defined in exactly one place.

What that buys you, concretely. The admin screen your ops team asks for on Friday is a keyword argument, not a sprint. A new field reaches the API, the search index and the audit log the moment it reaches the model — there is no second ticket, and no "we forgot to add it to the serializer" incident. And the fields you don't want exposed are excluded once, in the model, rather than re-excluded in every surface by whoever writes it next.

What it is not. It is not a theme, not a framework, and not a lock-in. Underneath it is ordinary Django — models, ModelAdmin, DRF viewsets. Override any generated piece, or stop using it, without rewriting your data layer. Your hand-written ModelAdmin classes are never replaced: SnapAdmin skips any model you registered yourself.

Proof it holds up

Adoption risk is the real question, so every answer below is something you can verify yourself rather than take on trust.

→ The full quality story, with the names of the test files, so a reviewer can read them.

For teams and enterprise

The questions a tech lead or a manager asks before approving a dependency:

python demo/manage.py seed_large            # 100,000 customers and orders
python demo/manage.py benchmark_list_view   # query count + wall time

Database sharding and replica routing

Outgrowing a single PostgreSQL or MySQL instance today usually means hand-rolling Django DATABASES and DATABASE_ROUTERS. SNAPADMIN_SHARDING replaces that with one settings dict, at two levels of effort — and is completely inert until you set ENABLED: True: no new DATABASES entry, no extra router, no query overhead for an install that ignores it.

# settings.py — the simple path: a flat list of DSNs, sliced automatically
SNAPADMIN_SHARDING = {
    "ENABLED": True,
    "SHARDING_ENABLED": True,    # partition data across shards
    "MIRRORING_ENABLED": True,   # give each shard read replicas
    "REPLICAS_PER_SHARD": 1,
    "DATABASES": [
        "postgres://user:pass@s1-primary:5432/db", "postgres://user:pass@s1-replica:5432/db",
        "postgres://user:pass@s2-primary:5432/db", "postgres://user:pass@s2-replica:5432/db",
    ],
}

Or name every shard's primary/replicas explicitly (SHARDS = {"shard_1": {"PRIMARY": ..., "REPLICAS": [...]}}) for full manual control, with STRATEGY picking how a row's shard is resolved — modulo, hash, range, or your own CUSTOM_ROUTER_FUNC.

A model opts in with shard_key — a field name, or True for the project-wide default — mirroring exactly how tenant_scoped opts a model into multi-tenancy above, so nothing (including Django's own auth/sessions/admin tables) is ever routed across shards without asking:

class Order(SnapModel):
    shard_key = "customer_id"

snap_master_only() / snap_target(shard="shard_2", replica=True) force routing for one block of code — both work as a context manager or a decorator, on a plain function or an async def one alike. manage.py snap_migrate migrates every shard's primary only (sequentially, or all at once with --parallel), and manage.py snapadmin_db_backup backs up every shard's primary too — neither command ever touches a replica. HA_SETTINGS controls failover (promote a live replica to serve writes when the primary is down) and fallback (read from the primary once every replica is down, or refuse outright if you'd rather protect the primary from that traffic). Full reference: Database sharding.

Encrypted model fields

PII masking hides a value at render time and encrypted backups protect the whole artefact. Neither protects the column: a stolen dump, a rogue read-replica or an over-broad SELECT still sees everything. SnapEncrypted*Field closes that — ciphertext at rest, the ordinary Python value in your code, and nothing above the field changes:

from snapadmin import fields as snap, models as snap_models

class Patient(snap_models.SnapModel):
    name  = snap.SnapCharField(max_length=200, searchable=True)
    ssn   = snap.SnapEncryptedCharField(max_length=32, show_in_list=False)
    email = snap.SnapEncryptedEmailField(blind_index=True)   # still findable by value

Patient.objects.create(name="A. Wiese", ssn="123-45-6789")
# the ssn column now holds: snap1.2026-09.<nonce>.<ciphertext>
Patient.objects.get(email="a@example.org").ssn      # → "123-45-6789"

Eight types — Char, Text, Email, JSON, Integer, Decimal, Date, DateTime — each its plain counterpart plus encryption, keeping its own form widget, validation and Python type. AES-256-GCM behind the optional [encryption] extra, a fresh random nonce on every write, and each value bound to its own app.model.field so a ciphertext copied into another column fails to decrypt instead of quietly relocating a secret. Keys come from a KMS/Vault provider, a mounted secret, the environment or settings — never SECRET_KEY, which a startup check refuses outright — and rotation is prepending one key: every ciphertext records the id that opens it.

What it costs, stated up front. The database cannot compare, order or index a column it cannot read. icontains, gt, startswith and ORDER BY are impossible, and each raises a FieldError naming the field rather than returning an empty queryset — encrypted data silently becoming invisible data is the failure that matters here. blind_index=True buys back __exact / __in and unique=True through an HMAC sibling column, at the documented cost that equality becomes observable to anyone who can read that column: fine for an email address, wrong for a national ID.

Encrypted values are excluded from Elasticsearch, redacted in the audit trail, masked by default in REST/GraphQL/exports/the changelist through the existing PII permission model, and emitted as ciphertext by dumpdata. manage.py snapadmin_encrypt_fields adopts an existing plaintext column, rotates rows onto a new key and rebuilds blind indexes — batched, resumable, and writing nothing without --apply. Full reference: Field encryption.

Getting started

Try it — 60 seconds, no setup

pip install django-snapadmin
snapadmin-new myshop
cd myshop
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Open http://127.0.0.1:8000/admin/. The admin, the REST API (/api/docs/) and GraphQL (/api/graphql/) are already running against a working example model. SQLite, no Docker, nothing to edit by hand.

Just want to look around first? snapadmin-demo downloads a fully-loaded demo — search, audit trail, background jobs, the works. Log in at /admin/ with admin / admin.

Your first model — 3 steps

You add keyword arguments to your fields. They describe how the field should behave, and they add no database migration.

1. Declare the model.

# models.py
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_form=True)
    price     = snap.SnapDecimalField(max_digits=10, decimal_places=2, filterable=True, show_in_form=True)
    available = snap.SnapBooleanField(default=True, filterable=True, show_in_form=True)

    api_write_fields = ["name", "price", "available"]   # what an API client may set

2. Turn on the surfaces you want.

# settings.py
SNAPADMIN_REST_API_ENABLED = True    # off by default — you opt in
SNAPADMIN_GRAPHQL_ENABLED  = True    # same
SNAPADMIN_SWAGGER_ENABLED  = True

3. Register every model — one line.

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

That is the whole setup. You now have:

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

The cheat sheet — the kwargs you'll actually use

Six keyword arguments cover most of what a new joiner needs on day one. None of them touch the database, so you can change your mind without a migration.

On the model itself:

More kwargs — tab / row layout, autocomplete, wysiwyg, upload validation — in the field reference. There are 30+ field types, from SnapCharField to SnapPhoneField, SnapColorField and SnapStatusBadgeField.

Already have models you cannot rewrite?

Subclassing SnapModel is the full route, and it is the natural choice for a new model. If your model layer already exists — a brownfield schema, a base class from a third-party package, fields from django-money or phonenumber_field — opt in from the outside instead. @snap_model adds no field and no attribute, so it needs no migration:

from django.db import models
from snapadmin import snap_model

@snap_model(
    api_write_fields=["name", "price"],   # what an API client may set
    api_exclude_fields=["cost_price"],    # never leaves the server
    search_fields=["name"],               # what ?search= matches on
)
class Product(models.Model):
    name       = models.CharField(max_length=200)
    price      = models.DecimalField(max_digits=10, decimal_places=2)
    cost_price = models.DecimalField(max_digits=10, decimal_places=2)

You get the REST API, the GraphQL schema, the offline endpoints, the system checks and the snapadmin-info inventory. You do not get the parts that need SnapModel's machinery — Elasticsearch mirroring, the retention purge, the generated admin — and those sweeps skip the model rather than half-work. The full comparison table says exactly which is which.

from django.db import models
from snapadmin.fields import snap_field

class Product(models.Model):
    name = snap_field(models.CharField(max_length=255), searchable=True, filterable=True)

→ Field types · SnapModel reference · @snap_model for plain models · snap_field() for one field · Mixing Snap & plain fields

The commands

snapadmin-new myshop --app-name storefront   # name the example app yourself
snapadmin-new myshop --full                  # + Dockerfile, compose, Postgres/Redis/ES

snapadmin-init --api --graphql               # also check the REST / GraphQL config

snapadmin-info --section features            # just the ✓/✗ capability checklist
snapadmin-info --health-check                # probes only; non-zero exit if one fails
snapadmin-info --json                        # the same report for CI / monitoring

snapadmin-license-check --critical-only      # only what blocks commercial use

Is your integration actually correct?

A runnable checklist — every row names the command that proves it, not just the thing to remember. snapadmin-init prints this itself, with a ✅/❌/⚠️ per row (⚠️ = needs a running project to check, never a false green):

→ Full checklist — Must work / Should be configured / Data safety / Optional, with a "why it matters" column.

What you get

🖥 Admin panel — list columns, search and filters derived from your fields · themed responsive UI · status badges, tabs, inlines, autocomplete · field-level change history · an offline mode that keeps a list usable with no connection

🔌 APIs — REST CRUD with Swagger and auto-derived filters · GraphQL with permissions on every traversed relation · API tokens hashed at rest · per-model and per-field guards for what may be read and written · @snap_action exposes a business operation — approve, refund, recalculate — as a permission-checked endpoint, not just CRUD · a model rule that rejects a write answers 400 naming the field, never an HTML 500, and api_full_clean makes your Model.clean() cross-field rules hold for API clients, not just in the admin

🔍 Search (optional) — Elasticsearch with the index mapping derived from your fields · ?search= routed to ES automatically, falling back to the database when ES is down · resumable bulk reindex · deletes keep the index in step, including a bulk QuerySet.delete() and rows removed by a cascade

⚙️ Operations — audit trail · GDPR retention · PII masking · backups · error and health alerts to email, Slack, Discord, Teams or Telegram · structured logging · 10 languages

🧭 Operability — misconfiguration surfaces at startup as a Django system check (snapadmin.E0xx / W0xx), not as a mystery at request time · snapadmin-info reports what is switched on, what is actually in use, and what is unreachable · snapadmin-license-check answers the legal question in one command

Quality & compatibility

This is a package other people's products depend on, so the test suite is treated as part of the product rather than as developer hygiene. Every count below is a floor, read off a real pytest --collect-only -q run rather than kept current by arithmetic — and what is not in place yet is part of this section rather than an omission from it.

Concretely, on the current release:

• 5,000+ tests across 153 files, run on every push. Twelve of them need a live Elasticsearch, so they carry a marker and are deselected by default: cloning the repository and typing pytest starts no container and takes about forty seconds.
• 100% line coverage on the shipped snapadmin/ package — 11,349 statements, 0 missing. CI runs pytest --cov=snapadmin --cov-fail-under=100, so a pull request that adds an untested line fails. Eighteen lines across twelve modules carry a # pragma: no cover, each with a written reason: abstract methods that only raise, if TYPE_CHECKING: blocks, the import-time branch taken when an optional dependency is absent, and five defensive guards for states their callers make unreachable. That list is pinned by a test so it cannot quietly grow. They are still exclusions, and this page will not claim there are none.
• Branch coverage is measured, and reported honestly: 99% — 3,300+ branches, 60 of them taken only one way. It is not a gate yet. Closing those partial branches and then turning the gate on is planned work; this page will say "enforced" only when it is.
• Random order on every run. pytest-randomly reshuffles the suite on each invocation, locally and in CI. A test that quietly depends on another one having run first fails instead of passing, and a seed-dependent failure is treated as a real defect in the tests — never as a reason to pin the order.
• The full compatibility matrix on every push — Python 3.10 / 3.11 / 3.12 / 3.13 × Django 5.2 and 6.0, six jobs. A release is gated on the same matrix: the tag-triggered publish workflow runs it before anything reaches PyPI.
• A seventh job runs the same suite against real services, not mocks — see below.

How those tests are written

The count is the least interesting part, so here is the method behind it.

• Test-first. A behaviour change or a bug fix starts with a test that fails for the right reason; the fix comes second. Every bug fix ships a regression test pinned to the specific input that broke.
• Assertions state a contract, not a pulse. assert result is not None is treated as a defect in the test: the suite asserts the value, the status code, the exception type and message, the row that was written, the query count. A guard test (tests/test_assertions_can_fail.py) reads the suite with ast and fails on assertions no outcome could falsify — assert True, assert x or True, and tests whose entire claim is "it did not raise".
• No test is ever weakened to get a green build. Not a loosened assertion, not a skip, not an xfail, not an extra mock, not an edited expected value. When code and test disagree the question of which one is right is answered first.
• Order-independent by construction — no shared mutable state, no ambient settings, no reliance on the wall clock or on a previously created row. Random order is what proves it.
• The backend is never assumed. The suite runs on SQLite locally and PostgreSQL in CI, so no test may hard-code one. Where behaviour genuinely differs, both halves are written and each skips on a capability (connection.features.supports_json_field_contains), never on a vendor name.

Where the mocks stop and real services start

Elasticsearch, Redis and Celery are stubbed in the everyday run, which keeps it at forty seconds and service-free — but a MagicMock accepts any call with any arguments, so the query DSL those methods exist to build is exactly what a mocked test cannot check. A malformed terms clause or a wrongly-shaped search_after cursor passes a mock and answers 400 from a cluster.

So one CI job (Python 3.12 · Django 5.2) runs against the real thing:

These tests are deselected by default (-m "not real_es"), so cloning the repo and running pytest needs no Docker.

The layers, and what each one protects

Not one pyramid but several overlapping ones, because a library fails in more ways than an application does. Each layer below exists today and runs in the same pytest invocation:

Backward compatibility is a test, not a promise

These suites exist for one purpose only: to fail loudly when a public name, signature or default changes, so a breaking change is a deliberate decision rather than a side effect of a refactor. 340+ of the tests below can only ever fail that way — they assert nothing about behaviour, only about the shape of the surface you import.

Removing or renaming a public name is a major-version-only change under the API-stability policy; deprecations warn first and name their replacement.

The documentation is tested too

Docs rot silently: nothing breaks at import time when a section disappears or a setting is never written down, it just teaches the next reader something false. So the docs are asserted, not trusted:

Automated checks on the operator tooling

snapadmin-info is the command an operator runs to answer "is this configured correctly?" — so a false green there is worse than no report at all. 220+ tests across eleven files cover the diagnostics package, including 80+ in tests/test_diagnostics_features.py alone, where every capability probe in the readiness audit is exercised both switched on and switched off. A capability cannot ship without a probe, and a probe cannot ship without both tests.

The same standard applies to the rest of the operator surface: 200+ tests on the startup system checks, 60+ on the licence audit and its command, and full suites on the scaffolding (snapadmin-new), the read-only integrator (snapadmin-init) and the demo fetcher (snapadmin-demo).

An end-to-end tripwire

Every layer has its own deep suite — and each can keep passing while the seam between layers quietly breaks. tests/test_critical_path_smoke.py walks the whole declarative pipeline in one test: it posts the real generated admin add form, then asserts the row that comes out is the same one the REST API serves and the same one the audit trail recorded, with the acting user and a per-field diff. It is deliberately small — a tripwire for "the pipeline stopped connecting", not a second copy of the deep suites.

What is not in place yet

A quality section that only lists what exists is marketing. These are the layers the project's own engineering standard asks for and does not have today. None of them is claimed anywhere above, and none will be claimed here until it actually runs in CI:

Install

pip install django-snapadmin

Requires Python ≥ 3.10 and Django ≥ 5.2. Pin an exact version in production.

Adding it to an existing project? Run snapadmin-init. It inspects your project and prints a checklist plus the exact snippets to paste. It edits nothing, so there is nothing to undo.

INSTALLED_APPS = [
    # ── Django itself ───────────────────────────────────────────────────────
    "django.contrib.admin",          # SnapAdmin generates ModelAdmins into this site
    "django.contrib.auth",           # permissions gate both the admin and the API
    "django.contrib.contenttypes",   # required by auth; the audit trail keys off it
    "django.contrib.sessions",       # admin login
    "django.contrib.messages",       # admin "saved successfully" banners
    "django.contrib.staticfiles",    # serves SnapAdmin's CSS/JS

    # ── SnapAdmin ───────────────────────────────────────────────────────────
    "snapadmin",

    "myapp",                         # …your own apps
]

# urls.py
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/", include("snapadmin.urls")),   # health check, and any surface you turn on
]

pip install "django-snapadmin[api,graphql]"   # or [api] alone, or [all]

INSTALLED_APPS = [
    ...,
    # ── The API stack — [api] + [graphql] extras ────────────────────────────
    "rest_framework",                # the generated REST endpoints are DRF viewsets
    "drf_spectacular",               # builds the OpenAPI schema behind /api/docs/
    "django_filters",                # backs the auto-generated ?field=… query filters
    "graphene_django",               # the generated GraphQL schema
    "snapadmin",
    ...,
]

# settings.py — the surfaces are opt-in
SNAPADMIN_REST_API_ENABLED = True
SNAPADMIN_GRAPHQL_ENABLED = True
SNAPADMIN_SWAGGER_ENABLED = True      # follows the REST setting unless set explicitly

INSTALLED_APPS = [
    # ── Themed UI — pip install django-snapadmin[theme] ─────────────────────
    # MUST come before django.contrib.admin: Unfold overrides admin templates,
    # and Django resolves templates in INSTALLED_APPS order.
    "unfold",
    "unfold.contrib.filters",        # the sidebar range/dropdown filters SnapAdmin generates
    "unfold.contrib.forms",          # themed form widgets
    "unfold.contrib.inlines",        # themed inline formsets

    # ── Rich text — pip install django-snapadmin[wysiwyg] ───────────────────
    # Only needed for wysiwyg=True / SnapRichTextField. Bundles CKEditor 5,
    # which is GPL-or-commercial — that is why it is not a core dependency.
    "django_ckeditor_5",

    # ── Django itself ───────────────────────────────────────────────────────
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",

    # ── REST API — pip install django-snapadmin[api] ────────────────────────
    # Needed only if you set SNAPADMIN_REST_API_ENABLED/SNAPADMIN_SWAGGER_ENABLED
    # to True — both default to False.
    "rest_framework",
    "drf_spectacular",
    "django_filters",

    # ── GraphQL — pip install django-snapadmin[graphql] ──────────────────────
    # Needed only with SNAPADMIN_GRAPHQL_ENABLED = True (default False). Independent of [api].
    "graphene_django",

    # ── SnapAdmin ───────────────────────────────────────────────────────────
    "snapadmin",

    # ── Background tasks — pip install django-snapadmin[celery] ─────────────
    # Needed for the GDPR purge, async exports, error digests and backups.
    "django_celery_beat",            # edit the schedule from the admin
    "django_celery_results",         # store task results in the database

    # ── Admin-editable settings — pip install django-snapadmin[extra-settings]
    # SnapAdmin does not use it; add it if you want a runtime key/value Setting
    # model in the admin (the demo shows the pattern). If you re-home that admin
    # with EXTRA_SETTINGS_ADMIN_APP, the value is matched against INSTALLED_APPS
    # verbatim: pass the entry ("myapps.shop"), never the app label ("shop") —
    # snapadmin.E025 names the entry to use when the two differ.
    "extra_settings",

    # ── Autocomplete list filters — [autocomplete-filter] (LGPL) ────────────
    # For your own AutocompleteFilter admin filters; SnapAdmin core never imports it.
    "admin_auto_filters",

    "myapp",
]

Configuration

Every surface is a plain Django setting. Switching one off removes its routes entirely:

SNAPADMIN_REST_API_ENABLED       = True    # REST CRUD endpoints — off by default, opt in explicitly
SNAPADMIN_GRAPHQL_ENABLED        = True    # GraphQL endpoint — same, off by default
SNAPADMIN_SWAGGER_ENABLED        = True    # Swagger UI + ReDoc
SNAPADMIN_URL_PREFIX             = ""      # relocate the whole API surface
SNAPADMIN_CONNECTIVITY_ENABLED   = False   # admin-wide health poll + offline save-guard (opt-in)

The first two default to False — a plain-admin migration that never asked for an API doesn't get one by accident. Set them to True to serve REST and/or GraphQL.

Don't want to decide all ~110 of them? SNAPADMIN_PROFILE = "admin" (or "api" / "full") picks sane defaults for the handful that actually matter — an explicit setting always overrides it.

Misconfiguration shows up at startup as a Django system check (snapadmin.W0xx / E0xx), not as a mystery at request time.

→ Every setting, with defaults · SNAPADMIN_PROFILE presets

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

Documentation

Working with an AI assistant? Two entry points ship for exactly that, and both are pinned by tests so they cannot drift from the code: the module map in the snapadmin package docstring (help(snapadmin) — no network needed) and llms.txt.

Security

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

Contributing

See CONTRIBUTING.md. The suite lives at tests/ in the source repository and must stay green with 100% coverage on snapadmin/:

pytest

Regression tests for a specific reported issue live next to the subsystem they cover (e.g. tests/test_fields.py for a field validator, tests/test_pii_masking.py for masking) — if you hit a bug, check there before filing one that might already be covered.

License

MIT — see LICENSE.