suricate-bank

⚠️ WORK IN PROGRESS (DEVELOPMENT RELEASE) ⚠️

Suricate Bank is an api that creates accounts and transfers money between them. It is being built following Clean Arch.

A very special thanks to my Golang and Clean Arch mentor, Helder. It's been a ride!

Contents

• Features
• Coming Soon
• Dependencies
• Getting Started
  • Running the App
  • Automated Tests
  • Manual Testing
  • Available Routes
    • POST /accounts
    • GET /accounts
    • POST /login
    • POST /transfers
    • GET /transfers

Features

• RESTful API
• Persistence on PostgreSQL DB with migrations
• Support for idempotent requests on create routes (account and transfer)
• Bearer Token (JWT) Auth on private routes (create transfer)
• Clean Architecture
• Containerized (Docker and Docker-Compose)
• Meaningful unit and integration tests
• Swagger Documentation

Coming Soon

• Logging, requestID tracing and panic recovery middlewares
• GitHub Actions

Dependencies

• uuid - For generating and inspecting unique account and transfer UUIDs;
• pgx - For configuring and connecting a pool to a PostgreSQL database and running queries;
• Dockertest - For running integration tests on temporary database containers;
• migrate - For running database migrations;
• bcrypt - For hashing and comparing hashed secrets;
• jwt - For signing and verifying JSON Web Tokens for authenticatioin;
• chi - For routing;
• cleanenv - For reading .env and loading env variables;
• redigo - For connecting and running commands on Redis (for idempotent HTTP requests);
• Logrus - For logging. This library is used in the dockertest example. I haven't set up logging for the project, so I will decide later if this will actually be used.
• Swaggo - For generating maintainable Swagger docs and Swagger UI

Getting started

To run this app in a container, the only requirement is Docker Compose.

To run without a container, you will need Go, PostgreSQL (configured and running), and optionally Docker to run integration tests.

An image of the application is available on Docker Hub registry on this repository. You can pull it and use the postgres and redis instances you prefer (directly on your machine or building a container) to run the app. To pull the image, just run make pull-container.

Running the app

1. Clone the project and enter directory:

   git clone https://github.com/jpgsaraceni/suricate-bank.git && cd suricate-bank
   

2. Run in docker container:

   make start
   

or without docker (after preparation instructed above):

make build

Automated tests (requires Docker for integration tests)

make test

Manual testing

The file /client.http can be used to test all available routes. I suggest using REST Client VS Code extension for this (or any other HTTP request service you prefer).

You can also use Swagger UI for manual testing, as explained below

Available routes

You check out all routes on Swagger UI. Just access http://HOST_RUNNING_THIS_APP:PORT_ITS_LISTENING_ON/swagger. If you are running on the default URL, http://localhost:8080/swagger

POST /accounts

Create new account

Content-Type: application/json

{
    "name": "another client",
    "cpf": "488.569.610-08",
    "secret": "really-good-one"
}

GET /accounts

List all accounts

GET /accounts/{account_id}/balance

Get account balance

POST /login

Login

Content-Type: application/json

{
    "cpf":"22061446035",
    "secret":"can't-tell-you"
}

POST /transfers

Create new transfer (requires Bearer token)

Content-type: application/json
Authorization: Bearer <JWT>
{
    "account_destination_id": "438e4746-fb04-4339-bd09-6cba20561835",
    "amount": 500
}

GET /transfers

List all transfers