django-tenantkit-core 0.3.0

A comprehensive Django multi-tenancy solution with schema isolation, tenant-aware middleware, and flexible routing

django-tenantkit

A Django-native multitenancy framework focused on explicit isolation strategies, clear shared-versus-tenant boundaries, and integration with Django middleware, routing, admin, and provisioning workflows.

---

Why this package?

Multi-tenant Django systems often need different trade-offs depending on scale, operational model, and isolation requirements. Some solutions focus primarily on PostgreSQL schema isolation, while others assume a narrower routing or provisioning model.

This project aims to provide a more flexible foundation for Django applications that need:

• explicit tenant isolation strategies
• clear separation between shared/public and tenant-scoped data
• Django-native integration points instead of a parallel platform model
• a path toward a reusable package plus a reference example project

---

Supported isolation strategies

The framework currently supports two primary isolation modes:

Strategy	Description	Best fit
schema	Multiple PostgreSQL schemas inside one shared database	Shared infrastructure with strong logical isolation
database	A dedicated database per tenant	Stronger operational isolation and backend flexibility

The shared/public control plane remains separate from tenant-scoped runtime behavior.

See Concepts for the model vocabulary and architectural terms.

---

Audit and soft-delete

All framework models include mandatory audit tracking via django-auditkit:

• created_at, updated_at, deleted_at — timestamps
• created_by, updated_by, deleted_by — user tracking (foreign keys to AUTH_USER_MODEL)

This provides:

• Soft delete — records are marked deleted but retained for audit/history
• User attribution — every change is traceable to a user
• Recovery — soft-deleted records can be restored

The framework models (Tenant, TenantInvitation, TenantSetting) all inherit from AuditModel and include these fields automatically. The admin interface shows audit information in a collapsed section at the bottom of each form.

---

Installation

This repository uses a package-first layout. The reusable package lives under src/tenantkit, while example/ contains the reference Django project.

For the current setup and integration path, see:

• Installation
• Quickstart

---

Minimal quickstart

At a high level, a Django project using the framework will:

1. add the multitenancy app to INSTALLED_APPS
2. add tenant-aware middleware
3. add the tenant database router
4. define shared and tenant-scoped models
5. create one or more tenants
6. run the appropriate migration workflow

The current reference Django project lives in example/, while the package source lives in src/tenantkit.

For the guided flow, see Quickstart.

Quick Configuration

Critical: The order of INSTALLED_APPS and MIDDLEWARE matters. See Setup Standard Guide for full details.

# settings.py - Minimal working configuration

INSTALLED_APPS = [
    # Django core FIRST (auth before tenantkit)
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    
    # TenantKit AFTER auth
    "tenantkit",
    
    # Your apps
    "myapp",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",  # BEFORE
    "tenantkit.middleware.TenantMiddleware",                  # AFTER
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
]

DATABASE_ROUTERS = ["tenantkit.routers.TenantRouter"]

TENANTKIT_BOTH_APPS = [
    "django.contrib.auth",
    "django.contrib.contenttypes",
]

Why this order matters:

• django.contrib.auth must come before tenantkit so User/Group/Permission models register first in the public schema
• AuthenticationMiddleware must come before TenantMiddleware so authentication happens in public before switching to the tenant schema

---

Official test command

The current stable validation path is:

uv sync --dev
uv run python example/manage.py test tenantkit

For local development, the repository is managed from the root and the example project acts as a consumer of the package.

See Testing for the current testing entrypoints.

---

Example project

The repository includes a Django reference project in example/. It currently serves as:

• the integration environment
• the test harness
• the reference wiring for settings, middleware, routing, and admin behavior

The reusable package itself lives in src/tenantkit.

See Example Project.

---

Documentation

Public documentation:

• Installation
• Setup Standard Guide - Start here for configuration order
• Configuration Guide
• Quickstart
• Concepts
• Commands
• Provisioning
• Testing
• Example Project
• API Reference

Technical and architectural material:

• Model Configuration Implementation
• Auth and Admin
• ADRs
• Architecture RFC (target)

---

Compatibility

Project status	Python	Django
Current main branch	3.12, 3.13	6.0

• Schema isolation requires PostgreSQL
• Database isolation depends on backend-specific provisioning and runtime support

---

Status

This project is under active development.

Current transition goals include:

• refining the public documentation structure
• stabilizing the new package-first repository layout
• keeping the example/ project as the reference integration environment

---

Contributing

See CONTRIBUTING.md. All changes should go through Pull Requests.

---

License

MIT License. See LICENSE.