Skip to main content

System Architecture

AuctioHub is built as a Next.js application with API-driven backend flows, JWT-based sessions, and a PostgreSQL data layer.

High-Level Architecture​

Browser Clients
  -> Next.js App Router UI
    -> API Route Handlers / Server Actions
      -> Domain Services (Auctions, Bids, Chat, Payments, Admin)
        -> PostgreSQL + External Services (Google OAuth, Stripe, Cloudinary)

Frontend Architecture​

  • Next.js App Router organizes public, user, and admin routes.
  • Client components handle interactive auction views and chat polling.
  • Server components fetch initial auction state and user context.
  • Middleware guards private route trees before rendering.

Backend API Architecture​

  • API routes handle auth-aware CRUD and state transitions.
  • Domain rules enforce bid validity, moderation rules, and payment eligibility.
  • Services publish notification events for user-visible updates.
  • Admin operations use stricter authorization and audit-oriented behavior.

Authentication And Authorization​

  • Sign-in uses Google OAuth through NextAuth.
  • Sessions are represented by JWT and resolved server-side.
  • Middleware restricts dashboard and admin routes.
  • Role checks are repeated in admin APIs for defense in depth.

Realtime And Polling Model​

  • Auction chat uses polling to fetch new messages.
  • Client deduplication avoids repeated messages in noisy refresh windows.
  • Auction state updates (current bid, time remaining) are polled at bounded intervals.

Notifications And Events​

  • Notification events are generated for auction and payment lifecycle milestones.
  • User-facing notification stream is ordered by event time.
  • Delayed visibility can occur under polling intervals or cache latency.

Critical Data Flows​

Bid Placement​

  1. Client submits bid amount.
  2. Server validates auth, auction state, ban status, and amount.
  3. Valid bid is persisted and current winner context updates.
  4. Notification event is emitted.

Auction Finalization And Payment​

  1. Auction closes by timer or moderation action.
  2. Winner is computed from valid bid history.
  3. Winner receives payment access.
  4. Completion endpoint finalizes paid or penalty outcome idempotently.

Reliability Notes​

  • Validation must always be server-authoritative.
  • Winner recomputation is required after moderation actions that remove bidders.
  • Payment completion handlers should be idempotent to avoid duplicate state transitions.