auctiora/docs/INTELLIGENCE_FEATURES_SUMMARY.md

Intelligence Features Implementation Summary

Overview

This document summarizes the implementation of advanced intelligence features based on 15+ new GraphQL API fields discovered from the Troostwijk auction system.

New GraphQL Fields Integrated

HIGH PRIORITY FIELDS (Implemented)

1. followersCount (Integer) - Watch count showing bidder interest

   • Direct indicator of competition
   • Used for sleeper lot detection
   • Popularity level classification

2. estimatedFullPrice (Object: min/max cents)

   • Auction house's estimated value range
   • Used for bargain detection
   • Price vs estimate analytics

3. nextBidStepInCents (Long)

   • Exact bid increment from API
   • Precise next bid calculations
   • Better UX for bidding recommendations

4. condition (String)

   • Direct condition field from API
   • Better than extracting from attributes
   • Used in condition scoring

5. categoryInformation (Object)

   • Structured category with path
   • Better categorization and filtering
   • Category-based analytics

6. location (Object: city, countryCode, etc.)

   • Structured location data
   • Proximity filtering capability
   • Logistics cost calculation

MEDIUM PRIORITY FIELDS (Implemented)

7. biddingStatus (Enum) - Detailed bidding status
8. appearance (String) - Visual condition notes
9. packaging (String) - Packaging details
10. quantity (Long) - Lot quantity for bulk items
11. vat (BigDecimal) - VAT percentage
12. buyerPremiumPercentage (BigDecimal) - Buyer premium
13. remarks (String) - Viewing/pickup notes

Code Changes

1. Backend - Lot.java (Domain Model)

File: src/main/java/auctiora/Lot.java

Changes:

• Added 24 new fields to the Lot record
• Implemented 9 intelligence calculation methods:
  • calculateTotalCost() - Bid + VAT + Premium
  • calculateNextBid() - Using API increment
  • isBelowEstimate() - Bargain detection
  • isAboveEstimate() - Overvalued detection
  • getInterestToBidRatio() - Conversion rate
  • getPopularityLevel() - HIGH/MEDIUM/LOW/MINIMAL
  • isSleeperLot() - High interest, low bid
  • getEstimatedMidpoint() - Average of estimate range
  • getPriceVsEstimateRatio() - Price comparison metric

Example:

public boolean isSleeperLot() {
    return followersCount != null && followersCount > 10 && currentBid < 100;
}

public double calculateTotalCost() {
    double base = currentBid > 0 ? currentBid : 0;
    if (vat != null && vat > 0) {
        base += (base * vat / 100.0);
    }
    if (buyerPremiumPercentage != null && buyerPremiumPercentage > 0) {
        base += (base * buyerPremiumPercentage / 100.0);
    }
    return base;
}

2. Backend - AuctionMonitorResource.java (REST API)

File: src/main/java/auctiora/AuctionMonitorResource.java

New Endpoints Added:

1. GET /api/monitor/intelligence/sleepers - Sleeper lots (high interest, low bids)
2. GET /api/monitor/intelligence/bargains - Bargain lots (below estimate)
3. GET /api/monitor/intelligence/popular?level={HIGH|MEDIUM|LOW} - Popular lots
4. GET /api/monitor/intelligence/price-analysis - Price vs estimate statistics
5. GET /api/monitor/lots/{lotId}/intelligence - Detailed lot intelligence
6. GET /api/monitor/charts/watch-distribution - Follower count distribution

Enhanced Features:

• Updated insights endpoint to include sleeper, bargain, and popular insights
• Added intelligent filtering and sorting for intelligence data
• Integrated new fields into existing statistics

Example Endpoint:

@GET
@Path("/intelligence/sleepers")
public Response getSleeperLots(@QueryParam("minFollowers") @DefaultValue("10") int minFollowers) {
    var allLots = db.getAllLots();
    var sleepers = allLots.stream()
                          .filter(Lot::isSleeperLot)
                          .toList();

    return Response.ok(Map.of(
        "count", sleepers.size(),
        "lots", sleepers
    )).build();
}

3. Frontend - index.html (Intelligence Dashboard)

File: src/main/resources/META-INF/resources/index.html

New UI Components:

Intelligence Dashboard Widgets (3 new cards)

1. Sleeper Lots Widget

   • Purple gradient design
   • Shows count of high-interest, low-bid lots
   • Click to filter table

2. Bargain Lots Widget

   • Green gradient design
   • Shows count of below-estimate lots
   • Click to filter table

3. Popular/Hot Lots Widget

   • Orange gradient design
   • Shows count of high-follower lots
   • Click to filter table

