Skip to content

User Groups Module – Developer Guide

1. Introduction

The User Groups module manages user group entities in the portal. Administrators can:

  • Create user groups
  • Assign users to groups
  • Update group configuration
  • Delete groups
  • Extend group data using metadata

This document explains the architecture, internal components, and extension patterns used by the module.

2. Technology Stack

Technology Purpose
React UI framework
TypeScript Static typing
MobX Global state management
RxJS Async API communication
Material UI UI components
DevExpress React Grid Data table system
Storybook UI development and testing
React Toastify User notifications

3. High-Level Architecture

User Interface
      │
      ▼
UserGroups React Component
      │
      ▼
Shared Table Components
      │
      ▼
API Layer
      │
      ▼
Backend REST Services

Responsibilities

Layer Responsibility
UI Rendering grid, dialogs, forms
Component Logic Managing state and events
Shared Components Popup editing, filtering, formatting
API Layer HTTP communication
Backend Data persistence and business logic

4. Module Structure

UserGroups/
│
├── UserGroups.tsx
├── types.ts
│
├── api/
│   └── usergroups.api.ts
│
├── common/
│   └── Table/
│       ├── CommandButtons.tsx
│       ├── DeleteDialog.tsx
│       ├── Popup.tsx
│       ├── PopupEditing.tsx
│       ├── FilterCells.tsx
│       ├── MetadataFormatter.tsx
│       └── UsersFormatter.tsx
│
└── stories/
    └── UserGroups.stories.tsx

5. Main Component

const UserGroupsLib: React.FC<UserGroupProps>

Props

Prop Description
host Backend API base URL
token Authentication token
metadata Optional metadata configuration

6. Data Flow

User Action
     │
     ▼
Grid Event
     │
     ▼
commitChanges()
     │
     ▼
API Layer
     │
     ▼
Backend Service
     │
     ▼
fetchUserGroups()
     │
     ▼
React State Update
     │
     ▼
UI Refresh

7. State Management

Local state is handled using React Hooks.

const [rows, setRows] = useState<UserGroupsData[]>([]);
const [users, setUsers] = useState<Record<string, string>[]>([]);
const [deletedDialog, setDeletedDialog] = useState(false);
const [deleteRow, setDeleteRow] = useState({});
State Purpose
rows User group list
users Available users
deletedDialog Delete confirmation dialog
deleteRow Selected row for deletion

8. Grid Implementation

The grid is powered by DevExpress React Grid.

Main plugins used:

FilteringState
SortingState
EditingState
IntegratedFiltering
IntegratedSorting
VirtualTable

Example:

<Grid rows={rows} columns={columns}>
  <FilteringState />
  <SortingState />
  <EditingState onCommitChanges={commitChanges} />
</Grid>

9. Command Buttons

Reusable action buttons are implemented as shared components.

Components:

  • AddButton
  • EditButton
  • DeleteButton
  • Command

Example:

const commandComponents = {
  add: AddButton,
  edit: EditButton,
  delete: DeleteButton
};

These are injected into TableEditColumn.

10. Delete Confirmation Dialog

Deletion requires confirmation using the DeleteDialog component.

Workflow:

  1. User clicks Delete
  2. Selected row is stored
  3. Confirmation dialog appears
  4. User confirms deletion
  5. API request is sent

11. Popup Editing System

Editing and creation are handled by two components:

Component Responsibility
PopupEditing Grid plugin managing editing lifecycle
Popup UI dialog for form editing

PopupEditing responsibilities:

  • Detect new vs edit mode
  • Track row changes
  • Apply metadata defaults
  • Commit changes
  • Cancel changes
  • Trigger toast notifications

12. Popup Form Validation

The popup validates multiple conditions before enabling Save.

Validation rules include:

  • Required field validation
  • Duplicate ID detection
  • Users selection validation
  • Metadata validation
  • Password validation (Accounts module)

Save button is disabled if validation fails.

13. Metadata System

Metadata allows dynamic extension of table columns.

Example configuration:

const metadata = [
  {
    key: "department",
    label: "Department",
    type: "SingleChoice",
    options: ["IT", "HR"]
  }
]

Metadata automatically:

  • Adds grid columns
  • Adds form fields
  • Enables filtering

14. Metadata Rendering

Metadata values are formatted through MetadataFormatter.

Supported types:

Type Rendering
Text Tooltip + text
SingleChoice Tooltip + text
MultiChoice Comma separated
MultiText Comma separated
Boolean Yes / No chip

15. Metadata Filtering

Filtering is implemented using:

  • FilterCellRow
  • InputFilterCell
  • BooleanFilterCell
  • filterRules(metadata)

Filtering logic is defined in metadataFilterService.

Type Filter Strategy
Text case-insensitive contains
SingleChoice contains
MultiChoice regex search
MultiText regex search
Boolean Yes/No mapping

16. Users Column Formatter

The UsersFormatter formats arrays of user IDs.

Example display:

alice, bob, charlie

Features:

  • Tooltip for full list
  • Text truncation with noWrap

17. Notifications

User feedback uses React Toastify.

Notifications are triggered when:

  • a save operation succeeds
  • an API request fails

Example:

toast("updated user", { type: "success" })

18. API Layer

Backend communication is handled by helper functions.

Method Endpoint
Fetch groups GET /api/usergroups
Create group POST /api/usergroups
Update group PUT /api/usergroups
Delete group DELETE /api/usergroups/{id}
Update groups for user POST /api/usergroups/user/{userId}

19. Type Definitions

interface UserGroupsData {
  id: string
  name: string
  users: string[]
  metadata?: {}
}

20. Storybook Development

Storybook allows isolated component development.

Example:

export const UserGroupStory = () => {
  return (
    <LoginGate host={host}>
      {({ token }) => (
        <UserGroups
          host={host}
          metadata={metadata}
          token={token.accessToken.token}
        />
      )}
    </LoginGate>
  )
}

Uses:

  • UI debugging
  • metadata testing
  • interaction testing

21. Extending the Module

Add new metadata type

Steps:

  1. Extend metadata configuration
  2. Update MetadataTypeProvider
  3. Update filter logic

Add custom column renderer

Create a new DataTypeProvider.

Example:

UsersTypeProvider
MetadataTypeProvider

Add validation rules

Update logic inside Popup.tsx.

22. Performance Considerations

Large datasets are optimized using:

  • VirtualTable
  • integrated filtering and sorting

Benefits:

  • fewer DOM updates
  • smoother scrolling

23. Testing Strategy

Test Type Tool
Unit Tests Jest
Component Tests React Testing Library
Visual Tests Storybook

Example:

test("renders user groups table", () => {
  render(<UserGroups />)
})

24. Known Limitations

Current limitations include:

  • No pagination
  • Error messages mostly console-based
  • Metadata validation depends on configuration

Conclusion

The User Groups module provides a flexible and extensible system for managing groups within the portal.

Key design characteristics:

  • reusable table infrastructure
  • popup-based editing workflow
  • metadata-driven columns
  • modular architecture

This architecture allows developers to extend functionality while maintaining consistency across modules.