SpellcastersDB

A community database and deck builder for Spellcasters Chronicles.

Live Site • Contributing • Documentation

Project Overview

SpellcastersDB is a Next.js application designed to serve as a community resource for the game Spellcasters Chronicles. It features:

• The Archive: A searchable, filterable database of all Units, Spells, Titans, and Spellcasters.
• Knowledge Tracker: An interactive calculator that connects to the community API to help you plan your unlocks, track owned entities, and forecast your daily progression.
• Guide Hub: A comprehensive, API-driven knowledge base covering game mechanics, ranked tier ladders, class upgrades, and progression systems.
• Smart Interlinking: Dynamic, context-aware glossary that automatically hyperlinks game terminology (units, spells, mechanics, schools) within all entity descriptions.
• The Forge: A logic-validating deck builder with a fluid, dynamically scaling CSS Grid layout supporting ultrawide monitors (1440p+), modals for saving/editing, short link sharing (via Upstash Redis), and toast notifications.
• Infusions Database: A dedicated hub detailing elemental effects, cumulative build-up mechanics, and scalable damage tiers cross-referenced globally across all game entities.
• The Trinity (Team Builder): Build and manage teams of 3 decks with shared card pool validation and short link sharing.
• Patch History: Real-time balance updates with visual badges (Buff/Nerf/Rework) and detailed before/after stat comparisons for every entity.
• Live Updates: Powered by a static JSON API that allows for rapid balance updates without full site rebuilds.
• Roadmap: A live, interactive issue tracker connected to GitHub, featuring search and filtering.
• Accessibility-Minded: Built with WCAG 2.1 AA guidelines in mind including skip navigation, focus-trapped modals, ARIA labels/states on interactive controls, and prefers-reduced-motion support (verified via automated auditing).
• PWA: Installable as a native-like app on mobile and desktop. Service worker provides offline caching for pages, API data, and card images.
• Theming: 7 custom themes (Dark, Light, Arcane, Inferno, Frost, Retro, GlitchWitch) plus a secret Rainbow mode (Konami Code).
• Design System: A dedicated /design-system route for previewing tokens, components, and building custom themes with live preview and export/import capabilities.
• SEO Optimized: Fully crawlable with dynamic sitemaps, structured data (JSON-LD), and semantic HTML for maximum discoverability.
• Legal Compliance: Dedicated /privacy and /terms pages with transparent data practices.
• Navigation: Integrated Breadcrumbs via PageShell for improved user wayfinding and SEO structure.
• Debug Suite: Internal analytics tools for tracking data integrity, balance statistics, and keyword frequency.

Architecture at a Glance

• Frontend: Next.js 16+ (App Router), TypeScript, Tailwind CSS v4.
• Data Layer:
  • Static Fetch: Fetches JSON data from the Spellcasters Community API.
  • Registry: An in-memory, O(1) lookup map (src/services/api/registry.ts) that initializes once per session.
  • Domain Services: Feature-based logic (e.g., DeckRules, TeamRules) that interacts with the Registry.
• State Management: Zustand (Global Store) split into slices (solo, team, ui) for robust state handling.
• Performance:
  • Read-Through Caching: Optimizes data fetching.
  • Virtualization: react-virtuoso for large lists.
  • Zod Validation: Ensures data integrity at runtime.
  • Comprehensive Testing: Rigorous unit and integration tests (Vitest) covering core logic, custom hooks, and data validation, enforced by strict coverage threshold lock (vitest.config.ts).
    • Adversarial Testing Suite: A specialized 85-test characterization suite (src/__tests__/adversarial and __tests__/**/*.adversarial.test.ts) that aggressively fuzzes inputs, breaks boundaries, and simulates data corruption (e.g., OOB array access, primitive injection, JSON sabotage) to guarantee the resilience of the deck building state machines and backup/import layers.
  • Revalidation API: On-demand cache invalidation via /api/revalidate (using Authorization header) with revalidateTag for robust content updates.
  • State Persistence: Optimized zustand/persist with partialize to serialize only critical user data, excluding transient UI state for consistent high performance.
  • Asset Caching & CDN Optimization: Open Graph generation edges and standard images use Cache-Control configured for stale-while-revalidate alongside NEXT_PUBLIC_PREFERRED_ASSET_FORMAT for robust background updating without freezing user interaction.
  • Bundle Profiling: Includes @next/bundle-analyzer to maintain lightweight chunks. Use npm run analyze to inspect footprints.
  • Browser Support: Targets modern browsers (Chrome 100+, Safari 15+, Firefox 100+) for smaller bundles and better performance.
