Nahalo Vault 🛡️

A self-hosted Magic: The Gathering card collection manager, visual tactical deck builder, MTG Cube designer, Scryfall explorer, and TradePost Hub built for collectors, players, cube curators, and local trade groups.

---

✨ Features

📦 Collection & Binder Vault

• Grid, Binder, & Table Views: High-res imagery, foil badges, finish indicators, quantity badges, and assigned binder tags.
• Dynamic Card Grid Zoom Density: Draggable density slider with 4 responsive levels (Showcase, Large, Standard, Compact) and persistent state.
• Binder Organization & Set Tracking: Assign custom binders with target MTG Set badges ([DSK], [OTJ]), glowing 2px completion micro-bars, and real-time completion percentage pills.
• Set Completion Matrix 2.0: Full physical set matrix tracking with Multi-Criteria Sorting (Collector #, Price, Name, Rarity), Market Price Badges, and Multi-Bonus Sheet quick switchers (OTJ + OTP, BIG).
• Interactive Portfolio Financials & Drill-Down: Real-time market valuation in USD ($) and EUR (€), with 1-click chart drill-down transitions to filtered collection views.
• Multi-Format CSV & Text Importer: One-click import for Standard MTG CSVs, Multi-Binder Exports, Moxfield, DelverLens, MTG Arena, and Plain Text.
• Condition & Printing Management: Easily switch card printings, art variants, foils, and language editions.

📈 Portfolio Financials, Market Movers & Price Drops

• Real-Time Multi-Currency Valuation: Track collection, binder, or deck worth in USD ($) and EUR (€) using live Scryfall / TCGplayer / Cardmarket market pricing.
• Top Gainers & Price Drops Tracking:
  • Instant discovery of Top Market Movers across customizable timeframes (24h, 48h, 7d, and 30d).
  • Track both percentage spikes/drops and steep absolute value shifts ($/€).
  • Filter by minimum card price threshold or search specific cards within your movers list.
• Interactive Historical Price Charts & Sparklines:
  • In-line mini sparklines for immediate visual price trajectory recognition.
  • Full modal price history charts tracking daily market movements.
• Deep Financial Drill-Down & Segmentations:
  • Breakdown portfolio values across Sets & Binders, Rarity & Finishes (foil, etched, non-foil), Price Brackets/Tiers ($0–$1, $1–$5, $5–$20, etc.), and Color/Card Types.
  • Bulk vs. Value Segmentation: Configure custom bulk price thresholds with 1-click drill-down to isolate high-value assets.
• Smart Conditional Price Syncing:
  • Automated detection: triggers rapid batch price refresh when viewing a single binder, or switches to high-throughput bulk sync when updating 500+ cards across your entire vault.

🎲 MTG Cubes Management Engine

• Dedicated Cube Catalog & Builder: Curate custom drafting pools with standard target sizes (180, 360, 450, 540, 720, 1000 cards).
• Multi-Board Architecture:
  • Main Cube Pool: Color-segregated sections (White, Blue, Black, Red, Green, Multicolor, Colorless, Lands).
  • Land Station: Quick basic land generator for drafting kits.
  • Maybeboard: Staging area for card considerations and swaps.
• Collapsible Color Groups: Interactive color group headers with real-time card counts, themed color indicators, and global Expand All / Collapse All toolbar.
• Cube Cobra CSV & Direct File Upload:
  • Import Cube Cobra CSV exports directly via drag-and-drop or .csv / .txt file upload, matching exact set printings, collector numbers, boards, and proxy statuses.
  • Plaintext and MTGO list compatibility.
• Vault Cross-Referencing & 1-Click Wishlist:
  • Live calculation of your cube completion percentage against cards in your Vault binders.
  • 1-click export of missing, non-proxy cards directly to a new Vault Wishlist binder.
• Analytics & Mana Curves: Visual breakdown of Mana Curves, Color balance, Card Types, and Rarities.

⚔️ Visual Tactical Deck Builder

• Format Support: Commander / EDH, Standard, Modern, Pioneer, Legacy, Vintage, and Pauper.
• Strict MTG Commander Legality Engine:
  • Automated validation adhering to official rules (Legendary Creatures, Vehicles, Spacecrafts, and Planeswalkers with "can be your commander" text).
  • Partner & Dual Commanders: Automatic support for Partner, Partner with [Name], Friends Forever, Choose a Background, and Doctor's Companion.
  • Dynamic Command Zone Switching: 1-click commander dropdown selector and seamless mainboard/command zone swaps.
• Direct Online URL Importers: Instant 1-click deck import from MTGGoldfish, Moxfield, Archidekt, and Scryfall with automatic Commander extraction.
• Analytics & Mana Visualizer: Live Mana Curve, Color Identity breakdown, card type distribution, and Commander-specific financial totals.
• Proxy Flagging: Mark cards as proxies in both Decks and Cubes; excluded from missing wishlist exports and tracked in analytics.
• Playtesting Simulator: 7-Card opening hand and mulligan testing suite.
• Precon Library: Instant pre-constructed deck loader backed by PostgreSQL JSONB storage.
• Multi-Format Deck Export: 1-click export and file download for MTG Arena, MTGO (.dec), Plain Text, and CSV.

🤝 TradePost & SilkRoad Network Sync

• Want / Have Exchange Matrix: Track trade-in and want lists with live multi-currency market values.
• SilkRoad Cloud Synchronization: Connect and synchronize trade pools across nodes with RS256 cryptographic lease verification and conflict resolution modes.
• Public Shareable Showcase Links: Generate isolated, cryptographically unguessable public URLs (/share/:type/:token) for wishlists, tradelists, binders, or constructed decks.
• Security Isolation: Public visitors access sanitized read-only views with zero internal credential or database visibility.

🔔 Price Alerts & Market Watcher

• Multi-Marketplace Alerts: Monitor price dips across TCGPlayer, Cardmarket, ManaPool, CardKingdom, and eBay.
• Automated Scanning & SMTP: Background price checking with instant email notifications when targets hit.

📷 AI Visual Card Scanner & Neural Vector Suite

• Zero-External-Dependency Computer Vision:
  • Client-side Web Worker inference powered by ONNX Runtime Web WebAssembly (WASM) for fast, real-time live video card detection.
  • Corner detector model (cornelius.onnx) and high-dimensional neural visual embeddings (milo.onnx) with zero cloud dependencies.
  • Complete standalone MTG vector catalog (nahalo-catalog.npz) containing 121,369+ indexed cards for lightning-fast cosine similarity identification.
• Self-Hosted Forgejo Release Asset Distribution:
  • One-click model and vector sync directly from your self-hosted Forgejo release assets (https://forge.nahalopagus.cc/przemchess/nahalo-vault-models/releases/download/latest).
  • Smart Remote Update Check: Performs HTTP HEAD verification against remote releases to skip redundant downloads and only pull updated or missing assets.
• Standalone CLI Neural Vector Indexer:
  • Built-in script npm run index:vectors to index new MTG sets from Scryfall images using multi-threaded CPU acceleration.
• Browser WASM Diagnostics:
  • Integrated diagnostics suite in Settings → Scanner & AI Models to benchmark Web Worker latency, WebAssembly capabilities, and test card identification samples.

🛡️ Security, Audit Trail & Control Panel

• Zero-Vulnerability Hardened Stack: Fully audited dependency graph (npm audit reporting 0 vulnerabilities).
• Master Password Security: BCrypt password hashing, session versioning, and auto-generated persisted JWT secrets.
• Comprehensive Audit Trail: Real-time logging of authentication events, collection mutations, binder changes, deck updates, and public link access.
• Scryfall Bulk Data & Offline Image Cache: Download sets for offline high-res image serving with disk telemetry and cache purge tools.
• Automated Scheduled Backups: Recurring database backup snapshots stored to disk or manual browser export.

💻 Standalone Native Desktop Edition (Windows & macOS)

• Zero-Dependency In-Process Database: Powered by an embedded @electric-sql/pglite WebAssembly PostgreSQL engine with full relational features, JSONB, and Drizzle migrations — no Docker or external database required.
• Ultra-Fast Cold Start: Instant frameless splash window with real-time phase progress and background Scryfall card catalog warmup.
• Isolated Native AppData Storage: Complete isolation of collections, card imagery cache, and backup dumps under user data directory (%APPDATA% on Windows, Application Support on macOS) guaranteed safe across all application updates.
• System Tray Controls & In-App Auto-Updates: Minimize-to-tray, quick navigation, live storage footprint telemetry, and background update checks against external Forgejo releases.

---

🖼️ Interface Showcase

Collection & Binder Vault	Portfolio Financials & Market Movers
Interactive card grid with density zoom slider, finish badges, and multi-criteria sorting.	Multi-currency valuation, top gainers, price drops, and historical sparklines.
Tactical Deck Builder	MTG Cube Designer
Commander legality engine, visual mana curve, and playtesting simulator.	Color-segregated cube boards, land stations, and live vault completion.
Set Completion Matrix & Buylist	AI Neural Card Scanner
Physical set matrices with bonus sheets and multi-store buylist export.	Zero-dependency live Web Worker card detection and vector similarity matching.

---

🚀 Quick Start (Production Docker)

The easiest way to run Nahalo Vault in production is using Docker Compose:

1. Clone & Configure Environment

git clone https://forge.nahalopagus.cc/przemchess/nahalo-vault.git
cd nahalo-vault
cp .env.example .env

Edit .env to set your desired POSTGRES_PASSWORD and host port APP_PORT (default 5175).

2. Launch the Production Stack

docker compose -f docker-compose.prod.yml up -d --build

• Web App: http://localhost:5175 (or your configured APP_PORT)
• Backend API: Proxied internally by Nginx to Node.js runtime

---

🔄 Updating Nahalo Vault

Checking for Updates

• Automatic Alerts: Nahalo Vault checks Forgejo for new releases in the background. A badge indicator appears on the navigation bar and in Settings whenever a new release is available.
• Manual Check: You can manually check for updates at any time by clicking "Check for Updates" in Settings or on the About page.

---

1. Configuring Local Git for Seamless Updates

Before updating, ensure your local repository is properly configured to track the upstream remote and authenticate without repetitive prompts.

A. Verify & Set Git Remote

Check your current Git remote configuration:

git remote -v

If your remote is not configured or needs to point to the repository, set your origin URL using either HTTPS or SSH:

# Option 1: Via HTTPS (Recommended for standard web/token access)
git remote set-url origin https://forge.nahalopagus.cc/przemchess/nahalo-vault.git

B. Configure Git Pull Strategy & Credentials

Avoid unexpected rebase errors or merge prompts when pulling new updates:

# Set standard 3-way merge strategy for pulls
git config pull.rebase false

# Ensure the local main branch tracks upstream origin/main
git branch --set-upstream-to=origin/main main

# (Optional) Cache HTTPS credentials so you don't have to re-enter tokens/passwords:
git config --global credential.helper store

C. Handling Local Changes Before Pulling

Nahalo Vault stores instance secrets, passwords, and ports in .env, which is listed in .gitignore and will never be overwritten by git pull.

If you have uncommitted changes or accidental modifications in your working tree:

# Check working tree status
git status

# Temporarily stash local changes before pulling:
git stash

# Or discard any accidental source file modifications to restore a clean state:
git restore .

---

2. Updating a Production Docker Instance (Recommended)

Once your Git remote is configured, updating your running instance takes two simple commands:

# Step 1: Pull the latest commits from the repository
git checkout main
git pull origin main

# (Optional) If updating to a specific release tag:
# git fetch --tags
# git checkout v1.5.6

# Step 2: Rebuild images and restart the containers in the background
docker compose -f docker-compose.prod.yml up -d --build
# Or if using default docker-compose.yml:
# docker compose up -d --build

Verify Container Status & Logs

# Check running containers
docker compose ps

# View backend logs to verify automated database schema verification
docker compose logs -f backend

Automatic Schema Migration: Upon launch, the backend container automatically runs internal database schema verification and applies any new tables, columns, or indexes (e.g. price history, joint binders) with zero manual SQL intervention.

🛡️ Data Persistence Guarantee: All collections, cards, binders, decks, cubes, price histories, audit logs, and downloaded Scryfall image caches are stored in persisted Docker volumes (pgdata_vault, card_images, scheduled_backups) and remain 100% safe and intact across updates and image rebuilds.

---

3. Updating a Local Node.js Development Setup

If you run Nahalo Vault directly on your machine without Docker:

# Step 1: Pull the latest changes
git checkout main
git pull origin main

# Step 2: Install updated workspace dependencies
npm install
npm --prefix server install
npm --prefix client install

# Step 3: Apply any new database schema migrations
npm --prefix server run db:push

# Step 4: Restart development mode
npm run dev

---

4. Automated 1-Command Update Scripts

Quick One-Liner (Linux / macOS / PowerShell)

git pull origin main && docker compose -f docker-compose.prod.yml up -d --build

Optional update.sh (Linux / macOS / WSL)

Create an update.sh script in the root of the project:

#!/usr/bin/env bash
set -e

echo "🛡️  Updating Nahalo Vault..."
git checkout main
git pull origin main

echo "📦 Rebuilding and restarting Docker containers..."
docker compose -f docker-compose.prod.yml up -d --build

echo "✅ Nahalo Vault updated successfully! Running on port ${APP_PORT:-5175}."
docker compose ps

Make it executable:

chmod +x update.sh
./update.sh

Optional update.bat (Windows Command Prompt)

Create an update.bat script in the root of the project:

@echo off
echo [Nahalo Vault] Updating to latest version...
git checkout main
git pull origin main
docker compose -f docker-compose.prod.yml up -d --build
echo [Nahalo Vault] Update complete!
docker compose ps

---

🛠️ Local Development

Prerequisites

• Node.js 20+
• PostgreSQL 16+ (or run via docker compose -f docker-compose.dev.yml up db -d)

1. Install Dependencies

npm install
npm --prefix server install
npm --prefix client install

2. Push Database Schema

npm --prefix server run db:push

3. Start Development Servers

npm run dev

• Client runs on http://localhost:5175
• Backend API runs on http://localhost:3005

4. Standalone Neural Vector Indexing (CLI)

To index new MTG sets or expand the standalone vector catalog directly on your workstation:

# Index the 5 most recent sets
npm --prefix server run index:vectors -- --recent=5

# Index specific MTG set codes
npm --prefix server run index:vectors -- --sets=BLB,OTJ,FDN

# Index all missing paper cards across the entire Scryfall database
npm --prefix server run index:vectors -- --all --concurrency=8

---

💻 Desktop Application (Windows & macOS Standalone)

Nahalo Vault can be packaged as a completely standalone native desktop application with zero external dependencies (no Docker or manual PostgreSQL setup required). It bundles an embedded @electric-sql/pglite in-process PostgreSQL database engine, an instant startup splash screen, window state persistence, system tray controls, automatic update checking, and isolated native local storage.

⚡ Highlights & Key Capabilities

• Zero-Configuration Embedded Database: Uses @electric-sql/pglite, an in-process PostgreSQL engine running via WebAssembly/Node.js. Full PostgreSQL dialect, ACID transactions, JSONB, and automated Drizzle ORM migrations without running any external database server.
• Instant Cold Start & Asynchronous Warmup: Launches a frameless splash screen in <100ms with real-time loading phase telemetry (allocating_port, storage_init, spawning_process, warming_cache). Heavy Scryfall card catalog caching and AI vector index loading run asynchronously in the background.
• System Tray & Window Management: Tray icon with quick actions (Open Vault, Open in External Browser, Open Data Directory, Check for Updates) and persistent window dimensions/position across restarts.
• In-App Auto-Updates (electron-updater): Queries external Forgejo releases in the background, showing one-click update prompts and background asset downloads.
• Direct SilkRoad Network Sync: Synchronizes public trade lists and wishlists with remote SilkRoad hub instances directly from the desktop client.

---

📂 Local Storage Architecture & Data Persistence

The desktop application stores all user data, database records, artwork caches, backups, and AI models in the operating system's native User Data (app.getPath('userData')) directory:

Storage Locations by Operating System

Operating System	Default Storage Path
Windows	%APPDATA%\nahalo-vault-desktop\ (C:\Users\<Username>\AppData\Roaming\nahalo-vault-desktop\)
macOS	~/Library/Application Support/nahalo-vault-desktop/
Linux	~/.config/nahalo-vault-desktop/

Internal Storage Hierarchy

nahalo-vault-desktop/
├── data/
│   ├── pglite/          # Embedded PostgreSQL database files (all collections, binders, decks, cubes, price history, audit logs)
│   ├── card-images/     # Local Scryfall card artwork & crop cache for offline browsing
│   ├── backups/         # Automated recurring snapshots and manual database export dumps
│   └── models/          # Neural scanner models (cornelius.onnx, milo.onnx) & vector catalog (nahalo-catalog.npz)
├── window-state.json    # Window geometry, dimensions, screen position, and maximized state
└── desktop.log          # Diagnostic log tracking process lifecycle and background server operations

🛡️ Data Persistence & Update Safety Guarantee

• Complete Decoupling: User data is strictly separated from the application binary / installation directory (Program Files or /Applications).
• Update Safety: Installing a new version (via NSIS installer, portable .exe, .dmg, or the in-app auto-updater) never modifies or deletes your userData directory. Your collection cards, binders, decks, custom price histories, and cached images remain 100% persistent and intact across all updates.
• Easy Backups & Migration: Because all state is stored under a single directory, you can back up or migrate your entire vault by simply copying the nahalo-vault-desktop folder.

📊 In-App Telemetry & File Explorer / Finder Access

• Disk Footprint Telemetry: Navigate to Settings → Desktop Environment & Local Storage to view real-time disk consumption broken down by Database (pglite/), Card Images (card-images/), Backups (backups/), and AI Models (models/).
• 1-Click Folder Access: Click "Open Folder in Explorer" (or "Reveal in Finder") in Settings, or right-click the System Tray icon and select "Open Data Directory" to open the storage folder instantly.

---

📥 Download Pre-Built Desktop Installers

Pre-compiled standalone binaries for Windows, macOS, and Linux are available directly from the Releases Page:

Platform	Format	Description
Windows	Nahalo Vault Setup <version>.exe	Full NSIS installer with desktop shortcuts and automatic background updates
Windows	Nahalo Vault <version>.exe	Standalone portable executable (no installation required)
macOS (Apple Silicon)	Nahalo Vault-<version>-arm64.dmg	Native Apple Silicon (arm64) disk image installer
macOS (Intel)	Nahalo Vault-<version>.dmg	Intel (x64) disk image installer
Linux	.AppImage / .deb	Linux portable binary and Debian/Ubuntu package

💡 In-App Auto Updates: Once installed, the desktop application checks for new releases on Forgejo automatically and can update seamlessly in place with zero data loss.

---

⚙️ Environment Configuration (.env)

Variable	Description	Default
APP_PORT	Host port exposed for web app	5175
NODE_ENV	Environment mode (production / development)	production
POSTGRES_USER	Database username	postgres
POSTGRES_PASSWORD	Database password	postgres
POSTGRES_DB	Database name	mtg_vault
CLIENT_URL	Public origin URL for reverse proxy routing	http://localhost:5175
ALLOWED_ORIGINS	Comma-separated list of allowed CORS origins	http://localhost:5175,http://localhost:80
FORGEJO_ASSETS_BASE_URL	Remote Forgejo release assets URL for AI models & vector catalog	https://forge.nahalopagus.cc/przemchess/nahalo-vault-models/releases/download/latest
NAHALO_CATALOG_URL	(Optional) Direct download URL override for nahalo-catalog.npz	Derived from Forgejo Base URL
JWT_SECRET	(Optional) Pre-defined 64-character JWT secret	Auto-generated in DB
VAULT_MASTER_PASSWORD	(Optional) Pre-configured master password fallback	Configured on first launch

---

📜 License & Disclaimers

License

This project is free and open-source software licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). Copyright (C) 2026 PJM.

In accordance with Section 13 of the AGPLv3, if you run a modified version of Nahalo Vault on a network server, you must provide the corresponding source code of your version to all users interacting with it remotely.

Wizards of the Coast Fan Content Policy

Nahalo Vault is unofficial Fan Content permitted under the Wizards of the Coast Fan Content Policy. Portions of the materials used are property of Wizards of the Coast. © Wizards of the Coast LLC.

Scryfall Attribution

Card data, prices, imagery, and mana symbols are powered by the Scryfall API. Scryfall is not affiliated with this project.