deckhearth/README.md

TCG Vault

A modern trading card game collection manager built with Next.js and Neon Database.

🚀 Features

• Card Management: Track your MTG, Pokémon, and Lorcana cards
• Collection Organization: Create and manage card collections
• Deck Building: Build and share decks
• Authentication: Secure user accounts with JWT
• Admin Panel: Manage cards and users
• Real-time Pricing: Track card values

🛠️ Tech Stack

• Frontend: Next.js 16 (Pages router), React 18, JavaScript (TypeScript is a devDep only — see AGENTS.md Gotcha #9)
• Backend: Next.js API Routes
• Database: Neon PostgreSQL (serverless)
• Authentication: JWT with bcrypt (24-hour expiry; lib/auth-secret.js is the single source of truth for JWT_SECRET)
• Rate limiting: @upstash/ratelimit on /api/auth/login + /api/auth/register (5 attempts / 15 min per IP)
• Testing: Vitest (unit); Playwright queued
• Styling: Tailwind CSS
• Deployment: Vercel

📦 Installation

1. Clone the repository

   git clone <repository-url>
   cd tcg-vault
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   cp .env.example .env.local
   

   Update .env.local with your Neon database URL and a real JWT secret:

   POSTGRES_URL="postgresql://your-username:your-password@your-host/your-database"
   JWT_SECRET="<generate with: openssl rand -hex 32>"
   # Optional — exercise the rate limiter locally. Without them, `lib/rate-limit.js`
   # warn-and-no-ops in dev. In production these are auto-provisioned by the
   # Vercel Upstash Marketplace integration.
   KV_REST_API_URL="https://<your-upstash-host>.upstash.io"
   KV_REST_API_TOKEN="<your-upstash-rest-token>"
   

   JWT_SECRET is required — lib/auth-secret.js throws at import time if it's unset.

4. Set up the database

   npm run setup-db
   

5. Start development server

   npm run dev
   

🗄️ Database Schema

The application uses the following tables:

• users - User accounts and authentication
• cards - Card information and metadata
• user_cards - User's card collections
• collections - Named card collections
• collection_cards - Cards in collections
• decks - Deck definitions
• deck_cards - Cards in decks

🔧 API Endpoints

Authentication

• POST /api/auth/register - User registration
• POST /api/auth/login - User login

Admin

• GET /api/admin - Admin panel data

Health Check

• GET /api/health - Application health

Note: Earlier revisions of this README also listed GET /api/test-db (and three other unauthenticated dev endpoints: /api/simple, /api/test-auth, /api/setup-database). All four were deleted in fix-auth-bypass Brief 3 (commit fc0dd73) and CI now blocks their reintroduction. Don't recreate them.

🚀 Deployment

This app is configured for deployment on Vercel:

1. Connect your repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

📁 Project Structure

tcg-vault/
├── pages/                 # Next.js pages and API routes
│   ├── api/              # API endpoints
│   │   ├── auth/         # Authentication routes
│   │   └── admin/        # Admin routes
│   ├── _app.js           # App wrapper
│   └── index.js          # Home page
├── lib/                  # Utility libraries
│   └── database.js       # Database adapter
├── scripts/              # Database setup scripts
├── public/               # Static assets
└── .env.local           # Environment variables

🔐 Default Admin Account

After running the database setup:

• Email: admin@tcgvault.com
• Password: admin123

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details