Enhanced Closing Soon Table

New Columns Added:

1. Watchers - Follower count with color-coded badges

   • Red (50+ followers): High competition
   • Orange (21-50): Medium competition
   • Blue (6-20): Some interest
   • Gray (0-5): Minimal interest

2. Est. Range - Auction house estimate (€min-€max)

   • Shows "DEAL" badge if below estimate

3. Total Cost - True cost including VAT and premium

   • Hover tooltip shows breakdown
   • Purple color to stand out

JavaScript Functions Added:

• fetchIntelligenceData() - Fetches all intelligence metrics
• showSleeperLots() - Filters table to sleepers
• showBargainLots() - Filters table to bargains
• showPopularLots() - Filters table to popular
• Enhanced table rendering with smart badges

Example Code:

// Calculate total cost (including VAT and premium)
const currentBid = lot.currentBid || 0;
const vat = lot.vat || 0;
const premium = lot.buyerPremiumPercentage || 0;
const totalCost = currentBid * (1 + (vat/100) + (premium/100));

// Bargain indicator
const isBargain = estMin && currentBid < parseFloat(estMin);
const bargainBadge = isBargain ?
    '<span class="ml-1 text-xs bg-green-500 text-white px-1 rounded">DEAL</span>' : '';

Intelligence Features

1. Sleeper Lot Detection

Algorithm: followersCount > 10 AND currentBid < 100

Value Proposition:

• Identifies lots with high interest but low current bids
• Opportunity to bid strategically before price escalates
• Early indicator of undervalued items

Dashboard Display:

• Count shown in purple widget
• Click to filter table
• Purple "eye" icon

2. Bargain Detection

Algorithm: currentBid < estimatedMin

Value Proposition:

• Identifies lots priced below auction house estimate
• Clear signal of potential good deals
• Quantifiable value assessment

Dashboard Display:

• Count shown in green widget
• "DEAL" badge in table
• Click to filter table

3. Popularity Analysis

Algorithm: Tiered classification by follower count

• HIGH: > 50 followers
• MEDIUM: 21-50 followers
• LOW: 6-20 followers
• MINIMAL: 0-5 followers

Value Proposition:

• Predict competition level
• Identify trending items
• Adjust bidding strategy accordingly

Dashboard Display:

• Count shown in orange widget
• Color-coded badges in table
• Click to filter by level

4. True Cost Calculator

Algorithm: currentBid × (1 + VAT/100) × (1 + premium/100)

Value Proposition:

• Shows actual out-of-pocket cost
• Prevents budget surprises
• Enables accurate comparison across lots

Dashboard Display:

• Purple "Total Cost" column
• Hover tooltip shows breakdown
• Updated in real-time

5. Exact Bid Increment

Algorithm: Uses nextBidStepInCents from API, falls back to calculated increment

Value Proposition:

• No guesswork on next bid amount
• API-provided accuracy
• Better bidding UX

Implementation:

public double calculateNextBid() {
    if (nextBidStepInCents != null && nextBidStepInCents > 0) {
        return currentBid + (nextBidStepInCents / 100.0);
    } else if (bidIncrement != null && bidIncrement > 0) {
        return currentBid + bidIncrement;
    }
    return currentBid * 1.05; // Fallback: 5% increment
}

6. Price vs Estimate Analytics

Metrics:

• Total lots with estimates
• Count below estimate
• Count above estimate
• Average price vs estimate percentage

Value Proposition:

• Market efficiency analysis
• Auction house accuracy tracking
• Investment opportunity identification

API Endpoint: /api/monitor/intelligence/price-analysis

Visual Design

Color Scheme

• Purple: Sleeper lots, total cost (opportunity/value)
• Green: Bargains, deals (positive value)
• Orange/Red: Popular/hot lots (competition warning)
• Blue: Moderate interest (informational)
• Gray: Minimal interest (neutral)

Badge System

1. Watchers Badge: Color-coded by competition level
2. DEAL Badge: Green indicator for below-estimate
3. Time Left Badge: Red/yellow/green by urgency
4. Popularity Badge: Fire icon for hot lots

Interactive Elements

• Click widgets to filter table
• Hover for detailed tooltips
• Smooth scroll to table on filter
• Toast notifications for user feedback

Performance Considerations

API Optimization

• All intelligence data fetched in parallel
• Cached in dashboard state
• Minimal recalculation on render
• Efficient stream operations in backend

Frontend Optimization

• Batch DOM updates
• Lazy rendering for large tables
• Debounced filter operations
• CSS transitions for smooth UX

