Version #

Version 1

Module Type #

Standard

Internal Name #

users

Status #

Draft

Description #

In Version 1, the Users module stores and manages basic user profiles, including each user”s name, contact details, and exactly one associated address. A user”s email must be unique within the system.

While this module creates and maintains the user record, it does not manage Authentication (that is handled by the Auth Module). By design, “Permanently Deleting” a user in Version 1 is effectively just a soft delete, flagging the user as inactive without physically removing the record. This approach allows for potential reactivation or auditing later.

Addresses are stored in a separate data structure to lay the groundwork for multi-address support in future releases (currently, only one address per user is allowed). Future versions may also separate the address-creation flow from the initial user-creation flow if needed.

This module has basic error handling.

User Journeys #

createUser #

Name

createUser

Overview

Allows an admin or an external system to create a new user record in the system. This journey captures the essential steps required to set up a user profile with minimal fields (name, email, optional address).

Actors

• Admin (initiator) or External System
• Users Module (system)

Preconditions

• The caller must have appropriate privileges to create a user (Authentication is handled via the Auth Module, though the Users module does not enforce this directly in Version 1).
• Required user details (e.g., FirstName, LastName, Email) must be available.

Flow

Primary Flow

1. The admin/external system sends a POST request to /users/create with the new user”s details (e.g., {“FirstName”: “John”, “LastName”: “Doe”, “Email”: “[email protected]”}).
2. The Users Module validates the mandatory fields (e.g., checks format, uniqueness of email).
3. On success, the system returns a success response containing the new UserID (e.g., {“status”: “success”, “UserID”: “1234-abcd”}).
4. A userCreated webhook is triggered to inform other modules or external services that a new user has been created.

Alternative/Exception Flows

• If mandatory fields are missing or invalid, the system returns an error response (e.g., {“status”: “Error”}).
• If any internal validation or database error occurs, no user record is created and an error response is returned.

Outcome

A new user record is successfully created, making the user available for subsequent operations (retrieve, update, etc.).

Error Handling

• On error, the response includes {“status”: “Error”}.
• A userError webhook is triggered with details such as error message, endpoint, and timestamp.

Postconditions

• On success, the new user is persisted in the system, ready for additional actions.
• On error, no new record is created, and the error is logged via webhook.

Triggers

• userCreated webhook on successful creation.
• userError webhook on failure.

Notes

• This flow assumes minimal user data in Version 1.
• Additional validations (e.g., checking for duplicate email) are performed before persistence.

retrieveUser #

Name

retrieveUser

Overview

Allows an admin or the user themselves (depending on business logic) to fetch a user”s information using the UserID.

Actors

• Admin User or External Caller (initiator)
• Users Module (system)

Preconditions

• UserID of the user to retrieve must be provided.
• The user is not permanently deleted or otherwise inaccessible.

Flow

Primary Flow

1. The caller sends a POST request to /users/get with the target UserID.
2. The Users Module retrieves the user”s details from the database.
3. The system returns the user information in the response, for example:{  “UserID”: “1234-abcd”,  “FirstName”: “John”,  “Email”: [email protected] }
4. If configured, a userRetrieved webhook might be triggered to log or process the retrieval (optional in Version 1).

Alternative/Exception Flows

• If the user does not exist, or is soft-deleted/permanently deleted, the system returns {“status”: “Error”}.
• A userError webhook is triggered describing the issue (invalid ID, user not found, etc.).

Outcome

The caller receives the user”s record, including personal details and any associated fields.

Error Handling

• On error, the system returns {“status”: “Error”}.
• A userError webhook is triggered containing error details.

Postconditions

• On success, the requested user details are provided to the caller.
• On error, the caller receives no user data, and the error is logged.

Triggers

• userRetrieved (if implemented; not mandatory in Version 1).
• userError on failure.

Notes

• Business logic may restrict whether a user can retrieve their own record or if only admins can do so.
• The error path covers both “no user found” and “user is soft/permanently deleted.”

updateUser #

Name

updateUser

Overview

Allows an admin user to modify an existing user”s details (e.g., last name, date of birth).

Actors

• Admin User (initiator)
• Users Module (system)

Preconditions

• The user to be updated must exist and not be permanently deleted.
• The admin must have appropriate privileges to update user records.

Flow

Primary Flow

1. Admin sends a POST request to /users/update with the UserID and the fields to update (e.g., {“UserID”:”1234-abcd”,”LastName”:”Smith”}).
2. The Users Module validates the request (e.g., checks the user”s status).
3. On success, the system updates the user record and returns {“status”: “success”}.
4. A userUpdated webhook may be fired to notify that the user record has been changed.

Alternative/Exception Flows

