SmartOrder: A Modern Microservices Reference Platform

Source: Dev.to

Introduction

A quick, hands‑on tour of the SmartOrder reference platform: why it’s structured the way it is, how the Docker‑based developer experience is designed, and where you can jump in and contribute.

Repository:

Overview

SmartOrder is not a toy. It is a full‑featured microservices reference platform that serves as a blueprint for production‑grade systems, including:

• Service discovery
• API gateway
• Messaging
• Observability
• Local developer tooling
• Reproducible environments

All components are wired together so you can boot the entire stack with a single command. If you design, build, or operate distributed systems, this repo gives you a realistic end‑to‑end example to read, extend, and reuse.

Core Components

This combination is designed as a blueprint—an opinionated, repeatable assembly of components you can copy into a real project and evolve.

Repository Layout

smartorder/
├─ docker/
│   ├─ config-services/
│   │   ├─ dashy/
│   │   ├─ grafana/
│   │   ├─ influxdb/
│   │   ├─ jmeter/
│   │   └─ prometheus/
│   ├─ docker-compose.all.yml
│   ├─ docker-compose.monitoring.yml
│   └─ docker-compose.persistence.yml
├─ docs/
│   ├─ openapi/
│   └─ asyncapi/
├─ services/
│   ├─ order/
│   ├─ inventory/
│   └─ product/
├─ gateway/
└─ pom.xml (multi‑module Maven parent)

Why a Single Multi‑Module Maven Project?

(If you prefer a poly‑repo for production microservices at scale, you can still take the blueprint and split services later. The repo is intentionally organized to make that extraction straightforward.)

Docker Setup

The Docker setup is central—it’s not an afterthought. The repo exposes a structured docker/ layout and multiple compose files so you can selectively boot only what you need or everything at once.

Common Compose Files

• docker-compose.all.yml – orchestrates the entire ecosystem (gateway, services, RabbitMQ, Consul, MongoDB, observability tools).
• docker-compose.monitoring.yml – starts only the monitoring stack (Prometheus, Grafana, InfluxDB, Dozzle, Dashy).
• docker-compose.persistence.yml – starts persistence services (MongoDB, RabbitMQ, Consul).

Running the Full Stack

# From the repository root
docker-compose -f docker/docker-compose.all.yml up --build

(Exact command and compose file names are in the docker/ folder.)

Design Philosophy

Domain‑Driven Design (DDD)

• Services own bounded contexts and encapsulate business responsibilities (orders, inventory, product).
• Model boundaries and data ownership are explicit, making the codebase easy to understand.

REST + HATEOAS

• APIs are exposed with HATEOAS‑friendly responses so clients can discover resources and transitions (links) instead of relying solely on out‑of‑band documentation.

OpenAPI / AsyncAPI

• Synchronous REST APIs are documented with OpenAPI.
• Asynchronous channels are described with AsyncAPI (where applicable).
• Artifacts live in the docs/ folder and within each service module, enabling automated client generation and message‑contract validation.

Quality & CI

• Unit tests and integration tests validate service logic and interactions.
• sonar-project.properties is included; the project is ready for analysis with SonarCloud/SonarQube.
• Coverage and CI badges are displayed in the README, providing a health‑at‑a‑glance view.
• The repo is a good place to experiment with mutation testing, contract tests (for messaging), and end‑to‑end test strategies.

Example Flow – Small Request (Order → Inventory)

1. Client → POST /api/orders (Gateway)
2. Gateway routes to Order Service (route registered via Consul)
3. Order Service persists the order in its bounded‑context DB (Mongo)
4. Order Service publishes an OrderCreated event to RabbitMQ
5. Inventory Service consumes OrderCreated, reserves stock, and may publish StockReserved or StockFailed
6. Client follows HATEOAS links to query order status or next steps

This event‑driven choreography is implemented in the services and wired up via the Dockerized messaging broker, so you can run the whole flow locally with a single docker-compose command.

Getting Started

1. Clone the repo

   git clone https://github.com/your-org/smartorder.git
   cd smartorder

2. Start the full stack

   docker-compose -f docker/docker-compose.all.yml up --build

3. Explore the services

   • API Gateway:
   • Prometheus:
   • Grafana: (admin / admin)
   • Dashy:

4. Run tests

   ./mvnw verify

5. Read the docs

   • OpenAPI specs: docs/openapi/
   • AsyncAPI specs: docs/asyncapi/

Contributing

• Fork the repository, create a feature branch, and submit a Pull Request.
• Follow the existing code style and run ./mvnw verify before pushing.
• Update documentation (README, OpenAPI/AsyncAPI) when adding new endpoints or events.

License

Distributed under the Apache License 2.0. See LICENSE for more information.

Overview

Architects – Read the composition choices (service discovery via Consul, why RabbitMQ for a demo blueprint, observability‑first stack) to get ideas for your next architecture review or to compare trade‑offs.

Developers – The repo contains tangible examples (Spring Boot apps, HATEOAS patterns, Micrometer instrumentation, Docker‑Compose orchestration) you can clone and run to learn by doing.

Contributors – Tests, docs, and monitoring dashboards are all designed to be extended. Help‑wanted items you can contribute:

• Sample OpenAPI/AsyncAPI files
• Additional integration tests (contract tests for messages)
• Example CI workflows
• Language‑agnostic client examples

Repository layout

(Replace the placeholder links with the actual URLs to the repository.)

How you can help (suggested first PRs)

• Add/extend AsyncAPI docs for message contracts so consumers/producers can be code‑generated.
• Add contract tests for event messages (e.g., Pact or custom consumer‑driven contracts).
• Harden the CI workflow with matrixed tests and coverage reporting.
• Improve examples for extracting a single service into its own repo (migration guide).
• Add sample client SDKs generated from OpenAPI for one service.

Final notes & follow‑ups

This post is the first of a short series that will walk through the repository in more detail:

1. Docker composition and observability dashboard
2. DDD and the messaging contracts
3. Testing strategies and a contributor’s guide

Coming as soon as possible.

Enjoy exploring the blueprint — contributions welcome!