deckhearth/README.md

Deck Hearth

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>"
   # Required for `npm run setup-db` — used once to hash the initial admin password.
   # Set in .env.local for local dev, or as a CI secret if you run setup from CI.
   ADMIN_INITIAL_PASSWORD="<generate with: openssl rand -base64 24>"
   # 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. ADMIN_INITIAL_PASSWORD is required for npm run setup-db — the script exits with code 1 if it's unset.

4. Set up the database

   npm run setup-db
   

   This applies every pending migration under migrations/ (via node-pg-migrate) and then seeds the initial admin user. To run just the migration step without seeding, use npm run migrate up.

5. Start development server

   npm run dev
   

🧱 Schema changes (post-migration-tool convoy)

Schema is now managed by node-pg-migrate. New migrations live under migrations/ at the repo root (the legacy scripts/migrations/ placeholder is preserved for the one pre-existing dated script and is not used going forward).

# 1. Generate a new migration file (JS template, timestamp-prefixed)
npm run migrate create add-foo-column -- -j js

# 2. Edit the generated file under migrations/<timestamp>_add-foo-column.js
#    Put your DDL in up(); write a real down() if rollback is safe.

# 3. Apply it locally (POSTGRES_URL from .env.local)
npm run migrate up

# 4. Commit the migration file + any docs/SCHEMA_MAP.md updates together.

Onboarding a new env is now exactly npm install → seed .env.local → npm run setup-db (which chains npm run migrate up and then seeds the admin user).

Do not edit historical scripts/add-*.js / scripts/fix-*.js / scripts/seed-*.js — those are already-run, append-only jobs. They are preserved for the audit trail; new column / constraint work goes through a migration file instead.

🗄️ 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

🔐 First-time admin setup

npm run setup-db first applies every pending migration (via npm run migrate up), then creates a single admin user. The password is read from the ADMIN_INITIAL_PASSWORD environment variable; the script exits with code 1 (and does not open a database connection) if the variable is unset or empty.

• Local dev: set ADMIN_INITIAL_PASSWORD in .env.local before running npm run setup-db. Use openssl rand -base64 24 (or any other strong source) to generate the value.
• CI / Vercel: set ADMIN_INITIAL_PASSWORD as a project secret if setup ever runs from CI. The env var is only read by the seed script; runtime auth uses the per-user password stored in the database.
• Admin email: the seed creates admin@deckhearth.com. Change the password immediately after first login via the app's profile settings.

Operators of envs that pre-date this change: npm run setup-db is idempotent (ON CONFLICT (email) DO NOTHING) — re-running it with ADMIN_INITIAL_PASSWORD set will not rotate an existing admin row's password. If your environment was set up before this change and still has the prior weak default, rotate the password manually via the app after logging in, or wait for the queued rotate-default-admin follow-up convoy.

Operators of envs that pre-date the pick-a-name convoy (2026-05-24): the admin row was renamed from admin@tcgvault.com to admin@deckhearth.com. Run node scripts/migrations/2026-05-24-rename-admin-email.js once after deploy to UPDATE any existing @tcgvault.com user rows (the admin row, plus alice/bob if npm run create-test-users was ever run). Re-running the migration after the first run is idempotent and prints "Nothing to migrate." Verify post-migration with psql $POSTGRES_URL -c "SELECT email FROM users WHERE email LIKE '%@tcgvault.com'" — expect zero rows.

🤝 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