How klarline/gavel works
Gavel is a surplus-food and item auction platform. Buyers discover auctions, bid in real time, and receive updates; sellers manage shops and listings, while auction winners proceed through payment. The map also includes user identity, recurring auction scheduling, reviews and uploads, and the AI recommendation and assistant capabilities documented in the README. Source excerpts establish several service-level calls; cross-service event and frontend relationships use README evidence where documented, so unsampled wiring is not inferred.
Main entry points: App.tsx Web application · KafkaPublisher.java Kafka events · main.py AI API and indexing · AuctionService.java Auction and bidding
Components 26
Buyer and seller experience
- Web application
frontend/src/App.tsx
Listings and auctions
- Shops and reviews
shop-service/src/main/java/com/gavel/shop/service/ShopService.java - Shop endpoints
shop-service/src/main/java/com/gavel/shop/controller/ShopController.java - Image uploads
shop-service/src/main/java/com/gavel/shop/storage/S3Uploader.java - Auction endpoints
auction-service/src/main/java/com/gavel/auction/controller/AuctionController.java - Auction and bidding
auction-service/src/main/java/com/gavel/auction/service/AuctionService.java - Recurring auctions
auction-service/src/main/java/com/gavel/auction/service/AuctionTemplateService.java - Bid history
bid-service/src/main/java/com/gavel/bid/controller/BidController.java - Bid records
bid-service/src/main/java/com/gavel/bid/service/BidService.java
Identity and payments
- User accounts
user-service/src/main/java/com/gavel/user/controller/UserController.java - Profiles and watchlists
user-service/src/main/java/com/gavel/user/service/UserService.java - Payment processing
payment-service/src/main/java/com/gavel/payment/service/PaymentService.java - Payment endpoints
payment-service/src/main/java/com/gavel/payment/controller/PaymentController.java
Events and notifications
- Kafka events
shared/src/main/java/com/gavel/shared/kafka/KafkaPublisher.java - Notification delivery
notification-service/src/main/java/com/gavel/notification/hub/NotificationHub.java - Notification history
notification-service/src/main/java/com/gavel/notification/controller/NotificationController.java
AI capabilities
- AI descriptions
shop-service/src/main/java/com/gavel/shop/service/AiService.java - Auction recommendations
ai-service/recommender.py - RAG assistant
ai-service/chatbot.py - AI API and indexing
ai-service/main.py - Vector retrieval
ai-service/vector_store.py
Other components
- Buyers and sellers
- Platform data stores
- S3 or MinIO
- LLM provider
- WebSocket clients
Connections 38
- Buyers and sellers → Web application: use
README.md - Web application → User accounts: authenticate
README.md - Web application → Shop endpoints: manage listings
README.md - Web application → Auction endpoints: browse and bid
README.md - Web application → Payment endpoints: pay winners
README.md - Web application → Notification history: view notifications
README.md - Web application → Auction recommendations: request picks
README.md - Web application → RAG assistant: ask questions
README.md - User accounts → Profiles and watchlists: delegates
user-service/src/main/java/com/gavel/user/controller/UserController.java - Profiles and watchlists → Platform data stores: persists users
README.md - Shop endpoints → Shops and reviews: delegates
shop-service/src/main/java/com/gavel/shop/controller/ShopController.java - Shops and reviews → Platform data stores: persists listings
README.md - Shops and reviews → Image uploads: uploads images
shop-service/src/main/java/com/gavel/shop/service/ShopService.java - Image uploads → S3 or MinIO: stores images
README.md - Shop endpoints → AI descriptions: requests description
README.md - AI descriptions → LLM provider: generates text
shop-service/src/main/java/com/gavel/shop/service/AiService.java - Auction endpoints → Auction and bidding: delegates
auction-service/src/main/java/com/gavel/auction/controller/AuctionController.java - Auction and bidding → Platform data stores: stores auctions
README.md - Recurring auctions → Auction and bidding: creates auctions
auction-service/src/main/java/com/gavel/auction/service/AuctionTemplateService.java - Auction and bidding → Kafka events: publishes bid and close
auction-service/src/main/java/com/gavel/auction/service/AuctionService.java - Kafka events → Bid records: dispatches bid events
README.md - Bid history → Bid records: delegates
bid-service/src/main/java/com/gavel/bid/controller/BidController.java - Bid records → Platform data stores: records history
README.md - Kafka events → Payment processing: dispatches close events
README.md - Payment endpoints → Payment processing: delegates
payment-service/src/main/java/com/gavel/payment/controller/PaymentController.java - Payment processing → Platform data stores: persists payments
README.md - Payment processing → Kafka events: publishes payment outcomes
payment-service/src/main/java/com/gavel/payment/service/PaymentService.java - Kafka events → Notification delivery: dispatches updates
README.md - Notification delivery → WebSocket clients: pushes WebSocket
README.md - Notification history → Notification delivery: reads metrics
notification-service/src/main/java/com/gavel/notification/controller/NotificationController.java - Notification history → Platform data stores: reads notification history
notification-service/src/main/java/com/gavel/notification/controller/NotificationController.java - Auction recommendations → Platform data stores: scores auctions
README.md - AI API and indexing → Auction recommendations: serves recommendations
README.md - AI API and indexing → RAG assistant: serves chat
README.md - RAG assistant → Vector retrieval: retrieves context
README.md - AI API and indexing → Vector retrieval: indexes events
ai-service/main.py - AI API and indexing → LLM provider: uses configured model
README.md - Kafka events → AI API and indexing: streams item and review events
README.md