Angular Material + Django Multi Tenant SaaS CLAUDE.md Template

Overview

This CLAUDE.md template describes a starter for a full-stack Angular Material frontend with a Django-based multi-tenant SaaS backend. It uses a schema-per-tenant tenancy model in PostgreSQL and DRF for API endpoints. It is designed to be copyable into Claude Code as a CLAUDE.md template to rapidly bootstrap tenant-aware features, authentication, data isolation, and a scalable deployable pipeline.

When to Use This CLAUDE.md Template

• You are building a SaaS with multiple tenants requiring strong data isolation.
• You want a single codebase serving many customers with isolated schemas.
• You need a Django REST Framework API backend paired with an Angular Material frontend.
• You require a repeatable, auditable starter for onboarding new tenants quickly.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are a Backend Django + Frontend Angular engineer building a multi-tenant SaaS with Angular Material UI. Claude must deliver a tenant-aware backend, secure APIs, and a responsive admin UI.

Architecture rules:
- Tenancy model: schema-per-tenant in PostgreSQL using django-tenants (or equivalent) for strict data isolation.
- API layer: Django REST Framework with JWT (SimpleJWT) authentication; CRUD endpoints for tenants, users, and resources.
- Frontend: Angular (v14+), Angular Material, lazy-loaded modules, and a token-based session managed by HttpOnly cookies.
- Deployment: Docker-based local dev, and Kubernetes-ready manifests for prod; CI/CD with automated migrations.
- Observability: structured logging, metrics, and tracing where possible.
- Do not tie all tenants to a single shared schema if isolation is required.

File structure rules:
- backend/ holds Django project with apps: core, tenants, users, billing.
- frontend/ holds Angular app with modules for auth, dashboard, tenants, and resources.
- migrations per tenant; avoid cross-tenant data duplication during seeds.
- environment/configs are not hard-coded; use environment variables.

Authentication rules:
- Use JWT (Access and Refresh tokens) with HttpOnly cookies.
- Protect /api/ endpoints with DRF permissions; require authentication for tenant data.
- Enforce per-tenant access controls in serializers and viewsets.

Database rules:
- PostgreSQL with one schema per tenant; migrations run within the tenant context.
- Seed an admin per tenant at onboarding; enforce unique tenant identifiers.

Validation rules:
- DRF serializers include explicit validators for required fields, length, and format.
- Validate tenant isolation on every request; never leak data across tenants.

Security rules:
- CSRF protection for state-changing endpoints; enable secure cookies and TLS in prod.
- Restrict CORS to approved origins; disable debug in production.
- Never expose secret keys or database passwords in code.

Testing rules:
- Unit tests for models, serializers, and viewsets; integration tests for tenant isolation.
- End-to-end tests for tenant onboarding flows using Cypress or Playwright.
- Run tests in CI on push/PRs; ensure migrations are part of the test suite.

Deployment rules:
- Use Docker Compose for local development; Kubernetes manifests or Helm for prod.
- Run migrations at startup; ensure admin seed data is created on tenant creation.
- Collect static files and serve them via a static host/CDN in prod.

Things Claude must not do:
- Do not bypass tenancy isolation or write cross-tenant queries without explicit filters.
- Do not embed plaintext secrets or credentials in code.
- Do not generate admin endpoints that are insecure or exposed publicly.
- Do not assume a single-tenant data model or hardcode tenant IDs.

Recommended Project Structure

backend/
  django_project/
    settings.py
    wsgi.py
  apps/
    core/
    tenants/
    users/
    billing/
  manage.py
  requirements.txt

frontend/
  src/
    app/
      core/
      tenants/
      shared/
  angular.json
  package.json

Core Engineering Principles

• Tenancy is the core contract: isolate data, scale per tenant, and enforce cross-tenant boundaries everywhere.
• API-first design: stable REST endpoints with clear contracts and versioning.
• Security by default: minimal surface area, secure defaults, and verifiable auth/authorization.
• Composable, testable code: unit and integration tests at backend and frontend layers.
• Observability: structured logs, metrics, and dashboards from day one.
• Infra as code: reproducible deployments with migrations and seed data baked in.

Code Construction Rules

• Follow Django REST Framework conventions; serializers with explicit validators and per-tenant filters.
• Use django-tenants for tenant schema management; ensure migrations apply per tenant.
• Frontend uses Angular Material components with strict type checking and lazy loading.
• JWT-based authentication with httpOnly cookies; avoid storing tokens in localStorage.
• Environment-based configuration; secrets loaded from environment variables, not code.
• Avoid raw SQL strings; use ORM with tenant-aware filters or parameterized queries.
• Do not mix tenant context between requests; always resolve tenant from request subdomain or header.

Security and Production Rules

• Enable TLS, use secure cookies; disable debug in prod.
• CSRF enabled for state-changing endpoints; use DRF’s CSRF protection when needed.
• CORS configured to allow only approved origins.
• Audit logging and access controls per tenant; protect admin endpoints from public exposure.
• Secret management: fetch from env vault or cloud secret manager; rotate credentials periodically.

Testing Checklist

• Unit tests for models, serializers, viewsets; mock external services.
• Integration tests that cover tenant creation, onboarding, and data isolation across tenants.
• End-to-end tests for authentication and core workflows on the Angular UI.
• CI pipeline runs migrations and linting; production-like test environments.

Common Mistakes to Avoid

• Ignoring tenant isolation and cross-tenant data leakage.
• Bootstrapping tenants without proper migrations or seed data.
• Storing secrets in code or using insecure defaults in Docker images.
• Hardcoding hostnames or tenant identifiers in code paths.

FAQ

What is a CLAUDE.md Template?

A copyable Claude Code starter that encodes best practices for a stack; paste into Claude Code to generate a ready-to-run skeleton.

Which stack does this template cover?

Angular Material frontend with a Django backend using a schema-per-tenant multi-tenant tenancy model.

What tenancy model is used?

Schema-per-tenant in PostgreSQL, enabled by django-tenants for strict isolation between tenants.

What authentication approach is used?

JWT-based authentication with HttpOnly cookies and DRF permissions to guard endpoints.

How do I test multi-tenancy?

Include unit tests for tenant context, integration tests for migrations per tenant, and end-to-end tests for onboarding flows.

How should I deploy?

Use Docker Compose for local development and Kubernetes for production; run migrations on tenant creation and startup.