24 — Master Admin

Tenant management, provisioning, system health, platform analytics

CEO Summary

Master Admin is the platform operator dashboard. Manage tenants, provisioning, system health. No access to tenant business data — only master-level metadata. Business value: SaaS operations, tenant lifecycle. Key metrics: Tenant count, system health, provisioning success. If this breaks: Cannot provision new tenants; operators lose visibility.

Architecture

flowchart TB subgraph frontend [Frontend] MA[Master Admin Portal] TP[Tenant Provisioning] TM[Tenant Management] DB[Database Ops] end subgraph api [API] MAR[masterAdmin.routes] TPR[tenant-provisioning.routes] ADR[admin.database.routes] end subgraph db [Databases] Master[(Master DB)] Tenant[Tenant DBs] end MA --> MAR TP --> TPR TM --> MAR DB --> ADR MAR --> Master TPR --> Master TPR --> Tenant ADR --> Tenant

Overview

Master Admin is for platform operators only. Requires master_admin role. No tenant business data access.

Base path: /api/master-admin
Auth: requireSessionAuth, requireRoles('master_admin')
Frontend: /master-admin/*

File Structure

backend/
├── routes/
│   ├── masterAdmin.routes.js
│   └── master-admin.tenant-provisioning.routes.js
├── middleware/
│   └── masterAdminTenantAccess.js
└── routes/api/master-admin/
    └── index.js
frontend/
├── src/pages/master-admin/
│   ├── MasterAdminPortal.jsx
│   ├── TenantProvisioning.jsx
│   ├── TenantManagement.jsx
│   ├── TenantManagementAdvanced.jsx
│   ├── TenantDetail.jsx
│   ├── PlatformCatalogAdmin.jsx
│   ├── Dashboard.jsx
│   ├── Analytics.jsx
│   ├── Billing.jsx
│   ├── BillingManagement.jsx
│   ├── FeatureManagement.jsx
│   └── DatabaseOperations.jsx
└── src/hooks/
    └── useMasterAdmin.js

API Endpoints

Method	Path	Purpose
GET	/api/master-admin/tenants	List all tenants (id, orgId, name, slug, plan, isActive, createdAt)
GET	/api/master-admin/system-health	DB connectivity, API status
GET	/api/master-admin/platform-analytics	Platform-level analytics
POST	/api/master-admin/tenants	Create tenant (provisioning)

Tenant Provisioning

tenantProvisioningRouter at /api/master-admin/tenants — create tenant, DBs. See 02 — Databases.

Data Access

Master Admin queries master DB (Tenants, Organizations) and tenant DBs only for health checks. Does NOT access tenant Invoices, Customers, etc. for business operations.

Frontend Routes

Path	Component	Purpose
/master-admin	MasterAdminPortal	Portal hub
/master-admin/tenants	TenantManagement	Tenant list
/master-admin/tenants/provision	TenantProvisioning	Create tenant
/master-admin/tenants/:id	TenantDetail	Tenant detail
/master-admin/platform-catalog	PlatformCatalogAdmin	Platform barcode / GTIN catalog
/master-admin/analytics	Analytics	Platform analytics
/master-admin/feature-management	FeatureManagement	Feature flags
/master-admin/database	DatabaseOperations	DB management

Related Routes

admin.payments, admin.orgs, admin.liability — may have master admin overlap. admin.database — DB management for master admin.

Key Paths

Path	Purpose
`backend/routes/masterAdmin.routes.js`	Master Admin API
`backend/config/roleConfig.js`	master_admin role
`frontend/src/pages/master-admin/`	Master Admin UI