Overview#
A platform administrator is preparing to onboard a new national police agency. She creates the tenant, sets storage and user quotas appropriate for a mid-size force, enables the specific feature flags agreed in the contract, and the agency is operational within minutes. Six months later, a billing dispute prompts a temporary suspension: one state change, fully logged, fully reversible. That controlled, auditable lifecycle is what the Tenant domain provides.
The domain handles organisational tenant management, giving platform administrators the tools to create, configure, and supervise tenant organisations. It covers status management, quota enforcement, usage monitoring, health checks, feature flag configuration, and backup and restore capabilities. Every management action is recorded in PostgreSQL for compliance and audit purposes. Multi-tenant organisation isolation is enforced at the database level so no tenant can access another's data.
Key Features#
-
Tenant Lifecycle Management: Manage tenants through a structured lifecycle from creation through activation, suspension, archival, and deletion, with controlled state transitions at each stage.
-
Quota Management: Define and enforce usage quotas for each tenant, including storage limits, user counts, and feature usage thresholds, to ensure fair resource distribution.
-
Usage Monitoring: Track tenant resource consumption in real time to provide visibility into how each organisation uses the platform and when they approach quota limits.
-
Health Monitoring: Continuously assess tenant operational health to proactively identify issues and ensure consistent service delivery across all organisations.
-
Feature Flag Configuration: Control which platform features are available to each tenant, supporting customised capability sets and phased feature rollouts.
-
Backup and Restore: Create tenant data backups and restore from backup when needed, providing data protection and disaster recovery capabilities.
-
Audit Logging: Record all tenant management actions for compliance tracking and administrative review, maintaining a complete history of configuration changes.
Tenant Lifecycle States#
| Status | Description |
|---|---|
| Created | Initial state after registration |
| Active | Fully operational tenant |
| Suspended | Temporarily disabled (billing, policy) |
| Archived | Data preserved, access removed |
Mermaid Diagram#
Use Cases#
-
Defence & Public Safety: Create and configure new tenant organisations for government agencies with appropriate quotas, feature flags, and initial settings, supporting rapid deployment to meet operational timelines.
-
Critical Infrastructure: Monitor usage across tenants and adjust quotas to optimise resource allocation and prevent service degradation during high-demand periods such as emergency events.
-
Managed Services: Enable or disable specific features per tenant to match contractual agreements, operational requirements, or phased rollout plans for different customer tiers.
-
Regulatory Compliance: Use audit logs and lifecycle controls to demonstrate proper tenant management practices for GDPR, NIS2, and other regulatory obligations.
Integration#
The Tenant domain provides foundational organisation management across the platform:
- User Management: Users are associated with their organisational tenant.
- Feature Management: Feature availability is controlled at the tenant level.
- Systems Integrator: Tenants are linked to their systems integrator partnerships.
- Audit and Compliance: Tenant management actions feed into compliance reporting.
Open Standards#
- GraphQL (June 2018 Specification): The entire tenant management API, queries for listing and resolving tenants, mutations for lifecycle transitions, quota updates, and security configuration, is exposed as a typed GraphQL schema implemented with Strawberry.
- OAuth 2.0 (RFC 6749) and JSON Web Tokens (RFC 7519): Service-to-service tenant operations are authorised via RS256-signed JWTs carrying scoped claims (e.g.
auth:tenant:write) and a boundtenant_id, ensuring that each token is constrained to the tenant it acts upon. - LDAP / LDAPS (RFC 4511): Per-tenant directory integration supports configurable LDAP and LDAPS server URLs and base distinguished names, enabling organisations to federate tenant authentication with an existing directory service.
- X.509 Public Key Infrastructure / PEM (RFC 7468): Per-tenant PKI configuration accepts PEM-encoded trusted CA certificates, allowing tenants to enforce certificate-based authentication against their own certificate authority.
- UUID Version 4 (RFC 4122): All tenant identifiers are randomly generated UUID v4 values, providing globally unique, collision-resistant keys for tenant records across distributed services.
- GDPR, NIS2, and eIDAS: Compliance frameworks are modelled as first-class configuration values; tenants may be tagged with one or more of GDPR, NIS2, or eIDAS, and configurable audit-log retention periods and data-residency zones are enforced accordingly.
- ISO 8601: All tenant timestamps (creation, last update) are serialised using ISO 8601 format via Python's
.isoformat(), ensuring interoperability with external systems and audit tooling.
Last Reviewed: 2026-02-05 Last Updated: 2026-04-14