Version #

Version 1

Module Type #

Standard

Internal Name #

admins

Status #

Draft

Description #

The Admins Module provides basic administrative user functionality. It allows for the creation of new admin users and retrieval of admin details. Each admin must have a unique email and is automatically assigned the Standard Admin role upon creation.

The first admin user must be created manually (e.g., via a setup script or direct database entry).

The Module have basic error handling.

User Journeys #

createAdmin #

Name

createAdmin

Overview

This user journey outlines the process for an existing admin to create a new admin account in the system.

Actors

– Existing Admin (initiator)

– Admin Module (system)

– Auth Module (for Authentication)

Preconditions

– The existing admin must be authenticated via the Auth Module (valid JWT Token required).

– Required admin data (e.g., FirstName, LastName, Email) must be provided.

Flow

Primary Flow:

1. The existing admin sends a POST request to the /admins/create endpoint with the new admin’s details.

2. The Admin Module validates the input data.

3. The system registers the new admin and automatically assigns the “Standard Admin” role.

4. The new admin’s details are returned in the response.

Alternative/Exception Flows:

– If input validation fails, the system returns an error response.

– If there is an internal error during registration, the creation process is aborted.

Outcome

A new admin account is successfully created and assigned the Standard Admin role.

Error Handling

– On error, the system returns a response indicating {“status”: “Error”}.

– An error webhook (adminError) is triggered with details such as the endpoint, error message, and timestamp.

Postconditions

– On success, the new admin is added to the system and can log in using their credentials.

– On error, no new admin is created, and the error is logged for debugging.

Triggers

– Success: The adminCreated webhook is triggered, sending details of the newly created admin.

– Error: The adminError webhook is triggered.

Notes

– This journey assumes that the first admin is pre-created manually.

– The system performs additional validations (e.g., duplicate email check) before creation.

logInAdmin #

Name

logInAdmin

Overview

This user journey details how an admin logs in by authenticating through the external Auth Module and retrieves their account details from the Admin Module.

Actors

– Admin User (initiator)

– Auth Module (handles Authentication)

– Admin Module (retrieves admin details)

Preconditions

– The admin must already exist in the system.

– The Auth Module must be operational to validate credentials.

– The admin must provide valid login credentials.

Flow

Primary Flow:

1. The admin submits their login credentials to the Auth Module.

2. The Auth Module validates the credentials and issues a JWT access Token.

3. The admin uses the JWT Token to send a POST request to the /admins/get endpoint in the Admin Module.

4. The Admin Module retrieves and returns the admin’s account details.

Alternative/Exception Flows:

– If the Auth Module fails to validate the credentials, an error response is returned.

– If the retrieval of admin details fails in the Admin Module, an error response is returned.

Outcome

The admin successfully logs in, receives a valid access Token, and their account details are returned.

Error Handling

– On error, the system returns a response indicating {“status”: “Error”}.

– An error webhook (adminError) is triggered with relevant details such as the endpoint, error message, and timestamp.

Postconditions

– On success, the admin is authenticated and can interact with other modules using the valid Token.

– On error, the admin remains unauthenticated and no account details are returned.

Triggers

– Success: The adminInfoRetrieved webhook is triggered, sending details of the admin account.

– Error: The adminError webhook is triggered.

Notes

– Authentication is delegated to the external Auth Module; the Admin Module only retrieves account details using the issued Token.

– Sensitive error information is securely logged without exposing details to the end user.

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 #

Admins #

Name	Type	Internal Name	Description
admin_id	String	admins.admins.admin_id	UUID
email	String	admins.admins.email	Admin”s unique email address
first_name	String	admins.admins.first_name	Admin”s first name
last_name	String	admins.admins.last_name	Admin”s last name

Functions #

Name	Endpoint	Description	Internal Name	Input	Response
createAdmin	/admins/create	Creates a new admin and registers them in the Auth Module. Sets the Admin Role = Standard.	admins.createAdmin	{ “first_name”: “Alice”, “last_name       “: “Smith”, “email”: “[email protected]” }	{ “status”: “success”, “admin_id”: “admin-001” }or{ “status”: “error” }
getAdmin	/admins/get	Retrieves admin details	admins.getAdmin	{ “admin_id”: “admin-001” }	{ “admin_id”: “admin-001”, “first_name”: “Alice”, “email”: “[email protected]” }or{ “status”: “error” }

Webhooks #

Name	Trigger	Destination	Payload	Description	Error Handling
adminCreated	When a new admin is created.	Log Module	{  “event”: “adminCreated”,  “timestamp”: “2025-03-13T12:00:00Z”,  “admin”: {    “AdminID”: “admin-001”,    “FirstName”: “Alice”,    “LastName”: “Smith”,    “Email”: “[email protected]”  }}	Send a webhook to the Log Module about this event.	None
adminInfoRetrieved	When an admin retrieves their own information.	Log Module	{  “event”: “adminInfoRetrieved”,  “timestamp”: “2025-03-13T12:15:00Z”,  “admin”: {    “AdminID”: “admin-001”,    “RequestedBy”: “admin-001”  }}	Send a webhook to the Log Module about this event.	None
adminError	Triggered when an error occurs in any Admin module operation.	Log Module	{  “event”: “adminError”,  “timestamp”: “2025-03-13T12:00:00Z”,  “error”: “Error message details”,  “endpoint”: “/admins/create”}	Send a webhook to the Log Module about this event.	None

Settings #

Not applicable

Clarifications #

• This module is intentionally minimal for Version 1; only essential fields are stored.
• Future versions may expand the admin profile with additional fields if needed.
• All operations require prior Authentication via the Auth module.
• For this version, the webhooks can be hardcoded to reach the Log Module, in later versions, this will be managed in Settings.
• Version one does not support Custom Fields.