🚀 django_resaas

The framework you've been missing for building multi-tenant SaaS apps in Django — without reinventing the wheel on every project.

If you've ever built a SaaS API in Django, you know the drill: multi-tenancy, per-group and per-branch permissions, soft delete, file uploads, PDF generation, i18n, plan-based billing… all of it again, project after project.

django_resaas solves that part once and for all. It's a framework built on top of Django + DRF that gives any application a production-ready foundation: multi-tenancy, RBAC, smart CRUD, dynamic search, per-client feature modules, and billing — so your team can focus on what actually matters: the business.

pip install django_resaas

Why it exists
Features
Installation & setup
Architecture
Full example in 3 files
Multi-tenancy & RBAC
Soft delete
Automatic search & filters
Per-client modules + billing
Middlewares
Internationalization (i18n)
CLI / management commands
Tech stack
Documentation
Roadmap
Contributing
License

🎯 Why it exists

"Building SaaS shouldn't be repetitive."

Every multi-tenant SaaS app ends up needing the same set of building blocks. django_resaas ships them ready-made, tested, and consistent with each other:

Without django_resaas	With django_resaas
Multi-tenancy hand-rolled on every project	`BaseModel` already ships `entity` + `branch`
Permissions checked manually in every view	Automatic RBAC via `Entity` + `Branch` + `Group`
CRUD written from scratch for every resource	`BaseAPIView` gives full CRUD in ~5 lines
Destructive delete with no way back	Native soft delete + restore + hard delete
Custom search per endpoint	Automatic dynamic search (`?search=`)
"All or nothing" modules	Per-client module activation (`App` + `EntityApp`)
Translations scattered across the code	Central i18n system (DB + `lang/` files)

✨ Features

🔐 RBAC — permissions by User + Group + context (Entity/Branch)
🏢 Native multi-tenancy — isolation by Entity and Branch
⚡ Automatic CRUD — BaseAPIView with pagination, ordering, filtering and permissions built in
🔎 Dynamic search — automatic search across text fields and relations
♻️ Soft delete — delete() / restore() / hard_delete() + dedicated managers
🧩 Per-client modules — toggle features on/off per entity without a deploy (App + EntityApp)
📎 Files & PDF — secure uploads, automatic metadata, PDF generation (WeasyPrint)
🔑 JWT auth + 2FA — simplejwt, OTP (pyotp) and QR codes built in
🌍 Built-in i18n — file-based translations (pt-pt, en-us, es-es, fr-fr) and database-backed
🌐 Dedicated middlewares — tenant context, frontend protection and file access control
💵 Native money support (django-money)

⚙️ Installation & setup

pip install django_resaas
# or, for local development:
pip install -e .

# settings.py
INSTALLED_APPS = [
    ...
    "django_resaas",
    "hr",  # example module included
]

MIDDLEWARE = [
    ...
    "django_resaas.core.middleware.tenant.TenantContextMiddleware",
    "django_resaas.core.middleware.front_end.FrontEndMiddleware",
]

make migrate
make superuser
make run          # http://0.0.0.0:7002

🧠 Architecture

User
 ↓
Person
 ↓
Employee (HR)
 ↓
Entity (tenant)
 ↓
Branch
 ↓
Groups + Permissions

Key concepts:

Concept	Role
`Entity`	The tenant — typically the client/company
`Branch`	A unit/location within an `Entity`
`Person`	Human data (name, email, contacts)
`User`	Authentication
`BranchUserGroup`	Links `User` + `Branch` + `Group`, allowing multiple groups per branch

🧪 Full example in 3 files

Model

from django.db import models
from django_resaas.core.base.models import BaseModel

class Employee(BaseModel):
    person = models.ForeignKey("django_resaas.Person", on_delete=models.CASCADE)
    role = models.CharField(max_length=100)

BaseModel already ships entity, branch, created_at/updated_at, created_by/updated_by and soft delete.

Serializer

from django_resaas.core.base.serializers import BaseSerializer

class EmployeeSerializer(BaseSerializer):
    class Meta:
        model = Employee
        fields = "__all__"

View

from django_resaas.core.base.views import BaseAPIView, registerView

@registerView(module="hr")
class EmployeeView(BaseAPIView):
    queryset = Employee.objects.all()
    serializer_class = EmployeeSerializer

That's enough to automatically get: full CRUD, multi-tenant isolation, permissions, search, soft delete, restore, and protection based on the active module.

🔐 Multi-tenancy & RBAC

Tenant context is never trusted from raw client-supplied values. It travels as a single signed, short-lived token, issued by the API after checking the user actually has access to the Entity/Branch/Group requested.

1. Issue a context, once the user is authenticated:

POST /api/resaas/context/
Authorization: Bearer <access_token>

{
  "entity_id": "...",
  "branch_id": "...",   // optional
  "group_id": "..."     // optional
}

ResaasContextService validates access (via EntityUser / BranchUser / BranchUserGroup, with a superuser/entity-admin bypass) and signs the result with django.core.signing — versioned and bound to a TTL (1h by default, RESAAS_CONTEXT_TTL setting):

{ "token": "<signed-context-token>", "context": { "entity_id": "...", "branch_id": "...", "group_id": "..." } }

2. Send it back on every request, alongside auth and language — three headers, one job each:

Header	Purpose
`Authorization`	`Bearer <JWT>` — who you are
`X-RESAAS-Context`	signed tenant context — where you're operating (`entity`/`branch`/`group`)
`L`	active language id

