User Management Module Modernization — Design Spec

Session: 210 Date: 2026-03-12 Status: Draft Approach: Rebuild from gmodules1 base into gspace1

1. Objective

Modernize the modules/core-modules/user-management module to:

1. Use real backend-api endpoints instead of mock data
2. Replace NGXS state management with autoFlashState from @storage-system
3. Incorporate the corrected L0-L4 user tier hierarchy (Session 209)
4. Support both SystemRoles (immutable, platform-wide) and custom space-level roles
5. Remain portable across gspace1 AND dynamically generated platforms

2. Architecture

2.1 Data Access: Dual-Layer Pattern

Components (UI)
    ↓ inject
Repository (domain queries, caching, events)
    ↓ delegates
API Service (HTTP, configurable base URL)
    ↓ HTTP
Backend API (port 3000 or platform backend)

Why dual-layer: The module must work in both gspace1 (where backend-api is at API_BASE_URL) and generated platforms (where the backend URL varies). The Repository abstracts this so components never know the URL.

2.2 State Management: autoFlashState

Replace NGXS @State + actions with autoFlashState signals:

// UI state — persisted locally, cross-tab synced
const userListState = autoFlashState<UserListState>('user-mgmt-list', {
  filters: {},
  pagination: { page: 1, pageSize: 20 },
  viewMode: 'table',
  bulkSelection: [],
}, {
  database: 'user-management',
  collection: 'ui-state',
  priority: 'normal',
  ttl: 7 * 24 * 60 * 60 * 1000, // 7 days
  debounceMs: 300,
});

Data (users, roles) is NOT stored in autoFlashState — it comes from the backend via API Service + Repository. Only UI preferences (filters, view mode, pagination, selection) are persisted locally.

Transient state (loading, error, selectedUser, total) lives as plain signal() values in the component or a lightweight service — NOT persisted. These reset on page load, which is correct behavior.

2.3 Tier Hierarchy Integration

There are TWO orthogonal classification systems. Both live on the User object:

System A: role: UserRole — Controls access level (what you CAN DO)

System B: userType: RegistrationUserType — Describes WHO you are (your tier)

Key: role determines access control enforcement (what the RolesGuard checks). userType determines the user's category in the platform hierarchy. A space_builder (L2) gets manager role by default but could be promoted to admin by an executive.

Rule: A user can only manage users with a LOWER role level than their own. Enforced at both API and UI level via the hierarchy-aware RolesGuard.

3. Module Structure (Target)

modules/core-modules/user-management/src/lib/
├── models/
│   ├── user.model.ts              # User, UserStatus, USER_PERMISSIONS
│   ├── user-api.model.ts          # Request/response types (CRUD, bulk, audit)
│   ├── user-filters.model.ts      # UserFilters, UserPagination
│   ├── role.model.ts              # Role, SystemRoles, ROLE_PERMISSIONS
│   ├── role-api.model.ts          # CreateRoleRequest, UpdateRoleRequest
│   └── index.ts
├── services/
│   ├── user-api.service.ts        # HTTP calls to /api/users (extends BaseCrudApiService)
│   ├── role-api.service.ts        # HTTP calls to /api/roles
│   └── index.ts
├── data/
│   └── repositories/
│       ├── user.repository.ts     # Domain queries, caching, event publishing
│       ├── role.repository.ts     # Role domain queries
│       └── index.ts
├── state/
│   ├── user-list.state.ts         # autoFlashState for user list UI
│   └── index.ts
├── components/
│   ├── user-list/                 # Main list (table/grid/cards, pagination, bulk)
│   ├── user-form/                 # Create/edit form (reactive forms, role selector)
│   ├── user-detail/               # Profile view + workflow state machine
│   ├── user-role-manager/         # Role assignment with hierarchy enforcement
│   ├── multi-role-lookup/         # Multi-select role dropdown
│   ├── user-card/                 # Card display
│   ├── user-avatar/               # Avatar with initials fallback
│   ├── user-filters/              # Filter panel (search, role, status, date)
│   ├── user-delete-confirm/       # Delete confirmation dialog
│   ├── role-list/                 # System + custom roles list
│   ├── role-form/                 # Create/edit role with permissions
│   ├── role-detail/               # Role details view
│   └── index.ts
├── actions/
│   ├── create-user.action.ts      # Public action (cross-module)
│   ├── update-user.action.ts
│   ├── delete-user.action.ts
│   ├── navigate-to-user.action.ts
│   ├── bulk-update-roles.action.ts
│   └── index.ts
├── events/
│   ├── user.events.ts             # UserCreated, UserUpdated, UserDeleted, etc.
│   ├── role.events.ts             # RoleAssigned, RoleRemoved
│   └── index.ts
├── workflow/
│   ├── user-workflow.definition.ts # Status state machine (pending→active→suspended→inactive)
│   └── index.ts
├── embeddables/
│   ├── user-list-widget/          # Compact embeddable widget
│   └── index.ts
├── mocks/
│   ├── user-mock-api.ts           # Mock API (dev/test only)
│   ├── user-mock-data.ts          # Generated test data
│   └── index.ts
├── user-management.module.ts      # Module manifest, lifecycle, navigation
├── user-management.routes.ts      # User routes with guards
├── role-management.routes.ts      # Role routes with guards
└── index.ts                       # Public API

13 components + 1 embeddable widget.

4. Backend API Endpoints

4.1 Existing Endpoints (backend-api:3000)

These already exist and the module will wire to them:

4.2 Endpoints to Add (backend-api enhancements)

