SaaS Multi-Tenant Reference Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The SaaS Multi-Tenant Reference Implementation serves as a minimal yet powerful architectural pattern for building Software-as-a-Service applications within the TAMV ecosystem. It demonstrates key concepts such as tenant data isolation, unified authentication, and scalable serverless infrastructure.
This implementation provides a "power pattern" for developers to follow, ensuring that every request is scoped to a specific tenant through automated context injection. The architecture utilizes a serverless stack combining AWS Lambda, DynamoDB, and API Gateway to achieve cost-effective scalability and robust security boundaries.
Sources: saas-example/README.md:1-5, saas-example/ANALYSIS-COMPLETE.md:100-105
Architectural Overview
The system follows a modern serverless architecture designed for high availability and strict isolation. It is divided into three primary tiers:
- Frontend: A React application built with TypeScript and Tailwind CSS, utilizing custom hooks to manage tenant-specific state and authentication.
- Backend: Node.js Lambda functions orchestrated by API Gateway, featuring a dedicated Authorizer for security.
- Database: A single-table DynamoDB design that enforces tenant isolation via composite keys and global secondary indexes (GSIs).
Sources: saas-example/README.md:7-12, saas-example/PROJECT-STATUS.md:37-45
Data Flow and Tenant Isolation
Every incoming request undergoes a strict validation and context injection process to prevent cross-tenant data leakage.
The flow ensures that the application logic only ever interacts with data prefixed by the current user's tenantId.
Sources: saas-example/README.md:25-32, saas-example/ANALYSIS-COMPLETE.md:78-85
Multi-Tenant Identity & Access Management
Authentication is managed via JSON Web Tokens (JWT) that include claims for both user identity and tenant context. The Lambda Authorizer is the critical component that decodes these tokens and provides the tenantId, userId, and roles to downstream functions.
Key Authentication Endpoints
| Endpoint | Method | Description |
|---|---|---|
/auth/signup | POST | Creates a new tenant and a primary owner user simultaneously. |
/auth/login | POST | Validates credentials and returns a scoped JWT. |
/auth/refresh | POST | Renews the access token to maintain session longevity. |
Sources: saas-example/PROJECT-STATUS.md:9-12, saas-example/ANALYSIS-COMPLETE.md:28-33
Role-Based Access Control (RBAC)
The implementation supports multiple roles to govern permissions within a tenant:
- Owner: Full access, including billing and tenant settings.
- Admin: Administrative access to user management and tasks.
- User: Standard access to view and manage assigned data.
Sources: saas-example/ANALYSIS-COMPLETE.md:91-95, saas-example/PROJECT-STATUS.md:68-70
Database Design (Single-Table Pattern)
The reference implementation utilizes a Single-Table Design in DynamoDB. This pattern uses generic primary keys (pk and sk) to store different entity types in the same table, optimizing for performance and cost.
Schema Structure
| Entity | Partition Key (pk) | Sort Key (sk) | Attributes |
|---|---|---|---|
| Tenant | Tenant#<tenantId> | Metadata | Name, Plan, Status |
| User | User#<userId> | Profile | Email, PasswordHash, Roles |
| Task | <tenantId>#Task | Task#<taskId> | Title, Description, Status |
To support efficient lookups, two Global Secondary Indexes (GSIs) are implemented:
- GSI1: Uses
Email#<email>as the partition key to enable fast login lookups across the entire table. - GSI2: Enables listing all users belonging to a specific
tenantId.
Sources: saas-example/PROJECT-STATUS.md:118-125, saas-example/ANALYSIS-COMPLETE.md:43-52
Frontend Integration
The frontend uses custom React hooks to abstract the complexity of multi-tenancy from the UI components.
Custom Hooks
useAuth: Manages the local storage of tokens and the authentication state.useTenant: Provides the current tenant's configuration and features (e.g., plan-based feature flags).useApi: An authenticated HTTP client that automatically attaches the JWT and handles tenant-specific error responses.
Sources: saas-example/PROJECT-STATUS.md:50-55, saas-example/ANALYSIS-COMPLETE.md:54-72
Implementation Details
The backend functions utilize bcryptjs for password hashing and jsonwebtoken for token management. Infrastructure is managed as code using the Serverless Framework or AWS CDK.
Configuration Variables
| Variable | Description |
|---|---|
JWT_SECRET | Secret key used for signing and verifying tokens. |
TABLE_NAME | The name of the central DynamoDB table. |
NODE_ENV | Environment flag (development/production). |
Sources: saas-example/PROJECT-STATUS.md:90-95, TAMV-MASTER-DOCUMENTATION.md:300-310
Security Hardening
The reference implementation includes:
- Double-Submit Cookie Pattern: For CSRF protection.
- XSS Prevention: Output sanitization using DOMPurify.
- Input Validation: Strict schema enforcement using Zod.
- Rate Limiting: Tiered limits at the API Gateway level to prevent resource exhaustion per tenant.
Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:195-210, saas-example/ANALYSIS-COMPLETE.md:87-95
Conclusion
The SaaS Multi-Tenant Reference Implementation provides a blueprint for scalable, secure, and isolated digital environments. By leveraging serverless technologies and strict data scoping at the architectural level, it ensures that multiple organizations can coexist within the TAMV ecosystem while maintaining total data sovereignty.