TenantContextMiddleware decodes the token and verifies its signature and expiry on every request, exposing:

request.entity_type_id
request.entity_id
request.branch_id
request.group_id

BaseAPIView then re-validates that the context still belongs to the authenticated user (ResaasContextService.validate_for_user) before touching the queryset — a forged, expired, or replayed token from another user/tenant is rejected even if it was valid at issue time.

If a resource's module isn't active for the Entity, access is blocked automatically — no extra code in the view.

⚠️ Breaking change from earlier versions: the old scheme (raw ET / E / S / G headers sent directly by the client) has been replaced by the signed X-RESAAS-Context token above. If you're upgrading, swap those headers for a call to POST /resaas/context/ and forward the returned token instead.

🔁 Soft delete

obj.delete()        # soft delete
obj.restore()       # restore
obj.hard_delete()   # permanently delete

Model.objects           # active only
Model.deleted_objects    # deleted only
Model.all_objects        # everything

🔎 Automatic search & filters

GET /api/employees/?search=john

BaseAPIView automatically searches text fields and relations (ForeignKey), with no per-endpoint configuration required.

🧩 Per-client modules

Each Entity only sees the modules it has activated:

Entity	Module	Status
Company A	HR	✅
Company A	CRM	❌

Activation is a direct App ↔ Entity link via EntityApp (toggled with its state field):

EntityApp.objects.get_or_create(app=app, entity=entity, state=1)

There is no plan-based billing layer yet (no Plan/EntityPlan model, no automatic plan-to-module sync) - that's tracked under Roadmap. Module activation today is a direct per-entity toggle, as used by python manage.py create_root (see docs/development/management-commands.md).

🌐 Middlewares

Middleware	Responsibility
`TenantContextMiddleware`	Decodes the signed `X-RESAAS-Context` token and resolves `entity`, `branch`, `group` (`L` header for language)
`FrontEndMiddleware`	Protects access via `FEK`/`FEP` frontend credentials and route/HTTP-method permissions
`FileAccessMiddleware`	Controls access to protected files and media

🌍 Internationalization (i18n)

Translations are resolved in cascade — database first, then each app's lang/ files — with automatic caching:

from django_resaas.core.utils.translate import Translate

Translate.tdc(request, "Register")

Languages included out of the box: pt-pt, en-us, es-es, fr-fr.

🛠 CLI / management commands

python manage.py setup             # initial SaaS bootstrap
python manage.py create_entity     # creates a new Entity (tenant)
python manage.py create_root       # creates the root user
python manage.py sync_language     # loads the default languages
python manage.py sync_actions      # syncs views registered in VIEW_REGISTRY
python manage.py check              # Django's system check framework
python manage.py check_metano       # validates compliance with the MetanoStack standard

🧰 Tech stack

Layer	Technology
Backend	Django 5.2 + Django REST Framework
Auth	`djangorestframework-simplejwt`, 2FA (`pyotp`, `qrcode`)
Database	PostgreSQL (`psycopg`)
Documents	WeasyPrint (PDF), `python-barcode`
Filtering	`django-filter`
Money	`django-money`
Deployment	Gunicorn

📚 Documentation

Full technical documentation lives in docs/:

FAQ / Getting started — installation and the practical "how do I...?" questions
Architecture · Multi-tenancy · Request lifecycle · Middleware · View registry
Schema 1.0 contract · Public API reference
BaseAPIView · Search · Filters & pagination
Permissions
Soft delete · Files & PDF
Creating a new resource · Management commands
The hr app
Git Flow & releases
Troubleshooting

🚀 Roadmap

Stripe integration
Billing dashboard
Resource auto-router
Action auditing
Multi-tenant logs
Permission cache (Redis)

🤝 Contributing

Pull requests are welcome. For larger changes, please open an issue first to discuss direction.

git clone https://github.com/metanochava/django_resaas.git
cd django_resaas
pip install -e .
make check

📄 License

Distributed under the MIT license.

Made by Metano Chavana

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_resaas-0.0.495.tar.gz (328.4 kB view details)

Uploaded Sep 6, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

django_resaas-0.0.495-py3-none-any.whl (537.0 kB view details)

Uploaded Sep 6, 2026 Python 3

File details

Details for the file django_resaas-0.0.495.tar.gz.

File metadata

Download URL: django_resaas-0.0.495.tar.gz
Upload date: Sep 6, 2026
Size: 328.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for django_resaas-0.0.495.tar.gz
Algorithm	Hash digest
SHA256	`8f53258e331d8c84eea5c04ca7f4b34c79a8112489537130af722b32ac563547`
MD5	`54d919f044993a480c15f6bb21c9e579`
BLAKE2b-256	`70d90472afb6757b7a10a1ecf8d07d97199f5660a8fae392aa3e935ddc01dd0f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for django_resaas-0.0.495.tar.gz:

Publisher: publish_pypi.yml on metanochava/django_resaas

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: django_resaas-0.0.495.tar.gz
- Subject digest: 8f53258e331d8c84eea5c04ca7f4b34c79a8112489537130af722b32ac563547
- Sigstore transparency entry: 2739661266
- Sigstore integration time: Sep 6, 2026
Source repository:
- Permalink: metanochava/django_resaas@4a5371298cd18d89cb3d37ab6454c662154f32d7
- Branch / Tag: refs/tags/0.0.495
- Owner: https://github.com/metanochava
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish_pypi.yml@4a5371298cd18d89cb3d37ab6454c662154f32d7
- Trigger Event: push