Partner Sync

The Partner Sync project aims to streamline the updating of internal partner data. By allowing bulk updates through CSV file uploads, we can reduce the time and effort spent on manual data entry, enhancing overall efficiency.

Table of Contents

• Technologies Used
• Getting Started
  • Running with Docker
  • Running locally with ASDF
• API Endpoints
• Libraries Used
• Code Quality
• Tests and Coverage Report

Technologies Used

• Elixir 1.14.2
• Phoenix 1.6.15
• Erlang 25.1.2
• PostgreSQL 14

Getting Started

There are two ways to run the application: using Docker or running it locally with ASDF.

Running with Docker

1- Download and install Docker: https://docs.docker.com/get-docker/

2- Once the installation is complete, verify that Docker is running. Open your preferred terminal and execute the commands below:

$ docker -v
# Docker version 20.10.21, build baeda1f

$ docker-compose -v
# docker-compose version 1.29.2, build unknown

If the version information appear, you're ready to proceed. If not, you'll need to install Docker using an alternative method. Below are some commands for different operating systems:

macOS:
$ brew update
$ brew install docker && brew install docker-compose

Linux (Ubuntu):
$ sudo apt-get update
$ sudo apt-get install docker docker-compose

3- In the terminal, with Docker running, navigate to the project root directory:

$ cd ~/partner_sync/

4- Run the command below to start the application and wait for it to initialize:

$ docker-compose up --build

5- That's it! The application is now accessible at the following URL: http://localhost:4000/

Running locally with ASDF

1- Download and install ASDF: https://asdf-vm.com/guide/getting-started.html

2- Once the installation is complete, verify that ASDF is running. Open your preferred terminal and execute the command below:

$ asdf --version
# v0.10.2-7e7a1fa

If the command above didn't work, check if the asdf command is present in your system's environment variables.

3- In the terminal, navigate to the project root directory:

$ cd ~/partner_sync/

4- Add the plugins for Erlang and Elixir by following the provided instructions.

Warning

Please read the README files of these 2 repositories carefully! There are dependencies that need to be installed, which vary depending on the operating system.

Run the commands below:

$ asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
$ asdf plugin add elixir https://github.com/asdf-vm/asdf-elixir.git

5- Install the versions of Erlang and Elixir using the commands below:

$ asdf install erlang 25.1.2
$ asdf install elixir 1.14.2

6- To verify that both have been installed, use the following command:

$ asdf current
# elixir          1.14.2          /path/partner_sync/.tool-versions
# erlang          25.1.2          /path/partner_sync/.tool-versions

Now that ASDF is properly configured, the next step is to install the database.

7- Download and install PostgreSQL 14: https://www.postgresql.org/download/ or use one of the commands below:

macOS:
$ brew install postgresql

Linux (Ubuntu):
$ sudo apt-get install postgresql

Tip

You can also use ASDF to install PostgreSQL 14:

$ asdf plugin add postgres https://github.com/smashedtoatoms/asdf-postgres.git
$ asdf install postgres 14.6
$ asdf global postgres 14.6

8- Configure the database username and password by following this tutorial. The default value are both postgres.

9- Your environment is ready to run the application. To get started, execute the following commands in the project directory:

$ mix deps.get # Installs the project's dependencies
$ mix ecto.setup # Creates the project's database
$ mix phx.server # Starts the Phoenix Endpoint (without debug)
$ iex -S mix phx.server # Starts the Phoenix Endpoint with debugging

10- That's it! The application is now accessible at the following URL: http://localhost:4000/

API Endpoints

Method	Endpoint	Description	Parameters / Body
GET	/api/v1/addresses	Lists all addresses
GET	/api/v1/addresses/:cep	Shows an address by ZIP Code
GET	/api/v1/partners	Lists all partners
GET	/api/v1/partners/:cnpj	Shows a partner by CNPJ
POST	/api/v1/partners	Imports a CSV file (See template) and inserts/updates each valid record	csv (file)
GET	/dev/mailbox	Provides access to the default email interface for viewing emails sent during development

Note

To set up the request POST - /api/v1/partners in Postman, click here for detailed instructions.

Libraries Used

• Credo: A static code analysis tool that ensures code follows best practices and recommended standards.
• Excoveralls: Generates detailed test coverage reports, with easy integration into CI tools.
• CSV: A library for parsing and generating CSV files efficiently in Elixir.
• HTTPoison: A simple and flexible HTTP client for making HTTP requests in Elixir applications.
• Brcpfcnpj: Provides functions for validating and formatting Brazilian CPF and CNPJ numbers.
• Oban: A robust background job processing framework with support for distributed queues and persistence via PostgreSQL.

Code Quality

To run the analysis, execute:

$ mix credo --strict

Tests and Coverage Report

To run the tests, execute:

$ mix test

To generate an HTML coverage report, execute:

$ mix coveralls.html

The report will be saved at: ~/partner_sync/cover/excoveralls.html