mtgc/README.md

mtgc — Personal Magic: The Gathering Library Catalog

A desktop app (Tauri v2 + React) for cataloging your MTG collection: rapid fuzzy card entry, rich criteria search (colors, commander color-identity compatibility, mana value, type/subtype/keyword), and deck organization with per-card deck membership. Built so the eventual mobile port is cheap — all logic lives in a platform-agnostic Rust core.

Architecture

src/                 React + TypeScript UI (swappable presentation)
src-tauri/           Tauri v2 shell — exposes the core as typed commands
crates/mtgc-core/    Pure Rust: db, fuzzy search, filters, decks, ingester

Two SQLite databases, joined at runtime via ATTACH:

• reference.db — read-only card data built from Scryfall bulk. Bulky, re-downloadable per device, not synced.
• library.db — your owned cards + decks. Small, portable, the file you sync (drop it in Syncthing/Dropbox/Nextcloud). Point the app at it via Choose library file….

Both default to the OS app-data dir (e.g. ~/.local/share/com.garrettmills.mtgc/).

First-time setup

./scripts/devel-setup.sh     # Tauri system libs (webkit2gtk/gtk3) + Tauri CLI
npm install                  # frontend deps

Run

cargo tauri dev              # launches the desktop app (dev mode)

On first launch, click Download card data — it fetches the Scryfall Oracle Cards + Default Cards bulk (~a few hundred MB) and builds reference.db. After that the app is fully offline.

You can also build the card database from the command line:

cargo run -p mtgc-core --bin mtgc-ingest -- /path/to/reference.db

Production build

Build an optimized app with the frontend embedded into the executable:

./scripts/devel-setup.sh   # once, if not already done
cargo tauri build

Outputs (under the workspace target/release/):

• target/release/mtgc-app — the standalone executable. The web UI and all app logic are baked into this one file. It dynamically links the system WebKit/GTK libraries (webkit2gtk4.1, gtk3), so those must be present on the machine that runs it — they are on any modern desktop Linux and are installed by devel-setup.sh.
• target/release/bundle/appimage/*.AppImage — a single portable file that bundles the app together with its runtime. This is the closest thing to a download-and-run single self-contained binary: chmod +x it and run. Recommended for copying to another machine.
• target/release/bundle/rpm/*.rpm and .../deb/*.deb — native installers (Fedora / Debian-based) that add a menu entry and icon.

Useful variants:

cargo tauri build --bundles appimage   # only the portable AppImage, skip installers
cargo tauri build --no-bundle          # only the bare target/release/mtgc-app binary

Notes:

• On Linux the truly portable single file is the AppImage; the bare mtgc-app binary is also a single file but relies on the system WebKit/GTK libs.
• The binary does not embed card data — first run still downloads the Scryfall bulk into the OS app-data dir, and your synced library.db lives there by default (override with Choose library file…).
• The [profile.release] settings in Cargo.toml (strip + LTO) make the release build take a few minutes but keep the binary small.

Using it

• Add Cards — type a name (typos OK); ↑/↓ then Enter adds a copy.
• Library — filter owned cards by name, colors, commander identity (color identity ⊆ chosen), mana value range, type/subtype/keyword, or deck. Hover a row's thumbnail for a full-size preview that tracks the cursor. Rows show which decks a card is in and a warning (⚠) when it's assigned to more decks than you own. Toggle List / Tiles (top-right) to switch between the table and a grid of full card images; the choice is remembered.
• Deck contents offer the same List / Tiles toggle and hover previews.
• Decks — create decks and assign owned cards; set per-deck quantities.

Develop / test

cargo test -p mtgc-core      # core unit tests (db, search, filters, decks, ingest)
npm run build                # typecheck + build frontend
cargo build                  # build everything incl. the desktop app

Mobile (future)

The core and frontend are platform-agnostic; cargo tauri icon already emitted iOS/Android icon sets. Porting is adding tauri ios / tauri android targets — only reference-data provisioning differs (download on-device).