Business Requirements

Problem Statement

In a multi-tenant SaaS platform, platform administrators need a secure way to manage tenants, monitor system health, and perform cross-tenant operations without exposing these capabilities to regular users. The SuperAdmin module provides an isolated interface for these critical platform operations.

Use Cases

1. Tenant Management

Actor: Platform Administrator (Super Admin)

Flow:

  1. View list of all tenants with key metrics
  2. Create new tenant with custom configuration
  3. View detailed tenant information
  4. Update tenant settings (name, plan, max users)
  5. Soft-delete tenant (data preserved, access revoked)
  6. Export tenant data

Acceptance Criteria:

  • All tenants visible across organization boundaries
  • Tenant creation with proper isolation setup
  • Audit trail for all tenant operations
  • Soft deletes preserve data for recovery

2. User Management Across Tenants

Actor: Platform Administrator

Flow:

  1. View users across all tenants with filtering
  2. Search users by email or name
  3. View user details and tenant affiliation
  4. Reset user password
  5. Manage super admin accounts

Acceptance Criteria:

  • Cross-tenant user visibility
  • Search/filter functionality
  • Password reset capability
  • User type modification

3. Platform Analytics

Actor: Platform Administrator, Finance Team

Flow:

  1. View total tenant count (active, trial, deleted)
  2. View total user statistics (total, active today/week/month)
  3. View system resource usage (storage, API calls)
  4. View activity trends (signups, usage over time)
  5. Filter metrics by date range

Acceptance Criteria:

  • Real-time metric availability
  • Time-series data for trends
  • Exportable analytics
  • Performance monitoring data

4. System Monitoring

Actor: Operations Team, Support Team

Flow:

  1. Access dashboard with health status
  2. View server metrics and resource usage
  3. Monitor error rates and latency
  4. Check database connectivity
  5. Review audit logs for suspicious activity

Acceptance Criteria:

  • Real-time health checks
  • Performance metrics visibility
  • Error tracking and alerts
  • Comprehensive logging

5. Session Management

Actor: Support Team

Flow:

  1. Invalidate user sessions (force logout)
  2. View active sessions across system
  3. Terminate suspicious sessions

Acceptance Criteria:

  • Session revocation capability
  • Active session visibility
  • Immediate effect on terminated sessions

Business Rules

User Type Rules

  1. Regular Users
    • Scoped to single tenant
    • Cannot access super admin features
    • Limited to their organization
  2. Super Admin Users
    • No tenant affiliation
    • Access to all platform data
    • Can create/modify/delete tenants
    • Can manage other super admin accounts

Tenant Rules

  1. Isolation
    • Users belong to single tenant
    • Data never visible across tenants
    • Each tenant has independent configuration
  2. Lifecycle
    • Tenants can be in states: active, trial, suspended, deleted
    • Soft deletes preserve historical data
    • Billing based on active tenants

Security Rules

  1. Access Control
    • Only super admin users can access SuperAdmin module
    • Super admin accounts created via database only
    • Session-based authentication with expiration
  2. Audit Requirements
    • All tenant operations logged with user, timestamp, action
    • All user management operations audited
    • Suspicious activity flagged for review
  3. Data Protection
    • All queries use parameterized statements
    • No raw SQL concatenation
    • Database credentials stored in secrets management
    • TLS for all database connections

Integration with Main Application

The SuperAdmin module shares:

  • Database: Same PostgreSQL instance with main application
  • User Table: Super admin users stored in core.users with type = ‘superadmin’
  • Sessions: Same session management as main application
  • Configuration: Same environment variables

Key Metrics Tracked

Tenant Metrics

  • Total active tenants
  • Total trial tenants
  • Total deleted tenants
  • Tenant signup trends

User Metrics

  • Total users across platform
  • Active users (DAU - Daily Active Users)
  • Weekly active users (WAU)
  • Monthly active users (MAU)
  • New signups trend

System Metrics

  • Total database size
  • Storage usage across tenants
  • API calls per day
  • Error rates
  • Response times (p50, p95, p99)

Success Criteria

  1. Usability
    • Dashboard loads in < 1 second
    • Filtering/searching works in < 500ms
    • All operations respond within 2 seconds
  2. Reliability
    • 99.9% uptime (separate from main app)
    • Audit logs never lost
    • Data consistency maintained
  3. Security
    • Zero unauthorized super admin accounts
    • All operations logged and audited
    • No data leakage between tenants
    • Regular security audits passing
  4. Scalability
    • Supports millions of users across thousands of tenants
    • Dashboard metrics available in real-time
    • Efficient cross-tenant queries

Constraints

  1. Deployment
    • Must run as separate service
    • Cannot mix with main application code
    • Requires dedicated configuration
  2. Data Access
    • Cannot modify regular user data directly
    • Cannot delete data (only soft delete for tenants)
    • Cannot access individual tenant business logic
  3. Performance
    • Analytics queries must not impact main application
    • Dashboard should use caching for metrics
    • Separate database connection pool recommended

Back to top

IOTA SDK - Multi-tenant Business Management Platform