Guide · Open source
How to use PiggyMetrics: setup, services and learning tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
PiggyMetrics is an open-source financial advisor app split into small services, built to demonstrate the microservice architecture pattern with Spring Boot, Spring Cloud and Docker. This guide is for Java developers and students who want to see how those services are split and how they talk to each other. By the end you will know where to start, what each service does and how config, auth and routing fit together.
Piggy Metricssqshq/piggymetrics · ★ 14k · MIT Install options & downloads Quick start
- 1Check prerequisites. Install Java and Docker on your machine. The source lists both as requirements.
- 2Clone the repository. Run git clone https://github.com/sqshq/piggymetrics to get the code locally.
- 3Read the service layout. Review the account, statistics and notification services and their REST endpoints in the README tables.
- 4Study the config service. Look at the shared directory and the bootstrap.yml client setup to see how services load configuration.
- 5Trace the auth flow. Review the OAuth2 grants and the @PreAuthorize example to see how services are protected.
- 6Follow the API gateway routing. Check the Zuul prefix-based route for the notification service and how requests reach it.
- 7Fork and modify. Change one small piece, such as a notification e-mail, and observe the effect.
What PiggyMetrics is and who it is for
PiggyMetrics is described in its README primarily as a tutorial. The project is meant to demonstrate the microservice architecture pattern, and you are welcome to fork it and turn it into something else.
It suits Java developers who want a concrete microservice example, students learning how Spring Cloud config, auth and API gateways fit together, and teams comparing how services are split and communicate over REST. It is not a finished finance app, and the code assumes familiarity with Java and Spring.
Prerequisites: Java and Docker
The install method is clone-and-build, and the source lists Java and Docker as prerequisites. You should be comfortable with Java and Spring before you start, because the code assumes that background.
- Java
- Docker
Get the code: clone the repository
Start by cloning the repository from GitHub. The README gives this command:
git clone https://github.com/sqshq/piggymetricsUnderstand the services: account, statistics and notification
PiggyMetrics is split into three core microservices, each organized around a business domain. Each has its own database, so you cannot bypass its API to reach persistence directly. MongoDB is the primary database for each service, and the services talk to each other over REST.
- Account service: input logic and validation for incomes/expenses items, savings and account settings. Includes POST /accounts/ to register a new account and GET /accounts/demo for demo data.
- Statistics service: calculations on major statistics and time series per account, with values normalized to a base currency. Includes GET /statistics/current and PUT /statistics/{account}.
- Notification service: stores contact information and notification settings such as reminders and backup frequency. A scheduled worker collects information from other services and sends e-mail messages.
See how config, auth and the API gateway work
The Config service uses Spring Cloud Config with the native profile, which loads files from the local classpath, including the shared directory. A client only needs the spring-cloud-starter-config dependency and a bootstrap.yml with its application name and config server URL. The Auth service grants OAuth2 tokens: the Password credentials grant is used for users (since only the UI uses it) and the Client Credentials grant for service-to-service calls. The API Gateway uses Zuul, enabled with @EnableZuulProxy, to serve the UI and route prefix-based requests such as /notifications/** to the Notification service.
- Config: fail-fast makes startup fail immediately if the config service cannot be reached.
- Config refresh: @RefreshScope lets you change e-mail text and subject without rebuilding or restarting, using a refresh call to the Notification service.
- Auth: services are scoped as server for backend services and ui for the browser, and @PreAuthorize can protect controllers.
spring:
application:
name: notification-service
cloud:
config:
uri: http://config:8888
fail-fast: trueFork it and adapt it
Because the project is intended as a tutorial, the most useful next step is to fork it and change one service at a time. Start with a small change, such as an e-mail subject in the Notification service, and follow how the config and routing flow to it.
The README does not cover production deployment, so treat the setup as a learning environment rather than a hardened system.
What people use it for
- Learning how Spring Cloud Config supplies shared and per-service settings to microservices
- Studying how OAuth2 password and client credentials grants are used between a UI and backend services
- Exploring how a Zuul API gateway routes requests by path prefix to separate services
- Using the codebase as a starting point for your own multi-service Spring project
- Comparing how a finance domain is split into account, statistics and notification services
Frequently asked questions
How do I install PiggyMetrics?
The install method is clone-and-build. The README gives the command git clone https://github.com/sqshq/piggymetrics, and the source lists Java and Docker as prerequisites. Build instructions beyond that are not covered in the material provided here, so check the repository README for the full steps.
What are the requirements for PiggyMetrics?
The source lists Java and Docker as prerequisites. The code assumes familiarity with Java and Spring, so beginners will find it hard to follow without that background.
Is PiggyMetrics free and open source?
PiggyMetrics is released under the MIT licence, according to the project listing, and it is written in Java. The MIT licence lets you fork and adapt the code.
Is PiggyMetrics a real finance app I can use?
No. The README describes it primarily as a tutorial demo that you can fork and adapt. It is a simple financial advisor app built to demonstrate the microservice pattern, not a finished product.
Can I use PiggyMetrics in production?
The README does not cover production deployment, so it is not a production-hardened setup. Use it to learn and as a starting codebase, and add your own hardening if you adapt it.
How does PiggyMetrics compare to other microservice examples?
Comparable projects include Spring Petclinic Microservices, JHipster, the Eureka Microservices Example and the Spring Cloud Netflix samples. Pick PiggyMetrics if you want to study a finance domain split into services that use Spring Cloud config, auth and a Zuul gateway.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
PiggyMetrics is a good choice for Java developers and students who want a concrete, forkable example of a microservice system built with Spring Boot, Spring Cloud and Docker. If you need a finished personal finance app or a production-ready deployment, pick a different project, because the README presents this one as a tutorial.
Install options & downloads