If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sqshq/piggymetrics shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 14 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sqshq/piggymetrics repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sqshq/piggymetrics.

What it runs against: a local clone of sqshq/piggymetrics — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sqshq/piggymetrics | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 751 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sqshq/piggymetrics. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sqshq/piggymetrics.git
#   cd piggymetrics
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sqshq/piggymetrics and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sqshq/piggymetrics(\\.git)?\\b" \\
  && ok "origin remote is sqshq/piggymetrics" \\
  || miss "origin remote is not sqshq/piggymetrics (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "account-service/src/main/java/com/piggymetrics/account/AccountApplication.java" \\
  && ok "account-service/src/main/java/com/piggymetrics/account/AccountApplication.java" \\
  || miss "missing critical file: account-service/src/main/java/com/piggymetrics/account/AccountApplication.java"
test -f "auth-service/src/main/java/com/piggymetrics/auth/config/OAuth2AuthorizationConfig.java" \\
  && ok "auth-service/src/main/java/com/piggymetrics/auth/config/OAuth2AuthorizationConfig.java" \\
  || miss "missing critical file: auth-service/src/main/java/com/piggymetrics/auth/config/OAuth2AuthorizationConfig.java"
test -f "account-service/src/main/java/com/piggymetrics/account/client/StatisticsServiceClient.java" \\
  && ok "account-service/src/main/java/com/piggymetrics/account/client/StatisticsServiceClient.java" \\
  || miss "missing critical file: account-service/src/main/java/com/piggymetrics/account/client/StatisticsServiceClient.java"
test -f "config/src/main/java/com/piggymetrics/config/ConfigApplication.java" \\
  && ok "config/src/main/java/com/piggymetrics/config/ConfigApplication.java" \\
  || miss "missing critical file: config/src/main/java/com/piggymetrics/config/ConfigApplication.java"
test -f "account-service/src/main/java/com/piggymetrics/account/config/ResourceServerConfig.java" \\
  && ok "account-service/src/main/java/com/piggymetrics/account/config/ResourceServerConfig.java" \\
  || miss "missing critical file: account-service/src/main/java/com/piggymetrics/account/config/ResourceServerConfig.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 751 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~721d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sqshq/piggymetrics"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Piggy Metrics is a personal finance microservice architecture demo built with Spring Boot, Spring Cloud, and Docker that shows how to decompose a financial advisory application into independently deployable services (Account, Statistics, Notification). It demonstrates OAuth2 security, inter-service communication via Feign clients, MongoDB persistence, and cloud patterns like service discovery (Eureka), distributed config (Spring Cloud Config), and distributed tracing (Sleuth). Multi-module Maven project with independent microservices as separate directories (account-service/, likely statistics-service/, notification-service/ at root level). account-service follows Spring Boot convention: src/main/java contains controllers, services, repositories, clients, and domain models; src/main/resources holds bootstrap.yml for Spring Cloud Config; src/test mirrors main structure. Feign clients (AuthServiceClient, StatisticsServiceClient) enable inter-service communication; CustomUserInfoTokenServices handles OAuth2 token validation.

Java backend engineers and architects learning microservice patterns who want a realistic, runnable example of Spring Cloud ecosystem in practice; DevOps engineers studying Docker containerization and service orchestration; tutorial seekers exploring OAuth2, Feign client fallbacks, and polyglot data handling.

Active tutorial project with Travis CI integration, code coverage tracking (codecov.io), and comprehensive test coverage across AccountServiceTest, AccountControllerTest, and repository tests. The architecture is production-pattern-aligned but explicitly framed as a learning demo rather than a production system; no recent commit data visible, suggesting stable but potentially dormant codebase.

Dependency on Spring Cloud stack (OAuth2, Eureka, Config Server, Bus, Sleuth, Feign) with no visible version pinning strategy in the snippet shown—Spring Cloud versions are notoriously coupled to Spring Boot releases. Single-service focus (account-service visible) makes it unclear if other services (statistics-service, notification-service, auth-service referenced in clients) are equally maintained. MongoDB dependency with no migration tooling visible in the file list.

