Auctions

Overview

The Auction feature allows organizers to create and manage online auctions. This includes setting up auction items, configuring bidding rules, scheduling start and end times, and monitoring auction performance. The auction system supports various auction types and provides real-time bidding capabilities.

Auction Architecture

The auction functionality is organized across several directories:

src/
├── widgets/
│   └── Create-auction/
│       ├── CreateAuctionButton.tsx        # Main auction creation button
│       └── CreateAuctionButton.module.css # Button styling
└── features/
    └── [auction features to be implemented]

Create Auction Button

The primary entry point for creating new auctions:

src/widgets/Create-auction/CreateAuctionButtton.tsx:3

import styles from './CreateAuctionButton.module.css';

export default function CreateAuctionbUTTON() {
  return (
    <div className={styles.cabContainer}>
      {/* Button content */}
    </div>
  )
}

The auction creation widget is currently a placeholder. The full implementation will include a form modal or dedicated page for auction setup.

Auction Data Model

Based on typical auction platform requirements, the auction model should include:

Core Fields
Bidding Configuration
Items
Settings

interface Auction {
  id: number;
  organizer_id: number;              // User who created the auction
  title: string;                      // Auction name/title
  description: string;                // Detailed description
  status: AuctionStatus;              // Current state
  
  start_time: Date;                   // When auction begins
  end_time: Date;                     // When auction ends
  timezone: string;                   // Auction timezone
  
  created_at: Date;
  updated_at: Date;
}

enum AuctionStatus {
  DRAFT = 'draft',           // Being created
  SCHEDULED = 'scheduled',   // Ready to start
  LIVE = 'live',            // Currently active
  ENDED = 'ended',          // Auction finished
  CANCELLED = 'cancelled'    // Cancelled by organizer
}

interface BiddingConfig {
  starting_bid: number;               // Minimum opening bid
  bid_increment: number;              // Minimum bid increase
  reserve_price?: number;             // Hidden minimum price
  buy_now_price?: number;             // Instant purchase price
  
  allow_proxy_bidding: boolean;       // Auto-bid up to max
  auto_extend: boolean;               // Extend if bid near end
  extension_time: number;             // Minutes to extend
  
  max_bid_per_user?: number;          // Limit per bidder
}

interface AuctionItem {
  id: number;
  auction_id: number;
  
  title: string;
  description: string;
  category: string;
  
  images: string[];                   // Image URLs
  thumbnail: string;                  // Primary image
  
  starting_bid: number;
  current_bid: number;
  bid_count: number;
  highest_bidder_id?: number;
  
  condition?: string;                 // New, Used, etc.
  quantity: number;                   // Number of items
  
  metadata: Record<string, any>;      // Custom fields
}

interface AuctionSettings {
  visibility: 'public' | 'private' | 'invite_only';
  require_approval: boolean;          // Approve bidders?
  allow_guest_bidding: boolean;       // Require account?
  
  currency: string;                   // USD, EUR, etc.
  language: string;                   // en, es, fr, etc.
  
  notification_settings: {
    notify_on_bid: boolean;
    notify_on_outbid: boolean;
    notify_before_end: number;        // Minutes
  };
  
  shipping_options?: {
    enabled: boolean;
    cost: number;
    international: boolean;
  };
}

Creating an Auction

The auction creation flow should follow these steps:

Basic Information

Collect auction title, description, and category:

const basicInfoSchema = [
  {
    id: "title",
    label: "Auction Title",
    type: "text",
    placeholder: "Enter auction title",
    fieldValidators: [
      { type: "required" },
      { type: "minLength", constraints: { minLength: 5 } },
      { type: "maxLength", constraints: { maxLength: 100 } }
    ]
  },
  {
    id: "description",
    label: "Description",
    type: "textarea",
    placeholder: "Describe your auction...",
    fieldValidators: [
      { type: "required" },
      { type: "minLength", constraints: { minLength: 20 } }
    ]
  }
]

Schedule & Duration

Set auction timing:

const scheduleSchema = [
  {
    id: "start_time",
    label: "Start Time",
    type: "datetime-local",
    fieldValidators: [
      { type: "required" },
      { type: "futureDate" }
    ]
  },
  {
    id: "end_time",
    label: "End Time",
    type: "datetime-local",
    fieldValidators: [
      { type: "required" },
      { type: "afterStartDate" }
    ]
  }
]

