Opportunity Detection & Recommendations

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;

import org.springframework.data.neo4j.core.schema.Id;
import org.springframework.data.neo4j.core.schema.Node;
import org.springframework.data.neo4j.core.schema.Relationship;
import org.springframework.data.neo4j.core.schema.RelationshipId;
import org.springframework.data.neo4j.core.schema.RelationshipProperties;
import org.springframework.data.neo4j.core.schema.TargetNode;

@Node("Customer")
public class Customer {

    @Id
    private String id;

    private String name;

    @Relationship(type = "WORKS_AT", direction = Relationship.Direction.OUTGOING)
    private Company company;

    @Relationship(type = "PURCHASED", direction = Relationship.Direction.OUTGOING)
    private List<Purchase> purchases = new ArrayList<>();

    protected Customer() {
    }

    public Customer(String id, String name, Company company) {
        this.id = id;
        this.name = name;
        this.company = company;
    }

    public void purchase(Product product, int quantity, LocalDate date) {
        purchases.add(new Purchase(product, quantity, date));
    }

    public String getId() { return id; }
    public String getName() { return name; }
}

@Node("Company")
public class Company {

    @Id
    private String id;
    private String name;
    private String segment;

    protected Company() {
    }

    public Company(String id, String name, String segment) {
        this.id = id;
        this.name = name;
        this.segment = segment;
    }
}

@Node("Product")
public class Product {

    @Id
    private String id;
    private String title;

    @Relationship(type = "IN_CATEGORY", direction = Relationship.Direction.OUTGOING)
    private Category category;

    protected Product() {
    }

    public Product(String id, String title, Category category) {
        this.id = id;
        this.title = title;
        this.category = category;
    }
}

@Node("Category")
public class Category {

    @Id
    private String id;
    private String name;

    protected Category() {
    }

    public Category(String id, String name) {
        this.id = id;
        this.name = name;
    }
}

@Node("Contact")
public class Contact {

    @Id
    private String id;
    private String name;

    @Relationship(type = "WORKS_AT", direction = Relationship.Direction.OUTGOING)
    private Company company;

    @Relationship(type = "KNOWS", direction = Relationship.Direction.OUTGOING)
    private List<Contact> knows = new ArrayList<>();

    protected Contact() {
    }

    public Contact(String id, String name, Company company) {
        this.id = id;
        this.name = name;
        this.company = company;
    }
}

@RelationshipProperties
public class Purchase {

    @RelationshipId
    private Long id;

    @TargetNode
    private Product product;

    private int quantity;
    private LocalDate purchasedAt;

    protected Purchase() {
    }

    public Purchase(Product product, int quantity, LocalDate purchasedAt) {
        this.product = product;
        this.quantity = quantity;
        this.purchasedAt = purchasedAt;
    }
}

import org.springframework.boot.ApplicationRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.neo4j.core.Neo4jClient;

@Configuration
public class RecommendationSchema {

    private static final List<String> STATEMENTS = List.of(
        "CREATE CONSTRAINT customer_id IF NOT EXISTS FOR (c:Customer) REQUIRE c.id IS UNIQUE",
        "CREATE CONSTRAINT product_id IF NOT EXISTS FOR (p:Product) REQUIRE p.id IS UNIQUE",
        "CREATE CONSTRAINT company_id IF NOT EXISTS FOR (c:Company) REQUIRE c.id IS UNIQUE",
        "CREATE CONSTRAINT category_id IF NOT EXISTS FOR (c:Category) REQUIRE c.id IS UNIQUE",
        "CREATE CONSTRAINT contact_id IF NOT EXISTS FOR (c:Contact) REQUIRE c.id IS UNIQUE",
        "CREATE INDEX purchased_at IF NOT EXISTS FOR ()-[p:PURCHASED]-() ON (p.purchasedAt)");

    @Bean
    ApplicationRunner createRecommendationSchema(Neo4jClient client) {
        return args -> STATEMENTS.forEach(statement -> client.query(statement).run());
    }
}

@Service
public class PurchaseWriter {

    private final Neo4jClient client;

    public PurchaseWriter(Neo4jClient client) {
        this.client = client;
    }

    @Transactional
    public void record(String customerId, String productId, int quantity, LocalDate date) {
        client.query("""
                MATCH (c:Customer {id: $customerId}), (p:Product {id: $productId})
                MERGE (c)-[purchase:PURCHASED]->(p)
                  ON CREATE SET purchase.quantity = $quantity, purchase.purchasedAt = $date
                  ON MATCH SET purchase.quantity = purchase.quantity + $quantity
                """)
            .bind(customerId).to("customerId")
            .bind(productId).to("productId")
            .bind(quantity).to("quantity")
            .bind(date).to("date")
            .run();
    }
}

public record RecommendationPage(String customerId, int page, int size, List<ProductScore> items) {
}

@Service
public class RecommendationService {

    static final int MAX_PAGE_SIZE = 50;

    private final RecommendationRepository repository;

