# jackmounts/the-planeswalker-archive architecture

> Architecture diagram of the GitHub repository jackmounts/the-planeswalker-archive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jackmounts/the-planeswalker-archive
- Repository: https://github.com/jackmounts/the-planeswalker-archive

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client PWA Layer
    subgraph "Client PWA" 
        direction TB
        NextRouter["Next.js App Router"]:::frontend
        subgraph "Pages & Layouts"
            direction TB
            RootLayout["Root Layout"]:::frontend
            Dashboard["Dashboard (Home)"]:::frontend
            Collections["Collections Module"]:::frontend
            CollectionsCols["Collections Columns Config"]:::frontend
            subgraph "Scanner"
                direction TB
                ScannerLayout["Scanner Layout"]:::frontend
                ScannerPage["Scanner Page"]:::frontend
            end
            subgraph "Auth Flows"
                direction TB
                LoginPage["Login Page"]:::frontend
                LoginLayout["Login Layout"]:::frontend
                RegisterPage["Register Page"]:::frontend
                RegisterLayout["Register Layout"]:::frontend
                RegisterLoad["Register Loading"]:::frontend
            end
            GlobalCSS["Global CSS"]:::frontend
        end

        subgraph "UI Components"
            direction TB
            UIComponents["src/components/ui"]:::frontend
            Buttons["Scanner Button"]:::frontend
            Header["Header"]:::frontend
            Footer["Footer"]:::frontend
            AuthHOC["Auth HOC"]:::frontend
        end

        subgraph "State Management"
            direction TB
            ProfileStore["Profile Store"]:::storage
            CollectionStore["Collection Store"]:::storage
        end

        subgraph "Persistence & Offline"
            direction TB
            Dexie["Dexie (IndexedDB)"]:::storage
            ServiceWorker["Service Worker"]:::storage
            DBSetup["IndexedDB Setup"]:::storage
        end

        subgraph "Specialized Modules"
            direction TB
            MLScanner["ML Scanner Module"]:::module
            ThreeViewer["3D Viewer Module"]:::module
        end

        subgraph "Assets"
            direction TB
            Models["3D Models (.glb)"]:::module
        end
    end

    %% External & Bundling Layer
    subgraph "External & Bundling"
        direction TB
        Scryfall["Scryfall REST API"]:::external
        Supabase["Supabase (Future)"]:::external
        NextBuild["Next.js Build"]:::build
        PWAConfig["PWA Manifest & SW Config"]:::build
        CapacitorShell["Capacitor Shell"]:::build
        BuildConfigs["Build Configs"]:::build
        CI["CI Workflows"]:::build
    end

    %% Relationships
    NextRouter -->|uses| RootLayout
    RootLayout --> Dashboard
    RootLayout --> Collections
    RootLayout --> ScannerLayout
    RootLayout --> LoginPage
    RootLayout --> RegisterPage

    UIComponents -->|render| Dashboard
    UIComponents -->|render| Collections
    UIComponents -->|render| ScannerPage

    Dashboard -->|reads/writes| CollectionStore
    Collections -->|reads/writes| CollectionStore
    ScannerPage -->|dispatch scan| MLScanner
    MLScanner -->|updates| CollectionStore

    ProfileStore -->|persists| Dexie
    CollectionStore -->|persists| Dexie
    Dexie -->|indexedDB| DBSetup
    ServiceWorker -->|caches| UIComponents
    ServiceWorker -->|caches| MLScanner
    ServiceWorker -->|caches| ThreeViewer

    ThreeViewer -->|loads| Models

    UIComponents -->|fetch| Scryfall
    Scryfall -->|returns metadata| CollectionStore

    NextBuild -->|outputs| PWAConfig
    NextBuild -->|outputs| CapacitorShell
    NextBuild -->|reads| BuildConfigs
    BuildConfigs -->|defines| NextBuild
    CI -->|validates| BuildConfigs

    %% Click Events
    click NextRouter "https://github.com/jackmounts/the-planeswalker-archive/tree/main/src/app"
    click Dashboard "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/(pages)/page.tsx"
    click Collections "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/(pages)/collections/page.tsx"
    click CollectionsCols "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/(pages)/collections/columns.tsx"
    click ScannerLayout "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/(pages)/scanner/layout.tsx"
    click ScannerPage "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/(pages)/scanner/page.tsx"
    click LoginPage "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/login/page.tsx"
    click LoginLayout "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/login/layout.tsx"
    click RegisterPage "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/register/page.tsx"
    click RegisterLayout "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/register/layout.tsx"
    click RegisterLoad "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/register/_loading.tsx"
    click RootLayout "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/layout.tsx"
    click GlobalCSS "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/globals.css"
    click DBSetup "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/app/db.ts"
    click UIComponents "https://github.com/jackmounts/the-planeswalker-archive/tree/main/src/components/ui"
    click Buttons "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/components/buttons/scanner-button.tsx"
    click Header "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/components/header/header.tsx"
    click Footer "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/components/footer/footer.tsx"
    click AuthHOC "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/components/hoc/withAuth.tsx"
    click ProfileStore "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/store/profile-store.ts"
    click CollectionStore "https://github.com/jackmounts/the-planeswalker-archive/blob/main/src/store/collection-store.ts"
    click Models "https://github.com/jackmounts/the-planeswalker-archive/tree/main/public/models"
    click PWAConfig "https://github.com/jackmounts/the-planeswalker-archive/blob/main/public/manifest.json"
    click CapacitorShell "https://github.com/jackmounts/the-planeswalker-archive/blob/main/capacitor.config.ts"
    click BuildConfigs "https://github.com/jackmounts/the-planeswalker-archive/blob/main/tailwind.config.ts"
    click BuildConfigs "https://github.com/jackmounts/the-planeswalker-archive/blob/main/postcss.config.mjs"
    click CI "https://github.com/jackmounts/the-planeswalker-archive/blob/main/ .github/workflows/lint.yml"
    click CI "https://github.com/jackmounts/the-planeswalker-archive/blob/main/ .github/workflows/codeql.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef storage fill:#E6F4EA,stroke:#228B22,color:#228B22
    classDef module fill:#F3E5F5,stroke:#8E24AA,color:#8E24AA
    classDef external fill:#FFF4E5,stroke:#FF8C00,color:#FF8C00
    classDef build fill:#F0F0F0,stroke:#666666,color:#666666
```
