This is how we document the modules.

1 User Journeys #

1.1 Definition #

A User Journey is a detailed narrative that outlines the steps a user (or an internal/external system) takes to accomplish a specific goal within a software application. It captures not only the primary flow of actions but also alternative paths, error handling, and postconditions, ensuring all stakeholders have a clear understanding of the required interactions and outcomes.

1.2 Description #

This is how we describe user journeys. The headings below are mandatory (the exact word(s) have to be used).

Heading	Description	Naming Convention
Name	A concise, descriptive name (e.g., “Create Admin”).	User Journeys should follow the camelCase format, starting with a verb (action) like get, create, or update, followed by a PascalCase entity (e.g., User, Admin) and an optional detail for clarity (e.g., List, ByEmail). For example, getUserList retrieves multiple users, while getUserByEmail fetches a specific user by email. Keep names concise, action-driven, and logical, using singular for specific items (getUserById) and plural for collections (listActiveUsers).
Overview	A brief summary of what the user journey intends to achieve.	[EMPTY CELL]
Actors	List all participants (users, systems, or external entities) involved in the journey.	[EMPTY CELL]
Preconditions	Clearly state what conditions must be met before the journey can begin (e.g., valid Authentication, required data provided).	[EMPTY CELL]
Flow	Primary Flow: The main sequence of steps or actions taken by the user/system and alternative/Exception Flows: Any alternate paths or error conditions, detailing how deviations from the primary flow are handled.	[EMPTY CELL]
Outcome	Define what a successful completion looks like (e.g., a new admin is created and a success response is returned).	[EMPTY CELL]
Error Handling	Describe how errors are managed, including any error responses and triggering of corresponding webhooks or notifications.	[EMPTY CELL]
Postconditions	Summarize the state of the system after the journey is executed, both in success and error scenarios.	[EMPTY CELL]
Triggers	Include any side effects such as webhooks or events that are triggered as part of the process.	[EMPTY CELL]
Notes	Note any specific business rules, security measures, or performance considerations relevant to the journey.	[EMPTY CELL]

2 Schema #

2.1 Definition #

Schema refers to the structured set of information or attributes that a module is responsible for persisting. It defines the key fields, their types, and the business-relevant details that must be maintained for the module to function correctly.

Note that the Schema is a recommendation. The NovaFacies Open Source Framework do not mandate how data is stored. The recommendation is that the implementation have these schemas, since it enables the implementation to be done much faster.

2.2 Description #

Functions are to be described in a table with these headings (see below for definitions). A module can have several schemas.

Example

Name	Type	Internal Name	Description
xxxxx	xxxxx	xxxxx	xxxxx

Definitions

Name	Description	Naming Convention
Name	The unique identifier for each piece of data.	Fields should use snake_case (lowercase_with_underscores), with clear prefixes when needed (e.g., user_id, account_balance). Primary keys should follow the format table_id (e.g., user_id), and foreign keys should match their referenced primary key (user_id in orders referencing users.id). Use is_ or has_ for booleans (is_active), and standard timestamps (created_at, updated_at, deleted_at). Keep names consistent, descriptive, and concise to ensure clarity and maintainability.
Type	The format of the data (e.g., string, number, UUID, JSON), which ensures proper handling and validation.	[EMPTY CELL]
Internal Name	The internal field name that is used as a reference internally to point to this field.	Merge name of the module with the name if the schema and the name of the row. For example: module.Schema.RowName
Description	A clear explanation of what the data represents and its role within the module.	[EMPTY CELL]

3 Functions #

3.1 Definition #

A Function is a discrete, callable unit of functionality within a module that encapsulates a specific operation or business logic. It represents a defined contract in the system, outlining how a particular task is to be executed through an API or internal process.

3.2 Descriptions #

Functions are to be described in a table with these headings (see below for definitions).

Example

Name	Endpoint	Description	Internal Name	Input	Response
XXXX	XXXX	XXXX	XXXX	XXXX	XXXX

Definitions

