Card Game 28 - Data Collection System

A web application for collecting bidding data for the Indian card game "28".

Features

• User Management: 6 concurrent users (Amit, Veronica, Ritika, Babu, Vinu, Others)
• Pool System: 6 pools of ~377 hands each (2,262 total unique canonical hands)
• Dynamic Assignment: Pools dynamically assigned based on availability
• Suit Isomorphism: Canonical hand representation reduces state space
• Back Button: Ability to go back and modify previous submission
• Inactivity Timeout: 5-minute session timeout with pool release
• Duplicate Handling: Automatic skipping of already-submitted hands
• Real-time Validation: Pool assignment checks every 30 seconds

Tech Stack

• Frontend: Next.js 14 (App Router), React, TypeScript, Tailwind CSS
• Backend: Next.js API Routes
• Database: PostgreSQL
• Deployment: Vercel

Local Setup

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Python 3.8+ (for preprocessing)

Installation

1. Clone the repository

2. Install dependencies:

   npm install
   pip install psycopg2-binary

3. Create PostgreSQL database:

   createdb card_game_28
   psql -d card_game_28 -f schema.sql

4. Populate database:

   python lib/preprocess.py

5. Configure environment:

   cp .env.example .env.local
   # Edit .env.local with your database URL

6. Run development server:

   npm run dev

Database Schema

Tables

• pools: Tracks pool assignments and activity
• pool_hands: Pre-populated hands for each pool
• submissions: User bid submissions

Key Constraints

• Unique constraint on canonical_key in submissions
• 5-minute inactivity timeout enforced
• Row-level locking for concurrent pool assignment

API Endpoints

• POST /api/assign-pool - Assign pool to user
• GET /api/get-hand - Fetch current hand
• POST /api/submit-bid - Submit trump card and bid
• POST /api/go-back - Navigate to previous hand
• POST /api/release-pool - Release pool on timeout
• GET /api/check-activity - Verify session validity

Deployment (Vercel)

1. Push to GitHub
2. Import project in Vercel
3. Add Vercel Postgres database
4. Run preprocessing script with Vercel database URL
5. Deploy

Game Rules

• 32-card deck (7, 8, 9, 10, J, Q, K, A in 4 suits)
• Users select trump card from their 4-card hand
• Users bid between 14-20 points
• Rank order: J > 9 > A > 10 > K > Q > 8 > 7

Data Collection Goals

• Collect optimal bidding strategies for each canonical hand
• Compare bidding patterns across different players
• Build training data for AI bot development

License

MIT