Quotes Demo

A Spring Boot WebFlux application that fetches random quotes from an external API and finds similar quotes using semantic search (embeddings via Ollama + pgvector).

User stories covered:

• Display a random quote, retrieved from a remote source https://dummyjson.com/quotes. Every request should respond with another random quote.
• Find quotes comparable to the currently shown quote.

Key features: Lazy Embedding

When you request a random quote, the quote is returned immediately while embedding generation happens in the background. This means:

• No Delay - quotes are shown instantly
• Automatic indexing - every quote is automatically embedded for similarity search - the more quotes are shown - the more quotes are available for similarity search.
• Eventually searchable - after a few seconds, the quote becomes available for semantic similarity search.

It also utilizes Java Backend Coding Technology, for more information see https://github.com/siy/coding-technology

Prerequisites

• Docker
• Java 25+ (for local development only)

Quick start

First time setup

Copy sample env file and adjust if needed:

cp .env.sample .env

./setup.sh

This starts PostgreSQL and Ollama and pulls the necessary embedding model (±280MB).

Option 1: Local Development (fast iterations)

./dev.sh

Option 2: Full Docker (CI/CD style)

./full.sh

API Endpoints

• GET /quote - Get a random quote
• GET /quote/{id}/similar - Find similar quotes
• Swagger UI: http://localhost:8080/
• Healthchecks
  • Common: http://localhost:8080/actuator/health
  • Application specific: http://localhost:8080/actuator/health/application
  • Custom metric: http://localhost:8080/actuator/metrics/quote.fetch
  • Build info: http://localhost:8080/actuator/info

Running Tests

Unit tests:

./mvnw test

Integration tests (requires Docker for Testcontainers):

./mvnw verify

Stopping

docker compose down

Or to clean the docker app and networks:

docker compose --profile full down

License

This project is licensed under the Apache License 2.0.

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.