394 lines
25 KiB
Markdown
394 lines
25 KiB
Markdown
# 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
|