Add Items

Add auction items with images and details:

const itemSchema = [
  {
    id: "item_title",
    label: "Item Title",
    type: "text",
    fieldValidators: [{ type: "required" }]
  },
  {
    id: "starting_bid",
    label: "Starting Bid",
    type: "number",
    fieldValidators: [
      { type: "required" },
      { type: "min", constraints: { min: 0 } }
    ]
  },
  {
    id: "images",
    label: "Item Images",
    type: "file",
    multiple: true,
    accept: "image/*"
  }
]

Configure Bidding

Set bidding rules and parameters:

const biddingSchema = [
  {
    id: "bid_increment",
    label: "Minimum Bid Increment",
    type: "number",
    defaultValue: 10,
    fieldValidators: [
      { type: "required" },
      { type: "min", constraints: { min: 1 } }
    ]
  },
  {
    id: "auto_extend",
    label: "Auto-extend on Late Bids",
    type: "checkbox"
  }
]

Review & Publish

Review all information and publish or save as draft:

const handlePublish = async (status: 'draft' | 'scheduled') => {
  const auctionData = {
    ...basicInfo,
    ...schedule,
    items,
    bidding_config: biddingConfig,
    status
  };
  
  await apiPOST('/auctions', {
    body: JSON.stringify(auctionData)
  });
}

Auction Creation Form

Implementation pattern for the auction creation form:

import { useState } from 'react';
import useFormEngine from '@app/hooks/useFormEngine';
import { Button } from '@shared/ui/Button/Button';

const STEPS = [
  { title: 'Basic Info', schema: basicInfoSchema },
  { title: 'Schedule', schema: scheduleSchema },
  { title: 'Items', schema: itemSchema },
  { title: 'Bidding Rules', schema: biddingSchema },
  { title: 'Review', schema: [] }
];

export function CreateAuctionForm() {
  const [currentStep, setCurrentStep] = useState(0);
  const [auctionData, setAuctionData] = useState({});
  
  const currentSchema = STEPS[currentStep].schema;
  const { formData, onChange, errors, validate } = useFormEngine(currentSchema);
  
  const handleNext = () => {
    if (validate()) {
      setAuctionData(prev => ({ ...prev, ...formData }));
      setCurrentStep(prev => prev + 1);
    }
  };
  
  const handleBack = () => {
    setCurrentStep(prev => prev - 1);
  };
  
  return (
    <div className={styles.formContainer}>
      <StepIndicator current={currentStep} steps={STEPS} />
      
      <form className={styles.form}>
        {currentSchema.map(field => (
          <TextField
            key={field.id}
            {...field}
            value={formData[field.id] ?? ''}
            onChange={(e) => onChange(e, field.id)}
            error={!!errors[field.id]}
            helperText={errors[field.id]}
          />
        ))}
      </form>
      
      <div className={styles.actions}>
        {currentStep > 0 && (
          <Button variant="secondary" onClick={handleBack}>
            Back
          </Button>
        )}
        
        {currentStep < STEPS.length - 1 ? (
          <Button variant="primary" onClick={handleNext}>
            Next
          </Button>
        ) : (
          <Button variant="primary" onClick={handlePublish}>
            Publish Auction
          </Button>
        )}
      </div>
    </div>
  );
}

Auction Management

Once created, auctions can be managed through various actions:

Edit Auction

Modify auction details before it goes live. Once live, only certain fields can be edited (description, images) to maintain bidding integrity.

Monitor Bidding

Real-time view of bids, bidders, and auction performance. See bid history and current highest bidder.

Manage Bidders

Approve/reject bidders for private auctions, block problematic users, and send messages to participants.

End/Cancel Auction

Manually end an auction early or cancel it. Cancelling requires notifying all bidders.

Auction Lifecycle

Auctions progress through defined states:

State Transitions

Draft → Scheduled

Auction is complete and ready to start at scheduled time.Requirements:

All required fields completed
At least one item added
Start time in the future
End time after start time

Scheduled → Live

Automatically triggered when current time reaches start_time.Actions:

Send notifications to subscribers
Enable bidding functionality
Start countdown timer

Live → Ended

Automatically triggered when current time reaches end_time, or extended if auto-extend is enabled.Actions:

Close bidding
Determine winners
Send winner notifications
Process payments

