How jackmounts/the-planeswalker-archive works
Project type and purpose
• This is a full-stack, cross-platform Progressive Web App built with Next.js/React.
• Purpose: Manage Magic: The Gathering card collections, organize them into virtual drawers/decks, scan cards via an in-app ML scanner, and view 3D models of cards/containers using Three.js.
File structure
• src/app: Next.js App Router pages (dashboard, collections, scanner, auth flows).
• src/components: Reusable UI (buttons, headers, footers, data-tables, forms), HOC for auth.
• src/store: Zustand stores for profile and collection state.
• src/lib & src/utils: Utility functions (e.g., placeholder generators, model types).
• public/models: GLB 3D assets.
• capacitor.config.ts & package.json: PWA + Capacitor mobile bundling.
• postcss.config.mjs, tailwind.config.ts: CSS toolchain.
• .github/workflows: CI for linting & security scans.
Key insights from README
• Tech stack: Next.js/React, PWA with service workers, Capacitor for mobile, Three.js (react-three/fiber/drei), GSAP, Dexie (IndexedDB), Zustand, Scryfall REST for card art, optional future Supabase.
• Core features: Home dashboard, typed groups & storage location, manual/ML scanner, 3D viewer.
a. Frontend (Next.js)
• App Router / pages / layouts – SSR/SSG fallback, client components.
• UI layer: shadcn/ui + custom components.
• State management: Zustand (profile-store, collection-store).
b. Local Storage Layer
• IndexedDB via Dexie.js – persistent collections, decks, settings.
• Service Worker (PWA caching strategy).
c. Scanner & ML Component
• Camera API → image frames → on-device or web-worker ML model (image recognition).
d. 3D Viewer
• Three.js + react-three-fiber + drei + GSAP for animations – render .glb models from public/models.
e. External Services
• Scryfall REST API – fetch card imagery/metadata.
• (Future) Supabase – hosted database for sync.
f. Bundling & Deployment
• Next.js build → static + serverless functions (if any).
• Capacitor native shells – iOS/Android wrappers.
• PWA manifest + service worker → offline support.
Architectural patterns & design principles
• Separation of concerns:
• Presentation (React components) vs. state (Zustand) vs. data persistence (Dexie).
• Scanner and 3D viewer isolated as specialized modules.
• Modular components: easy to plug in/replace ML model or external DB.
• PWA first: offline-first, caching layers.
• Client-heavy: minimal backend dependencies (reads static Scryfall, local DB).
Final recommendations
• Folder’s responsibility as a component in the system.
• How the PWA shell and service worker manage offline cache.
• Bundling pipeline (Next.js → PWA vs. Capacitor mobile).