Skip to main content

Developer Guide

This guide helps contributors extend AuctioHub safely and consistently.

Repository Structure​

  • App Router route trees for public, user, and admin experiences.
  • API handlers grouped by domain (auctions, bids, chat, payments, admin).
  • Data access layer with model wrappers around SQL queries.
  • Shared UI components and domain utilities.

Coding Conventions​

  • Keep route handlers thin; move business logic into services.
  • Keep validation close to API boundary and repeat critical checks in service layer.
  • Use explicit types for request and response payloads.
  • Prefer small, testable functions for auction and payment state logic.

Model And API Patterns​

  • Map SQL rows to domain interfaces in a dedicated layer.
  • Avoid leaking raw database field naming into UI payloads.
  • Keep response contracts stable; add versioning strategy for breaking changes.

UI Component Patterns​

  • Keep auction session components resilient to polling delays.
  • Isolate bid form validation and submission state.
  • Ensure role-based UI behavior mirrors backend authorization outcomes.

Auction Logic Hotspots​

Review these areas carefully before modifying:

  • Bid validation and amount comparison.
  • Winner determination at auction close.
  • Ban side effects and winner recomputation.
  • Payment completion transitions and idempotency guards.

Add A New Admin Endpoint Safely​

  1. Define exact authorization requirement.
  2. Add request validation.
  3. Implement service logic with audit event emission.
  4. Add tests for allowed and denied access.
  5. Document side effects in API reference.

Add A New Notification Event​

  1. Define event type and payload schema.
  2. Emit event from domain service at authoritative state transition.
  3. Ensure user stream query returns it in expected order.
  4. Add UI rendering fallback for unknown event types.

Testing Strategy​

  • Unit tests for bidding, winner selection, and payment rules.
  • Integration tests for API route contracts.
  • Role-based access tests for admin and dashboard routes.
  • Smoke tests for end-to-end auction and payment flows.

Change Management Checklist​

  • Docs updated for changed behavior.
  • Backward compatibility reviewed.
  • Migration scripts reviewed when schema changes.
  • Observability updates included for new critical flows.