Heading	Description	Naming Convention
Name	A clear and descriptive identifier for the function, which serves as a recommendation for developers.	Functions should follow the camelCase format, starting with a verb (action) like get, create, or update, followed by a PascalCase entity (e.g., User, Admin) and an optional detail for clarity (e.g., List, ByEmail). For example, getUserList retrieves multiple users, while getUserByEmail fetches a specific user by email. Keep names concise, action-driven, and logical, using singular for specific items (getUserById) and plural for collections (listActiveUsers).
Endpoint	The specific API route (e.g., POST /admins/create) where the function can be accessed, marked as a strict requirement.	[EMPTY CELL]
Description	A narrative explanation of what the function does, outlining its purpose within the module.	[EMPTY CELL]
Internal Name	The identifier used internally by the system to refer to this function, which may differ from the Name.	Merge name of the module with the name if the function. For example: module.FunctionName
Input	The required data payload and its structure, defined as a strict requirement to ensure that the function receives all necessary information.	[EMPTY CELL]
Response	The expected output or result when the function is invoked, including success responses and error handling paths.	[EMPTY CELL]

4 Webhooks #

4.1 Definition #

A Webhook is an automated HTTP callback mechanism that is triggered by specific events within the system, sending real-time data to a designated external or internal endpoint.

4.2 Descriptions #

Webhooks are to be described in a table with these headings (see below for definitions).

Example

Name	Trigger	Destination	Payload	Description	Error Handling
xxxxx	xxxxx	xxxxx	xxxxx	xxxxx	xxxxx

Definitions

Heading	Description	Naming Convention
Name	The name of the event.	Webhooks should follow the camelCase format, starting with a verb (action) like get, create, or update, followed by a PascalCase entity (e.g., User, Admin) and an optional detail for clarity (e.g., List, ByEmail). For example, getUserList retrieves multiple users, while getUserByEmail fetches a specific user by email. Keep names concise, action-driven, and logical, using singular for specific items (getUserById) and plural for collections (listActiveUsers).
Trigger	Specifies the event or condition that activates the webhook (e.g., when a new admin is created or an error occurs).	[EMPTY CELL]
Destination	The URL or system endpoint where the payload is delivered.	[EMPTY CELL]
Payload	The data, typically in JSON format, that the webhook sends, containing relevant details about the event.	[EMPTY CELL]
Description	A narrative explanation of the webhook”s purpose, detailing its role in the overall system communication and any additional operational context.	[EMPTY CELL]
Error Handling	Outlines how errors during the webhook process are managed, such as retry mechanisms or logging procedures.	[EMPTY CELL]

5 Modules #

The Descriptions of the Modules will be as follows:

5.1 Description of Module Type “Standard” #

This is how we describe a module of type Standard. When something is required, this is clearly stated.

• Name
• Version number
• Module Type
• Internal Name (A name that can be used internally to reference to this module)
• Status (Incomplete or Complete, if Complete, no more changes will be done for this module)
• Description (High level description of the module)
• User Journeys (Describes User Journeys for this module, note that this is not only for physical persons, a User Journey can be something triggered with another module)
• Authentication (Describe how the user auth against the module to see his/her information and how an admin can auth and see all information)
• Schema (The data that the module need to store, how the data is stored is not a requirement, but recommendations can be given)
• Functions
  • Name of function (The name is a recommendation, but the function needs to exist and behave as described)
  • Endpoint (Strict requirement)
  • Description (Description of the function)
  • Internal Function Name (Name of the function that is being used internally by the system, for example for Rights for Admins and Users).
  • Input (Strict requirement)
  • Response (Strict requirement)
• Webhooks (Describes the webhooks for this module)
• Settings (For configuration management)
• Clarifications (For special considerations)

5.2 Description of Module Type “Non-Standard” #

Non-Standard modules are those that do not follow the default implementation pattern of the framework. These modules often integrate with external services, provide specialized functionalities, or require unique Authentication mechanisms. Examples include the Auth Module, which relies on external identity providers such as Keycloak, and future modules that may handle Blockchain-based transactions. These modules can be described in many different ways and there is no set standard for it.