Golang App Structure

[omolazabal]

This issue will track discussion regarding the structure of the Go application

[omolazabal]

I suggest a domain driven design as specified in this video. She goes over structuring Golang APIs. I believe we can follow a similar structure and adjust as we are developing the codebase.

[omolazabal]

This the structure I am proposing for the directories.

It takes into account all current entities and aggregates for the application. Please refer to the Entities and Aggregates section of the design specification.

I am basing this off of:

• Domain Driven Design Quickly
• Kat Zien's 2018 talk
• golang project samples
• Modules from the design specification

You can find Kat's code example here: https://github.com/katzien/go-structure-examples/tree/master/domain-hex

.
├─ cmd/                        # File to execute applications
│  └─ flowthru-server/         # Files to run flowthru-server app
│
├─ pkg/                        # Contains package for core functionality of our application
│  ├─ add/                     # Creation of entities
│  ├─ remove/                  # Deletion of entities
│  ├─ list/                    # List entities and attributes
│  ├─ notify/                  # Send org/event notifications
│  ├─ invite/                  # Send org/event invites
│  ├─ request/                 # Send requests to join organizations
│  ├─ privilege/               # Modify user privileges within events and organizations
│  ├─ attendance/              # Handle event attendance
│  ├─ follow/                  # Follow functionality for users
│  ├─ http/                    # HTTP communication
│  └─ storage/                 # Deals with the repositories the application will be interfacing with
│
└─ docs/                       # Godoc generated documentation

[kevin5112]

I'm having difficulty understanding specifically where files will belong in a certain directory. An example being, for add, will that be solely for adding a user? Or is it for adding anything to the database? Right now it only say entities which is a bit vague to me. Same for remove and list. Will list be listing everything in our database or only specific things?

[omolazabal]

I'm having difficulty understanding specifically where files will belong in a certain directory. An example being, for add, will that be solely for adding a user? Or is it for adding anything to the database? Right now it only say entities which is a bit vague to me. Same for remove and list. Will list be listing everything in our database or only specific things?

I see where you're coming from and I think that demonstrates that the designed I proposed is flawed. I believe one should be able to interpret the meaning of packages based on their structure. I will be working on an updated proposal and please post suggestions here.

In the meantime, I found this video on package oriented design. He brings up a lot of good points. Here is essentially a transcript: https://www.ardanlabs.com/blog/2017/02/package-oriented-design.html

[kevin5112]

Here is the file structure that @omolazabal and I went over today. Let me know how everything looks and if there are any changes that are needed.

.
├── cmd/
│   └── server/
├── flowthru/
│   ├── event/
│   ├── form/
│   ├── org/
│   ├── tag/
│   ├── task/
│   └── user/
├── internal/
│   ├── http/
│   │   └── rest/
│   └── platform/
│       ├── auth/
│       └── pg/
└── pkg/
    ├── create/
    ├── delete/
    ├── enroll/
    ├── follow/
    ├── list/
    ├── privilege/
    ├── send/
    │   ├── invite/
    │   ├── notification/
    │   └── request/
    └── withdraw/

[omolazabal]

I'm going to try to break it down so it can be clear. Feel free to chime in. Note, this will require some knowledge of Go and I suggest looking over some of the resources that were provided in this issue.

cmd

.
├── cmd/
│   └── server/

cmd/ contains files that will be ran in order to launch a specific version of our application. As of right now, it only contains server/, which is a version of our application that will host a REST API.

Within server/ will be a main.go file that will be ran to initialize the application. In other words, cmd/ will consists of our "main" packages

flowthru

├── flowthru/
│   ├── event/
│   ├── form/
│   ├── org/
│   ├── tag/
│   ├── task/
│   └── user/

flowthru/ consists of sub packages that contain all necessary structs and interfaces to achieve the business logic of our API. In other words, it consists of sub packages that have our "domain types" in order to successfully implement our "domain logic".

This may consist of models such as user structs and organization structs. And it will container interfaces to interface with the domain logic.

internal

├── internal/
│   ├── http/
│   │   └── rest/
│   └── platform/
│       ├── auth/
│       └── pg/

internal consists of packages that are unique for the applications within cmd/. No other application will import the packages, as they provide very specific functionality to the scope of this application's domain.

These specific functionalities are sepcified with the subpackages rest, auth, and pg which, respectively, handle routing, authentication, and database management and queries.

pkg

└── pkg/
    ├── create/
    ├── delete/
    ├── enroll/
    ├── follow/
    ├── list/
    ├── privilege/
    ├── send/
    │   ├── invite/
    │   ├── notification/
    │   └── request/
    └── withdraw/

pkg consists of packages that both handle the domain logic that is universal across all Flowthru applications and have potential for reusability. The flowthru/ packages will heavily rely on pkg to carry out the domain logic of our application.

Below are what each of the packages are in charge of followed by an example.

• create: Creates domain types (create users, create organizations, etc)
• delete: Delete domain types (delete users, delete events, etc)
• enroll: Enrolls domain types to other domain types (user rsvp to event, user joins an organization, user checks into an event, etc)
• follow: Handles following features (user follows another user)
• list: listing specific types (listing organizations, users, etc)
• privilege: modifier for privileges (user becomes owner of org, user becomes admin of event, etc)
• invite: invitations to types (org invites user to org, user invites user to event, etc)
• notification: notification sending (org sends notification to members)
• request: requests to do an action (user sends requests to join org)
• withdraw: removal of an enrollment (user removes their RSVP to an event)

[kevin5112]

└── pg/
I was wondering if you think we should keep this as the name pg, or maybe rename it to a more obvious name for database? I just looked at it right now and completely forgot what pg is. Either name it to postgres or database?

[omolazabal]

└── pg/
I was wondering if you think we should keep this as the name pg, or maybe rename it to a more obvious name for database? I just looked at it right now and completely forgot what pg is. Either name it to postgres or database?

Thats a good point. What about it gets restructured to

│   └── platform/
│       ├── auth/
│       └── database/
│           └── pg/
│           └── memory/

So we can eventually move to memory for testing, instead of having people set up docker to run/test the application. I think its good to specify pg so people know what database they are importing

[kevin5112]

Yea that makes more sense to me. Should we keep the name as pg or would it be clearer if we put postgres as the directory name.

[omolazabal]

Proposed simplified format

.
├── cmd/
│   └── server/
├── web-app/
├── internal/
│   ├── http/
│   │   └── rest/
│   ├── models/
│   │   ├── account/
│   │   ├── organization/
│   │   └── events/
│   ├── repository/
│   │   ├── pg/
│   │   └── memory/
│   └── middleware/
│       └── auth/
└── pkg/

Changes

web-app

Contains the frontend web application

internal

internal consists of packages that are unique for the applications within cmd/. No other application will import the packages, as they provide very specific functionality to the scope of this application's domain.

This is further emphasized by specifying a middleware folder and moving he models in.

pkg

Purely consists of packages that other projects can utilize. Common utils and tools will be inserted here.