Django Multi-Tenant SaaS Starter Template: Enterprise Architecture Practice Based on PostgreSQL Schema Isolation

The Django Multi-Tenant SaaS starter template introduced in this article achieves complete tenant data isolation based on PostgreSQL schema isolation, integrated with DRF, JWT authentication, Docker development environment, and a full CI/CD workflow. Its design philosophy is "Codex-First", treating maintenance as a first-class citizen, supporting Agent-assisted development, and suitable for teams to quickly build secure and compliant enterprise-level SaaS products.

When building SaaS products, it is necessary to solve the tenant data isolation problem. There are three common solutions: 1. Shared database + tenant identifier column (simple but prone to data leakage due to missing filters); 2. Independent database (good isolation but high operation and maintenance cost); 3. Shared database + independent schema (balances isolation and operation complexity). This template chooses the third solution, implemented based on PostgreSQL schema isolation.

1. PostgreSQL schema isolation: Using the django-tenants library, the public schema stores tenant metadata (e.g., public.tenants), and each tenant has an independent schema (e.g., tenant_1.users); 2. Tenant-aware JWT authentication: Login requires specifying the tenant domain, the token contains the tenant identifier, and middleware automatically sets the context; 3. Dockerized development: Provides Compose configuration for one-click startup (./scripts/bootstrap-env.sh + docker compose up); 4. Application structure: apps/tenants (public schema models), apps/authentication (JWT authentication), config/settings (environment configuration), etc.; 5. Request flow: Domain Middleware determines the tenant → sets the context → JWT verification → business logic → tenant-scoped query.

1. Testing: Provides the TenantAPITestCase base class to automatically handle tenant context; 2. Verification script: ./scripts/verify.sh executes code format check, type check, unit test, document synchronization check, etc.; 3. CI/CD: GitHub Actions workflow automatically performs PR checks (code style, tests, etc.) and main branch deployment; 4. Standardized collaboration: Pre-configured Issue templates (bug reports, feature requests, etc.) and PR templates.

The template supports Agent-assisted development, with the core being the AGENTS.md file (containing project map, security rules, verification commands, skill triggers) and the .agents/skills directory (predefined workflows such as tenant policy checks). Example Agent workflow: User needs to add a status field to the orders table → Agent reads AGENTS.md to confirm permission → generates migration → executes verification → submits PR (if verification passes) or reports error (if fails).

Applicable scenarios: B2B SaaS, education platforms (school data isolation), medical systems (patient data isolation), financial applications (compliance requirements), white-label products. Inapplicable scenarios: C2C products (high user interaction), ultra-large-scale tenants (exceeding PostgreSQL schema limits), cross-tenant analysis (frequent data aggregation). Roadmap v0.2.0: Completed AGENTS.md, CI/CD, Issue templates; planned to add more sample applications, Kubernetes deployment, monitoring and alerting, multi-region support.

This template is not only a code template but also a complete engineering practice, solving core problems of multi-tenant architecture: data isolation (PostgreSQL schema), development experience (Docker environment), code quality (testing and verification), collaboration efficiency (Agent-ready), long-term maintenance (document synchronization). It is recommended that teams planning SaaS architecture deeply study this template as a safe and practical starting point.