This blog is the part of the series Building a Web App with Golang.

In today's article we are going to define the basic entities and the operations on them for our web application. In the first part we defined the scope of the application.

We are going to build a system that can issue issue invoices for clients.

Let's create a new git branch to work on:

git checkout -b basic-domain

Company

Every client and "us" (our company/the freelancer) will be represented by an entity Company .

Let's create a file named company.go in the root of our project

then we define a struct with the basic attributes we have:

package invoicehub

type Company struct {
    ID           int
    Name         string
    Address      Address
    Email        string
    TaxID        string
    VatID        string
    BankAccounts []BankAccount
}

type Address struct {
    Street     string
    City       string
    PostalCode string
    Country    string
}

type BankAccount struct {
    BankName      string
    AccountNumber string
    IBAN          string
    BIC           string
}

The idea is that we will represent each real life company using the above struct.

Invoice

Create an invoice.go in the root of the project

Each invoice will have at least the following:
- Seller
- Buyer
- Amount
- Issue Date
- Invoice Number
- Days (number of days after issuance that must be paid).

We need to install first one dependency to handle decimal numbers:

get github.com/shopspring/decimal

Now let's start with that:

package invoicehub

import (
    "time"

    "github.com/shopspring/decimal"
)

type Invoice struct {
    ID            int
    InvoiceNumber string
    IssueDate     time.Time
    SellerID      int
    BuyerID       int
    DaysToPay     int

    LineItems []LineItem
}

type LineItem struct {
    Description string
    Amount      Amount
    VatRate     decimal.Decimal
}

type Amount struct {
    Value    decimal.Decimal
    Currency string
}

The above structs should satisfy our needs for now.

Pay, attention that I am using ids for Buyer and Seller. We could have used a Company struct there.

Why I choose to use ids instead of a company struct?

Our application now is a "monolithic" application. In the future we might want to split into different microservices (maybe one microservice to handle the companies and one microservice to handle the invoices). Let's be proactive and try to decouple the Companies with the Invoices.

I does not look that we need other structs to represent our business domain. Of-course , we might forgotten something but then we will change.

Operations

Our application is pretty simple:

For a Company we need to be able to:

Create a company
Read a company
Update a company

Our requirements don't have a Delete so we skip for now.

Creating, Reading, Updating a company are straightforward.

First we need a way to do these operations in our storage layer.
For this we are going to create an interface CompanyRepository

Let's do that:

in your company.go add the following:

type CompanyRepository interface {
    Create(ctx context.Context, company *Company) (int, error)
    Update(ctx context.Context, company *Company) error
    Get(ctx context.Context, id int) (Company, error)
}

Now for our invoices:

We need to be able to :

Create Invoice
Read Invoice
Create a PDF from an invoice

we don't have full CRUD (Create Read Update Delete) since we don't want to Update or Delete invoices.

Let's define the repository also for invoices:

in the invoice.go add:

type InvoiceRepository interface {
    Create(ctx context.Context, invoice *Invoice) (int, error)
    Get(ctx context.Context, id int) (Invoice, error)
}

What about PDF generation here? This is not a database operation.
Additionally, what about creation of an invoice? It is a little bit more complex.

In the requirements we had that the InvoiceNumber looks like:

1031/24

so we have two parts:
1. a number that resets every year (1031)
2. the year (24)

So the next invoice should look like 1032/24 but if it is the first for 2025 should look like 1001/24 .

Notice that we start always with 1000.

This is just one way others, might do it differently.

It would be nice to have a generic way to compute that per customer. BUT, do not forget our requirements. We want to code for now and not for imaginary use cases. Let's get stuff done

Since invoices are a bit more complex let's also create a Service Layer that will handle the business logic .

open invoices.go and add:

type InvoiceService interface {
    Create(ctx context.Context, invoice *Invoice) error
    Get(ctx context.Context, id int) (Invoice, error)
    CreatePDF(ctx context.Context, id int) ([]byte, error)
}

We also need an extra method in the Repository that returns the last invoice of the year. We are going to use that to compute the invoice number

Add the GetLastInvoiceForYear in the repository

Adding the interfaces in our HTTP layer

Now that we have "described" the operations of our system via the interfaces let's see where we are going to use them.

in the http/router.go we defined a base handler :

Let's add the interfaces there:

type baseHandler struct {
    e         *echo.Echo
    companies invoicehub.CompanyRepository
    invoices  invoicehub.InvoiceService
}

so when we create the baseHandler we should inject the implementations of the interfaces:

Since we don't have any concrete implementation yet let's pass nil where we call the NewRouter function in our cmd/main.go .

Commit and Push

let's commit our code and push our branch

git add .
git commit -m "add basic domain entities"
git push origin basic-domain

And as usual, you can find today's code in the github branch

Summary and what is next

In today's blog post we started implementing our business logic. We first defined the required structs and the operations that we can do on these.
The operations are defined using interfaces. Utilizing interfaces allows us to think about our business logic without having to think about implementation details. Additionally, it will allow us to easily unit test our application later.

I would like to share a piece of advice here. When you have to develop an application no matter how complex it is try first to focus on what is your goal. Don't fall into the trap of questioning your self all the time like:

what if the user wants also that?
what if this changes ?
what if ... ?

These what if may never happen. If they do be confident that when it's required you will handle it.

I am not saying or implying do not think about scalability, changes of requirements etc . I am saying think about them try to code in a way that some decisions are deferred but don't waste your time trying to code something smart when it is not required.

The moments I am writing these lines I am thinking the following:

- How am I distinguish which company is the Seller when we don't have a User entity ?
- What if when we create an invoice someone else does it parallel (so the invoice number may come wrong?_
- How am i going to create an invoice number when I do it near the end of the year and I use UTC in the system but my current timezone is UTC+3 and I am in the next year?
- ...

and many many more.

Some of these are maybe valid concerns. But so far we don't have anything working yet. We don't have to aim for perfection, a working software is better that no software in the end.

Links to the other part of that series

https://blog.gkomninos.com/crafting-a-web-application-with-golang-a-step-by-step-guide

https://blog.gkomninos.com/setting-up-a-docker-development-enviroment-for-go

https://blog.gkomninos.com/building-a-robust-web-server-in-go-a-step-by-step-guide

https://blog.gkomninos.com/tutorial-deployment-of-golang-web-app-using-systemd

👍 Please leave a comment or like the article if you like it. This will help me gain visibility.

❤️ Following me on Github or X or LinkedIn motivates me keep writing.