• If the UserID is invalid or the user is permanently deleted, the system returns {“status”:”Error”}.
• If any validation fails (e.g., invalid data), an error response is returned.

Outcome

The specified user”s record is updated with the new information.

Error Handling

• On error, the system returns {“status”: “Error”}.
• A userError webhook is triggered with details on the failure.

Postconditions

• On success, the updated fields are persisted in the database.
• On error, the record remains unchanged.

Triggers

• userUpdated (optional) on success.
• userError on error.

Notes

• In Version 1, any advanced field validations (beyond basic checks) may be minimal.
• This flow does not handle changes to addresses (see the address-specific journeys).

permanentlyDeleteUser #

Name

permanentlyDeleteUser

Overview

Marks a user as permanently deleted, though in Version 1 this is effectively just a “flag” rather than a physical removal of the data.

Actors

• Admin User (initiator)
• Users Module (system)

Preconditions

• The target user must exist in the system and not already be flagged as permanently deleted.
• Admin must have privileges to delete user records.

Flow

Primary Flow

1. Admin sends a POST request to /users/delete with the user”s UserID.
2. The Users Module sets IsPermanentlyDeleted = true.
3. The system returns {“status”:”success”} upon successful flag update.
4. A userDeleted webhook is triggered to notify that the user has been marked for permanent removal.

Alternative/Exception Flows

• If the user is already permanently deleted, the system returns {“status”:”Error”}.
• If the user does not exist or any internal error occurs, the system returns {“status”:”Error”}.

Outcome

The user is marked as permanently deleted, effectively removing them from active use.

Error Handling

• On error, returns {“status”:”Error”}.
• A userError webhook is triggered, providing details about the failure.

Postconditions

• On success, the user is flagged as permanently deleted.
• On error, no changes are made to the user”s record.

Triggers

• userDeleted on success.
• userError on failure.

Notes

• Physically removing user data from the database is not mandated in Version 1.
• This approach simplifies potential auditing or reactivation tasks.

softDeleteUser #

Name

softDeleteUser

Overview

Disables a user account by marking it as inactive, without permanently deleting the record.

Actors

• Admin User (initiator)
• Users Module (system)

Preconditions

• The user must not be permanently deleted already.
• Admin must have privileges to modify user status.

Flow

Primary Flow

1. Admin sends a POST request to /users/softDelete with the user”s UserID.
2. The Users Module updates IsSoftDeleted = true in the user”s record.
3. The module returns {“status”:”success”}.
4. A userSoftDeleted webhook is triggered, indicating the user is now inactive.

Alternative/Exception Flows

• If the user is not found or is permanently deleted, {“status”:”Error”} is returned.
• If any validation fails, the system returns an error.

Outcome

The user is marked as inactive but is still in the database for auditing or future reinstatement.

Error Handling

• On error, returns {“status”:”Error”}.
• A userError webhook logs the issue.

Postconditions

• On success, the user can no longer perform active tasks (depending on system logic).
• On error, the record remains unchanged.

Triggers

• userSoftDeleted on success.
• userError on failure.

Notes

• This approach preserves historical data while preventing an active user from operating.
• In future versions, reactivation flows may be introduced.

listUsers #

Name

listUsers

Overview

Retrieves a list of users, potentially filtered by certain criteria and with pagination/sorting.

Actors

• Admin User or Internal Process (initiator)
• Users Module (system)

Preconditions

• The admin or process must be authorized to view user listings.
• The request may include parameters like page, pageSize, filter conditions.

Flow

Primary Flow

1. The caller sends a POST request to /users/list with optional filters (e.g., {“page”:1,”pageSize”:20}).
2. The Users Module retrieves matching user records from the database.
3. The system returns a JSON object with an array of user objects and metadata (e.g., total count).
4. If configured, a userListRetrieved webhook may be triggered to log or act on the retrieval.

Alternative/Exception Flows

• If invalid parameters are provided or an internal error occurs, the system returns {“status”:”Error”}.
• A userError webhook may be triggered detailing the issue.

Outcome

The admin or internal process receives a paginated list of users based on the specified criteria.

Error Handling

• On error, {“status”:”Error”} is returned.
• A userError webhook is triggered with error details.

Postconditions

• On success, the caller has the requested user data set.
• On error, no valid list is returned.

Triggers

• userListRetrieved on success (optional).
• userError on error.

Notes

• Sorting and additional filtering logic may be expanded in later versions.
• Large lists may require further performance considerations.

searchUsers #

Name

searchUsers

Overview

Allows an admin or external module to find users by name, email, or other criteria.

Actors

• Admin User or External System (initiator)
• Users Module (system)

Preconditions

• The caller has permissions to perform user searches.
• A search query is provided (e.g., partial name or email).

