Tractian Challenge POC

Full Stack Development Project
Browse Back End code» - Browse Front End code»

Built With

Table of Contents

• Deployed Instances
• Installation and Usage
• Error Handling and Logging
  • AppError
  • AppLog
• Middlewares
• API Reference
  • Models
  • Routes
  • Authentication
  • Users
  • Companies
  • Units
  • Assets

Deployed Instances

• Server https://tractian-poc.herokuapp.com/
• Client https://tractian-poc.vercel.app/

Installation and Usage

Pre-requisites: Node.js ^16.14.0, TypeScript ^4.7.4

Download the zip file and extract it in the root of a new project folder by running these commands:

wget https://github.com/NivaldoFarias/tractian-challenge/archive/main.zip

Then run the following command to install the project's dependencies:

npm install

That's it! You can now start developing your TypeScript Project by running the command below. Happy coding!

npm run dev

Error Handling and Logging

While dealing with errors in a Layered Structure Project enviroment, you may notice that the project's debugging complexity scales beyond common console.log() usage. The AppLog Object and AppError Object structures were set to counter that exact issue, by trying to keep the Development process as clean and concise as possible. Both are frequently referenced in the code, but do have a specific usage.

▸   AppError

An AppError Object is used to handle errors in the application. It that takes four parameters:

• log: A string containing a simplified error message, for Server side use. This is the message that will be used by the AppLog Object
• statusCode: An integer containing the HTTP status code.
• message: A string containing a simplified error message, for Client side use. This is the message that will be displayed to the user.
• details: A string containing a detailed error message, for Client side use. Can be used to provide more information about the error, such as the stack trace, or suggestions on how to counter the error.

Example Usage

  // ..../middlewares/auth.middleware.ts

  import * as repository from './../repositories/auth.repository.ts';
  import AppError from './../events/AppError';
  ...
  ..

  async function usersExists(req: Request,...){
    ...
    ..
    const user = await repository.findbyId(req.body.id);

    if (!user){
      throw new AppError(
        'User not found',
        404,
        'User not found',
        'Ensure to provide a valid user ID.'
      );
    }
    ..
    ...
  }

▸   AppLog

An AppLog Object is used to handle logs in the application. It takes two parameters:

• type: A string containing the main Layer Structure that contains the log. There are seven allowed values: Error, Server, Controller, Middleware, Repository, Service, and Util.
• text: A descriptive string containing the log message. Generally, a short message that describes the output event of the function that generated the log.

Example Usage

  // ..../middlewares/auth.middleware.ts

  import AppLog from './events/AppLog';
  ...
  ..

  async function usersExists(req: Request,...){
    ...
    ..

    // output: [Middleware] User Found
    AppLog('Middleware', 'User found');
    res.locals.user = user;
    return next();
  }
  ..
  ...

Middlewares

While aiming to provide a reusable, modular and extensible architecture, the middlewares are generally the first structures to be refactored into self-contained modules. The validateSchema(), processHeader() and requireToken() middlewares were set in order to achieve that goal. The following section describes useMiddleware(), which incorporates the forementioned functions as key–value pairs in an Object, along with their structure and usage.

‣  UseMiddleware

The useMiddleware() function takes two parameters:

• middlewares: An Object containing the key–value pairs of the middlewares to be used, takes one to three parameters:
  • schema: A Joi Schema Object that will be used to validate the data provided by the client. If the data provided by the client is not valid, an AppError Object will be thrown.
  • header: A string containing the name of the header that will be used to authenticate the action. If the client-provided header is missing, an AppError Object will be thrown.
  • token: A boolean indicating whether the token provided by the client will be verified or not. If the token is not valid, an AppError Object will be thrown.
• endpoint: A string that will be used to identify the endpoint at which the client–api interaction is undergoing, which will be logged to console by the AppLog Object.

Reference: useMiddleware function declaration

Example Usage

// ..../routes/admin.route.ts
import useMiddleware from '../utils/middleware.util';
import * as schema from '../models/admin.model';
...
..
const endpoint = '/admin';

const registerEndpoint = '/create';
adminRouter.post(endpoint,
  createEndpoint,
  useMiddleware({
    schema: schema.create,
    header: 'admin-api-key',
    token: true
  },
  endpoint + createEndpoint),
  middleware.createValidations,
  controller.create,
);
..
...

API Reference

In this section, you will find the example API's endpoints and their respective descriptions, along with the request and response examples, as well as the MongoDB BSON types for each entity, that can be used as guide for data formatting. All data is sent and received as JSON.

Models

User model User

• _id: A unique identifier for each user. ObjectId
• full_name: The user's full name. String required max(100)
• username: The user's username. String required unique max(25)
• password: The user's password. String required max(50)
• last_update: The date and time when the user was last updated. Date
• created_at: The date and time when the user was created. Date

Company model Company

• _id: A unique identifier for each company. ObjectId
• name: The companys's name. String required unique max(100)
• units: An array containing the company's units. Unit[]
• users: An array containing the company's users. User[]
• x-api-key: The company's API key. String required
• last_update: The date and time when the company was last updated. Date
• created_at: The date and time when the company was created. Date

Unit model Unit