    public RecommendationService(RecommendationRepository repository) {
        this.repository = repository;
    }

    @Cacheable(cacheNames = "recommendations", key = "#customerId + ':' + #page + ':' + #size")
    @Transactional(readOnly = true)
    public RecommendationPage recommend(String customerId, int page, int size) {
        int boundedSize = Math.min(Math.max(size, 1), MAX_PAGE_SIZE);
        int boundedPage = Math.max(page, 0);
        var items = repository.recommendations(customerId, (long) boundedPage * boundedSize, boundedSize);
        return new RecommendationPage(customerId, boundedPage, boundedSize, items);
    }
}

@RestController
@RequestMapping("/customers/{customerId}")
public class RecommendationController {

    private final RecommendationService recommendations;

    public RecommendationController(RecommendationService recommendations) {
        this.recommendations = recommendations;
    }

    @GetMapping("/recommendations")
    public RecommendationPage recommendations(@PathVariable String customerId,
                                              @RequestParam(defaultValue = "0") int page,
                                              @RequestParam(defaultValue = "10") int size) {
        return recommendations.recommend(customerId, page, size);
    }
}

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.within;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.data.neo4j.core.Neo4jClient;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.neo4j.Neo4jContainer;

@Testcontainers
@SpringBootTest
class RecommendationIntegrationTest {

    @Container
    @ServiceConnection
    static final Neo4jContainer NEO4J = new Neo4jContainer("neo4j:2026.10.1")
        .withEnv("NEO4J_PLUGINS", "[\"graph-data-science\", \"apoc\"]");

    @Autowired
    Neo4jClient client;

    @Autowired
    SimilarityService similarity;

    @Autowired
    RecommendationService recommendations;

    @Autowired
    CustomerRepository customers;

    @BeforeEach
    void loadDataset() {
        client.query("MATCH (n) DETACH DELETE n").run();
        client.query("""
            CREATE (ada:Customer {id: 'ada', name: 'Ada'})
            CREATE (bo:Customer {id: 'bo', name: 'Bo'})
            CREATE (cy:Customer {id: 'cy', name: 'Cy'})
            CREATE (m1:Product {id: 'nine-lives', title: 'Nine Lives'})
            CREATE (m2:Product {id: 'red-horizon', title: 'Red Horizon'})
            CREATE (m3:Product {id: 'glass-orchard', title: 'Glass Orchard'})
            CREATE (ada)-[:PURCHASED {quantity: 1}]->(m1)
            CREATE (ada)-[:PURCHASED {quantity: 1}]->(m2)
            CREATE (bo)-[:PURCHASED {quantity: 1}]->(m1)
            CREATE (bo)-[:PURCHASED {quantity: 1}]->(m2)
            CREATE (bo)-[:PURCHASED {quantity: 1}]->(m3)
            CREATE (cy)-[:PURCHASED {quantity: 1}]->(m3)
            """).run();
    }

    @Test
    void plainCypherRecommendsTheProductOnlyBoBought() {
        var items = customers.alsoBought("ada", 0, 10);

        assertThat(items).extracting(ProductScore::title).containsExactly("Glass Orchard");
    }

    @Test
    void similarityIsWrittenAsSimilarRelationships() {
        var run = similarity.recomputeSimilarity();

        assertThat(run.relationshipsWritten()).isEqualTo(4);
        var adaToBo = client
            .query("MATCH (:Customer {id: 'ada'})-[s:SIMILAR]->(:Customer {id: 'bo'}) RETURN s.score AS score")
            .fetchAs(Double.class)
            .mappedBy((typeSystem, record) -> record.get("score").asDouble())
            .one()
            .orElseThrow();
        assertThat(adaToBo).isCloseTo(2.0 / 3.0, within(1e-6));
        var adaToCy = client
            .query("MATCH (:Customer {id: 'ada'})-[s:SIMILAR]->(:Customer {id: 'cy'}) RETURN count(s) AS n")
            .fetchAs(Long.class)
            .mappedBy((typeSystem, record) -> record.get("n").asLong())
            .one()
            .orElseThrow();
        assertThat(adaToCy).isZero();
    }

    @Test
    void servesRecommendationsFromPersistedSimilarity() {
        similarity.recomputeSimilarity();

        var forAda = recommendations.recommend("ada", 0, 10);
        assertThat(forAda.items()).extracting(ProductScore::title).containsExactly("Glass Orchard");
        assertThat(forAda.items().get(0).score()).isCloseTo(2.0 / 3.0, within(1e-6));

        var forCy = recommendations.recommend("cy", 0, 10);
        assertThat(forCy.items()).extracting(ProductScore::title)
            .containsExactlyInAnyOrder("Nine Lives", "Red Horizon");
    }

    @Test
    void secondPageOfCyIsEmptyAndPageSizeIsBounded() {
        similarity.recomputeSimilarity();

        assertThat(recommendations.recommend("cy", 1, 2).items()).isEmpty();
        assertThat(recommendations.recommend("cy", 0, 1_000).size()).isEqualTo(50);
    }
}