SmartOrder — a production-ready microservices blueprint (for architects & devs)
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: GitHub
TL;DR — why this repo matters (put this first)
This is not a toy. SmartOrder is a full microservices reference platform that aims to be a blueprint for production-grade systems: service discovery, API gateway, messaging, observability, local developer tooling and reproducible environments — all wired together so you can boot everything 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.
Big-picture architecture (the elevator pitch)
API Gateway: Spring Cloud Gateway acts as a single entry point, dynamically routing using Consul and providing cross-cutting policies (CORS, circuit-breaker fallback, etc.). GitHub+gateway
Service mesh-ish primitives: Consul is used for service discovery and configuration (auto-registration, health checks). GitHub+docker
Business microservices: multiple standalone Spring Boot services (Order, Inventory, Product, …) expose HATEOAS-enabled REST APIs and are instrumented with Micrometer. GitHub+services
Asynchronous communication: RabbitMQ for event-driven messaging (CQRS-friendly, eventual consistency patterns). Kafka is intentionally omitted to keep local dev simple. GitHub+services
Persistence: MongoDB per service for schema-less persistence where appropriate.
Observability & dashboards: a fully dockerized stack (Prometheus, Grafana, InfluxDB, Dozzle, Dashy) with pre-provisioned dashboards.
This combination is designed as a blueprint — an opinionated, repeatable assembly of components you can copy into a real project and evolve.
Platform UIs
Gateway UI
Consul UI
Dashy
Dozzle
Grafana UI
Why a large Maven project (and why not many separate repos)
Maintainers often face a choice: many tiny repositories (one per service) vs a single repository (or multi-module Maven project) that groups related services. This repository chooses the latter to deliver a few concrete advantages for a blueprint:
Single versioned snapshot — everything boots together and the Docker Compose orchestrations match code checked into the repo. That makes local reproducibility and tutorial-style onboarding trivial.
Synchronized dependency management — parent POMs and shared dependencyManagement / pluginManagement reduce version drift across services and simplify CI.
Coordinated local dev environment — the
docker/folder anddocker-compose.all.ymlorchestrate the full ecosystem so you can run the whole stack with the correct versions of monitoring, messaging and persistence. Trying to coordinate cross-repo snapshots for a demo/blueprint is brittle; a single multi-service Maven project keeps the blueprint faithful.Blueprint clarity — grouping the services makes it easier to show architecture diagrams, end-to-end flows, and example scenarios without jumping between dozens of independent repos.
(If you prefer a polyrepo 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 & local dev — the reproducible playground
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:
docker
├── config-services
│ ├── dashy
│ ├── grafana
│ ├── influxdb
│ ├── jmeter
│ ├── prometheus
├── docker-compose.all.yml
├── docker-compose.monitoring.yml
├── docker-compose.persistence.yml
docker-compose.all.yml orchestrates the entire ecosystem (gateway, services, RabbitMQ, Consul, MongoDB, observability tools). The intent: one command to reproduce a realistic environment for debugging, load testing, or demoing features.
Run the full stack (example):
# from repo root (example)
docker-compose -f docker/docker-compose.all.yml up --build
(Exact command and compose file names are in the docker/ folder in the repo.) GitHub+docker
Domain-Driven Design (DDD), REST + HATEOAS, OpenAPI & AsyncAPI
The project follows DDD thinking: services own bounded contexts and encapsulate business responsibilities (orders, inventory, product). That makes the model boundaries and data ownership explicit to anyone reading the code.
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 docs.
OpenAPI / AsyncAPI: the repo is organized to document synchronous REST APIs with OpenAPI and asynchronous channels with AsyncAPI (where applicable). That makes automated client generation and message contract validation straightforward.
(You’ll find OpenAPI or API docs and AsyncAPI artifacts in the docs folder and service modules; see the repo link below.)
Testing, quality gates and CI
The project is set up with attention to quality:
Unit tests and integration tests are used to validate both service logic and interactions.
A
sonar-project.propertiesis present — the project is prepared to be analyzed with SonarCloud/ SonarQube for code smells, bugs, and coverage tracking.Coverage and CI badges are included to communicate health at a glance (see README). The repo is a good place to experiment with mutation testing, contract tests (for messaging), and end-to-end test strategies.
Example — small request flow (Order → Inventory)
Client hits the Gateway:
POST /api/ordersGateway routes to Order Service (route registered via Consul).
Order Service persists the order into its bounded-context DB (Mongo).
Order Service publishes an
OrderCreatedevent to RabbitMQ.Inventory Service consumes
OrderCreated, reserves stock, and may publishStockReservedorStockFailed.Clients can follow HATEOAS links to query order status or next steps.
This kind of event-driven choreography is implemented in the services and wired up via the Dockerized messaging broker so you can step through it locally.
Why you should read (and contribute)
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, or language-agnostic client examples.
Where to look in the repo
README.md— quick architecture overview and goals. GitHubdocker/— all the compose files and monitoring stacks (the reproducible dev environment). GitHub+dockerservices/— the individual Spring Boot applications (Order, Inventory, Product, …). GitHub+services
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: next posts will deep-dive into the Docker composition and observability dashboard, then into DDD and the messaging contracts, and finally into testing strategies and a contributor’s guide — coming as soon as possible.
Enjoy exploring the blueprint — contributions welcome!
Top comments (0)