Phase 1 Schema Changes

Phase 1 Schema Changes

This document details the schema changes required for Phase 1 MCP tool enhancements.

Overview

Phase 1 adds three key tool enhancements:

1. Store analytics for purchase history
2. Venue-type filtering for offers
3. Points balance API integration

Schema Changes Required

1. Offer Node - New Property

Property: venue_type

• Type: String
• Values: "grocery", "convenience", "airport", "gas_station", "pharmacy", "restaurant"
• Optional: Yes (defaults to "grocery" if not specified)
• Purpose: Enable filtering of offers by venue type for location-specific recommendations

2. New Index

Index: offer_venue_type

• Node Label: Offer
• Property: venue_type
• Purpose: Performance optimization for venue-type filtering queries

Implementation Details

Schema Update (schema.go)

The index is automatically created by the schema initialization:

{
    name:  "offer_venue_type",
    query: "CREATE INDEX offer_venue_type IF NOT EXISTS FOR (o:Offer) ON (o.venue_type)",
}

Model Updates (offer.go)

type Offer struct {
    OfferID   string    `json:"offer_id"`
    Title     string    `json:"title"`
    Points    int       `json:"points"`
    Start     time.Time `json:"start"`
    End       time.Time `json:"end"`
    Priority  int       `json:"priority,omitempty"`
    VenueType string    `json:"venue_type,omitempty"` // NEW FIELD
}

Data Migration

For Existing Databases

Run the migration script to add venue_type to existing Offer nodes:

cat scripts/migrations/001_add_venue_type_to_offers.cypher | cypher-shell

The migration script:

1. Analyzes offer titles and descriptions for keywords
2. Assigns appropriate venue types
3. Defaults to “grocery” for unmatched offers
4. Creates the index if not already present
5. Provides a verification report

For New Databases

The schema initialization will create the index automatically. New offers should include the venue_type property when created.

Store Analytics (No Schema Changes)

The store analytics feature requires no schema changes. It leverages the existing PURCHASED_AT relationship between User and Retailer nodes, which already contains:

• times - Number of visits
• total_spent - Total amount spent
• last - Last visit datetime

Points Balance API (No Schema Changes)

The points balance integration is an external API and requires no Neo4j schema changes.

Verification

After running migrations, verify the changes:

// Check index exists
SHOW INDEXES
YIELD name, labelsOrTypes, properties
WHERE name = 'offer_venue_type'

// Check venue_type distribution
MATCH (o:Offer)
RETURN o.venue_type as venue_type, count(*) as count
ORDER BY count DESC

// Test venue-type filtering
MATCH (o:Offer {venue_type: 'airport'})
RETURN count(o) as airport_offers

Backward Compatibility

• Reading: Queries without venue_type filter continue to work unchanged
• Writing: New offer creation supports optional venue_type field
• Migration: Existing offers without venue_type will be assigned defaults via migration script

Performance Impact

• Index Creation: One-time cost, negligible for typical offer volumes (<100k nodes)
• Query Performance: Filtering by venue_type will use the index for O(log n) lookups
• Storage: Minimal (~20 bytes per offer for the property)

Integration Testing

Comprehensive integration tests have been added for all Phase 1 features to ensure proper functionality and data integrity.

Test Coverage

Store Analytics Tests (pkg/tools/integration_test/phase1_test.go):

• TestGetUserPurchaseHistoryWithStoreAnalytics - Verifies store analytics aggregation
• TestGetUserPurchaseHistoryWithoutStoreAnalytics - Ensures analytics not included when not requested
• TestStoreAnalyticsEdgeCases - Tests users with no stores, single store, etc.

Venue-Type Filtering Tests (pkg/tools/integration_test/phase1_test.go):

• TestGetActiveOffersWithVenueTypeFilter - Tests filtering by each venue type
• TestGetActiveOffersWithMultipleFilters - Combines venue-type with other filters

Points API Tests (pkg/points/client_test.go):

• TestGetBalance - Tests balance retrieval with mock HTTP server
• TestGetBalanceError - Tests error handling (404, timeout)
• TestGetRedemptionOptions - Tests redemption options retrieval

Running Integration Tests

Run all integration tests:

go test ./pkg/tools/integration_test/... -v

Run only Phase 1 tests:

go test ./pkg/tools/integration_test/... -v -run "^Test.*Phase1|TestGetUserPurchaseHistoryWithStoreAnalytics|TestGetActiveOffersWithVenueType"

Run Points client tests:

go test ./pkg/points/... -v

Test Data

The integration tests use extended fixtures that include:

• 5 offers with diverse venue types (grocery, convenience, airport, gas_station)
• User-retailer visit relationships with times and total_spent for analytics
• Multiple eligibility relationships to test filtering combinations

See internal/graph/repository/fixtures/fixtures.go for complete test data setup.

Verifying Phase 1 Functionality

After running migrations, verify all Phase 1 features work correctly:

# 1. Run integration tests
make test

# 2. Start server locally
make run ENV=local

# 3. Test store analytics via MCP
# (Use MCP client to call get_user_purchase_history with include_store_analytics=true)

# 4. Test venue-type filtering
# (Use MCP client to call get_active_offers with venue_type="airport")

# 5. Test points balance (requires POINTS_API_KEY env var)
# (Use MCP client to call get_points_balance with user_id)

Continuous Integration

All Phase 1 integration tests are included in the standard test suite and will run automatically in CI/CD pipelines via:

make test