🚀 COMPLETE BACKEND AGENT PROMPT FOR AUCTION AND PREBID SYSTEM¶

You are a senior backend engineer responsible for building a production-grade auction system with prebid functionality for a fintech SaaS platform called “Dichit” (chit fund domain).

Your goal is to design and implement the system step-by-step with correctness, scalability, and data integrity as top priorities.

Tech stack:¶

• Node.js (TypeScript)
• PostgreSQL
• Redis (for locks / realtime support)
• Fastify framework
• Prisma ORM

SYSTEM CONTEXT¶

We are building a chit fund auction system where:

• Each chit group has multiple installments (monthly cycles)
• Each installment has one auction
• Subscribers place bids (discount amount)
• Lowest bid wins
• Prebid allows users to submit bids before auction starts

⸻

IMPORTANT RULES¶

1. Lowest bid wins (reverse auction)
2. Prebids are confidential and only applied when auction starts
3. Only one active prebid per user per auction
4. All financial data must be consistent and auditable
5. Race conditions MUST be handled
6. Never trust frontend validation
7. Auction and prebid should be optionally allowed for the first cycle as well
8. Prebid is available only after the subscriber has completed payment for that specific cycle
9. If a valid prebid or bid reaches the program minimum bid amount, there is no need for further auction bidding
10. If multiple subscribers reach the minimum bid amount, the winner must be selected by lot
11. An enrolled subscriber can win only once in a program; past winners must be blocked from future prebids and bids in the same program

⸻

UPDATED BUSINESS RULES¶

1. First cycle support:
2. Do not hard-block auction/prebid for cycle 1

3. Make this configurable / optional so first-cycle auction flow can run when required

4. Payment-gated prebid:

5. A subscriber becomes eligible for prebid only after completing the payment for that exact cycle

6. Eligibility must be validated from backend payment / transaction records, not from frontend state

7. Minimum bid short-circuit:

8. If a prebid reaches the minimum bid amount, live auction is not needed
9. If exactly one eligible subscriber reaches the minimum bid amount, that subscriber should be treated as the winning candidate directly

10. If more than one eligible subscriber reaches the minimum bid amount, the flow must move to a lot-based winner selection

11. Minimum bid tie rule:

12. Multiple subscribers are allowed to place the minimum bid amount
13. This applies to both prebid and live bid flows

14. Minimum-bid ties must not be broken by timestamp; they must go to lot

15. One win per program:

16. Once an enrolled subscriber has already won in a program, that subscriber must be ineligible for any future prebid or auction participation in that same program
17. This validation must happen before allowing prebid creation, prebid update, or live bid placement

⸻

IMPLEMENTATION PLAN (FOLLOW STRICTLY IN ORDER)¶

⸻

STEP 1: DATABASE SCHEMA¶

Design Prisma models for:

• User
• Program
• SubscriberProgram
• ProgramCycle
• Auction
• Bid
• Prebid
• AuctionResult
• Transaction (ledger)

Requirements:

• Use Unique IDs
• Add proper relations
• Add indexes for performance
• Enforce constraints:
• One prebid per user per auction (partial unique index)
• Use Decimal for monetary values

After schema:

• Generate migrations
• Provide SQL for critical indexes

⸻

STEP 2: PREBID MODULE¶

Implement:

APIs:¶

1. Create prebid
2. Update prebid
3. Cancel prebid
4. Get user’s prebid

Rules:¶

• Only before auction start
• Only after subscriber payment completion for that specific cycle
• Validate bid range
• Enforce single active prebid
• Block subscribers who have already won once in the same program
• Allow prebid for cycle 1 when first-cycle auction is enabled
• Log history (optional but recommended)

Edge cases:¶

• Auction already started → reject
• Cycle payment not completed → reject
• Subscriber already won in this program → reject
• Duplicate prebid → update instead
• Minimum bid amount reached:
• one subscriber at minimum → no live auction required
• multiple subscribers at minimum → move to lot selection flow instead of live auction

⸻

STEP 3: AUCTION START LOGIC (CRITICAL)¶

Implement a service:

startAuction(auctionId)

Flow:¶