Flow

Primary Flow

1. The caller sends a POST request to /users/search with the search parameter (e.g., {“query”:”John”}).
2. The Users Module performs a lookup based on the provided search string.
3. The system returns {“results”:[ … ]} containing matching user data, if found.

Alternative/Exception Flows

• If no matches are found, an empty array is returned: {“results”:[]}.
• If an internal error occurs, {“status”:”Error”} is returned along with a userError webhook.

Outcome

User records matching the search criteria are returned, enabling the caller to refine or proceed with further actions (e.g., retrieve or update a user).

Error Handling

• On error, returns {“status”:”Error”}.
• A userError webhook is triggered, providing error context.

Postconditions

• On success, the caller receives zero or more matches.
• On error, no results are returned, and the error is logged.

Triggers

• userSearchPerformed (optional) on success.
• userError on error.

Notes

• Implementation details of how the search is performed (e.g., partial string match, indexing) may vary.
• In Version 1, advanced search filters are minimal.

validateUserExistence #

Name

validateUserExistence

Overview

Checks if a user exists in the system based on a unique field (e.g., email or username).

Actors

• Admin User or Another Module (initiator)
• Users Module (system)

Preconditions

• The caller must supply a unique user field in the request (e.g., email).
• The user might or might not exist in the database.

Flow

Primary Flow

1. The caller sends a POST request to /users/validate with a unique field, for example: {“Email”:”[email protected]”}.
2. The Users Module checks the database to see if a matching record exists.
3. The system returns {“exists”: true} or {“exists”: false}.
4. Optionally, a userValidated webhook may be triggered on success.

Alternative/Exception Flows

• If the field is missing or invalid, the system returns {“status”:”Error”}.
• A userError webhook logs the issue.

Outcome

The caller learns whether the user record is present in the system.

Error Handling

• On error, {“status”:”Error”} is returned.
• userError webhook is triggered.

Postconditions

• On success, the result clarifies if the user exists.
• On error, no valid existence check result is returned.

Triggers

• userValidated on success (optional).
• userError on error.

Notes

• Future versions might combine existence checks with additional user data or constraints.
• The call does not return user details—only a boolean.

Authentication #

Authentication for is managed via the Auth Module. Module-to-module communication in Version 1 does not require Authentication. Internal services can call the Admins Module freely.

Schema #

This data needs to be stored, in what way and how is to be decided by the implementation. But the data needs to be stored.

User #

Name	Type	Internal Name	Description
user_id	UUID/String	users.user.user_id	Unique identifier for each user.
first_name	String	users.user.first_name	User”s first name.
middle_name	String (nullable)	users.user.middle_name	User”s middle name (optional).
last_name	String	users.user.last_name	User”s last name.
salutation	String	users.user.salutation	Salutation (e.g., Mr, Mrs, Dr).
date_of_birth	Date	users.user.date_of_birth	User”s date of birth.
email	String	users.user.email	User”s primary email address.
user_is_soft_deleted	bool	users.user.is_soft_deleted	If record is soft deleted
user_s_permanently_deleted	bool	users.user.is_permanently_deleted	If record is permanently

Address #

Name	Type	Internal Name	Description
address_id	UUID/String	users.address.address_id	Unique identifier for each address.
user_id	UUID/String	users.address.user_id	Links the address to a specific user.
address_name	String	users.address.address_name	Descriptive label (home, office, etc.).
street_address_1	String	users.address.street_address_1	Primary street address line.
street_address_2	String (nullable)	users.address.street_address_2	Secondary street address line (optional).
city	String	users.address.city	City of the address.
state_region	String	users.address.state_region	State or region of the address.
Postal_code	String	users.address.postal_code	Postal or ZIP code.
country	String	users.address.country	ISO 3166-1 alpha-2 country code.
address_is_soft_deleted	bool	users.address.is_soft_deleted	If record is soft deleted
address_is_permanently_deleted	bool	users.address.is_permanently_deleted	If record is permanently

Functions #

Name	Endpoint	Description	Internal Name
createUser	/users/create	Creates a new user record.	users.createUser
getUser	/users/get	Retrieves user details based on a UserID.	users.getUser
getUserID	/users/getUserID	Retrieves UserID by querying unique fields.	users.getUserID
updateUser	/users/update	Updates existing user information.	usesr.updateUser
deleteUser	/users/delete	Permanently deletes a user record.	users.deleteUser
softDeleteUser	/users/softDelete	Soft deletes (marks inactive) a user.	users.softDeleteUser
listUsers	/users/list	Lists users with pagination, sorting, and filtering.	users.listUsers
searchUsers	/users/search	Searches users by name, email, etc.	users.searchUsers
validateUserExists	/users/validate	Checks if a user exists (by email or username).	users.validateUserExists
getSettings	/users/settings/get	Retrieves Users module settings.	users.getSettings
UpdateSettings	/users/settings/save	Saves Users module settings.	users.saveSettings