• Infrastructure Hardening:
  • Architecture Enforcement: dependency-cruiser validates import boundaries (components/ui ↛ features, features ↛ app) on every preflight run.
  • Observability: A MonitoringService (src/services/monitoring/) abstracts error reporting. Default ConsoleAdapter outputs structured logs; swap in a Sentry/Axiom adapter with zero app-code changes.
  • PWA Engine: @serwist/next provides automatic precaching, runtime caching (StaleWhileRevalidate for API data, CacheFirst for images), and a /~offline fallback route.
  • E2E Readiness: Standardized data-testid attributes on all shell, database, and deck builder components. Full Playwright E2E suite (14 tests) covering navigation, theming, drag-and-drop, team builder, and deck state management across Desktop Chromium and Mobile Safari. See E2E Conventions for naming rules.

Getting Started

1. Clone & Install:

   git clone https://github.com/TerribleTurtle/spellcastersdb.git
   npm install

2. Configure Environment:

   cp .env.local.example .env.local

   Note: The .env.local file contains several important configuration flags (e.g., NEXT_PUBLIC_PREFERRED_ASSET_FORMAT, REVALIDATION_SECRET, NEXT_PUBLIC_SENTRY_DSN). Please review the full Environment Variables Table in CONTRIBUTING.md for details on all available options.

3. Run Development Server:

   npm run dev

For detailed setup instructions, including Local API Development, please see CONTRIBUTING.md.

Available Scripts

Command	Description
npm run dev	Starts the development server
npm run build	Builds the application for production
npm run start	Starts the production server
npm run test	Runs the test suite (Vitest)
npm run test:coverage	Runs tests with coverage report
npm run test:watch	Runs tests in watch mode
npm run lint	Runs ESLint
npm run type-check	Runs TypeScript compiler check
npm run check-data	Verifies API data fetching logic
npm run preflight	Runs Type-Check, Format, Lint, Tests, and Dep Validation
npm run format:check	Checks formatting matches Prettier rules
npm run deps:validate	Validates import boundary rules
npm run new:component	Scaffolds a new React component
npm run new:route	Scaffolds a new App Router page
npm run script:validate	Validates production data integrity
npm run test:e2e	Runs the E2E test suite (Playwright)
npm run test:e2e:ui	Opens the Playwright UI for interactive debugging
npm run analyze	Builds with @next/bundle-analyzer enabled to inspect bundle sizes
npm run dead-code	Scans for unused code and files via knip
npm run audit	Scans for CVEs, respecting the .nsprc whitelist

Documentation

• API Info: Specification for the JSON data consumed by this app.
• Brand Guidelines: Colors, fonts, and styling rules.
• Changelog: Release history and version notes.
• E2E Conventions: data-testid naming rules and viewport strategy.
• GitHub Token Setup: How to configure a GitHub token for roadmap data.
• Privacy Audit: GDPR/CCPA privacy audit findings.
• Security Audit: Security audit findings and remediation status.
• SEO Strategy: Keyword research and SEO strategy.
• Site Design Document: High-level site architecture and design decisions.
• State Management: Zustand store architecture and persistence strategy.
• Full Index: Complete documentation index.

🌐 Part of the Spellcasters Ecosystem

• Spellcasters Community API — The shared data source (GitHub Pages)
• The Grimoire — Data management & patch publishing
• Spellcasters Bot — Discord integration

All tools consume the same Community API v2.

License

This project is licensed under the MIT License - see the LICENSE file for details.