Skip to content

Design

Jump to bottom
Brandon Young edited this page Oct 11, 2020 · 21 revisions

On This Page

Inspirations

At a high level, scaffold's intent is to be a tool to streamline the process of getting a new go project up and running, which embodies our collective experience and preferences for how this should look and act. Scaffold draws inspiration from tools such as kit, and boilr.

Kit

Kit is a go code generation tool for quickly laying out a project structure based on go-kit. It can do several interesting things, but the particular workflow of interest to us is the basic project creation workflow.

The basic project creation workflow using kit:

# Initialize a local project (basic form)
$ kit new service <service_name>

# Edit the newly generated service interface, describing the API methods 
$ vim <service_name>/pkg/service/service.go

# Generate the project layout from the above service interface
$ kit generate service <service_name>

Benefits

  1. Utilizes clean architecture
  2. Programmatically stubs out all the methods, endpoints, etc with proper error handling
  3. Super quick to get up and running since what remains is an exercise in filling in the business logic

Drawbacks

  1. Uses a different directory structure than we use
  2. Makes different choices for default libraries to include, and in some cases includes several of the same kind (such as tracing)
  3. Kit does not include some ancillary capabilities or elements of a project we consider standard
  4. Since it uses a code generation library, it is limited to the go language

The obvious question, then, is why not submit patches to kit? After making a couple of minor modifications to explore the idea, our assessment is that the scope and apparent goals of kit are sufficiently different from what we envision that such changes would not be small patches. Thus, we view kit more as inspiration for our own project than the foundation of it.

Boilr

Boilr is another neat project attempting to streamline and standardize new project creation through templating. Boilr takes a JSON template describing a project and converts it to a concrete directory structure and text files by rendering the template using supplied parameters. Templates can be reused and shared. A nice side effect of the decision to use templates is that projects are not limited to the go language; and can be any type of project or language which can be composed of text files and directory structures.

Benefits

  1. Supports Template Libraries
  2. Supports any project structure that can be composed of text files and directories
  3. Can leverage a central repository of templates (i.e. a library)

Drawbacks

  1. Scope of tool is limited to project creation on local disk
  2. Tool leverages templates, which somewhat limits the ultimate sophistication of its capabilities, compared to kit, which generates source code files with a code generation library.

Scaffold

Scaffold aspires to encompass a more complete scope when defining what it takes to create a new project than cited sources of inspiration. There's more to a project than creating a local directory with some files, even if those files are a fairly complete, well considered set of source files. The project should be under version control. There should be a remote repository the local project is linked to. The project should empower and promote consistency through thoughtful elements such as shared git hooks; and local development and testing capabilities which are easily reproducible by others and are as similar to the automated CI/CD pipeline as possible. In general, scaffold seeks to make the "right" path the easiest path to take.

Proposed Feature Set

Initially, scaffold will target the following toolchain, but be designed to allow for extension to include other options over time:

  1. Go
  2. Go Kit
  3. Git (Github and Github Enterprise)
  4. Make/Mage
  5. Docker and Docker Compose
  6. Kubernetes [OPTIONAL]

Project Layout

At a high level, after initializing a new project with scaffold we expect the following statements to be true:

  1. A git remote will exist at the specified repository URL
  2. A local checkout of the git project will exist
  3. A local project will resemble: 
    ├── .githooks
│   └── pre-commit
├── .gitignore
├── LICENSE
├── Makefile
├── README.md
├── cmd
│   ├── main.go
│   └── service
│       ├── service.go
│       └── service_test.go
├── docker
│   ├── Dockerfile
│   └── docker-compose.yaml
├── endpoint
│   └── endpoint.go
├── go.mod
├── go.sum
├── http
│   ├── handler.go
│   └── handler_test.go
├── internal
│   └── service
│       ├── middleware.go
│       ├── service.go
│       └── service_test.go
└── kubernetes
    ├── DEPLOYMENT.md
    ├── SETUP.md
    ├── deployment.yaml
    ├── ingress.yaml
    └── service.yaml
    • .githooks/pre-commit which performs go fmt, go lint, and go vet
    • README.md detailing how to enable githooks and conduct local development and testing
    • LICENSE
    • Makefile to manage local development and testing
    • docker/ containing Dockerfile and docker-compose.yaml files for easily running the project dev environment locally
    • kubernetes/ with necessary manifests to deploy the application into a Kubernetes environment (if selected)
    • cmd/ and internal/ contain project source code

Workflows

Libraries

Our preferences for various libraries include (if you need more than the stdlib for something):

Clone this wiki locally