Any → Cancelled

Organizer cancels the auction.Actions:

Notify all participants
Refund any deposits
Record cancellation reason

Real-time Bidding

Implement WebSocket connection for live auction updates:

websocket-client.ts

class AuctionWebSocket {
  private ws: WebSocket;
  
  connect(auctionId: number) {
    this.ws = new WebSocket(`${WS_URL}/auctions/${auctionId}`);
    
    this.ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      
      switch (data.type) {
        case 'new_bid':
          this.handleNewBid(data.bid);
          break;
        case 'auction_ending_soon':
          this.handleEndingSoon(data.time_remaining);
          break;
        case 'auction_ended':
          this.handleAuctionEnded(data.winner);
          break;
      }
    };
  }
  
  placeBid(amount: number) {
    this.ws.send(JSON.stringify({
      type: 'place_bid',
      amount
    }));
  }
}

Permission Checks

Before allowing auction creation, verify user permissions:

const canCreateAuction = () => {
  const { user } = useAuthStore();
  
  if (!user || !user.is_onboarded) {
    return { allowed: false, reason: 'Complete onboarding first' };
  }
  
  // Check from onboarding data
  if (user.is_suspended) {
    return { allowed: false, reason: 'Account suspended' };
  }
  
  if (!user.can_create_auction) {
    return { allowed: false, reason: 'Permission denied' };
  }
  
  if (user.active_auctions >= user.max_active_auctions) {
    return { 
      allowed: false, 
      reason: `Maximum ${user.max_active_auctions} active auctions` 
    };
  }
  
  return { allowed: true };
};

Best Practices

Auction Setup

Provide clear guidance for each form field
Allow saving draft auctions to complete later
Validate all data before allowing publish
Preview auction as bidders will see it

Image Management

Support multiple images per item
Generate thumbnails automatically
Compress images for faster loading
Maximum file size limits (5MB per image)

Bidding Rules

Set reasonable bid increments
Consider auto-extend to prevent sniping
Clearly display all rules to bidders
Prevent bid manipulation

Security

Validate all auction data on backend
Prevent price manipulation
Rate limit bid submissions
Audit all auction modifications

API Endpoints

/auctions

POST

Create a new auctionRequest Body:

{
  "title": "Vintage Watch Collection",
  "description": "Rare vintage watches from the 1950s",
  "start_time": "2026-03-15T10:00:00Z",
  "end_time": "2026-03-22T10:00:00Z",
  "status": "scheduled",
  "bidding_config": {
    "starting_bid": 100,
    "bid_increment": 10,
    "auto_extend": true
  },
  "items": [
    {
      "title": "Rolex Submariner 1956",
      "starting_bid": 5000,
      "images": ["url1", "url2"]
    }
  ]
}

Response:

{
  "id": 1,
  "status": "scheduled",
  "created_at": "2026-03-07T15:00:00Z"
}

/auctions/:id

GET

Get auction details

/auctions/:id

PATCH

Update auction (restricted based on status)

/auctions/:id

DELETE

Delete draft auction or cancel live auction

/auctions/:id/bids

GET

Get bid history for an auction

/auctions/:id/bids

POST

Place a bid on an auctionRequest Body:

{
  "amount": 5100,
  "item_id": 1
}

Get Started

Components

Features

Architecture

Development

Overview

Auction Architecture

Create Auction Button

Auction Data Model

Creating an Auction

Auction Creation Form

Auction Management

Edit Auction

Monitor Bidding

Manage Bidders

End/Cancel Auction

Auction Lifecycle

State Transitions

Real-time Bidding

Permission Checks

Best Practices

API Endpoints

Build docs developers (and LLMs) love

Get Started

Components

Features

Architecture

Development

​Overview

​Auction Architecture

​Create Auction Button

​Auction Data Model

​Creating an Auction

​Auction Creation Form

​Auction Management

Edit Auction

Monitor Bidding

Manage Bidders

End/Cancel Auction

​Auction Lifecycle

​State Transitions

​Real-time Bidding

​Permission Checks

​Best Practices

​API Endpoints

Build docs developers (and LLMs) love

Overview

Auction Architecture

Create Auction Button

Auction Data Model

Creating an Auction

Auction Creation Form

Auction Management

Auction Lifecycle

State Transitions

Real-time Bidding

Permission Checks

Best Practices

API Endpoints