Webhooks #

Name	Trigger	Destination	Payload	Description	Error Handling
userCreated	When the createUser function successfully completes and a new user is registered.	Log Module	{ “event”: “userCreated”, “timestamp”: “2025-03-15T10:00:00Z”, “user”: { “userId”: “user-001”, “email”: “[email protected]”, “name”: “John Doe” } }	Notifies external systems that a new user account has been created. Enables follow-up actions such as sending welcome emails and updating user analytics.	None
userInfoRetrieved	When the getUser function successfully retrieves the user’s details.	Log Module	{ “event”: “userInfoRetrieved”, “timestamp”: “2025-03-15T10:30:00Z”, “user”: { “userId”: “user-001”, “email”: “[email protected]”, “name”: “John Doe” } }	Notifies external systems that the user’s complete profile information has been retrieved via the getUser function.	None
userIdRetrieved	When the getUserID function successfully retrieves the user’s ID.	Log Module	{ “event”: “userIdRetrieved”, “timestamp”: “2025-03-15T10:35:00Z”, “user”: { “userId”: “user-001” } }	Notifies that the user’s unique identifier has been successfully retrieved by the getUserID function.	None
userUpdated	When the updateUser function successfully updates a user’s profile.	Log Module	{ “event”: “userUpdated”, “timestamp”: “2025-03-15T11:00:00Z”, “user”: { “userId”: “user-001”, “updatedFields”: { “name”: “John A. Doe” } } }	Informs external systems that the user’s profile has been updated, enabling them to synchronize or refresh stored data.	None
userDeleted	When the deleteUser function successfully deletes the user account.	Log Module	{ “event”: “userDeleted”, “timestamp”: “2025-03-15T12:00:00Z”, “user”: { “userId”: “user-001” } }	Notifies that a user account has been deleted, triggering any necessary cleanup processes in downstream systems.	None
userSoftDeleted	When the softDeleteUser function successfully soft-deletes a user account.	Log Module	{ “event”: “userSoftDeleted”, “timestamp”: “2025-03-15T13:00:00Z”, “user”: { “userId”: “user-001”, “status”: “soft-deleted” } }	Notifies that a user has been soft-deleted, flagging the account for future potential restoration.	None
usersListed	When the listUsers function successfully retrieves a list of users.	Log Module	{ “event”: “usersListed”, “timestamp”: “2025-03-15T13:05:00Z”, “users”: [ { “userId”: “user-001”, “email”: “[email protected]” } ] }	Notifies that the complete list of users has been retrieved.	None
usersSearched	When the searchUsers function successfully completes a search operation for users.	Log Module	{ “event”: “usersSearched”, “timestamp”: “2025-03-15T13:10:00Z”, “query”: “search term”, “results”: [ { “userId”: “user-001”, “email”: “[email protected]” } ] }	Notifies that a search operation on users has been completed, returning matching user records.	None
userExistenceValidated	When the validateUserExists function successfully confirms the existence of a user.	Log Module	{ “event”: “userExistenceValidated”, “timestamp”: “2025-03-15T13:15:00Z”, “user”: { “userId”: “user-001”, “exists”: true } }	Notifies that the existence of a user has been validated.	None

Settings #

Settings for the Users module are stored internally in a key-value “Settings” table. Each mandatory field has settings stored in JSON, defining constraints such as mandatory status, max/min lengths, allowed values, and validation rules.

Example (JSON)

{

  “FirstName”: {“isMandatory”: true, “minLength”: 1, “maxLength”: 50},

  “MiddleName”: {“isMandatory”: false, “minLength”: 0, “maxLength”: 50},

  “LastName”: {“isMandatory”: true, “minLength”: 1, “maxLength”: 50},

  “Email”: {“isMandatory”: true, “validation”: “email”},

  “Salutation”: {“isMandatory”: false, “allowedValues”: [“Mr”, “Ms”, “Mrs”, “Dr”]},

  “DateOfBirth”: {“isMandatory”: true, “validation”: “date”}

}

(JSON format is recommended due to its flexibility, but other storage formats such as YAML are possible.)

Clarifications #

• Authentication (login, logout, MFA, session management) is handled by the Auth Module.
• User roles management (assign/remove roles) is managed by the User Roles Module.
• Permissions and access rights are managed separately by the User Rights Module.
• User activity logging is captured by the Audit Log Module.
• Custom fields currently must be defined when building the module or directly in the DB schema post-deployment. No API is provided yet. API-based management is planned for future versions.