No current PR or milestone data visible in the file structure. Project appears to be in maintenance mode as a reference implementation rather than actively evolving; the .travis.yml and GitHub issue templates suggest CI/CD is in place but no recent activity indicators are present in the provided data.

Clone the repository: git clone https://github.com/sqshq/piggymetrics.git && cd piggymetrics. Build all services with Maven: mvn clean install. Ensure Docker daemon is running, then start infrastructure (Eureka, Config Server, RabbitMQ, MongoDB) via Docker Compose (inferred from README context), then start individual services: java -jar account-service/target/account-service-1.0-SNAPSHOT.jar.

Daily commands: Start the Config Server and Eureka Server first (reference infra services not shown in this snippet). Then for account-service: mvn spring-boot:run -Dspring-boot.run.arguments='--spring.profiles.active=dev' from account-service/ directory, or build and run: mvn clean package && java -jar target/account-service-1.0-SNAPSHOT.jar. Services autodiscover via Eureka and fetch config from Config Server via bootstrap.yml.

• account-service/src/main/java/com/piggymetrics/account/AccountApplication.java — Entry point for the Account Service microservice; demonstrates Spring Boot application bootstrap and cloud configuration.
• auth-service/src/main/java/com/piggymetrics/auth/config/OAuth2AuthorizationConfig.java — Core OAuth2 authorization server configuration; essential for understanding the authentication and token generation flow across all services.
• account-service/src/main/java/com/piggymetrics/account/client/StatisticsServiceClient.java — Demonstrates inter-service communication using Spring Cloud Feign with circuit breaker fallback pattern for resilience.
• config/src/main/java/com/piggymetrics/config/ConfigApplication.java — Central configuration server using Spring Cloud Config; coordinates externalized configuration for all microservices.
• account-service/src/main/java/com/piggymetrics/account/config/ResourceServerConfig.java — Resource server security configuration; gates API endpoints with OAuth2 token validation.
• account-service/src/main/java/com/piggymetrics/account/service/AccountServiceImpl.java — Primary business logic layer for account operations; shows domain-driven design and service-layer patterns.
• config/src/main/resources/shared/application.yml — Centralized configuration properties shared across all services; defines service discovery, database, and logging settings.

Add a New REST Endpoint to Account Service

1. Define a new domain entity in account-service/src/main/java/com/piggymetrics/account/domain/ (e.g., Budget.java) (account-service/src/main/java/com/piggymetrics/account/domain/Budget.java)
2. Create a MongoDB repository extending MongoRepository in account-service/src/main/java/com/piggymetrics/account/repository/ (account-service/src/main/java/com/piggymetrics/account/repository/BudgetRepository.java)
3. Implement business logic in a service class following AccountServiceImpl pattern (account-service/src/main/java/com/piggymetrics/account/service/BudgetServiceImpl.java)
4. Add @RestController endpoints in AccountController or create BudgetController following existing patterns (account-service/src/main/java/com/piggymetrics/account/controller/BudgetController.java)
5. Add endpoint-specific security rules in ResourceServerConfig.authorizeRequests() (account-service/src/main/java/com/piggymetrics/account/config/ResourceServerConfig.java)
6. Write integration tests using AccountControllerTest as a template (account-service/src/test/java/com/piggymetrics/account/controller/BudgetControllerTest.java)

Add Inter-Service Communication via Feign Client

1. Create a new Feign client interface in account-service/src/main/java/com/piggymetrics/account/client/ (account-service/src/main/java/com/piggymetrics/account/client/NotificationServiceClient.java)
2. Define the Feign interface with @FeignClient(name='notification-service') and @GetMapping/@PostMapping methods (account-service/src/main/java/com/piggymetrics/account/client/NotificationServiceClient.java)
3. Create a fallback class implementing the interface (see StatisticsServiceClientFallback.java pattern) (account-service/src/main/java/com/piggymetrics/account/client/NotificationServiceClientFallback.java)
4. Inject the Feign client into your service and call it; configure circuit breaker thresholds in shared/account-service.yml (account-service/src/main/java/com/piggymetrics/account/service/AccountServiceImpl.java)

