MeLi-Clean-Architecture

This project is designed to provide a clean architecture for the MeLi API.

Prerequisites

• Node.js 20.0.0 or above

Run Locally

1. Clone the project

git clone https://github.com/mau-io/meli-clean-architecture.git

2. Go to the project directory

cd meli-clean-architecture

3. Install dependencies

npm install

4. Start the server

npm run start

Environment Variables

This project uses Node.js and Express.js. To run this project, you will need to add the following environment variables:

• PROJECT_NAME: The name of the project
• ENVIRONMENT: The environment where the server is running. It could be 'development' or 'production'
• PROJECT_VERSION: The current version of the project
• SERVER_HOSTNAME: The hostname of the server
• SERVER_PORT: The port where the server will listening
• MELI_SERVICE_URL: The URL of the Mercado Libre API service
• MELI_SERVICE_TOKEN: The token for the Mercado Libre API service
• MELI_SERVICE_FAKE_TOKEN: This is a mock token for the Mercado Libre API service. When this token is used, actual requests to the Mercado Libre API will not be made. Instead, mocked data will be returned.
• MELI_SERVICE_TIMEOUT: The timeout setting for the Mercado Libre API service
• MELI_SERVICE_ITEMS_CACHE_TTL: The time-to-live setting for the Mercado Libre API items cache
• MELI_SERVICE_SEARCH_CACHE_TTL: The time-to-live setting for the Mercado Libre API search cache

You can add these variables in a .env file at the root of your project:

PROJECT_NAME=MeLi
ENVIRONMENT=development
PROJECT_VERSION=0.0.0
SERVER_HOSTNAME=localhost
SERVER_PORT=3030
MELI_SERVICE_URL=https://api.mercadolibre.com
MELI_SERVICE_TOKEN=xxxxx
MELI_SERVICE_FAKE_TOKEN=xxxxx
MELI_SERVICE_TIMEOUT=3500
MELI_SERVICE_ITEMS_CACHE_TTL=20000
MELI_SERVICE_SEARCH_CACHE_TTL=5000

Installation

To install this project follow these steps:

1. Clone the repository

git clone https://github.com/mau-io/meli-clean-architecture.git

2. Install the dependencies

npm install

3. Start the project

npm run start

Available Scripts

In the project directory, you can run:

npm run start

Starts the application in the development mode.
Open http://localhost:3030 to view it in the browser.

npm run watch

This script is used to start the server and watch for any changes in the 'src' directory. The server will automatically restart whenever changes are detected.

npm run test

This script is used to start the Jest test runner.

npm run eslint

This script is used to run ESLint which is a static code analysis tool for identifying problematic patterns found in JavaScript code. It's used for checking the code for readability, maintainability, and functionality errors.

npm run docs

This script is used to generate documentation for the project using JSDoc.

API Reference

Overview

This API provides functionality to interact with the Mercado Libre marketplace. With this API, you can search for items and get item details. It provides endpoints to perform these operations.

Endpoints

Search Items

GET /api/v1/search (Performs a search for items in a specific Mercado Libre site)

Parameters

name	type	data type	description
query	required	string	The search term
site	required	string	The Mercado Libre site for the search.
sort	optional	string	The sorting order.
limit	optional	number	The maximum number of results to return.
offset	optional	number	The number of results to skip before starting to return results.

Responses

http code	content-type	response
200	application/json

{
  "paging": {
    "total": Number,
    "offset": Number,
    "limit": Number
  },
  "categories": [String, ...],
  "items": [
    {
      "id": String,
      "title": String,
      "price": {
        "currency": String,
        "amount": Number,
        "decimals": Number
      },
      "picture": String,
      "condition": String,
      "free_shipping": Boolean
    },
    ...
  ]
}
``` |

Example cURL

 curl -X GET -H "Content-Type: application/json" -H "x-auth-token: your_token" "http://localhost:3030/api/v1/search?query=iphone&site=MLA"

Get Item

GET /api/v1/items/:id (Fetches details of a specific item)

Parameters

name	type	data type	description
id	required	string	The Mercado Libre item Id.

Responses

http code	content-type	response
200	application/json

{
  "author": {
    "name": String,
    "lastname": String
  },
  "item": {
    "id": String,
    "title": String,
    "price": {
      "currency": String,
      "amount": Number,
      "decimals": Number
    },
    "picture": String,
    "condition": String,
    "free_shipping": Boolean,
    "sold_quantity": Number,
    "description": String
  }
}
``` |

Example cURL

 curl -X GET -H "Content-Type: application/json" -H "x-auth-token: your_token" "http://localhost:3030/api/v1/items/MLA816019440"

Sequence diagram

sequenceDiagram
    participant Client
    participant ExpressController
    participant AppController
    participant UseCase
    participant DataRepository
    participant HttpClient

    Client->>ExpressController: API Request (Client makes an API request to the server)
    ExpressController->>AppController: forwardRequest() (ExpressController forwards the request to AppController)
    AppController->>UseCase: execute() (AppController executes the corresponding use case)
    UseCase->>DataRepository: read() (UseCase asks for data from the repository)
    DataRepository->>HttpClient: fetch() (DataRepository uses HttpClient to get data)
    HttpClient-->>DataRepository: HTTP Response (HttpClient returns the HTTP response)
    DataRepository-->>UseCase: Data (DataRepository provides the fetched data to UseCase)
    UseCase-->>AppController: Data (UseCase returns the data to AppController)
    AppController-->>ExpressController: Response Data (AppController provides the response data to ExpressController)
    ExpressController-->>Client: API Response (ExpressController sends the API response back to the client)

Diagram live

Documentation

This project uses JSDoc to generate its documentation. The documentation will include details about all the JavaScript files found in the ./src directory.

Generating the Documentation

To generate the documentation, we use the following command:

npm run docs

Viewing the Documentation

After running the command, the generated documentation will be available in the ./docs/ directory. You can open the index.html file in your browser to view the documentation.

MeLi Application Docker Tutorial

This tutorial will walk you through the two basic Docker commands: docker build and docker run.

Docker Build

The Docker build command is used to build Docker images from a Dockerfile and a context. The context is the set of files in the directory specified in the command, or in this case, the current directory (designated by the dot).

docker build -t app-meli .

Breaking down this command, -t app-meli is used to tag the image with the name app-meli, and . specifies that the Dockerfile is in the current directory.

After running this command, you'll have a Docker image named app-meli that's ready to run.

Docker Run

The Docker run command is used to create a container from a Docker image and start the container.

docker run -p 3030:3030 --env-file .env app-meli

In this command, -p 3030:3030 maps the host's port 3030 to the container's port 3030. This is essential for accessing web services running on the container. Following that, app-meli specifies the image to create the container from.

Once this command is executed, your application will be running in a Docker container and can be accessed at http://localhost:3030.

Kubernetes Deployment

Once you have your Docker image, you can deploy your application to Kubernetes.

Before applying the deployment, you need to create a ConfigMap from your .env file. You can do this using the following commands:

kubectl create configmap my-config-map --from-env-file=.env

Confirm that the ConfigMap has been successfully created:

kubectl get configmaps my-config-map -o yaml

The Kubernetes manifest can then be applied with:

kubectl apply -f deployment.yaml

To monitor the running Pods, the following commands can be used:

kubectl get pods
kubectl get deployments
kubectl get services

In case the Pods need to be deleted, use:

kubectl delete service my-app
kubectl delete deployment my-app

Now you can access your application through the LoadBalancer on your local machine at http://localhost:3030.

Authors

• @mau-io

License

MIT