Fix mock tests

docs/INTEGRATION_FLOWCHART.md

@@ -0,0 +1,393 @@
+# Auctiora Intelligence Integration Flowchart
+
+## Complete System Integration Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    COMPLETE SYSTEM INTEGRATION DIAGRAM                       │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────────────────┐
+│  PHASE 1: EXTERNAL SCRAPER (Python/Playwright) - ARCHITECTURE-TROOSTWIJK    │
+└──────────────────────────────────────────────────────────────────────────────┘
+                                      │
+        ┌─────────────────────────────┼─────────────────────────────┐
+        ▼                             ▼                             ▼
+  [Listing Pages]              [Auction Pages]              [Lot Pages]
+  /auctions?page=N             /a/auction-id                /l/lot-id
+        │                             │                             │
+        │ Extract URLs                │ Parse __NEXT_DATA__         │ Parse __NEXT_DATA__
+        ├────────────────────────────▶│ JSON (GraphQL)              │ JSON (GraphQL)
+        │                             │                             │
+        │                             ▼                             ▼
+        │                    ┌────────────────┐           ┌────────────────┐
+        │                    │ INSERT auctions│           │  INSERT lots   │
+        │                    │ to SQLite      │           │  INSERT images │
+        │                    └────────────────┘           │  (URLs only)   │
+        │                             │                   └────────────────┘
+        │                             │                            │
+        └─────────────────────────────┴────────────────────────────┘
+                                      ▼
+                            ┌──────────────────┐
+                            │  SQLITE DATABASE │
+                            │  output/cache.db │
+                            └──────────────────┘
+                                      │
+                    ┌─────────────────┼─────────────────┐
+                    ▼                 ▼                 ▼
+            [auctions table]   [lots table]    [images table]
+            - auction_id       - lot_id        - id
+            - title            - auction_id    - lot_id
+            - location         - title         - url
+            - lots_count       - current_bid   - local_path
+            - closing_time     - bid_count     - downloaded=0
+                               - closing_time
+                               - followersCount ⭐ NEW
+                               - estimatedMin ⭐ NEW
+                               - estimatedMax ⭐ NEW
+                               - nextBidStepInCents ⭐ NEW
+                               - condition ⭐ NEW
+                               - vat ⭐ NEW
+                               - buyerPremiumPercentage ⭐ NEW
+                               - quantity ⭐ NEW
+                               - biddingStatus ⭐ NEW
+                               - remarks ⭐ NEW
+                                      │
+┌─────────────────────────────────────┴─────────────────────────────────────┐
+│  PHASE 2: MONITORING & PROCESSING (Java) - THIS PROJECT                   │
+└────────────────────────────────────────────────────────────────────────────┘
+                                      │
+                    ┌─────────────────┼─────────────────┐
+                    ▼                 ▼                 ▼
+         [TroostwijkMonitor]  [DatabaseService]  [ScraperDataAdapter]
+                    │                 │                 │
+                    │ Read lots       │ Query lots      │ Transform data
+                    │ every hour      │ Import images   │ TEXT → INTEGER
+                    │                 │                 │ "€123" → 123.0
+                    └─────────────────┴─────────────────┘
+                                      │
+            ┌─────────────────────────┼─────────────────────────┐
+            ▼                         ▼                         ▼
+   [Bid Monitoring]         [Image Processing]        [Closing Alerts]
+   Check API every 1h       Download images           Check < 5 min
+            │                         │                         │
+            │ New bid?                │ Process via             │ Time critical?
+            ├─[YES]──────────┐        │ ObjectDetection         ├─[YES]────┐
+            │                 │        │                         │          │
+            ▼                 │        ▼                         │          │
+   [Update current_bid]       │  ┌──────────────────┐          │          │
+   in database                │  │ YOLO Detection   │          │          │
+                              │  │ OpenCV DNN       │          │          │
+                              │  └──────────────────┘          │          │
+                              │         │                       │          │
+                              │         │ Detect objects        │          │
+                              │         ├─[vehicle]            │          │
+                              │         ├─[furniture]          │          │
+                              │         ├─[machinery]          │          │
+                              │         │                       │          │
+                              │         ▼                       │          │
+                              │  [Save labels to DB]            │          │
+                              │  [Estimate value]               │          │
+                              │         │                       │          │
+                              │         │                       │          │
+                              └─────────┴───────────────────────┴──────────┘
+                                                │
+┌───────────────────────────────────────────────┴────────────────────────────┐
+│  PHASE 3: INTELLIGENCE LAYER ⭐ NEW - PREDICTIVE ANALYTICS                │
+└────────────────────────────────────────────────────────────────────────────┘
+                                                │
+                              ┌─────────────────┴─────────────────┐
+                              ▼                                   ▼
+                   [Intelligence Engine]              [Analytics Calculations]
+                              │                                   │
+          ┌───────────────────┼──────────────┐                   │
+          ▼                   ▼              ▼                   │
+   [Sleeper Detection]  [Bargain Finder] [Popularity Tracker]   │
+   High followers       Price < estimate  Watch count analysis   │
+   Low current bid      Opportunity       Competition level      │
+          │                   │              │                   │
+          │                   │              │                   │
+          └───────────────────┴──────────────┴───────────────────┘
+                                                │
+                              ┌─────────────────┴─────────────────┐
+                              ▼                                   ▼
+                   [Total Cost Calculator]              [Next Bid Calculator]
+                   Current bid × (1 + VAT/100)         Current bid + increment
+                   × (1 + premium/100)                 (from API or calculated)
+                              │                                   │
+                              └─────────────────┬─────────────────┘
+                                                │
+┌───────────────────────────────────────────────┴────────────────────────────┐
+│  PHASE 4: NOTIFICATION SYSTEM - USER INTERACTION TRIGGERS                  │
+└────────────────────────────────────────────────────────────────────────────┘
+                                                │
+                              ┌─────────────────┴─────────────────┐
+                              ▼                                   ▼
+                   [NotificationService]                [User Decision Points]
+                              │                                   │
+          ┌───────────────────┼───────────────────┐              │
+          ▼                   ▼                   ▼              │
+   [Desktop Notify]    [Email Notify]     [Priority Level]       │
+   Windows/macOS/      Gmail SMTP          0=Normal              │
+   Linux system        (FREE)              1=High                │
+   tray                                                           │
+          │                   │                   │              │
+          └───────────────────┴───────────────────┘              │
+                              │                                  │
+                              ▼                                  ▼
+                    ┌──────────────────┐              ┌──────────────────┐
+                    │ USER INTERACTION │              │ TRIGGER EVENTS:  │
+                    │ NOTIFICATIONS    │              │                  │
+                    └──────────────────┘              └──────────────────┘
+                              │                                  │
+          ┌───────────────────┼───────────────────┐             │
+          ▼                   ▼                   ▼             │
+┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
+│ 1. BID CHANGE    │ │ 2. OBJECT        │ │ 3. CLOSING       │ │
+│                  │ │    DETECTED       │ │    ALERT         │ │
+│ "Nieuw bod op    │ │                  │ │                  │ │
+│  kavel 12345:    │ │ "Lot contains:   │ │ "Kavel 12345     │ │
+│  €150 (was €125)"│ │  - Vehicle       │ │  sluit binnen    │ │
+│                  │ │  - Machinery     │ │  5 min."         │ │
+│ Priority: NORMAL │ │  Est: €5000"     │ │ Priority: HIGH   │ │
+│                  │ │                  │ │                  │ │
+│ Action needed:   │ │ Action needed:   │ │ Action needed:   │ │
+│ ▸ Place bid?     │ │ ▸ Review item?   │ │ ▸ Place final    │ │
+│ ▸ Monitor?       │ │ ▸ Confirm value? │ │   bid?           │ │
+│ ▸ Ignore?        │ │ ▸ Add to watch?  │ │ ▸ Let expire?    │ │
+└──────────────────┘ └──────────────────┘ └──────────────────┘ │
+          │                   │                   │             │
+          └───────────────────┴───────────────────┴─────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  INTELLIGENCE NOTIFICATIONS ⭐ NEW                                          │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  4. SLEEPER LOT ALERT                                                       │
+│     "Lot 12345: 25 watchers, only €50 bid - Opportunity!"                  │
+│     Action: ▸ Place strategic bid  ▸ Monitor competition  ▸ Set alert     │
+│                                                                              │
+│  5. BARGAIN DETECTED                                                        │
+│     "Lot 67890: Current €200, Estimate €400-€600 - Below estimate!"        │
+│     Action: ▸ Bid now  ▸ Research comparable  ▸ Add to watchlist          │
+│                                                                              │
+│  6. HIGH COMPETITION WARNING                                                │
+│     "Lot 11111: 75 watchers, bid velocity 5/hr - Strong competition"       │
+│     Action: ▸ Review strategy  ▸ Set max bid  ▸ Find alternatives         │
+│                                                                              │
+│  7. TOTAL COST NOTIFICATION                                                 │
+│     "True cost: €500 bid + €105 VAT (21%) + €50 premium (10%) = €655"      │
+│     Action: ▸ Confirm budget  ▸ Adjust bid  ▸ Calculate logistics         │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Intelligence Dashboard Flow
+
+```mermaid
+flowchart TD
+    subgraph P1["PHASE 1: DATA COLLECTION"]
+        A1[GraphQL API] --> A2[Scraper Extracts 15+ New Fields]
+        A2 --> A3[followersCount]
+        A2 --> A4[estimatedMin/Max]
+        A2 --> A5[nextBidStepInCents]
+        A2 --> A6[vat + buyerPremiumPercentage]
+        A2 --> A7[condition + biddingStatus]
+
+        A3 & A4 & A5 & A6 & A7 --> DB[(SQLite Database)]
+    end
+
+    DB --> P2_Entry
+
+    subgraph P2["PHASE 2: INTELLIGENCE PROCESSING"]
+        P2_Entry[Lot.java Model] --> Intelligence[Intelligence Methods]
+
+        Intelligence --> Sleeper[isSleeperLot<br/>High followers, low bid]
+        Intelligence --> Bargain[isBelowEstimate<br/>Price < estimate]
+        Intelligence --> Popular[getPopularityLevel<br/>Watch count tiers]
+        Intelligence --> Cost[calculateTotalCost<br/>Bid + VAT + Premium]
+        Intelligence --> NextBid[calculateNextBid<br/>API increment]
+    end
+
+    P2_Entry --> API_Layer
+
+    subgraph API["PHASE 3: REST API ENDPOINTS"]
+        API_Layer[AuctionMonitorResource] --> E1[/intelligence/sleepers]
+        API_Layer --> E2[/intelligence/bargains]
+        API_Layer --> E3[/intelligence/popular]
+        API_Layer --> E4[/intelligence/price-analysis]
+        API_Layer --> E5[/lots/:id/intelligence]
+        API_Layer --> E6[/charts/watch-distribution]
+    end
+
+    E1 & E2 & E3 & E4 & E5 & E6 --> Dashboard
+
+    subgraph UI["PHASE 4: INTELLIGENCE DASHBOARD"]
+        Dashboard[index.html] --> Widget1[Sleeper Lots Widget<br/>Opportunities]
+        Dashboard --> Widget2[Bargain Lots Widget<br/>Below Estimate]
+        Dashboard --> Widget3[Popular Lots Widget<br/>High Competition]
+        Dashboard --> Table[Enhanced Table<br/>Watchers | Est. Range | Total Cost]
+
+        Table --> Badges[Smart Badges:<br/>DEAL | Watch Count | Time Left]
+    end
+
+    Widget1 --> UserAction
+    Widget2 --> UserAction
+    Widget3 --> UserAction
+    Table --> UserAction
+
+    subgraph Actions["PHASE 5: USER ACTIONS"]
+        UserAction[User Decision] --> Bid[Place Strategic Bid]
+        UserAction --> Monitor[Add to Watchlist]
+        UserAction --> Research[Research Comparables]
+        UserAction --> Calculate[Budget Calculator]
+    end
+```
+
+## Key Intelligence Features
+
+### 1. Follower/Watch Count Analytics
+- **Data Source**: `followersCount` from GraphQL API
+- **Intelligence Value**:
+  - Predict lot popularity before bidding wars
+  - Calculate interest-to-bid conversion rates
+  - Identify "sleeper" lots (high followers, low bids)
+  - Alert on sudden interest spikes
+
+### 2. Price vs Estimate Analysis
+- **Data Source**: `estimatedMin`, `estimatedMax` from GraphQL API
+- **Intelligence Value**:
+  - Identify bargains: `currentBid < estimatedMin`
+  - Identify overvalued: `currentBid > estimatedMax`
+  - Build pricing models per category
+  - Track auction house estimate accuracy
+
+### 3. True Cost Calculator
+- **Data Source**: `vat`, `buyerPremiumPercentage` from GraphQL API
+- **Intelligence Value**:
+  - Calculate total cost: `bid × (1 + VAT/100) × (1 + premium/100)`
+  - Budget planning with accurate all-in costs
+  - Compare true costs across lots
+  - Prevent bidding surprises
+
+### 4. Exact Bid Increment
+- **Data Source**: `nextBidStepInCents` from GraphQL API
+- **Intelligence Value**:
+  - Show exact next bid amount
+  - No calculation errors
+  - Better UX for bidding recommendations
+  - Strategic bid placement
+
+### 5. Structured Location & Category
+- **Data Source**: `cityLocation`, `countryCode`, `categoryPath` from GraphQL API
+- **Intelligence Value**:
+  - Filter by distance from user
+  - Calculate pickup logistics costs
+  - Category-based analytics
+  - Regional pricing trends
+
+## Integration Hooks & Timing
+
+| Event                          | Frequency         | Trigger                    | Notification Type          | User Action Required   |
+|--------------------------------|-------------------|----------------------------|----------------------------|------------------------|
+| **Sleeper lot detected**       | On data refresh   | followers > 10, bid < €100 | Desktop + Email            | Review opportunity     |
+| **Bargain detected**           | On data refresh   | bid < estimatedMin         | Desktop + Email            | Consider bidding       |
+| **High competition**           | On data refresh   | followers > 50             | Desktop                    | Review strategy        |
+| **Bid change detected**        | Every 1 hour      | Monitor detects higher bid | Desktop + Email            | Place counter-bid?     |
+| **Closing soon (< 30 min)**    | When detected     | Time-based check           | Desktop + Email            | Review lot             |
+| **Closing imminent (< 5 min)** | When detected     | Time-based check           | Desktop + Email (HIGH)     | Final bid decision     |
+| **Object detected**            | On image process  | YOLO finds objects         | Desktop + Email            | Confirm identification |
+| **True cost calculated**       | On page load      | User views lot             | Dashboard display          | Budget confirmation    |
+
+## API Endpoints Reference
+
+### Intelligence Endpoints
+- `GET /api/monitor/intelligence/sleepers` - Returns high-interest, low-bid lots
+- `GET /api/monitor/intelligence/bargains` - Returns lots priced below estimate
+- `GET /api/monitor/intelligence/popular?level={HIGH|MEDIUM|LOW}` - Returns lots by popularity
+- `GET /api/monitor/intelligence/price-analysis` - Returns price vs estimate statistics
+- `GET /api/monitor/lots/{lotId}/intelligence` - Returns detailed intelligence for specific lot
+
+### Chart Endpoints
+- `GET /api/monitor/charts/watch-distribution` - Returns follower count distribution
+- `GET /api/monitor/charts/country-distribution` - Returns geographic distribution
+- `GET /api/monitor/charts/category-distribution` - Returns category distribution
+- `GET /api/monitor/charts/bidding-trend?hours=24` - Returns time series data
+
+## Dashboard Intelligence Widgets
+
+### Sleeper Lots Widget
+- **Color**: Purple gradient
+- **Icon**: Eye (fa-eye)
+- **Metric**: Count of lots with followers > 10 and bid < €100
+- **Action**: Click to filter table to sleeper lots only
+
+### Bargain Lots Widget
+- **Color**: Green gradient
+- **Icon**: Tag (fa-tag)
+- **Metric**: Count of lots where current bid < estimated minimum
+- **Action**: Click to filter table to bargain lots only
+
+### Popular/Hot Lots Widget
+- **Color**: Orange gradient
+- **Icon**: Fire (fa-fire)
+- **Metric**: Count of lots with followers > 20
+- **Action**: Click to filter table to popular lots only
+
+## Enhanced Table Features
+
+### New Columns
+1. **Watchers** - Shows follower count with color-coded badges:
+   - 50+ followers: Red (high competition)
+   - 21-50 followers: Orange (medium competition)
+   - 6-20 followers: Blue (some interest)
+   - 0-5 followers: Gray (minimal interest)
+
+2. **Est. Range** - Shows auction house estimate: `€min-€max`
+   - Displays "DEAL" badge if current bid < estimate
+
+3. **Total Cost** - Shows true cost including VAT and buyer premium:
+   - Hover tooltip shows breakdown: `Including VAT (21%) + Premium (10%)`
+
+### Smart Indicators
+- **DEAL Badge**: Green badge when `currentBid < estimatedMin`
+- **Watch Count Badge**: Color-coded by competition level
+- **Urgency Badge**: Time-based coloring (< 10 min = red)
+
+## Technical Implementation
+
+### Backend (Java)
+- **File**: `src/main/java/auctiora/Lot.java`
+  - Added 24 new fields from GraphQL API
+  - Added 9 intelligence calculation methods
+  - Immutable record with Lombok `@With` annotation
+
+- **File**: `src/main/java/auctiora/AuctionMonitorResource.java`
+  - Added 6 new REST API endpoints
+  - Enhanced insights with sleeper/bargain/popular detection
+  - Added watch distribution chart endpoint
+
+### Frontend (HTML/JavaScript)
+- **File**: `src/main/resources/META-INF/resources/index.html`
+  - Added 3 intelligence widgets with click handlers
+  - Enhanced closing soon table with 3 new columns
+  - Added `fetchIntelligenceData()` function
+  - Added smart badges and color coding
+  - Added total cost calculator display
+
+## Future Enhancements
+
+1. **Bid History Table** - Track bid changes over time
+2. **Comparative Analytics** - Compare similar lots across auctions
+3. **Machine Learning** - Predict final hammer price based on patterns
+4. **Geographic Filtering** - Distance-based sorting and filtering
+5. **Email Alerts** - Custom alerts for sleepers, bargains, etc.
+6. **Mobile App** - Push notifications for time-critical events
+7. **Bid Automation** - Auto-bid up to maximum with increment logic
+
+---
+
+**Last Updated**: December 2025
+**Version**: 2.1
+**Author**: Auctiora Intelligence Team

docs/INTELLIGENCE_FEATURES_SUMMARY.md

@@ -0,0 +1,422 @@
+# 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**:
+```java
+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**:
+```java
+@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**:
+```javascript
+// 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**:
+```java
+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:
+
+```sql
+-- 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:
+
+```python
+# 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