jibaru / home-inventory-api Goto Github PK

This is a simple API to organize your items at home. It allows you to create rooms, boxes, and items.

You can also add items into boxes, remove items from boxes, and other functionalities.

The API is built with Go and uses MySQL as the database. It also uses Docker to run the app and the database. The API is also versioned and uses Sentry to log errors. The API uses smtp to send emails to users. The API uses JWT to authenticate users. The API use AWS S3 to store the assets.

1. Clone the repository
2. Clone app.env.example to app.env and fill the environment variables
3. Run docker-compose --env-file app.env up to start the app or if you use make, then use of the Makefile commands
4. Run docker exec -it home-inventory-api-workspace-1 /bin/bash -c "make run" to start running the API
5. Also you must need run migrations on your database
6. Access the API at http://0.0.0.0:your-port

• User: A person who uses the API
• Room: A place in the house where boxes are located
• Box: A container that holds items
• Item: An object that is stored in a box
• ItemKeyword: A keyword that describes an item
• Asset: A file that is stored in the cloud
• BoxItem: A relation between a box and an item, it contains the quantity of the item in the box
• BoxTransaction: A register of the movement of items in boxes
• Version: A version of the API

• Authentication
  • Register a user
  • Login a user
• Rooms
  • Create a room
  • List all rooms (paginated)
  • Update a room
  • Delete a room
• Boxes
  • Create a box
  • List all boxes (paginated)
  • Update a box
  • Delete a box
  • Add items into a box
  • Remove items from a box
  • Transfer items from a box to another
• Items
  • Create an item with a photo
  • List all items (paginated)
  • Update an item and its photo
  • Delete an item
• Assets
  • Create an asset

The API is versioned and the current version is v1.

The API use a Hexagonal Architecture and the structure is as follows:

On the application layer, the business logic is implemented. The business logic is implemented.

On the domain layer, there are some elements like:

• Entities: They are the main objects of the application.
• Repositories: They are the interfaces that define the methods to interact with the database.
• Services: They are the interfaces that define the methods to interact with external services.

There are interesting services in domain layer:

• EventBus: It is a service that allows to publish async events.
• EmailSender: It is a service that allows to send emails to users.
• FileManager: It is a service that allows to store files in the cloud.
• TokenGenerator: It is a service that allows to generate/decode tokens for users.

On the infrastructure layer, the implementation of the interfaces is done. The implementation is done using the database, the email service, the file storage, etc.

Here is where the API is implemented. The API is implemented using the echo framework, and the persistence with gorm.

There are two features that cross the entire layers. There are the logger and notifier (sentry).

The coding flow is as follows:

1. Create a task in the project board
2. Create a branch from main with the name feat-number
3. Implement the feature. The feature must be tested
4. Create a pull request to main
5. The pull request must be reviewed and tested. There are some actions to do test.
6. The pull request is merged to main is all test pass and if it satisfies the task.

The API is tested using the testing package and the testify package. For the repositories, the test is done using SQL testing using sqlmock package.