Quality and Troubleshooting

Validate behavior and inspect generated documentation.

The project uses Maven verification, JaCoCo, Javadoc, OpenAPI export, and GitHub Pages assembly as its main quality path.

Testing

Run the full verification build:

./mvnw clean verify

The test suite covers:

  • authenticated dashboard access and unauthenticated rejection
  • public health endpoint access and denied-by-default behavior
  • OpenAPI JSON/YAML generation and Bearer JWT metadata
  • local Swagger UI availability when documentation is enabled
  • dashboard aggregation and downstream success/failure behavior
  • circuit-breaker open-state behavior
  • DTO serialization and structured error responses
  • package boundaries with ArchUnit

Testcontainers is intentionally not used because the project has no database, broker, or containerized external dependency where it would add useful signal.

Coverage

JaCoCo runs during verify and writes HTML to:

target/site/jacoco/index.html

Current bundle gates:

  • instruction coverage: 70%
  • branch coverage: 50%

Generated coverage artifacts are ignored and must not be committed.

Open Published Coverage

Javadoc

Generate Javadoc locally:

./mvnw javadoc:javadoc

Open the generated output:

target/site/apidocs/index.html

Javadoc is also generated in CI and published to GitHub Pages.

Open Published Javadoc

GitHub Pages Artifact Structure

CI assembles Pages content under target/pages before upload and deployment.

Route Source
/Landing page from .github/pages/index.html
/user-guide/HTML User Guide from .github/pages/user-guide/
/javadoc/Generated Javadoc from target/site/apidocs
/coverage/Generated JaCoCo report from target/site/jacoco
/api/openapi.jsonGenerated OpenAPI JSON from the running BFF
/api/openapi.yamlGenerated OpenAPI YAML from the running BFF
/swagger-ui/Generated static Swagger UI assets assembled from Springdoc

Generated Pages artifacts are not committed.

Troubleshooting

Dashboard returns 401

Generate a new token with scripts/create-local-jwt.ps1. Confirm the app uses the local profile or matching BFF_JWT_SECRET, BFF_JWT_ISSUER, and BFF_JWT_AUDIENCE values.

Dashboard returns an empty product list

Check whether the product service is running on http://localhost:8082 or whether the Compose service product-service is healthy. The BFF intentionally falls back to an empty recommendation list when product calls fail.

Dashboard returns Guest User

Check whether the user service is running on http://localhost:8081 or whether the Compose service user-service is healthy. The BFF intentionally falls back to a safe placeholder user when user calls fail.

Swagger UI is unavailable

Swagger UI is disabled in the default profile. Run with SPRING_PROFILES_ACTIVE=local or set SPRINGDOC_SWAGGER_UI_ENABLED=true.

OpenAPI endpoints are unavailable

OpenAPI endpoints are disabled in the default profile. Run with SPRING_PROFILES_ACTIVE=local or set SPRINGDOC_API_DOCS_ENABLED=true.

Port 8080, 8081, or 8082 is already in use

Stop the process using the port, or adjust Compose port mappings and matching downstream base URL environment variables.