hexolan/stocklet

An event-driven microservice e-commerce example application

Stocklet

An event-driven microservices-based distributed e-commerce example application written in Golang. (mouthful)

📘 About

This project was originally built as an experiment with event-driven architecture. But I hope it can future serve as a beneficial demonstration of utilising the architecture and exemplify the implementation of some other miscellaneous microservice patterns.

Any ideas, suggestions or direct contributions to better conform with general and evolving industry practices are welcome and will be greatly appreciated, as I'd like for this project to evolve to the stage of being somewhat a reflection of a production-ready enterprise application.

⚠️ The application should be considered in the experimental prototype stage. Breaking changes can be expected between any future commits to this repo, in order to ease the development process and allow for clean refactoring of the project.

📝 Features

• Monorepository layout
• Microservice architecture
• Event-driven architecture
• Interfacing with services using gRPC
• User-facing RESTful HTTP APIs with gRPC-Gateway
• Distributed tracing with OpenTelemetry
• Transactional outbox pattern with Debezium
• API gateway pattern using Envoy
• Distributed transactions utilising the saga pattern

🗃️ Architecture

🔎 Overview

🧰 Technical Stack

Libraries, Frameworks and Tools

• API Tooling

  • google.golang.org/grpc
  • github.com/grpc-ecosystem/grpc-gateway/v2

• Client Libraries

  • go.opentelemetry.io/otel
  • github.com/twmb/franz-go
  • github.com/jackc/pgx/v5

• Protobuf Libraries

  • google.golang.org/protobuf
  • github.com/bufbuild/protovalidate-go

• Tools

  • plantuml.com
  • github.com/bufbuild/buf/cmd/buf
  • github.com/golang-migrate/migrate/v4

• Miscellaneous

  • golang.org/x/crypto/bcrypt
  • github.com/rs/zerolog
  • github.com/lestrrat-go/jwx/v2
  • github.com/doug-martin/goqu/v9

Infrastructure

• Message Brokers
  • Kafka
• Databases
  • PostgreSQL
• Miscellaneous
  • OpenTelemetry
  • Envoy
  • Debezium Connect
• Provisioning and Deployment
  • Docker and Docker Compose

🧩 Services

Name	gRPC (w/ Gateway)	Produces Events	Consumes Events
auth	✔️	❌	✔️
order	✔️	✔️	✔️
payment	✔️	✔️	✔️
product	✔️	✔️	✔️
shipping	✔️	✔️	✔️
user	✔️	✔️	❌
warehouse	✔️	✔️	✔️

Each service is prepared by a service-init container; a deployment responsible for performing any database migrations and configuring Debezium outbox connectors for that service.

📇 Events

The events are schemed and serialised using protocol buffers. They are dispatched using the transactional outbox pattern, with Debezium used as a relay to read and publish events from database outbox tables to the message broker.

Further documentation on the events can be found at /docs/EVENTS.md

💻 Deployment

Using Docker

The application can be deployed using Docker Compose (with the compose files located in /deploy/docker/). Ensure the correct configuration is in place by copying and removing .example from the end of the example environment files located in /deploy/configs/.

Deploy using the following command: docker compose -f deploy/docker/compose.yaml -f deploy/docker/compose.override.yaml up --build

🧪 Contributing

If you like this project then please leave a ⭐ to show your support. All forms of feedback and contributions are welcome and greatly appreciated!

Have any ideas for improvements? Please don't hesistate to open an issue to discuss, or a pull request with enhancements.

📓 License

This project is licensed under the GNU Affero General Public License v3.