itimalia

Backend application for an animal shelter

Topics

Introduction
Features
Stack
Usage
Application Deployed
API Documentation

Introduction

Itimalia is a personal project that aims to build a backend application with the best practices to study about them. The motivation came from close friends that help animals in shelters. The stack not follows well-known Spring Boot due to need to study new technologies and know backend techniques more in-depth.

Features

User

Create a user in database
Grant/remove admin permissions
Modify a user (admin can modify any user)
Delete an user (admin can delete any user)
Get a user by id

Animal

Add an animal in shelter by an admin (cat or dog)
Modify the status of the animal (only admin) (gone, dead, adopted)
Remove an animal from shelter (only admin)
Search an animal and filter by name, sex, age, if is castrated, status
Adopt an animal (only user)
Add photos to animal (default max: 8)

Technical

Unit tests with a minimum coverage of 90% (excluding some files)
Integration tests (WIP)
Lint check
Database migration
Filter animals by name, status, specie, size, sex, or castrated
Paging animals search
Order by id, name, or modification date, giving option to order ascending or descending
Github actions to check build, lint and coverage
Automatic deploy after successful build in master on Heroku
Dependency Injection
Hash passwords

Stack

Javalin - Web Framework
Exposed - ORM
Swagger - Documentation
Koin - Dependency Injection
Mockk - Mocking Library
Cloudinary - Images Library
ktlint - Lint
kover - Coverage tests
Test Containers - Containers for integration tests

Usage

Run locally

Run docker compose

docker-compose up

or install a PostgreSQL application in your machine with DATABASE_USERNAME=user and DATABASE_PASSWORD=password

Load environment variables:

JDBC_URL=jdbc:postgresql://localhost:5432/database
DATABASE_USERNAME=user
DATABASE_PASSWORD=password

This would run the application without support to save animal images. To save images, make a Cloudinary Account and add your API credentials:

CLOUDINARY_API_KEY=<api_key>
CLOUDINARY_API_SECRET=<api_secret>
CLOUDINARY_CLOUD_NAME=<cloud_name>

Run the application

./gradlew run

Tests

To run all tests, including integration:

./gradlew test

To only run unit tests:

./gradlew unitTest

To run integration tests:

./gradlew integrationTest

NOTE: integration tests need a docker environment.

Lint and coverage

If you want to check lint, run ./gradlew ktlintCheck

You can format your code to agree with ktlint rules with ./gradlew ktlintFormat

To generate coverage reports, run ./gradlew koverMergedReport You should see a message like Kover: merged HTML report file:///<your_file_location>/itimalia/build/reports/kover/html/index.html

The application has a default admin user with the following fields:

{
    "id": 1,
    "email": "admin@itimalia.org",
    "birthDate": "Datetime actual date",
    "gender": "undefined",
    "name": "Admin",
    "phone": "8199999999",
    "role": "admin",
    "creationDate": "Datetime actual date"
}

Application deployed

The application was deployed in Northflank and can be accessed in https://site--web--b59kk4m4p49y.code.run/ On the image below, we can see the current architecture. Itimalia has a connection with PostgreSQL database and both them are hosted on Northflank (image will be updated). Itimalia saves the image in Cloudinary that compress images and generate a link for access them.

API documentation

Local: http://localhost:7000/swagger
Northflank: https://site--web--b59kk4m4p49y.code.run/swagger

You also can see Postman collections in this repository in folder /postman.

demisgomes / itimalia