vitepress-template

Appearance

Multi-Tenant Architecture ​

**Referenced Files in This Document** - [[architecture-bi-tenant.md]](file/bi-tenant/docs/architecture-bi-tenant.md) - [[prd-bi-tenant.md]](file/bi-tenant/docs/prd-bi-tenant.md) - [[design.md]](file/bi-tenant/docs/database/design.md) - [[schema.sql]](file/bi-tenant/docs/database/schema.sql) - [[init.sql]](file/bi-tenant/docs/database/init.sql) - [[tenant.proto]](file/bi-tenant/api/tenant-m/v1/tenant.proto) - [[tenant.go (biz)]](file/bi-tenant/internal/biz/tenant.go) - [[tenant.go (data)]](file/bi-tenant/internal/data/tenant.go)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction ​

This document explains the bi-tenant multi-tenant architecture, focusing on tenant isolation, data partitioning, and tenant-specific resource management. It covers the tenant lifecycle from registration to deactivation, including creation workflows, configuration management, and tenant-specific database schemas. Architectural patterns include logical isolation via tenant identifiers, schema-based separation, and dynamic table management triggered by tenant actions. The document also outlines tenant metadata management, subscription tiers, resource quotas, onboarding processes, administrative operations, performance considerations, scaling strategies, and monitoring approaches.

Project Structure ​

The bi-tenant module provides a tenant management service with:

  • API definitions (gRPC/HTTP) for tenant operations
  • Business logic for tenant lifecycle and administrative tasks
  • Data access layer implementing repositories and persistence
  • Database design and initialization scripts for StarRocks
  • Documentation covering architecture, PRD, and database schema

Diagram sources

Section sources

Core Components ​

  • Tenant Service API: Defines tenant CRUD, status updates, package assignment, admin password reset, batch deletion, dropdown options, and statistics retrieval.
  • Business Use Cases: Orchestrates tenant creation (including default organization and admin user), updates, deletions, status/package changes, password resets, and statistics aggregation.
  • Data Repositories: Implements persistence operations with tenant isolation enforced via tenant_id filters, package resolution via subscription, and statistical queries.
  • Database Schema: StarRocks primary key tables with bitmap indexes and dynamic partitions for audit logs; normalized schema supporting roles, menus, subscriptions, organizations, and users.

Key tenant lifecycle operations:

  • Registration: Create tenant, optionally attach a subscription, create default organization, and create admin user.
  • Configuration: Update tenant info, set status, assign/update package, reset admin password.
  • Deactivation: Soft-delete tenant records; statistics reflect active/expired/disabled tenants.

Section sources

Architecture Overview ​

The bi-tenant service enforces tenant isolation through:

  • Context injection: All upper services must validate tenant status against bi-tenant.
  • Dynamic table management: On tenant shop addition, triggers DBA agent or StarRocks MCP to create dynamic tables (e.g., base_order_goods_{tenant}_{shop}).
  • Logical isolation: Data layer filters all queries by tenant_id.

Diagram sources

Section sources

Detailed Component Analysis ​

Tenant Lifecycle Orchestration ​

The tenant creation workflow integrates tenant record creation, subscription attachment, default organization creation, and admin user provisioning. Password hashing and random password generation are handled securely. Package assignment is optional during creation and mandatory for enabling features.

Diagram sources

Section sources

Tenant Metadata, Subscription Tiers, and Resource Quotas ​

  • Tenant metadata includes identification, contact info, status, and optional package linkage.
  • Subscription tiers are defined in tenant_package with associated menus via tenant_package_menu.
  • Resource quotas are not explicitly modeled in the schema; however, feature access is controlled by package menus and current subscription status.

Diagram sources

Section sources

Tenant-Specific Administrative Operations ​

Administrative capabilities include:

  • Listing tenants with filters (name, phone, status, package)
  • Retrieving tenant details and options
  • Updating tenant info and status
  • Assigning/updating package (subscription)
  • Resetting admin password
  • Deleting tenants (soft-delete)
  • Batch deletion
  • Retrieving tenant statistics

Diagram sources

Section sources

Tenant Isolation Mechanisms and Data Partitioning Strategies ​

  • Logical isolation: All queries filter by tenant_id; the data layer enforces this pattern.
  • Dynamic table management: On tenant shop addition, dynamic tables are created (e.g., base_order_goods_{tenant}_{shop}) to support per-tenant/per-shop datasets.
  • StarRocks modeling: Primary key tables with bitmap indexes; duplicate-key tables with dynamic partitions for logs.

Diagram sources

Section sources

Tenant Onboarding Process Examples ​

  • Platform onboarding: Create tenant, optionally assign a package, create default organization, provision admin user, and initialize permissions via package menus.
  • Tenant-side onboarding: Configure departments, roles, and employees; assign roles to users; manage data delegation and store associations.

Diagram sources

Section sources

Dependency Analysis ​

The bi-tenant module follows clean architecture with clear boundaries:

  • API depends on business use cases
  • Business use cases depend on repositories
  • Repositories depend on the data layer and StarRocks schema
  • Documentation informs API design and schema decisions

Diagram sources

Section sources

Performance Considerations ​

  • Indexing: Bitmap indexes on frequently filtered columns (status, type, tenant_id) improve query performance.
  • Distribution: Primary key tables distributed by tenant_id reduce skew and improve join performance.
  • Partitions: Dynamic monthly partitions on audit logs minimize scan sizes and improve retention management.
  • Transactions: StarRocks transaction limitations require careful sequencing of operations (e.g., mixed INSERT/UPDATE handled outside strict transactions).

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

Common operational checks:

  • Tenant creation failures: Verify tenant code uniqueness and package existence before creation.
  • Subscription updates: Ensure old subscription is invalidated before creating a new one.
  • Password reset: Confirm admin user exists and update hashed password atomically.
  • Statistics accuracy: Validate subscription status and end_time comparisons for active/expired tenant counts.

Section sources

Conclusion ​

The bi-tenant module implements a robust multi-tenant architecture centered on logical isolation via tenant_id, normalized StarRocks schemas, and dynamic table management for per-tenant/per-shop datasets. The TenantService API, combined with business use cases and repositories, supports end-to-end tenant lifecycle management, subscription tiering, and administrative operations. Documentation and schema design emphasize maintainability, scalability, and operability across platform and tenant-side workflows.

[No sources needed since this section summarizes without analyzing specific files]

Appendices ​

Appendix A: Tenant Lifecycle Summary ​

  • Registration: Create tenant, optional subscription, default org, admin user
  • Configuration: Update info/status, assign package, reset admin password
  • Deactivation: Soft-delete tenant records
  • Monitoring: Tenant stats and audit logs

Section sources