About this project

Nucleus Cards is an MVP for market monitoring, portfolio management, and assisted analysis aimed at NBA card collectors in Mainland China and Hong Kong. The project is built with Next.js App Router, TypeScript, Supabase, Zod, Recharts, Vitest, and Playwright, and can run fully with deterministic demo data even without external accounts or API keys. The platform has implemented public routes including the market homepage (market overview, gainers/losers, 2020–2026 rookie classes, player generation hotspots, risk and data quality), standardized market search and multi-dimensional filtering, all 30 teams, players, and card details. Card details support CNY/HKD/USD switching, 7D/30D/90D/1Y charts, transaction samples, outliers, AI evidence, and risk labels. The cross-draft rookie tool compares the 2023, 2024, and 2025 classes by default, can switch among 2020–2026, and displays same-class rankings and valuation observations. Local holdings support adding, editing, deleting, valuation, unrealized gains/losses, and player generation distribution. Privacy is off by default, and data is stored in the current browser. There are also public collections, transaction/signing/generation alerts, privacy settings, demo login, and an admin backend that supports batch tagging. The data layer includes normalized PostgreSQL migrations, RLS policies, seed data, CSV templates, adapter interfaces, and a placeholder implementation for the eBay Browse API. The deterministic AI Provider validates structured output through Zod and does not fabricate conclusions randomly when no key is available. The project provides a PWA Manifest and Service Worker, light/dark themes, desktop/mobile responsive layouts, keyboard focus, loading/empty/error states, as well as API input validation, rate-limited endpoints, admin production route protection, and account export/deletion interface design. All market data is explicitly marked as demo data, with no crawlers for unauthorized sources, and listed prices are not misrepresented as actual transactions. Quick start requires Node.js 22.13+ and pnpm 11+. Run pnpm install, copy .env.example to .env.local, then run pnpm dev. By default NEXT_PUBLIC_DEMO_MODE=true, so no account registration is needed; the admin backend is at /admin and is directly visible in demo mode. The project is open source under the MIT License and includes documentation on data licensing, API, architecture, and analysis.