1. Begin DB transaction
2. Lock auction row (SELECT FOR UPDATE)
3. Fetch all ACTIVE prebids
4. Find lowest prebid
5. Check whether the lowest prebid is equal to the minimum bid amount
6. If minimum bid amount is reached:
7. if only one subscriber is at minimum → skip live auction and mark direct winning flow
8. if multiple subscribers are at minimum → skip live auction and move to lot-based selection
9. If minimum bid amount is not reached:
10. insert winning prebid into bids table
11. update auction.currentLowestBid
12. mark prebids as APPLIED / SUPERSEDED as needed
13. set auction status = LIVE
14. Commit transaction

If no prebids:

• auction starts without initial bid

⸻

STEP 4: LIVE BIDDING SYSTEM¶

Implement:

API:

• Place bid

Rules:

• Bid must be < currentLowestBid
• Reject invalid bids
• Must handle concurrency
• Block subscribers who have already won once in the same program
• If a bid reaches the minimum bid amount:
• stop further auction bidding
• if only one subscriber is at minimum → direct winning flow
• if multiple subscribers are at minimum → lot-based winner selection

Concurrency handling:

• Use transaction + row locking OR Redis lock
• Prevent two users from winning same position

Flow:

1. Lock auction row
2. Validate bid
3. Check winner eligibility (no previous win in same program)
4. Insert bid
5. Update currentLowestBid
6. If minimum bid amount is reached, close bidding and move to direct winner or lot flow
7. Commit

⸻

STEP 5: AUCTION END¶

Implement:

endAuction(auctionId)

Flow:

1. Lock auction
2. Fetch lowest bid / minimum-bid candidates
3. If minimum bid tie exists, resolve by lot
4. Assign winner
5. Store in auction_results
6. Update auction status = COMPLETED
7. Trigger transaction entry (payout)

⸻

STEP 6: LEDGER / TRANSACTIONS¶

Implement transaction table logic:

• installment payments
• payout to winner
• penalties (optional)

Ensure:

• consistency
• no duplicate payouts

⸻

STEP 7: REAL-TIME EVENTS (BASIC)¶

Design event system (no need full infra yet):

Events:

• AUCTION_STARTED
• NEW_BID
• OUTBID_NOTIFICATION
• AUCTION_ENDED

⸻

STEP 8: VALIDATION & SECURITY¶

• Input validation (Zod or similar)
• Auth middleware
• Role-based access:
• Admin vs Subscriber

⸻

STEP 9: TESTING¶

Write tests for:

• Prebid creation
• Auction start with prebids
• Concurrent bid placement
• Winner selection
• Edge cases:
• same bid values
• no prebids
• rapid bidding
• first cycle auction enabled vs disabled
• prebid blocked before cycle payment completion
• minimum bid reached by one subscriber
• minimum bid reached by multiple subscribers → lot required
• previous program winner blocked from prebid
• previous program winner blocked from live bid

⸻

STEP 10: PERFORMANCE & INDEXING¶

Ensure:

• indexes on bids (auction_id, bid_amount)
• indexes on prebids
• query optimization

⸻

OUTPUT FORMAT

For each step: 1. Explain approach briefly 2. Provide code (TypeScript + Prisma) 3. Provide SQL where needed 4. Mention edge cases handled

⸻

DO NOT:

• Skip concurrency handling
• Assume single user environment
• Use floating point for money
• Over-engineer with microservices initially

⸻

SUCCESS CRITERIA

The system should:

• Handle multiple concurrent bidders safely
• Correctly apply prebids
• Always select correct winner
• Maintain financial integrity
• Be extensible for real-time updates later

Proceed step-by-step. Do NOT jump steps.

STEP X: ADMIN CONTROL & MODERATION¶

Implement full admin control over auctions.

Requirements:

1. Auction lifecycle control:
2. Admin can start, pause, resume, end auctions

3. Enforce valid state transitions

4. Winner approval:

5. After auction ends, winner must be approved
6. Allow override with reason

7. Store audit logs

8. Prebid moderation:

9. Admin can view all prebids

10. Reject invalid/suspicious prebids

11. Bid moderation:

12. Admin can reject bids (fraud/manual correction)

13. Audit logging:

14. Every admin action must be logged

15. Store metadata in JSONB

16. Authorization:

17. Only ADMIN role can access these APIs

18. Safety:

19. Prevent illegal actions (e.g., ending already completed auction)

Output:

• APIs
• service layer
• schema updates
• validations