Home

Description

The service starter kit is a starting point for building production grade scalable web service applications that can run in Kubernetes. The goal of this project is to provide a proven starting point that reduces the repetitive tasks required for a new project to be launched into production. It uses minimal dependencies, implements idiomatic code and follows Go best practices. Collectively, the project lays out everything logically to minimize guess work and enable engineers to quickly maintain a mental model for the project.

This project should not be considered a web framework. Coding is a discovery process and with that, this project leaves you in control of your project’s architecture and development. There are four areas of expertise that an engineer or their engineering team must possess for a project to be successful. Based on our experience, a few core decisions were made for each of these areas.

• Micro level - Design philosophies and guidelines being applied to lines of code and functions. This project focuses on making things easy to understand and precision based semantics.
• Macro level - Design philosophies and guidelines being applied to the project structure, packaging decisions, architecture, logging, configuration and production systems concerns. This project focuses on 4 layers of code, App, Business, Foundation, Vendoring. Choices around logging and configuration have been made and the use of a POD based architecture.
• Deployment and Operations - Engineering decisions about local and production environments. Management of such environments and integrations with continuous deployment or integration systems. This project uses CircleCI for CI and Kubernetes for the compute environment.
• Observability - Engineering decisions with the observability of logging, metrics, and tracing. Where the data is stored and how it is accessed. What kind of information will be gathered and maintained. OpenTelemetry has been chosen for tracing and the use of the expvar package for metrics.

Design Philosophy, Review, and Culture

This class tries to teach to these core design philosophies, review practices, and culture.

There are three core design philosophies that drive every guideline:

• Don’t make things easy to do, make things easy to understand.
• Every encapsulation must define a new and precise semantic.
• Engineer with clear and obvious layers of concern and purpose.

There are three core reviews that must be performed with each change:

• Can this change be maintained, managed, and debugged by the team?
• Is this change the minimal code needed right now to solve the problem?
• Does this change violate any style or project guidelines?

There are three core aspects of a team’s culture that should be cultivated:

• Uncertainty is not a license to guess, but a directive to stop and learn more.
• Don’t focus on reuse, focus on constant review and refactoring.
• Be open to discussion and pivot as new things are learned and discovered.

Features

This project contains the following features:

• Ground up architecture and design for Kubernetes.
• Configure and manage local and production K8s environments.
• Minimal web service application framework.
• Middleware integration.
• Database support using Postgres.
• Secret support using Hashicorp Vault.
• CRUD based pattern.
• Role-based access control (RBAC).
• Account signup and user management.
• Distributed logging and tracing.
• Integration with OpenTelemetry for enterprise-level observability.
• Testing patterns.
• Use of Docker, Docker Compose, and Makefiles.
• Vendoring dependencies with Modules, requires Go 1.18 or higher.
• Continuous deployment pipeline.
• Integration with CircleCI for enterprise-level CI/CD.
• Tempo and Grafana support to collect and visualize otel traces.

Business Problem

The service project is solving the problem of providing a backend for a sales-api that supports the running of a multi-family garage sale. Authenticated users can manage users, products and sales.

Services

The following services are used within the scope of the project.

Tooling

• sales-admin : Command line tool to help manage the system and database.

Internal Services

• sales-api : Service that provides CRUD based endpoints for the garage sale business problem.
• metrics : Sidecar for handling support for metics data. Showcases how a sidecar can be used.

External Services

• vault : System used to manage private/public keys.
• postgres : Database used to store users, products, and sales.
• Tempo/Grafana : System used to collect and query application traces.