Skip to content

Architecture

Jump to bottom
mcinquin edited this page Oct 12, 2026 · 1 revision

Architecture

HobbyHoops is a Next.js application for managing an NBA card collection.

Stack

  • Next.js (App Router) + TypeScript + React
  • SQLite via better-sqlite3 (data/hobbyhoops.db)
  • Auth — session cookies (httpOnly, SameSite=strict)
  • i18n — French (default) and English (US), cookie hh_locale, files messages/fr.json / messages/en.json
  • CardSight — optional photo recognition API (CARDSIGHT_API_KEY)
  • Docker — image published to GHCR; runtime user UID/GID 1111

The app deliberately avoids sharp so it runs on older CPUs (e.g. Intel Atom N2800, no x86-64-v2 / Wasm SIMD). Card photos are stored as uploaded (JPEG / PNG / GIF / WebP).

Features

  • Dashboard — collection totals, charts by brand/year/set, recent additions, incoming shipments
  • Collection — filterable/searchable card grid with tags (RC, AUTO, MEM, NUM, TRADE, NBA/WNBA)
  • Players — per-player inventory grouped by set and variation
  • Incoming — track eBay/Vinted/etc. purchases before they join the collection
  • Admin — manage cards and reference lists (brands, sets, variations, years, teams)
  • Card recognition — analyze a card photo (CardSight AI) to prefill year, brand, set, variation, and more
  • CSV — import / export from Admin (see CSV-import-export)

Data layout

Everything lives under data/ (gitignored), mounted as /app/data in Docker:

Path Role
data/hobbyhoops.db SQLite (collection, references, accounts, sessions, rate limiting)
data/card-photos/ Card front/back images
data/backups/ Local DB backups (gitignored)

See Data-and-backup for backup / restore.

Languages

French (default) and English (US). The selected language is stored in the hh_locale cookie and can be changed from the sidebar or the login screen.

Related

Clone this wiki locally