Administration — Tenant Service
Language: Java 21
Framework: Spring Boot 3.5.5
Source: ~/IdeaProjects/NEXIVO/tenant-service
Purpose
The Tenant Service is the administration and tenant lifecycle management service for the Nexivo platform. It manages tenant provisioning, subscription packages, licence assignment, and billing integration. Tenants and subscription packages are stored as Kubernetes Custom Resources (CRDs).
Responsibilities
| Responsibility |
Implementation |
| Tenant CRUD |
Kubernetes CRD operations via Fabric8 client |
| Subscription packages |
Package CRD management |
| Billing overview |
Feign client → Billing Service |
| Licence management |
Per-tenant licence assignment |
| Multi-tenant provisioning |
Kubernetes namespace + realm per tenant |
| Migration |
Bootstrap legacy ConfigMap-based tenants to CRDs |
Tenant Data Model (Kubernetes CRD)
API Group: corecognitics.app/v1
TenantSpec
| Field |
Description |
name |
Unique tenant identifier |
description |
Human-readable description |
domain |
Tenant domain |
adminEmail |
Primary admin email |
enabled |
Active flag |
subscriptionPackage |
Reference to SubscriptionPackage CRD |
seatCount |
Licensed agent seats |
licences |
Array of NexivoLicence entries |
realm |
Keycloak realm name |
audio |
Audio processing configuration |
storage |
Storage allocation |
TenantStatus
| Phase |
Description |
Active |
Tenant fully provisioned |
Provisioning |
Creation in progress |
Deleting |
Deletion in progress |
REST API
Tenants
| Method |
Path |
Purpose |
GET |
/api/v1/tenants |
List tenants (paginated, filterable by enabled / phase / package) |
POST |
/api/v1/tenants |
Create tenant |
GET |
/api/v1/tenants/{name} |
Get tenant details |
PUT |
/api/v1/tenants/{name} |
Update tenant spec |
DELETE |
/api/v1/tenants/{name} |
Delete tenant (cascading cleanup) |
GET |
/api/v1/tenants/{name}/licences |
Get tenant licence assignments |
Subscription Packages
| Method |
Path |
Purpose |
GET |
/api/v1/packages |
List packages (paginated) |
POST |
/api/v1/packages |
Create package |
GET |
/api/v1/packages/{name} |
Get package |
PUT |
/api/v1/packages/{name} |
Update package |
DELETE |
/api/v1/packages/{name} |
Delete package |
GET |
/api/v1/packages/{name}/tenants |
List tenants on this package |
Billing
The Tenant Service proxies billing data from the Billing Service via Feign client.
| Method |
Path |
Purpose |
GET |
/api/v1/billing/{tenantName} |
Billing overview (seat costs + AI usage) |
GET |
/api/v1/billing/summary |
All-tenant billing summary |
GET |
/api/v1/billing/{tenantName}/usage |
Usage summary (with time range filters) |
GET |
/api/v1/billing/{tenantName}/usage/trends |
Usage trends (HOURLY / DAILY / MONTHLY) |
GET |
/api/v1/billing/{tenantName}/costs |
STT / LLM / TTS cost breakdown |
GET |
/api/v1/billing/{tenantName}/costs/by-provider |
Costs grouped by provider |
GET |
/api/v1/billing/{tenantName}/costs/forecast |
30-day cost forecast |
Migration
| Method |
Path |
Purpose |
POST |
/api/v1/migration/bootstrap |
Migrate ConfigMap-based tenants → CRDs |
Licence Keys
Feature access is controlled by licences assigned per tenant via the licences array in TenantSpec:
| Licence Key |
Feature |
CALL_TRACKING |
Voice calls |
WHATSAPP |
WhatsApp channel |
EMAIL |
Email channel |
WIDGET |
Web chat widget |
AI_AGENT |
AI agent management |
Licences are surfaced in the Keycloak token claims and enforced in the Agent Desktop via LicenseGuard.
External Dependencies
| Dependency |
Purpose |
| Kubernetes API Server |
Tenant and package CRD storage and watch |
| Fabric8 Kubernetes Client |
Java client for CRD operations |
| PostgreSQL |
Tenant metadata and audit logs |
| Billing Service |
Usage and cost data (Feign, http://billing-service) |
| Keycloak |
Realm provisioning per tenant |
| Spring Cloud Kubernetes |
Service discovery |