• _id: A unique identifier for each unit. ObjectId
• name: The units's name. String required unique max(50)
• street: The unit's street. String max(100)
• number: The unit's number. String max(10)
• city: The unit's city. String required max(50)
• state: The unit's state. String required max(50)
• postal_code: The unit's postal code. String max(20)
• assets: An array containing the unit's assets. Asset[]
• opens_at: The date and time when the unit opens. String required length(5)
• closes_at: The date and time when the unit closes. String required length(5)
• last_update: The date and time when the unit was last updated. Date
• created_at: The date and time when the unit was created. Date

Asset model Asset

• _id: A unique identifier for each asset. ObjectId
• name: The assets's name. String required max(50)
• description: The assets's description. String
• model: The assets's model. String required max(100)
• owner: The assets owner's user. User required
• image: The assets's image URL. String
• status: The assets's status. String required enum('RUNNING', 'ALERTING', 'STOPPED')
• health: The assets's healthscore. Number required min(0) max(100)
• last_update: The date and time when the asset was last updated. Date
• created_at: The date and time when the asset was created. Date

Routes

Authentication /auth

• Sign In
• Sign Out token

Users /users

• Create x-api-key
• Search All Users token
• Search by Id token
• Update token x-api-key
• Delete token x-api-key

Companies /companies

• Create x-api-key
• Search All Companies token
• Search by Id token
• Update token x-api-key
• Delete token x-api-key

Units /units

• Create token x-api-key
• Search All Units token
• Search by Id token
• Update token x-api-key
• Delete token x-api-key

Assets /assets

• Create token x-api-key
• Search All Assets token
• Search by Id token
• Update token x-api-key
• Delete token x-api-key

Authentication

  ‣   Sign in

    POST /auth/sign-in

  ☰   Request

Body

{
  "username": "JohnDoe",
  "password": "123456789"
}

Headers

{
  "Content-Type": "application/json"
}

  ☰   Responses

  ‣   Sign out

    POST /auth/sign-out

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "token": "server-generated-token"
}

  ☰   Responses

Users

  ‣   Create an User

    POST /users/create

  ☰   Request

Body

{
  "full_name": "John Doe Junior the Third",
  "username": "JohnDoe",
  "password": "123456789",
  "company": "5f9f1b9f9d1b9d1b9f1b9d1b"
}

Headers

{
  "Content-Type": "application/json",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

  ‣   Search all Users

    GET /users/all

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

Query Parameters

  ☰   Responses

  ‣   Search User by id

    GET /users/:id

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

  ☰   Responses

  ‣   Update an User

    PUT /users/:id/update

  ☰   Request

Body

{
  "full_name": "John Doe Junior the Second",
  "username": "JohnDoe"
}

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

  ‣   Delete an User

    DELETE /users/:id/delete

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>".
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

Companies

  ‣   Create a Company

    POST /companies/create

  ☰   Request

Body

{
  "name": "Acme Inc."
}

Headers

{
  "Content-Type": "application/json",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

  ‣   Search all Companies

    GET /companies/all

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

Query Parameters

  ☰   Responses

  ‣   Search Company by id

    GET /companies/:id

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

  ☰   Responses

  ‣   Update a Company

    PUT /companies/:id/update

  ☰   Request

Body

{
  "name": "Acme Inc. 2"
}

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

  ‣   Delete a Company

    DELETE /companies/:id/delete

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

Units

  ‣   Create an Unit

    POST /units/create

  ☰   Request

Body

{
  "name": "Acme Inc. - Unit 1",
  "description": "Lorem Ipsum Dolor Sit Amet, Consectetur Adipiscing Elit.",
  "city": "New York",
  "state": "NY",
  "opens_at": "08:00",
  "closes_at": "18:00",
  "company": "5f9f1b9f9d1b9d1b9f1b9d1b"
}

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

  ‣   Search all Units

    GET /units/all

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

Query Parameters

  ☰   Responses

  ‣   Search Unit by id

    GET /units/:id

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

  ☰   Responses

  ‣   Update an Unit

    PUT /units/:id/update

  ☰   Request

Body

{
  "name": "Acme Inc. - Unit 1",
  "description": "Now at a new location!",
  "address": "Main Street",
  "number": "123",
  "city": "New York",
  "state": "NY",
  "postal_code": "12345",
  "opens_at": "08:00",
  "closes_at": "18:00"
}

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

  ‣   Delete an Unit

    DELETE /units/:id/delete

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

Assets

  ‣   Create an Asset

    POST /assets/create

  ☰   Request

Body

{
  "name": "Assembly Machine",
  "description": "This is a machine for assembly",
  "model": "AM-123",
  "owner": "7f9f1b9f9d1b9d1b9f1b9342",
  "image": "https://www.example.com/image.jpg",
  "status": "STOPPED",
  "health": 94
}

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

  ‣   Search all Assets

    GET /assets/all

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

Query Parameters

  ☰   Responses

  ‣   Search Asset by id

    GET /assets/:id

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

  ☰   Responses

  ‣   Update an Asset

    PUT /assets/:id/update

  ☰   Request

Body

{
  "name": "Assembly Machine - Now with more assembly",
  "description": "This is a machine for assembly, but now we use the Assembly programming language",
  "model": "AM-123",
  "status": "RUNNING",
  "health": 81
}

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses

  ‣   Delete an Asset

    DELETE /assets/:id/delete

  ☰   Request

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>",
  "x-api-key": "extremely-secure-hash-key"
}

  ☰   Responses