Organization Management
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document describes the organizational structure management capabilities within the multi-tenant environment. It covers hierarchical organization creation, department management, organizational unit relationships, and the integration of organizational context into user-role-permission models. It also documents APIs for organization CRUD operations, user-organization associations, and organizational hierarchy management, along with patterns for synchronizing organizational data with external HR systems and tracking organizational changes.
Project Structure
The organization management feature spans three layers:
- API layer: Protocol buffer definitions for organization, user, and role services
- Service layer: Business logic and RPC handlers for organization operations
- Data layer: Repositories and persistence logic for tenant-scoped entities
Diagram sources
- [org.proto]
- [user.proto]
- [role.proto]
- [org.go]
- [user.go]
- [role.go]
- [org.go]
- [user.go]
- [role.go]
- [org.go]
- [user.go]
- [role.go]
Section sources
Core Components
- Organization service: Provides endpoints to list, create, update, delete organizations and to render hierarchical trees and dropdown options.
- User service: Manages user records and integrates organization assignment, role assignment, store permission assignment, and delegation patterns.
- Role service: Manages roles and menu permissions scoped to tenant subscriptions and packages.
- Persistence: Tenant-scoped tables for organizations, users, roles, and related association tables.
Key tenant-scoped tables supporting organization management:
- tenant_org: Hierarchical organization units with ancestors tracking
- tenant_user: Users linked to organizations and roles
- tenant_user_store: User-store permission mapping
- tenant_user_delegate: User delegation relationships
Section sources
Architecture Overview
The organization management architecture follows a clean domain-driven design with explicit separation of concerns:
- API layer defines gRPC/HTTP endpoints and request/response messages
- Service layer handles tenant scoping, context extraction, and orchestrates use cases
- Business logic encapsulates domain rules (e.g., ancestor computation, deletion constraints)
- Data layer persists tenant-scoped entities and enforces soft deletes
Diagram sources
Section sources
Detailed Component Analysis
Organization Management API
Endpoints support:
- List organization tree filtered by status
- List organization options for dropdowns
- Get organization details
- Create, update, delete organizations
- Validation via protobuf annotations and field constraints
Diagram sources
Section sources
User-Organization Assignment and Delegation
Users are associated with organizations and roles, and can inherit permissions via delegation:
- User creation/update supports org_id assignment
- Role assignment per user
- Store permission assignment per user
- Delegation allows inheriting another user’s store permissions
Diagram sources
Section sources
Role Management and Menu Permissions
Roles are tenant-scoped with menu permissions derived from the tenant’s subscription package. Available menus are filtered to those included in the current package.
Diagram sources
Section sources
Organizational Chart and Reporting Relationships
Organizations support hierarchical relationships with ancestors tracking. The service builds tree structures from flat lists and provides dropdown options for selection.
Diagram sources
Section sources
Organizational-Level Permissions
Tenant-scoped permissions are computed as:
- Super admin: all menus within the tenant’s package
- Regular users: intersection of user role menus and tenant package menus
- Store permissions: union of direct store associations and delegated stores
- Delegation: user inherits another user’s store permissions
Diagram sources
Section sources
API Documentation: Organization CRUD Operations
- ListOrgTree: GET /api/v1/tenant/orgs/tree?status=
- ListOrgOptions: GET /api/v1/tenant/orgs/options?status=
- GetOrg: GET /api/v1/tenant/orgs/
- CreateOrg: POST /api/v1/tenant/orgs
- UpdateOrg: PUT /api/v1/tenant/orgs/
- DeleteOrg: DELETE /api/v1/tenant/orgs/
Validation rules:
- Organization type constrained to company, department, team
- Organization name length limits
- Parent ID must reference an existing organization
Section sources
API Documentation: User-Organization Associations
- UpdateUserRoles: PUT /api/v1/tenant/users/{id}/roles
- UpdateUserStores: PUT /api/v1/tenant/users/{id}/stores
- UpdateUserDelegates: PUT /api/v1/tenant/users/{id}/delegates
- ResetUserPassword: POST /api/v1/tenant/users/{id}/reset-password
- UpdateUserStatus: PUT /api/v1/tenant/users/{id}/status
- UpdateUserAdmin: PUT /api/v1/tenant/users/{id}/admin
Section sources
API Documentation: Organizational Hierarchy Management
- ListOrgTree: Returns nested OrgInfo with children
- ListOrgOptions: Returns flattened OrgOption tree for dropdowns
Section sources
Organizational Data Synchronization with External HR Systems
Recommended patterns:
- Use batch endpoints to import organizations and users
- Maintain org_code as external HR system identifiers
- Track last_sync_timestamp per organization/user
- Implement idempotent upserts with conflict resolution on org_code
- Validate parent-child relationships against external hierarchy
- Audit changes via operation logs
[No sources needed since this section provides general guidance]
Organizational Change Tracking
- Soft delete pattern: deleted_at timestamp
- Operation logging: tenant_operation_log captures administrative actions
- Ancestor propagation: changes to parent affect descendants’ computed ancestry
Section sources
Common Organizational Management Scenarios and Integration Patterns
- Onboarding new departments under a company: create child org with parent_id set to company
- Rehiring employees: restore user status and reassign roles/stores/delegates
- Team restructuring: move users between departments by updating org_id
- HR sync integration: import org tree from external system, reconcile with org_code, update parent_id accordingly
- Delegation setup: assign delegate relationships to inherit store permissions
Section sources
Dependency Analysis
The organization management stack depends on:
- Tenant scoping via tenant_id
- RBAC middleware for authorization
- OpenAPI/Swagger generation for API documentation
- Soft delete and bitmap indexing for performance
Diagram sources
Section sources
Performance Considerations
- Use bitmap indexes on tenant_org for parent_id, org_type, status, and tenant_id
- Leverage soft delete with deleted_at for auditability without physical deletion
- Ancestor computation during create/update ensures efficient tree queries
- Pagination for user and role listings to avoid large payloads
Section sources
Troubleshooting Guide
Common issues and resolutions:
- Cannot delete organization: ensure no child organizations or users are assigned
- Invalid parent_id: verify parent exists and belongs to the same tenant
- Permission denied: confirm tenant_id extracted from context matches requested resource
- Password reset failures: default/admin accounts are protected from modifications
Section sources
Conclusion
The organization management subsystem provides robust tenant-scoped hierarchical organization support, integrated user-role-permission management, and extensible patterns for external HR system synchronization. The clean architecture, strong tenant isolation, and comprehensive APIs enable scalable multi-tenant organizational administration.
Appendices
Appendix A: Database Schema Highlights
- tenant_org: hierarchical organization with ancestors, parent_id, and tenant_id
- tenant_user: user records linked to organizations and roles
- tenant_user_store: user-store permission mapping
- tenant_user_delegate: user delegation relationships
Section sources
Appendix B: RBAC and Authorization
- Tenant-aware context extraction
- Middleware enforcing tenant isolation
- Role-based menu permissions aligned with package subscriptions
Section sources
Appendix C: System-wide Organization vs Tenant Organization
- bi-sys provides system-level organization (dept) for platform administration
- bi-tenant provides tenant-level organization for client-side management
Section sources