Multi-Tenancy

Neostra is built as a multi-tenant platform where each tenant operates in an isolated environment with its own users, data, configurations, and subscription plans. A single user credential can belong to multiple tenants, and access within each tenant is controlled through a hierarchical RBAC model scoped to brands, processes, and sub-processes.

Architecture Overview

Tenant Model

Each tenant represents an isolated organization on the platform. The tenant document stores core identity and configuration fields.

Tenant Fields

Tenant Settings

Each tenant has a TenantSetting document that controls localization, feature availability, notifications, and DSAR (Data Subject Access Request) configuration.

{
  "supportedLocales": ["en", "de", "fr", "es", "pt"],
  "globalLanguages": ["en", "de"]
}

{
  "featureGroups": [
    {
      "name": "consent-management",
      "features": [
        { "key": "cookie-consent", "enabled": true },
        { "key": "preference-center", "enabled": true },
        { "key": "consent-analytics", "enabled": false }
      ]
    },
    {
      "name": "data-discovery",
      "features": [
        { "key": "auto-scan", "enabled": true },
        { "key": "classification", "enabled": true }
      ]
    }
  ]
}

{
  "notificationPreferences": {
    "emailOnIncident": true,
    "emailOnDSAR": true,
    "emailOnAssessment": false,
    "digestFrequency": "weekly"
  }
}

{
  "dsarSettings": {
    "autoAcknowledge": true,
    "defaultDeadlineDays": 30,
    "requireIdentityVerification": true,
    "allowedRequestTypes": [
      "access",
      "deletion",
      "rectification",
      "portability"
    ]
  }
}

Tenant Isolation

All database queries are automatically scoped to the authenticated user's tenant. The tenantId is extracted from the JWT and applied as a filter condition on every query. There is no cross-tenant data access at the application layer.

Role-Based Access Control (RBAC)

Brand Access Model

Within a tenant, user access is further scoped by a hierarchical model of brands, processes, and sub-processes. Each user has a BrandAccess list that defines exactly which parts of the organization they can interact with.

BrandAccess Structure

{
  "brandAccess": [
    {
      "brandId": "brand-marketing-001",
      "brandName": "Marketing",
      "processes": ["email-processing", "social-media"],
      "subProcesses": ["newsletter", "ad-campaigns"]
    },
    {
      "brandId": "brand-sales-002",
      "brandName": "Sales",
      "processes": ["crm-processing"],
      "subProcesses": ["lead-tracking", "pipeline"]
    }
  ]
}

RBACQueryBuilder

The RBACQueryBuilder automatically applies brand, process, and sub-process filters to database queries based on the authenticated user's access list.

// Internally, RBACQueryBuilder constructs filtered queries:
Query query = RBACQueryBuilder.build(userDetails);
// Equivalent to:
// { tenantId: "tenant-abc", brandId: { $in: ["brand-marketing-001", "brand-sales-002"] } }

{
  "tenantId": "tenant-abc-123",
  "brandId": {
    "$in": ["brand-marketing-001", "brand-sales-002"]
  },
  "process": {
    "$in": ["email-processing", "social-media", "crm-processing"]
  }
}

Multi-Tenant User Support

A single UserCredential (email + password) can be associated with multiple tenants. During sign-in, the user receives a list of all tenants they belong to and selects one to receive a tenant-scoped JWT.

Subscription Plans

Subscriptions control feature limits and quotas per tenant. The system uses a two-tier plan model.

Plan Tiers

Neostra offers five subscription tiers, each enabling different modules and feature limits.

Plan Fields

Tenant Provisioning

New tenants are provisioned through the astra-core service, which handles the administrative control plane.

curl -X POST https://api.neostra.io/v1/admin/tenants \
  -H "Authorization: Bearer <admin_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Organization",
    "domains": ["neworg.com"],
    "senderName": "New Org Privacy",
    "senderEmail": "privacy@neworg.com",
    "subscriptionPlanId": "plan-enterprise-001"
  }'

curl -X POST https://api.neostra.io/v1/admin/tenants/tenant-new-001/provision \
  -H "Authorization: Bearer <admin_jwt>"

Feature Flags Reference