G6Flow® - BEI Development Framework

Introduction

This documentation provides a guide to developing new BEIs (Backend Integrators) using the base skeletons. It details the essential components, project structure, and development recommendations.

Component Name

G6Flow® - BackEnd Integrator

General Description

G6Flow® is a solution entirely developed by Global SEIS, aimed at simplifying enterprise architectures and accelerating the deployment of BACKENDS, from integration with data sources to web service exposure in API Rest format, leveraging the documentation and availability of services for development areas and strategic partners.

Base Skeletons

The base skeletons include the following components:

• Fastify Server: Server configuration using Fastify.
• APIKeys Validator: Module for validating API keys of incoming requests.
• Configuration Service: Management and storage of system configurations.
• Metadata Service: Management of metadata related to database tables.
• Routes File (routes): Definition of API routes and supported HTTP methods.
• CRUD Methods: Functions to handle Get, GetById, Post, Put, Delete operations.

Creating a New BEI

When developing a new BEI, you can choose to:

• Create from scratch: Build a new BEI entirely from scratch and adapt it to a new database table.
• Adapt an existing one: Use an existing BEI as a template and configure it for a new table.

---

Technical Details

G6Flow® uses the following technologies and dependencies:

• Node.js: Runtime environment for the backend server.
• Fastify: Fast and low-overhead web framework used to handle HTTP requests.
• Database: Adaptable to different database systems.
• Libraries and Modules:
• dotenv: Module for managing environment variables.
• fastify: Main framework for the web server.
• Specific library for the database (e.g., mysql, pg, mssql, etc.).

Connection Pool Configuration

The connection-pool.js file handles the configuration of the database connection. Below is an example of a general configuration:

const databaseLibrary = require("your-database-library"); // Replace with the specific database library

const poolPromise = new databaseLibrary.ConnectionPool(config)
  .connect()
  .then((pool) => {
    //Your code HERE!!
    console.log("Connected to the database");
    return pool;
  })
  .catch((err) => console.log("Database Connection Failed! Bad Config: ", err));

module.exports = { databaseLibrary, poolPromise };

To change the configuration to a new database, update the values in the environment variables and ensure that the new database is correctly configured in config.

CRUD Methods

Each CRUD method has its own handler file. Below are the components and logic for each one:

Get Method (get-handler.js)

Retrieves all records from a specific table.

const { databaseLibrary, poolPromise } = require("./connection-pool");

module.exports = async (req, reply) => {
  try {
    //Your code HERE!!
    reply.send(result.recordset);
  } catch (err) {
    reply.status(500).send({ message: err.message });
  }
};

GetById Method (getById-handler.js)

Retrieves a specific record by its ID.

const { databaseLibrary, poolPromise } = require("./connection-pool");

module.exports = async (req, reply) => {
  try {
    //Your code HERE!!
  } catch (err) {
    reply.status(500).send({ message: err.message });
  }
};

Post Method (post-handler.js)

Creates a new record in the table.

const { databaseLibrary, poolPromise } = require("./connection-pool");

module.exports = async (req, reply) => {
  try {
    //Your code HERE!!
    reply.send({ message: "Record inserted successfully" });
  } catch (err) {
    reply.status(500).send({ message: err.message });
  }
};

Put Method (put-handler.js)

Updates an existing record.

const { databaseLibrary, poolPromise } = require("./connection-pool");

module.exports = async (req, reply) => {
  try {
    //Your code HERE!!
    reply.send({ message: "Record updated successfully" });
  } catch (err) {
    reply.status(500).send({ message: err.message });
  }
};

Delete Method (delete-handler.js)

Deletes a specific record.

const { databaseLibrary, poolPromise } = require("./connection-pool");

module.exports = async (req, reply) => {
  try {
    //Your code HERE!!
    reply.send({ message: "Record deleted successfully" });
  } catch (err) {
    reply.status(500).send({ message: err.message });
  }
};

---

Component Objective

Main Purpose

The main purpose of the G6Flow® - BackEnd Integrator component is to provide a standard and reusable template for building APIs that interact with databases. This component facilitates the rapid and consistent implementation of new endpoints, allowing developers to focus on business logic rather than infrastructure.

Key Benefits

