Suricate Bank

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
• Documentation (Swagger UI)
• 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
• Structured logging
• CI with GitHub Actions

Swagger UI

You can try out the API without any instalation by accessing the Swagger UI of the app deployed on Heroku. You can also use the Swagger UI or any other http client locally to run it on a clean DB, as instructed in the Getting Started section below.

Coming Soon

• Apache Kafka events

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, panic recovery and requestID tracing;
• cleanenv - For reading .env and loading env variables;
• redigo - For connecting and running commands on Redis (for idempotent HTTP requests);
• Swaggo - For generating maintainable Swagger docs and Swagger UI
• zerolog - For structured logging.

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, Redis (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 can 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, localhost/8080/swagger

POST /accounts

Create new account

Create account request payload example

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

Login request payload example

Content-Type: application/json

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

POST /transfers

Create new transfer (requires Bearer token)

Create transfer payload example

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

GET /transfers

List all transfers