KitabBid — Campus C2C Textbook Marketplace & Dynamic English Auction System

KitabBid is an enterprise-grade Consumer-to-Consumer (C2C) campus e-commerce platform engineered to facilitate peer-to-peer academic textbook circulation, competitive note bidding, and trusted exchange across university colleges.

Developed as a flagship capstone for the Tribhuvan University (TU) B.Sc. CSIT curriculum (CSC370: E-Commerce), the platform addresses the high recurring costs of prescribed textbooks and out-of-print study materials by connecting senior and junior students within college circles.

⚡ Architectural Overview & System Flow

sequenceDiagram
    autonumber
    participant Buyer as Student Buyer
    participant Client as Browser (SignalR Client)
    participant Hub as ASP.NET Core SignalR Hub
    participant Server as Kestrel / MVC Controller
    participant Worker as Background Closer Worker
    participant PG as PostgreSQL 16 (MVCC xmin)
    participant Gateway as Payment Gateway (eSewa / Khalti)

    Buyer->>Client: Place Real-Time Bid (Rs. 1,500)
    Client->>Hub: Invoke Bid Submission
    Hub->>Server: Process Bid Transaction
    Server->>PG: Validate Increment & Optimistic Concurrency (xmin)
    alt Bid Accepted
        PG-->>Server: Persist New Highest Bid
        Server->>Hub: Broadcast Updated Price & Extended Timer
        Hub-->>Client: Live UI Update (All Connected Peers)
    else Concurrency Collision (Higher Simultaneous Bid)
        PG-->>Server: DbUpdateConcurrencyException
        Server-->>Client: Prompt Instant Refresh & Higher Bid
    end

    Note over Worker,PG: Auction Closing & Escrow Checkout
    Worker->>PG: Check Expired Auctions (AuctionEndTime <= UtcNow)
    Worker->>PG: Lock Concluded Auction & Assign Winning Buyer
    Buyer->>Gateway: Escrow Payment (HMAC-SHA256 Signed / Khalti Lookup)
    Gateway-->>Server: Digital Transaction Verified
    Server->>PG: Mark Order as "Escrow Held"
    Note over Buyer,Server: 4-Digit Campus Hand-off OTP Verification

⚡ Core Engineering Highlights

1. Dynamic English Auction Engine with Real-Time Bidding (SignalR)

• Ascending Bid Increment Rule: Implements automated minimum bid calculation where every subsequent bid must satisfy BidAmount >= CurrentHighestBid + MinimumIncrement.
• Anti-Sniping Soft-Close Protection: If an aggressive bid is placed within the final 2 minutes of an active auction, the closing window automatically extends by 2 additional minutes, preventing automated bot sniping.
• Low-Latency WebSocket Broadcasts: Leverages ASP.NET Core SignalR hubs to push live price updates, bidding history events, and synchronized countdown timers to all peer viewers without page refreshes.
• Background Daemon Lifecycle: Includes an AuctionClosingWorker background service continuously monitoring concluding auctions, locking final bids, and notifying winning participants.

2. High-Performance Relational Tier & Concurrency Safety

• PostgreSQL 16 Multi-Version Concurrency Control (MVCC): Utilizes native xmin transaction system columns mapped via Entity Framework Core 10. Simultaneous bids automatically detect conflicting modifications through DbUpdateConcurrencyException, protecting database integrity without heavy table-level locking.
• Strict Idempotency: Configured filtered unique database indexes on payment transaction references (TransactionUuid), safeguarding the platform against duplicate payment execution and double-spend attacks.

3. Digital Escrow & Physical Campus Hand-off Protocol

• Dual Wallet Integration:
  • eSewa ePay v2: Form-based redirection generating cryptographic HMAC-SHA256 signatures across total_amount, transaction_uuid, and product_code, validated upon callback.
  • Khalti v2: Server-to-server REST initiation (/epayment/initiate/) and verification (/epayment/lookup/) utilizing a typed HttpClientFactory client.
• Campus Safe Hand-off: Payments remain in platform escrow while buyer and seller coordinate physical inspection on campus. Release of funds requires a two-sided verification protocol using student roll numbers and a one-time 4-digit hand-off OTP.

🛠️ Technology Stack Breakdown

| Architectural Tier | Technologies Deployed | | :--- | :--- | | Application Framework | ASP.NET Core MVC (.NET 10.0 SDK), C# 12 | | Real-Time Layer | ASP.NET Core SignalR, WebSockets | | Relational Database | PostgreSQL 16, Entity Framework Core 10 (Npgsql) | | Concurrency Control | PostgreSQL native xmin optimistic concurrency tokens | | Payment & Security | eSewa ePay v2 (HMAC-SHA256), Khalti v2 REST, ASP.NET Core Identity | | Presentation Tier | Razor Views (.cshtml), Bootstrap 5, Custom CSS Tokens |

🔗 Repository & Documentation

• GitHub Repository: github.com/nischalneupanee/KitabBid
• Academic Syllabus: Tribhuvan University (TU), Institute of Science & Technology — B.Sc. CSIT 6th Semester (CSC370: E-Commerce)
• Author: Nischal Neupane