• API Structure Standardization: By providing a base skeleton, it ensures a uniform and consistent structure across all developed APIs, making maintenance and code understanding easier.
• Development Time Reduction: The reuse of predefined components and configurations allows developers to accelerate the process of creating and deploying new APIs.
• Facilitates Integration with Various Databases: The base configuration and provided examples are designed to be adaptable to different database systems, simplifying connection and data management.
• Built-in Security: Includes modules for validating API keys, ensuring that only authorized users can access resources.

Scope and Limitations

Scope

• Basic CRUD APIs: Supports basic operations for creating, reading, updating, and deleting records in the database.
• APIKey Authentication: Validates incoming requests using API keys to secure access.
• Configuration Management: Allows centralization and dynamic modification of system configurations.
• Metadata Management: Facilitates understanding and manipulation of stored data by managing metadata.

Limitations

• Focus on Database Flexibility: The component is designed to be adaptable to various databases but requires specific configuration for each system.
• Version Compatibility: Ensure that the versions of Node.js, Fastify, and the database library used are compatible and aligned with project specifications.
• Extension of Functionality: Any additional functionality beyond basic CRUD operations and configuration/metadata management should be implemented and documented separately.

---

Development Recommendations

Best Practices

• Folder Structure: Maintain a clear separation between controllers, models, and services.

• Database Connection Management: It is good practice to manage database connections in a centralized file like connection-pool.js. This ensures proper handling of connections, making sure they are opened and closed correctly. Centralizing the connection logic also facilitates code reuse and maintenance.

• Opening and Closing Connections: Make sure to open connections before executing any operation on the database and to close them immediately after the operation has concluded. This prevents potential connection leaks and ensures the stability and efficiency of the application.

• Data Validation: Use Fastify schemas for request validation.

• Error Handling: Implement global error handlers.

Security Considerations

• APIKeys: Store and validate API keys securely.
• User Input: Sanitize all inputs to prevent SQL injections.

Testing and Validation

• Unit Tests: Implement tests for each controller using a test database.
• Integration Tests: Test the integration with the database and proper transaction management.

Maintenance and Updates

• Version Control: Use Git for code versioning.
• Continuous Documentation: Keep documentation updated with every new feature or significant change.

---

Requirements and Form Factor

Technical Requirements

• Platform: Node.js 14+
• Database: Adaptable to various database systems (e.g., MySQL, PostgreSQL, MSSQL).
• Libraries:
• fastify
• dotenv (for environment variable management)
• Specific library for the database (e.g., mysql, pg, mssql).

Environment Configuration

• Environment Variables:
• DB_USER: Database user
• DB_PASSWORD: Database password
• DB_HOST: Database host
• DB_NAME: Database name
• API_KEY: Key for request authentication

Dependencies

• Node.js: Required to run the server and frontend.
• Docker: Used for containerization and deployment (optional based on project needs).

Format and Compatibility

• API Response Format: JSON
• Browser Compatibility: For the frontend, it should be compatible with modern browsers.

---

Here is a table describing each main file in a BEI (Backend Integrator) skeleton and its central function. This table can be used to document and explain the project structure to developers.

---

Project Structure

File Path	Central Point	Description / Main Function
/index.js	Main server entry point	Initializes the Fastify server, loads necessary plugins, and starts listening on the specified port.
/routes/index.js	Route definition	Centralizes the API route definitions, linking each route to its corresponding controller.
/controllers/	Business logic controllers	Contains files for each CRUD controller (get-handler.js, post-handler.js, etc.), handling business logic and interaction with the database.
/config/config.js	General configuration	Manages the application's general configuration, including environment variables, and other global parameters.
/config/connection-pool.js	Database connection management	Centralizes the database connection configuration, handling the opening and closing of connections.
/middlewares/	Validation and security middleware	Contains middlewares for APIKey validation, authentication, and other security functions.
/services/metadata.js	Metadata management service	Provides functions to manage metadata related to database tables.
/services/configuration.js	Configuration management service	Manages application configurations, allowing access and modification from a single point.
/middlewares/apiKeyValidator.js	API Key Validator	Verifies that incoming requests contain a valid API key before processing them.
/test/	Unit and integration tests	Contains unit and integration tests to verify the functionality of each BEI module.

---