Multi-Tenant Platform

Overview

The multi-tenant platform transforms Knowledge Tree into a SaaS-ready service. Each tenant operates in an isolated environment with its own discovery pipelines, graph data, users, and configuration. The platform handles tenant lifecycle, usage-based billing, custom domain mapping, and data retention policies.

Tenant isolation

Every tenant is isolated at the data plane and control plane levels. Tenant data is stored in separate schema namespaces within PostgreSQL and Apache AGE, ensuring that queries, graph traversals, and vector searches never cross tenant boundaries.

Account management

Each tenant has a full account profile including contact details, subscription tier, feature flags, and service-level agreement (SLA) parameters. Account management is exposed through both the admin UI and a REST API.

• Account creation -- manual (admin) or self-service via onboarding flow
• Profile updates -- company name, billing address, technical contacts
• Subscription tier -- Starter, Pro, Enterprise with feature gating
• SLA configuration -- uptime guarantees, support response times
• Account suspension -- graceful and hard suspension modes
• Tenant deletion -- full erasure with configurable grace period

Self-service onboarding

New tenants can sign up, provision their environment, and complete a guided first-run without any administrator intervention. The onboarding flow includes:

1. Sign up -- email, password, company name via the registration form
2. Email verification -- optional, configurable per deployment
3. Environment provisioning -- database schemas, encryption keys, default roles
4. Provider connection -- guided wizard to connect AWS, Azure, or GCP
5. First discovery -- automated scan of the connected provider
6. Dashboard preview -- review discovered resources and relationships
7. Billing setup -- payment method and plan selection

Billing and metering

Usage is metered at multiple dimensions and reported to the billing system. Metering dimensions include:

Stripe integration

Billing is handled natively through Stripe. The integration supports:

• Subscription plans -- monthly and annual billing cycles with tiered pricing
• Usage-based billing -- metered dimensions reported via Stripe usage records
• Invoicing -- automatic invoice generation and email delivery
• Payment methods -- credit cards, ACH, wire transfer for Enterprise plans
• Coupons and promotions -- discount codes, trial extensions, referral credits
• Webhook handling -- subscription updates, payment failures, churn events
• Customer portal -- Stripe-hosted portal for plan changes and billing history

# Example: metering usage via the billing API
POST /api/v1/billing/meter
Content-Type: application/json

{
  "tenant_id": "tnt_abc123",
  "dimension": "discovered_resources",
  "quantity": 147,
  "timestamp": "2025-06-01T00:00:00Z"
}

Custom domains

Each tenant can be assigned a custom domain (e.g., infra.acme.com). The platform automatically provisions TLS certificates via Let's Encrypt and routes requests to the correct tenant environment.

• Domain mapping -- CNAME or A record pointed to the Knowledge Tree ingress
• Automatic TLS -- ACME certificate provisioning and renewal
• Path-based routing -- optional sub-path isolation for development tenants
• Custom branding -- per-domain logo, favicon, and color scheme

# Configure a custom domain
PATCH /api/v1/admin/tenants/tnt_abc123/domain
Content-Type: application/json

{
  "domain": "infra.acme.com",
  "auto_tls": true
}

Data retention

Data retention policies are configurable per tenant and per data category. The platform enforces automated cleanup based on the defined schedule.