Add a New Microservice to the Ecosystem

1. Create a new Maven module (e.g., notification-service/) with pom.xml inheriting from parent piggymetrics POM (notification-service/pom.xml)
2. Bootstrap the service following AuthApplication.java pattern with @SpringBootApplication and @EnableResourceServer (notification-service/src/main/java/com/piggymetrics/notification/NotificationApplication.java)
3. Add service-specific configuration in config/src/main/resources/shared/notification-service.yml (config/src/main/resources/shared/notification-service.yml)
4. Create Dockerfile for containerization following existing service Dockerfile patterns (notification-service/Dockerfile)
5. Register the new service with Spring Cloud Config Server by defining bootstrap.yml in the service (notification-service/src/main/resources/bootstrap.yml)
6. Create Feign clients in existing services to call the new notification-service (see pattern in account-service/client/) (account-service/src/main/java/com/piggymetrics/account/client/NotificationServiceClient.java)

Extend OAuth2 Authentication with Custom Claims

1. Extend the User domain entity to include additional fields (e.g., roles, permissions) (auth-service/src/main/java/com/piggymetrics/auth/domain/User.java)
2. Modify CustomUserInfoTokenServices in account-service to extract custom claims from the JWT token (account-service/src/main/java/com/piggymetrics/account/service/security/CustomUserInfoTokenServices.java)
3. Update OAuth2AuthorizationConfig to include custom claims in the issued token (auth-service/src/main/java/com/piggymetrics/auth/config/OAuth2AuthorizationConfig.java)
4. Add fine-grained security rules in ResourceServerConfig using @PreAuthorize or custom authorities (account-service/src/main/java/com/piggymetrics/account/config/ResourceServerConfig.java)

1. Spring Cloud Config Server must be running and accessible before Account Service starts—bootstrap.yml will hang on missing Config Server. 2) OAuth2 requires Auth Service endpoint to be registered in Config Server; missing or misconfigured auth-server-url breaks CustomUserInfoTokenServices token validation. 3) Eureka Server must be running for Feign clients to discover Statistics Service; hardcoded fallbacks (StatisticsServiceClientFallback) mask discovery failures but don't eliminate them. 4) MongoDB connection string is likely in Config Server properties, not in bootstrap.yml—local dev requires running MongoDB or configuring a test in-memory instance. 5) RabbitMQ is required for Spring Cloud Bus (amqp dependency visible); missing RabbitMQ broker prevents config refresh events.

• Service Discovery (Eureka) — In account-service, @EnableEurekaClient auto-registers this service and enables Feign clients to discover Statistics Service by name rather than hardcoded URLs—critical for dynamic cloud environments.
• Feign Client + Fallback Pattern (Hystrix) — StatisticsServiceClient demonstrates how to make inter-service calls resilient; StatisticsServiceClientFallback ensures Account Service degrades gracefully if Statistics Service is unavailable rather than failing the request.
• OAuth2 Resource Server Token Validation — CustomUserInfoTokenServices validates JWT tokens from a centralized Auth Service, enabling role-based access control across independent microservices without each service needing direct Auth Service state.
• Spring Cloud Config Server (Externalized Configuration) — bootstrap.yml enables account-service to fetch application properties (database URLs, OAuth endpoints, API timeouts) from a centralized server without rebuilding the JAR, enabling true 12-factor app compliance.
• Distributed Request Tracing (Spring Cloud Sleuth) — spring-cloud-starter-sleuth auto-injects trace IDs into logs across Account, Statistics, and other services, enabling operators to follow a single user request through all microservices for debugging.
• Event-Driven Configuration Refresh (Spring Cloud Bus + RabbitMQ) — spring-cloud-starter-bus-amqp enables Config Server to broadcast /refresh events to all running instances without restarting services, reducing deployment friction in polyglot microservice clusters.
• Polyglot Persistence (MongoDB Document Model) — Account.java is stored as a MongoDB document with nested Savings and Items objects—this denormalization is appropriate for this bounded context, contrasting with typical SQL normalization and showing when NoSQL shines in microservices.

