Accounts Module – Developer Guide¶
1. Introduction¶
The Accounts Module is a React-based user management interface used within the portal to manage user accounts and their associated user groups.
It integrates with backend services through REST APIs and uses a DevExpress React Grid interface for displaying and editing data.
Key capabilities include:
- Account CRUD operations
- User group assignment
- Dynamic metadata fields
- Authentication with Bearer tokens
- Reactive state management using MobX
- Shared popup editing infrastructure
2. Technology Stack¶
| Technology | Purpose |
|---|---|
| React | UI rendering |
| TypeScript | Type safety |
| MobX | State management |
| RxJS | Async API handling |
| Material UI | UI components |
| DevExpress React Grid | Data grid UI |
| Storybook | Component testing |
| React Toastify | UI notifications |
3. Project Structure¶
Example logical structure of the module:
```text id="j8tqdp" accounts/ │ ├── Accounts.tsx ├── api/ │ └── index.ts │ ├── common/ │ ├── Table/ │ │ ├── CommandButtons │ │ ├── PopupEditing │ │ ├── Popup │ │ ├── DeleteDialog │ │ ├── FilterCells │ │ ├── MetadataFormatter │ │ └── UsersFormatter │ ├── UserGroups/ │ └── types.ts │ ├── types/ │ └── Accounts.types.ts │ └── stories/ └── Accounts.stories.tsx
---
# 4. Component Architecture
The Accounts module consists of two main components.
## Wrapper Component
This component injects authentication and configuration into the Accounts UI.
```tsx id="m6p0f3"
const Accounts = observer(
({ configuration }: { configuration: Configuration }) => {
const { authService, appSession } = observableStates;
const { accessToken } = authService!.getSession();
return (
<DHIAccounts
token={appSession.pageAccessToken || accessToken}
host={configuration.authHost}
userGroupsDefaultSelected={configuration?.userGroupsDefaultSelected}
metadata={configuration?.metadata}
/>
);
}
);
Responsibilities:
- Access MobX store
- Retrieve authentication token
- Inject configuration into UI component
Core Accounts Component¶
Main responsibilities:
- Render accounts table
- Manage editing state
- Communicate with API layer
- Handle metadata fields
- Manage popup editing workflow
```tsx id="rqz3sn"
const Accounts: React.FCProps:
| Prop | Description |
| ------------------------- | ---------------------------- |
| host | API base URL |
| token | Bearer authentication token |
| metadata | Optional dynamic fields |
| userGroupsDefaultSelected | Default groups for new users |
---
# 5. Data Flow
```text id="3mtzqg"
User Action
│
▼
React Grid Event
│
▼
commitChanges()
│
▼
PopupEditing lifecycle
│
▼
API Layer
│
▼
Backend Service
│
▼
fetchAccounts()
│
▼
React State Update
│
▼
UI Refresh
6. API Integration¶
The module communicates with the backend through a dedicated API layer.
Fetch Accounts¶
```ts id="c6j1pe" GET /api/accounts
```ts id="z4e8d0"
fetchAccounts(host, token)
Returns a list of accounts.
Create Account¶
```ts id="i9zkl3" POST /api/accounts
```ts id="y9x9q1"
createAccount(host, token, payload)
Creates a new account and activates it automatically.
Update Account¶
```ts id="i5aqn7" PUT /api/accounts
Important requirement:
All fields must be included in the payload except the password.
---
### Delete Account
```ts id="5bnz8u"
DELETE /api/accounts/{username}
Deletion occurs only after confirmation.
7. Grid Implementation¶
The Accounts table uses DevExpress React Grid.
Main plugins:
```ts id="0dy0me" FilteringState SortingState EditingState IntegratedFiltering IntegratedSorting VirtualTable
Example configuration:
```tsx id="ow1d5i"
<Grid rows={rows} columns={columns}>
<FilteringState />
<SortingState />
<EditingState onCommitChanges={commitChanges} />
</Grid>
Features supported:
- Column filtering
- Sorting
- Inline editing
- Column visibility control
- Virtual scrolling
8. Command Buttons¶
Row actions are implemented using shared components.
Components:
AddButtonEditButtonDeleteButtonCommand
Example:
```tsx id="2y3ypb" const commandComponents = { add: AddButton, edit: EditButton, delete: DeleteButton };
These integrate with `TableEditColumn`.
---
# 9. Delete Confirmation Dialog
Deletion is handled through the `DeleteDialog` component.
Workflow:
1. User clicks Delete
2. Selected row is stored
3. Confirmation dialog appears
4. User confirms deletion
5. API request executes
This prevents accidental data removal.
---
# 10. Popup Editing System
Editing and creation are managed through:
| Component | Role |
| ------------ | ------------------------- |
| PopupEditing | Editing lifecycle manager |
| Popup | Form dialog |
PopupEditing responsibilities:
* Track row changes
* Manage add/edit modes
* Apply metadata defaults
* Commit row changes
* Cancel editing
* Trigger notifications
---
# 11. Popup Form Validation
Validation logic includes:
* Duplicate ID detection
* Required fields validation
* Email sanitization
* Password confirmation
* Password strength indicator
* Metadata validation
If validation fails:
* the Save button is disabled
* error messages are shown
---
# 12. Password Strength Indicator
Accounts include password strength visualization.
Strength indicator uses colored dots:
| Strength | Color |
| -------- | --------------- |
| Weak | Red |
| Medium | Yellow / Orange |
| Strong | Green |
Implemented using `passwordStrength()` utility.
---
# 13. Metadata System
Metadata allows dynamic extension of the Accounts table.
Example configuration:
```ts id="0ljy63"
const metadata = [
{
key: "department",
label: "Department",
type: "SingleChoice",
options: ["IT","Finance","HR"]
}
];
Supported metadata types:
| Type | Description |
|---|---|
| Text | String input |
| Boolean | Checkbox |
| SingleChoice | Dropdown |
| MultiChoice | Multi-select |
| MultiText | List of values |
14. Metadata Rendering¶
Metadata values are rendered through MetadataFormatter.
Rendering rules:
| Type | Display |
|---|---|
| Text | Tooltip + text |
| SingleChoice | Tooltip + text |
| MultiChoice | Comma-separated |
| MultiText | Comma-separated |
| Boolean | Yes/No chip |
15. Filtering Rules¶
Filtering logic is generated dynamically based on metadata.
```ts id="9ncz4c" setFilteringColumnExtensions(filterRules(metadata));
Filtering supports:
* text search
* boolean dropdown filters
* regex matching for array values
---
# 16. Users Column Formatter
The user groups column uses `UsersFormatter`.
Example output:
```text id="z0xqut"
Admin, Editor, Reviewer
Features:
- Tooltip display
- Text truncation
- Comma-separated formatting
17. Notifications¶
User feedback uses React Toastify.
Notifications appear when:
- account is updated
- API errors occur
Example:
```ts id="7m81gq" toast("updated user", { type: "success" });
---
# 18. State Management
State is managed locally using React hooks.
Main states:
```ts id="k5r2qq"
rows
userGroups
deletedDialog
errorMessage
filteringColumnExtensions
Example:
```ts id="gyn6c8"
const [rows, setRows] = useState---
# 19. Data Fetching
Initial data loading occurs when the component mounts.
```ts id="m1f7z6"
useEffect(() => {
fetchData();
}, []);
fetchData() retrieves:
- Accounts list
- User groups
20. Storybook Development¶
Example story:
```tsx id="q6q1ml"
export const AccountsStory = () => {
return (
Benefits:
* UI testing
* metadata experimentation
* component isolation
---
# 21. Security Considerations
Recommended practices:
* Validate user input
* Sanitize email fields
* Handle tokens securely
* Restrict operations through user groups
Example:
```ts id="ts33ne"
const sanitizeAccountPayload = (row) => {
const payload = { ...row };
payload.email = payload.email?.trim() || "";
return payload;
};
22. Performance Considerations¶
Large datasets are optimized using:
VirtualTable
IntegratedFiltering
IntegratedSorting
Benefits:
- reduced DOM rendering
- smoother scrolling
- faster filtering
23. Testing Strategy¶
| Test Type | Tool |
|---|---|
| Unit tests | Jest |
| UI tests | React Testing Library |
| Component tests | Storybook |
| API mocking | MSW |
Example:
ts id="y1zqk9"
test("renders accounts table", () => {
render(<Accounts />);
});
24. Known Limitations¶
Current limitations include:
- No pagination support
- Update requires full payload
- Password update not integrated in UI
- Error handling mostly UI-level
25. Future Improvements¶
Potential improvements:
- Role-based access control
- Pagination support
- Improved form validation
- Audit logging
- GraphQL integration
Conclusion¶
The Accounts module provides a flexible and extensible user management system built with modern React architecture.
Key design principles include:
- reusable table infrastructure
- popup-based editing workflow
- metadata-driven columns
- modular API integration
- consistent UI patterns across modules
These patterns allow developers to extend functionality while maintaining maintainable code structure.