Controller: New AdminUsersController at /api/admin/users to avoid route conflicts with the existing UsersController (which handles /api/users/me/*, /api/users/resolve-channel, etc.). All endpoints use @UseGuards(JwtAuthGuard, RolesGuard) at class level.

Note: The existing GET /api/admin/users in AdminStatsController already supports limit, skip, search. We extend it or replace it with the new AdminUsersController that adds pagination, filters, sorting, and full CRUD.

4.3 Backend Schema Enhancements

The existing User schema needs:

• Confirm roles: string[] supports multiple roles (it does — default ['user'])
• Add status field: 'active' | 'inactive' | 'suspended' | 'pending' (the existing UserHierarchyStatus uses 'deleted' instead of 'inactive' — we standardize on 'inactive' for soft-delete, 'deleted' is reserved for hard-delete/GDPR purge)
• Add userType: RegistrationUserType field alignment with frontend types

New schema needed:

• Role schema for custom roles (name, description, permissions[], isSystemRole, priority, spaceId?)

4.4 Pagination Strategy

All list endpoints use offset pagination (matching existing PlatformUsersController pattern):

• Query params: page (1-based), limit (1-100, default 20), search, sortBy, sortOrder
• Response: { data: T[], pagination: { page, pageSize, total, totalPages, hasNext, hasPrevious } }

5. Component Design

5.1 All Components

All components follow:

• Standalone: standalone: true with explicit imports
• OnPush: changeDetection: ChangeDetectionStrategy.OnPush
• DI: inject() function, never constructor injection
• Signals: Component state via signal(), computed(), effect()
• Async: RxJS Observables only, takeUntilDestroyed() for cleanup
• Separate files: .ts, .html, .scss — no inline templates

5.2 Key Component Details

UserListComponent:

• Reads from UserRepository.findAll() (Observable)
• UI state (filters, pagination, view mode, selection) from autoFlashState
• Supports table, grid, and card views
• Bulk operations: activate, deactivate, delete, change role
• Permission-gated actions (users:create, users:delete, etc.)

UserFormComponent:

• Reactive Forms with validation
• Mode: 'create' | 'edit' (input)
• Multi-role selector via MultiRoleLookupComponent
• Status dropdown (only visible for edit mode, requires users:status permission)
• Avatar upload

UserDetailComponent:

• Displays full user profile
• Embedded UserRoleManagerComponent for role assignment
• Workflow state machine visualization (pending → active → suspended → inactive)
• Status transitions with confirmation dialogs
• Workflow history timeline

UserRoleManagerComponent:

• Shows current roles with hierarchy levels
• Enforces: can only assign roles BELOW your own level
• Distinguishes system roles (immutable) from custom roles
• Primary role selector

RoleListComponent / RoleFormComponent / RoleDetailComponent:

• CRUD for custom roles within a space
• System roles shown as read-only (marked with badge)
• Permission picker for custom roles

5.3 Workflow State Machine

[pending] ──approve──→ [active] ──suspend──→ [suspended]
                           │                      │
                       deactivate            reactivate
                           ↓                      ↓
                       [inactive] ←──reactivate──+

Transitions require users:status permission. Confirmation dialogs for destructive transitions (suspend, deactivate).

6. Route Configuration

User Routes (/users)

Role Routes (/users/roles)

7. Domain Events

Events extend DomainEvent<T> from the module system's event bus.

8. Public Actions (Cross-Module API)

9. Module Manifest

@ModuleDecorator({
  id: 'user-management',
  version: '2.0.0',
  basePath: 'users',
  repositories: [UserRepository, RoleRepository],
  permissions: [
    'users:read', 'users:create', 'users:update', 'users:delete',
    'users:status', 'users:role', 'users:bulk', 'users:manage',
    'roles:read', 'roles:create', 'roles:update', 'roles:delete', 'roles:manage',
  ],
  navigation: {
    menuItems: [
      { label: 'Users', icon: 'people', route: 'list', permission: 'users:read',
        children: [
          { label: 'All Users', icon: 'list', route: 'list' },
          { label: 'Create User', icon: 'person_add', route: 'create' },
          { label: 'Admin Management', icon: 'shield', route: 'admin/manage' },
        ]
      },
      { label: 'Roles', icon: 'admin_panel_settings', route: 'roles/list', permission: 'roles:read',
        children: [
          { label: 'All Roles', icon: 'list', route: 'roles/list' },
          { label: 'Create Role', icon: 'add', route: 'roles/create' },
        ]
      },
    ]
  }
})

10. Portability Considerations

When embedded in gspace1:

• Base URL resolves via API_BASE_URL injection token (port 3000)
• Auth interceptor adds JWT from AuthService
• Tenant context from ContextInterceptor
• SystemRoles hierarchy available

When embedded in a generated platform:

• Base URL resolves via platform's provideApiConfig() call
• Auth interceptor from platform's auth module
• Tenant context = the platform's universe
• Custom roles only (SystemRoles reduced to platform-relevant subset)

Key abstraction points:

• UserApiService base URL is injected, never hardcoded
• Permission constants are exported, not hard-wired to specific guard implementations
• Module contract interface (BrowserModuleContract) ensures lifecycle compatibility

11. What We Are NOT Doing

• Not building a permissions editor UI (that's a separate module)
• Not implementing user groups/teams (future scope)
• Not adding 2FA management UI (backend schema exists but no UI needed yet)
• Not building CSV import/export (future scope)
• Not adding user impersonation (admin feature, separate scope)

12. Risks and Mitigations