• spring-cloud/spring-cloud-microservices-example — Official Spring Cloud reference implementation showing the same patterns (Eureka, Config, Feign, Hystrix) in a simpler context for learning.
• Netflix/Hystrix — Fallback and circuit-breaker library used implicitly via spring-cloud-starter-openfeign; Piggy Metrics demonstrates its practical integration.
• eugenp/tutorials — Baeldung's Spring Cloud microservices tutorials cover the individual components (Feign, Eureka, OAuth2) used in this project in isolation.
• microservices-patterns/ftgo-application — Chris Richardson's reference microservices architecture showing saga patterns, event sourcing, and CQRS as evolved alternatives to Piggy Metrics' simpler HTTP-RPC style.
• GoogleCloudPlatform/spring-cloud-gcp — Cloud-native evolution of Spring Cloud patterns using GCP managed services (Datastore, Cloud Config) instead of self-hosted Eureka/Config Server.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for inter-service communication (AccountServiceClient & StatisticsServiceClient)

The account-service has Feign clients (AuthServiceClient, StatisticsServiceClient) with fallback implementations, but account-service/src/test/java/com/piggymetrics/account/client/StatisticsServiceClientFallbackTest.java only tests the fallback, not the actual client behavior or circuit breaker integration. This is critical for a microservices architecture where service-to-service calls can fail. Adding integration tests would catch communication issues early.

• [ ] Create account-service/src/test/java/com/piggymetrics/account/client/AuthServiceClientTest.java to test OAuth2 token exchange with auth-service
• [ ] Enhance StatisticsServiceClientFallbackTest.java with tests for successful client calls (not just fallback scenarios)
• [ ] Add timeout and retry behavior tests for both Feign clients
• [ ] Verify error handling when downstream services are unavailable

Add Testcontainers integration tests for MongoDB persistence across services

The repo uses spring-boot-starter-data-mongodb and has AccountRepositoryTest.java, but there's no evidence of containerized MongoDB testing. With multiple services (account-service, auth-service, statistics-service, notification-service) using MongoDB, Testcontainers would provide reliable, isolated test environments that mirror production. This prevents environment-dependent test failures.

• [ ] Add Testcontainers dependency to account-service/pom.xml and auth-service/pom.xml (MongoDB container)
• [ ] Refactor account-service/src/test/java/com/piggymetrics/account/repository/AccountRepositoryTest.java to use @Testcontainers and @Container annotations
• [ ] Create similar tests for auth-service/src/test (UserRepository tests)
• [ ] Document the approach in a test-setup section for other services to follow

Add GitHub Actions workflow for multi-service build and Docker image publishing

The repo has .travis.yml (legacy CI) but no GitHub Actions workflow. Given the microservices architecture with multiple Dockerfiles (account-service/Dockerfile, auth-service/Dockerfile, etc.), a GitHub Actions workflow should: (1) build each service independently, (2) run tests in parallel, (3) publish Docker images to a registry on release. This modernizes CI/CD and improves developer experience.

• [ ] Create .github/workflows/build-services.yml with matrix strategy for account-service, auth-service, statistics-service, notification-service, and config-server
• [ ] Each matrix job should run 'mvn clean test' for the service and build Docker image with service name tag
• [ ] Add separate workflow .github/workflows/publish-release.yml triggered on git tags to push images to Docker Hub/GitHub Container Registry
• [ ] Document Docker registry credentials setup in CONTRIBUTING.md or README.md

• Add integration tests for StatisticsServiceClient fallback behavior in account-service/src/test/java/com/piggymetrics/account/client/StatisticsServiceClientFallbackTest.java—currently only one test exists; add scenarios for timeout, 503, network error to verify resilience patterns.
• Implement missing test coverage for AccountService.java domain logic—AccountServiceTest.java exists but AccountServiceImpl.java has complex business logic (savings calculations, item validation) that should have explicit unit tests for edge cases (zero balance, currency conversion, time period boundaries).
• Document the inter-service communication contract between Account and Statistics services—add JavaDoc to StatisticsServiceClient methods and create examples in a new account-service/FEIGN_CLIENTS.md explaining how Feign clients work, fallback triggers, and timeout configuration in this codebase.

