🎵 Hitster Card Generator

Generate printable QR code cards for your custom Hitster music game

Upload a CSV of songs, match them to Spotify tracks, customize your card colors, and export a PDF ready for printing and cutting. Perfect for creating custom Hitster decks with your favorite music!

Quick Start

# docker-compose.yml
services:
  hitster:
    build: https://github.com/SixFive7/HitsterCardGenerator.git
    container_name: hitster-card-generator
    ports:
      - "8080:8080"
    environment:
      TZ: Europe/Amsterdam
      PUID: 1000
      PGID: 1000
      SPOTIFY_CLIENT_ID: your_client_id_here
      SPOTIFY_CLIENT_SECRET: your_client_secret_here
    restart: unless-stopped

docker compose up -d

Then open http://localhost:8080 in your browser.

Need Spotify credentials? Create an app at developer.spotify.com/dashboard to get your Client ID and Secret.

Screenshots

Upload	Match

Preview	Export

Deployment

Traefik Setup (Reverse Proxy)

For production with SSL. No port exposure - Traefik handles routing.

# docker-compose.yml
services:
  hitster:
    build: https://github.com/SixFive7/HitsterCardGenerator.git
    container_name: hitster-card-generator
    environment:
      TZ: Europe/Amsterdam
      PUID: 1000
      PGID: 1000
      SPOTIFY_CLIENT_ID: your_client_id_here
      SPOTIFY_CLIENT_SECRET: your_client_secret_here
    labels:
      traefik.enable: true
      traefik.http.routers.hitster.rule: Host(`hitster.yourdomain.com`)
      traefik.http.services.hitster.loadbalancer.server.port: 8080
    restart: unless-stopped

Multi-architecture: Builds on both AMD64 (Intel/AMD) and ARM64 (Apple Silicon, Raspberry Pi).

Environment Variables

Variable	Required	Default	Description
`SPOTIFY_CLIENT_ID`	Yes	-	Your Spotify API client ID
`SPOTIFY_CLIENT_SECRET`	Yes	-	Your Spotify API client secret
`TZ`	No	`Europe/Amsterdam`	Container timezone
`PUID`	No	`1000`	User ID for file ownership
`PGID`	No	`1000`	Group ID for file ownership

Get your Spotify credentials from the Spotify Developer Dashboard. Create an app, and you'll find the Client ID and Secret in the app settings.

Unraid users: Set PUID=99 and PGID=100 to match the default nobody/users permissions.

Developer Guide

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Web Browser                         │
│            (Svelte 5 + Tailwind CSS v4)                 │
└─────────────────────────┬───────────────────────────────┘
                          │ HTTP/REST
┌─────────────────────────▼───────────────────────────────┐
│                  .NET 10 Minimal API                     │
│  ┌──────────────┐  ┌─────────────┐  ┌────────────────┐  │
│  │ CSV Parsing  │  │  Spotify    │  │  PDF Export    │  │
│  │              │  │  Matching   │  │  (QuestPDF)    │  │
│  └──────────────┘  └──────┬──────┘  └───────┬────────┘  │
│                           │                 │           │
│                           ▼                 ▼           │
│                    SpotifyAPI.Web      QRCoder          │
└─────────────────────────────────────────────────────────┘

Tech Stack

Component	Technology
Backend	.NET 10 Minimal API
Frontend	Svelte 5 + Tailwind CSS v4 (Vite)
PDF Generation	QuestPDF
QR Codes	QRCoder
Spotify Integration	SpotifyAPI.Web

Local Development

Prerequisites:

.NET 10 SDK
Node.js 18+
Spotify API credentials

Quick Start:

# Clone the repo
git clone https://github.com/SixFive7/HitsterCardGenerator.git
cd HitsterCardGenerator

# Set up environment (create .env or export)
export SPOTIFY_CLIENT_ID=your_client_id
export SPOTIFY_CLIENT_SECRET=your_client_secret

# Run backend (serves frontend in production mode)
cd HitsterCardGenerator
dotnet run

With Hot Reload (Frontend Development):

# Terminal 1: Backend
cd HitsterCardGenerator
dotnet run

# Terminal 2: Frontend with HMR
cd HitsterCardGenerator/web
npm install
npm run dev

Then open http://localhost:5173 for the Vite dev server.

E2E Testing

The project includes an E2E test procedure executed via the project's Playwright MCP servers (see playwright/).

Test File:

tests/e2e-test-procedure.md - Complete test procedure with steps

Running Tests:

Start the application:
```
dotnet run
```
Have Claude Code execute the test procedure using the playwright-headless MCP server:
- Open the test procedure file
- Execute each step using the appropriate MCP tool
- Verify expected outcomes at each step

Test Coverage:

Landing page load and API connection
CSV file upload and validation
Spotify track matching
Card preview with carousel
Card flip functionality
PDF export
Flow restart (Start New Batch)

License

MIT - Feel free to use this for your own Hitster game nights!

SixFive7/HitsterCardGenerator

README