KALA

Kala (meaning goods) is an online shop backend written in Go.
It aims to be fast, simple, and extensible. As well as a showcase of my personal project structure.

Project Structure

Note

I've been working on a new architecture which is, at least in my opinion, much more robust and maintainable.
This project will see a complete overhaul in the near future. In the meantime, take this structure with a grain of salt (You can get a glimpse of what I'm working on here).

The general structure follows the guidelines I picked up from Let's Go Further, but over time I found some shortcomings in that approach, which led me to explore my desired structure.
The following is the result of my experience of developing many Go projects. What I find more logical and extensible approach, compile-time checks (I'm looking at you, import cycle), my constant experiment with different designs, and on top of all, my personal taste.

While I find this overall structure to make sense the most, feel free to adapt it partially or completely for your own projects!

(For older iterations and alternative structures, they can be found on other branches)

In a look

.
├── cmd
│   └── api
│       ├── main.go
│       ├── run.go
│       └── ...
├── config
│   ├── configs.json
│   └── state.go
├── docs
├── internal
│   ├── data
│   │   ├── mocks.go
│   │   ├── models.go
│   │   └── ...
│   ├── doc
│   ├── ent
│   ├── handlers
│   │   ├── handlers.go
│   │   ├── routes.go
│   │   └── ...
│   ├── structure
│   └── transfer
│       ├── errors.go
│       └── response.go
├── pkg
│   ├── logger
│   ├── validator
│   └── ...
├── go.mod
└── ...

cmd/api

This package is tasked with retrieving the configurations, their validation, opening database connections, and then finally starting the server.
It handles the graceful shutdown as well.

The configurations, logger, and one instance of Model will be passed down from here to the handlers package.

config

The configuration and settings structures are defined here, as they'll be used inside the application to control the API's behavior.
Application will look for configurations with the following priority:

1. Config file
2. Flag arguments
3. Environment variables

If specific data is not present, it will look for it at the next level.

internal/data

Database queries and transactions will take place here. Each table features a struct with db methods attached to it, they all will be initialized with the Models struct by a database connection.
With the use of interfaces, it's easy to write mocks for test cases.

internal/handlers

The handlers package features the struct handler which all handlers are a receiver function to it. It has a single exported receiver function named Router which will be called inside the cmd/api/run.go to instantiate the router.

Multiple structs such as Json and Response will be embedded inside the handler struct, so they can be used directly by the handlers.

internal/doc

Including multiple structs used solely for documentation purposes and serves no other responsibilities.

internal/structure

This package consists of structs to define the request, response, and data structure; hence the name.
It's equivalent of dto in some other architectures.

internal/transfer

This package is tasked with the data transfer inside the application, as well as to the clients. It features a general HTTP response function, besides many other helper functions each meant for a specific status code.

transfer also is home to a handful of structs that all implement error interface. They are meant to be used as a mean of conveying state between other layers and the handlers.

pkg

The purpose of this folder is to copy-paste the commonly used packages that get used often and yet have no dependency on the project and can be plugged in or out based on various needs. Packages such as logger and validator, among others, reside here.

Running

Install dependencies:

go mod tidy

Then, run the application:

go run ./cmd/api 

Create a configuration file, pass them as flag arguments, or provide configs as environmental variables.

To run in development mode, add the following flag: -env dev

Documentation

API documentation follows Swagger Documentation 2.0 and is generated by swaggo. It resides in docs folder.

swag init -q -g cmd/api/main.go --parseInternal

TODOs:

• Simplify the application logic
• Improve error handling Created new transfer package
• Load configurations from a file as an option
• Defining the log level from the configurations
• Add more logs to the application
• Add a new layer between the handlers and data packages
• Integrate Websocket