• Critical · Exposed Credentials in Environment Variables — .env, docker-compose.yml (environment variables). The docker-compose.yml references CONFIG_SERVICE_PASSWORD from environment variables (.env file), which is likely to contain hardcoded secrets. The .env file is present in the repository structure, indicating sensitive credentials may be version-controlled. Fix: Remove .env from version control immediately (add to .gitignore if not already). Use Docker secrets, external secret management (HashiCorp Vault, AWS Secrets Manager), or .env file patterns with .gitignore. Never commit credentials to the repository.
• High · Outdated Spring Cloud OAuth2 Dependency — account-service/pom.xml, auth-service/pom.xml. The pom.xml uses 'spring-cloud-starter-oauth2' which is deprecated and no longer maintained as of Spring Cloud 2020.0.0+. This dependency has known security vulnerabilities and should be migrated to Spring Security OAuth2. Fix: Replace spring-cloud-starter-oauth2 with spring-boot-starter-oauth2-resource-server and spring-boot-starter-oauth2-client. Update to Spring Boot 2.5+ and Spring Cloud 2021.0.0+ (or newer) which use the modern OAuth2 implementation.
• High · Unspecified Dependency Versions — account-service/pom.xml (parent pom). The pom.xml snippet shows incomplete dependency declarations without explicit version pins for critical security components like spring-boot-starter-security, spring-cloud-starter-oauth2, and others. This can lead to unpredictable security updates. Fix: Define explicit version ranges in the parent pom.xml for all dependencies. Consider using a Bill of Materials (BOM) like spring-cloud-dependencies to maintain consistency. Regularly audit dependencies using tools like OWASP Dependency-Check.
• High · RabbitMQ Service Exposed Without Authentication Configuration — docker-compose.yml (rabbitmq service). The docker-compose.yml exposes RabbitMQ management port (15672) without documented authentication. Default RabbitMQ credentials (guest/guest) are often left unchanged, allowing unauthorized access to message queues and sensitive financial data. Fix: Set strong RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS environment variables. Disable guest user access. Use TLS/SSL for RabbitMQ connections. Restrict port access to internal networks only via firewall rules.
• High · Missing HTTPS/TLS Configuration — docker-compose.yml (gateway service, port 80:4000). The gateway service exposes port 80 (HTTP) without evidence of HTTPS enforcement. For a financial application handling sensitive data, unencrypted communication is a critical risk. Fix: Enable HTTPS on the gateway with valid SSL/TLS certificates. Add HTTP to HTTPS redirect. Configure spring.server.ssl properties in application configuration. Use environment-specific secrets for SSL keystores.
• High · Eureka Registry Exposed Without Authentication — docker-compose.yml (registry service). The registry service (Eureka) is exposed on port 8761 without documented security configuration. Unauthorized service discovery can enable attackers to enumerate and target internal services. Fix: Enable Eureka authentication and configure it in the registry service. Restrict network access to the registry port via firewall rules. Use Spring Cloud Security to protect the Eureka dashboard and APIs.
• Medium · Insufficient Input Validation Architecture — account-service/src/main/java/com/piggymetrics/account/controller/, auth-service/src/main/java/com/piggymetrics/auth/controller/. While not visible in the snippets, the presence of AccountController, UserController, and other REST endpoints without explicit mention of validation frameworks suggests potential injection vulnerabilities (SQLi, XSS, NoSQL injection). Fix: Implement @Valid annotations with @NotNull, @Size, @Pattern for all request DTOs. Use Spring Security's built-in XSS protection. For MongoDB queries, use parameterized queries and avoid string concatenation. Sanitize all user inputs.
• Medium · Missing Security Headers Configuration — undefined. No explicit security header configuration visible in the bootstrap.yml or application configuration. This leaves the application Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.