User Groups Module – Developer Guide¶

1. Introduction¶

The User Groups module provides functionality to manage groups of users in the portal. It allows administrators to organize users into groups, assign users to those groups, and extend group data using configurable metadata.

This guide explains the architecture, code structure, and development workflow for developers who want to modify or extend the User Groups module.

2. Technology Stack¶

The module is built using modern frontend technologies.

Technology	Purpose
React	UI framework
TypeScript	Static typing
MobX	Global state management
RxJS	Asynchronous API calls
Material UI	UI components
DevExpress React Grid	Data grid functionality
Storybook	Component development and testing

3. High-Level Architecture¶

The User Groups module follows a layered architecture.

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

Layer Responsibilities¶

Layer	Responsibility
UI Layer	Rendering grid, forms, dialogs
Component Logic	State handling and event management
API Layer	Communication with backend endpoints
Backend	Data storage and business logic

4. Module Structure¶

Typical structure for the User Groups module:

UserGroups/
│
├── UserGroups.tsx
├── types.ts
├── api/
│   └── usergroups.api.ts
│
├── common/
│   └── Table/
│       ├── PopupEditing
│       ├── DeleteDialog
│       └── TypeProviders
│
└── stories/
    └── UserGroups.stories.tsx

File Responsibilities¶

File	Description
`UserGroups.tsx`	Main component for the module
`types.ts`	TypeScript interfaces
`api`	API functions for backend communication
`common/Table`	Shared table utilities
`stories`	Storybook UI testing

5. Main Component¶

The main component is UserGroupsLib.

const UserGroupsLib: React.FC<UserGroupProps>

Props¶

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

6. Data Flow¶

The data flow within the module works as follows:

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

7. State Management¶

The module uses React hooks for local state management.

Key States¶

const [rows, setRows] = useState<UserGroupsData[]>([]);
const [users, setUsers] = useState<Record<string, string>[]>([]);
const [deletedDialog, setDeletedDialog] = useState(false);
const [deleteRow, setDeleteRow] = useState({});

State Description¶

State	Purpose
rows	List of user groups
users	List of available users
deletedDialog	Controls delete confirmation dialog
deleteRow	Selected row for deletion

8. Data Fetching¶

Data is loaded when the component mounts.

useEffect(() => {
  fetchData();
  setFilteringColumnExtensions(filterRules(metadata));
}, []);

API Calls¶

The module retrieves:

User Groups
Accounts (users)

Example:

fetchUserGroups(host, token)
fetchAccounts(host, token)

9. Grid Implementation¶

The module uses DevExpress React Grid.

Main grid plugins:

FilteringState
SortingState
EditingState
IntegratedFiltering
IntegratedSorting
VirtualTable

Example grid configuration:

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

Features Provided¶

Feature	Description
Filtering	Filter rows by column
Sorting	Sort table columns
Editing	Add/edit/delete rows
Virtual scrolling	Optimized rendering

10. Editing Workflow¶

All create/update/delete operations are handled by commitChanges.

const commitChanges = ({ added, changed, deleted }) => {}

Possible Actions¶

Action	Description
added	Create new user group
changed	Update existing group
deleted	Trigger delete dialog

11. Create User Group¶

Creating a new user group triggers the API call:

createUserGroup(host, token, data)

Example payload:

{
  id: row.id,
  name: row.name,
  users: row.users,
  metadata: row.metadata
}

12. Update User Group¶

Updating a group calls:

updateUserGroups(host, token, data)

Example payload:

{
  id: data.id,
  name: data.name,
  users: data.users,
  metadata: data.metadata
}

13. Delete User Group¶

Deletion occurs after confirmation.

API call:

deleteUserGroup(host, token, row.id)

After deletion:

Backend removes the group
fetchData() refreshes the table
Delete dialog closes

14. Users Column Formatter¶

The users column uses a custom formatter.

export const UsersFormatter = ({ value }) => {
  const list = value?.join(', ')
}

Behavior¶

Displays users as comma-separated values
Shows full list in tooltip
Prevents overflow with Typography noWrap

15. Metadata System¶

Metadata allows dynamic extension of the User Groups table.

Example configuration:

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

Metadata automatically:

Creates additional columns
Adds form inputs in popup editing
Supports filtering rules

Add and edit actions open a popup dialog.

Example configuration:

<PopupEditing
  popupComponent={Popup}
  title="User Groups"
  allUsers={users}
  metadata={metadata}
  defaultColumns={DEFAULT_COLUMNS}
  onSave={handleSubmit}
/>

Form Fields¶

Field	Description
Name	User group name
Users	Selected users
Metadata	Additional custom fields

17. API Layer¶

All backend communication is handled through API helper functions.

Fetch Groups¶

GET /api/usergroups

Create Group¶

POST /api/usergroups

Update Group¶

PUT /api/usergroups

Delete Group¶

DELETE /api/usergroups/{id}

Update Groups for a User¶

POST /api/usergroups/user/{userId}

18. Type Definitions¶

Main TypeScript interface:

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

Field Explanation¶

Field	Description
id	Unique group identifier
name	Display name
users	Assigned users
metadata	Optional metadata fields

19. Storybook Development¶

The module includes a Storybook example.

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

Storybook is useful for:

UI debugging
testing metadata configurations
isolated component development

20. Extending the Module¶

Common extension scenarios include:

Add new metadata type¶

Steps:

Add metadata configuration
Update MetadataTypeProvider
Update filter rules

Add validation rules¶

Update the form component and metadata validation logic.

Add custom column renderer¶

Create a new TypeProvider similar to UsersTypeProvider.

21. Performance Considerations¶

The module uses VirtualTable to support large datasets.

Benefits:

reduces DOM rendering
improves scroll performance
handles large user group lists efficiently

22. Testing Strategy¶

Recommended testing tools:

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