Testing Recommendations

Backend Tests

1. Test Lot intelligence methods with various inputs
2. Test API endpoints with mock data
3. Test edge cases (null values, zero bids, etc.)
4. Performance test with 10k+ lots

Frontend Tests

1. Test widget click handlers
2. Test table rendering with new columns
3. Test filter functionality
4. Test responsive design on mobile

Integration Tests

1. End-to-end flow: Scraper → DB → API → Dashboard
2. Real-time data refresh
3. Concurrent user access
4. Load testing

Future Enhancements

Phase 2 (Bid History)

• Implement bid_history table scraping
• Track bid changes over time
• Calculate bid velocity accurately
• Identify bid patterns

Phase 3 (ML Predictions)

• Predict final hammer price
• Recommend optimal bid timing
• Classify lot categories automatically
• Anomaly detection

Phase 4 (Mobile)

• React Native mobile app
• Push notifications
• Offline mode
• Quick bid functionality

Migration Guide

Database Migration (Required)

The new fields need to be added to the database schema:

-- Add to lots table
ALTER TABLE lots ADD COLUMN followers_count INTEGER DEFAULT 0;
ALTER TABLE lots ADD COLUMN estimated_min DECIMAL(12, 2);
ALTER TABLE lots ADD COLUMN estimated_max DECIMAL(12, 2);
ALTER TABLE lots ADD COLUMN next_bid_step_in_cents BIGINT;
ALTER TABLE lots ADD COLUMN condition TEXT;
ALTER TABLE lots ADD COLUMN category_path TEXT;
ALTER TABLE lots ADD COLUMN city_location TEXT;
ALTER TABLE lots ADD COLUMN country_code TEXT;
ALTER TABLE lots ADD COLUMN bidding_status TEXT;
ALTER TABLE lots ADD COLUMN appearance TEXT;
ALTER TABLE lots ADD COLUMN packaging TEXT;
ALTER TABLE lots ADD COLUMN quantity BIGINT;
ALTER TABLE lots ADD COLUMN vat DECIMAL(5, 2);
ALTER TABLE lots ADD COLUMN buyer_premium_percentage DECIMAL(5, 2);
ALTER TABLE lots ADD COLUMN remarks TEXT;
ALTER TABLE lots ADD COLUMN starting_bid DECIMAL(12, 2);
ALTER TABLE lots ADD COLUMN reserve_price DECIMAL(12, 2);
ALTER TABLE lots ADD COLUMN reserve_met BOOLEAN DEFAULT FALSE;
ALTER TABLE lots ADD COLUMN bid_increment DECIMAL(12, 2);
ALTER TABLE lots ADD COLUMN view_count INTEGER DEFAULT 0;
ALTER TABLE lots ADD COLUMN first_bid_time TEXT;
ALTER TABLE lots ADD COLUMN last_bid_time TEXT;
ALTER TABLE lots ADD COLUMN bid_velocity DECIMAL(5, 2);

Scraper Update (Required)

The external scraper (Python/Playwright) needs to extract the new fields from GraphQL:

# Extract from __NEXT_DATA__ JSON
followers_count = lot_data.get('followersCount')
estimated_min = lot_data.get('estimatedFullPrice', {}).get('min', {}).get('cents')
estimated_max = lot_data.get('estimatedFullPrice', {}).get('max', {}).get('cents')
next_bid_step = lot_data.get('nextBidStepInCents')
condition = lot_data.get('condition')
# ... etc

Deployment Steps

1. Stop the monitor service
2. Run database migrations
3. Update scraper to extract new fields
4. Deploy updated monitor JAR
5. Restart services
6. Verify data populating in dashboard

Performance Metrics

Expected Performance

• Intelligence Data Fetch: < 100ms for 10k lots
• Table Rendering: < 200ms with all new columns
• Widget Update: < 50ms
• API Response Time: < 500ms

Resource Usage

• Memory: +50MB for intelligence calculations
• Database: +2KB per lot (new columns)
• Network: +10KB per dashboard refresh

Documentation

• Integration Flowchart: docs/INTEGRATION_FLOWCHART.md
• API Documentation: Auto-generated from JAX-RS annotations
• Database Schema: wiki/DATABASE_ARCHITECTURE.md
• GraphQL Fields: wiki/EXPERT_ANALITICS.sql

---

Implementation Date: December 2025 Version: 2.1 Status: ✅ Complete - Ready for Testing Next Steps:

1. Deploy to staging environment
2. Run integration tests
3. Update scraper to extract new fields
4. Deploy to production