crudkit

A metadata-driven CRUD framework for Django. Define models; get typed object IDs, soft delete, merge, change logging, an activity feed, saved views, AI-populated fields and a generic REST API — without writing per-model serializers, viewsets or routes.

Core concepts

Every CrudKit model inherits BaseCrudKitModel and declares a 3-letter TYPE_ID. Object IDs are rendered as <TYPE_ID><pk> (e.g. CUS42) across the API and UI.

from django.db import models
from crudkit.models import BaseCrudKitModel

class Customer(BaseCrudKitModel):
    TYPE_ID = "CUS"
    name = models.CharField(max_length=255)

    class CrudKitSettings(BaseCrudKitModel.CrudKitSettings):
        search_fields = ["name"]

Included with every model: created_by/updated_by/created_at/updated_at audit columns, a deleted soft-delete flag (soft_delete()), merge support (delete_and_merge_with()), a change log, an activity feed (FeedItem), external-system sync (ExternalObject), saved views/layouts, and optional AI fields (AISummaryField, AICategoryField, AIBooleanField, AITagsField, AIForeignKeyField) populated asynchronously via Celery and pydantic-ai.

Installation

pip install crudkit[api]          # REST API included
pip install crudkit[assistant]    # + per-object AI assistant (Channels)

INSTALLED_APPS = [
    ...,
    "rest_framework",
    "crudkit",
    "crudkit_assistant",  # optional
]

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "crudkit_api.permissions.CrudKitModelPermissions",
    ],
    "DEFAULT_PAGINATION_CLASS": "crudkit_api.pagination.CrudKitPagination",
    "DEFAULT_FILTER_BACKENDS": ["crudkit_api.filters.BasicFilter"],
    "PAGE_SIZE": 50,
}

# urls.py — one include registers a full CRUD API for every TYPE_ID model
urlpatterns = [path("api/v1/", include("crudkit_api.urls"))]

CrudKit requires the standard Django model permissions for every API and assistant operation. Projects that need row-level rules can override CrudKitSettings.get_authorized_queryset(user, queryset, action); action is one of view, add, change, or delete. Model actions require change permission and can be narrowed further with CrudKitSettings.has_action_permission(user, instance, action_name).

Settings

Bundled frontend

The wheel ships the built CrudKit web SPA. To serve it, add the app, the context processor, a config dict, and a catch-all url include (last!):

INSTALLED_APPS = [..., "crudkit_frontend"]

TEMPLATES = [{
    ...,
    "OPTIONS": {"context_processors": [
        ...,
        "crudkit_frontend.context_processors.crudkit_config",
    ]},
}]

CRUDKIT_FRONTEND_CONFIG = {"app_name": "My App"}  # injected into the SPA at runtime
CRUDKIT_FRONTEND_LOGIN_REQUIRED = False  # True → redirect anonymous users to LOGIN_URL

# urls.py — must be the LAST pattern; everything unmatched serves the SPA
urlpatterns = [..., path("", include("crudkit_frontend.urls"))]

Static assets are served by django.contrib.staticfiles (or WhiteNoise et al.) from crudkit_frontend/static/, under whatever STATIC_URL the project uses — nothing assumes the default static/ prefix. Contributors hacking on the SPA itself run the Vite dev server from ../frontend against any CrudKit backend; npm run build there regenerates the bundled assets.

Running the tests

cd backend
uv sync --all-extras
uv run manage.py test crudkit crudkit_api crudkit_assistant crudkit_frontend tests

License

MIT