| name | multi-tenancy |
| description | Design patterns for multi-tenant architecture including org scoping, row-level security, and tenant data isolation. Use when designing or auditing tenant isolation boundaries. |
| user-invokable | false |
Multi-Tenancy
Reference
- ID: S-ENG-04
- Category: Engineering
- Inputs: data model, tenant boundaries, isolation requirements, compliance constraints
- Outputs: multi-tenancy design document โ artifacts/engineering/
- Used by: Engineering Agent
- Tool scripts: ./tools/artifact/validate.sh
Purpose
Defines the architecture and conventions for multi-tenant data isolation, ensuring that tenant data is properly scoped, row-level security is enforced, and cross-tenant data leakage is prevented at every layer of the stack.
Procedure
Step 0: Multi-Tenancy Check
Read architecture.multi_tenant from company.config.yaml.
If false or absent: output "Multi-tenancy not configured for this project. Set architecture.multi_tenant: true in company.config.yaml to enable multi-tenant design patterns." and skip the remaining procedure.
If true: proceed with full multi-tenancy design.
Steps
- Define the tenant model: what constitutes a tenant (org, workspace, account).
- Choose the isolation strategy: shared database with RLS, schema-per-tenant, or database-per-tenant.
- Design the org-scoping layer: how every query is automatically scoped to the current tenant.
- Implement row-level security (RLS) policies at the database level.
- Define middleware/context propagation to carry tenant ID through the request lifecycle.
- Audit all data access paths to ensure no unscoped queries exist.
- Design tenant-aware caching: cache keys must include tenant ID.
- Define cross-tenant operation policies (admin access, data migration, support tooling).
- Document testing strategy: how to verify isolation in automated tests.
- Save the design document to
artifacts/engineering/.
- Validate the artifact using
./tools/artifact/validate.sh.
Quality Checklist
