mtgc/README.md

# mtgc — Personal Magic: The Gathering Library Catalog

A desktop and Android 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, price, format
legality), and deck organization with per-card deck membership. All logic lives
in a platform-agnostic Rust core, so both platforms share it.

## 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, sync
crates/mtgc-server/  Optional sync server: one library per user, OIDC and/or passwords
```

Two kinds of data, both in the OS app-data dir (e.g.
`~/.local/share/com.garrettmills.mtgc/`):

- **your library** — owned cards, decks, deck contents. Lives on each device
  and works fully offline; sign in to a sync server to share it between
  devices (see [Sync](#sync)). **Export library…** in the Info tab saves it as
  a JSON backup.
- **`reference.db`** — read-only card data built from Scryfall bulk. Bulky and
  re-downloaded per device, so it's never synced.

## First-time setup

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

> **Why GTK3, not GTK4?** Tauri v2's Linux backend (`wry`/`tao`) hard-depends on
> GTK3 + `webkit2gtk-4.1`; there's no GTK4/webkitgtk-6.0 option yet. GTK4 support is
> tracked upstream but unmerged with no ETA:
> [tauri#7335](https://github.com/tauri-apps/tauri/issues/7335),
> [tao#1104](https://github.com/tauri-apps/tao/pull/1104),
> [wry#1228](https://github.com/tauri-apps/wry/issues/1228). Revisit once Tauri
> ships GTK4 support (likely Tauri v3).

## Run

```bash
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:

```bash
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:

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

Outputs (under the workspace `target/release/`):

- **`target/release/mtgc`** — 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/rpm/*.rpm`** and **`.../deb/*.deb`** — native installers
  (Fedora / Debian-based) that add a menu entry and icon.

Useful variants:

```bash
cargo tauri build --no-bundle          # only the bare target/release/mtgc binary
```

Notes:

- The `mtgc` binary is a single file but relies on the system WebKit/GTK libs
  being present (installed by `devel-setup.sh`).
- The binary does **not** embed card data — first run still downloads the Scryfall
  bulk into the OS app-data dir. Your library lives there too; to share it
  between devices, see [Sync](#sync).
- 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, power/toughness, price, format legality,
  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.
- **Card Search** — the same filters over *every* card, owned or not. Select
  rows (or tiles) and bulk-add them to a deck; one undo covers the whole batch.
- Deck contents offer the same List / Tiles toggle and hover previews.
- **Decks** — create decks and assign owned cards; set per-deck quantities.

Both filter panels share a row of quick toggles: hide **Universes Beyond**
(cards that exist only as another property — Lord of the Rings, Warhammer
40,000, Marvel), hide **digital-only** (Arena/MTGO cards such as Alchemy
rebalances), hide **Un-set** joke cards, or keep only cards that **can be a
commander**. The three exclusions are derived as *every* printing, so an
ordinary card reprinted into one of those sets — Lightning Bolt appears in
Marvel Commander — isn't hidden.

> Those three, plus the power/toughness filters, live in `reference.db`, which
> is rebuilt rather than migrated. After upgrading, click **Update card data**
> once to enable them; until then they're inert rather than broken. Price,
> format legality and *can be a commander* work immediately.

## Sync

Your library always lives on the device you're using, so the app works the
same with or without a network. To keep several devices in step, run an
[mtgc sync server](#running-the-sync-server) and sign in to it from each one:
**Info → Sync server**, enter its address, and **Sign in…**. Sign-in happens
in your browser, on the server's own page — with a username and password, or
through your single sign-on provider, whichever the server offers — and the
browser hands the app back a token for that device alone.

Editing in two places merges rather than one side overwriting the other. Each
device remembers the last version of the library it knows the server had, and
merges three ways against it — which is what lets it tell "you changed this"
from "they deleted it": edit different cards on a phone offline and on the
desktop, and both survive. When both sides change the *same* field, the
server's value wins and the change is reported so you can correct it.

Sync runs by itself — at launch, on every switch away from and back to the app,
on reconnecting, and every few minutes while open. The top bar shows where it
stands (**Synced**, **Offline — changes will sync**, …); **Sync now** in the
Info tab forces a pass. Offline, edits simply wait on the device: nothing is
lost, and they go out with the next sync that reaches the server.

The first time a device signs in to an account that already has a library,
and the device has one too, it asks whether to **combine** them (nothing from
either is lost) or **use the server's library** instead of this device's.

The Info tab also lists the account's signed-in devices, so a lost phone can be
signed out from another one.

> **Upgrading from folder sync?** Earlier versions kept the library as a JSON
> file in a folder your sync tool watched. Your library is already on each
> device, so signing in to a server picks up from there; the first device to
> sign in uploads it. If one device's copy is out of date, use **Import library
> file…** on it to combine in the `library.json` from the synced folder. Builds
> older still had you manage `library.db` yourself; the Info tab offers
> **Import old library** once for that.

## Running the sync server

`mtgc-server` is a single binary with a SQLite database, shipped as a
container image. Inside the container it listens on port 8080 and keeps its
database in `/data`; everything else is environment variables (below).

To run it locally, build the image, then run it with the port forwarded to
localhost and a named volume for the data:

```bash
docker build -f crates/mtgc-server/Dockerfile -t mtgc-sync-server .

docker run -d --name mtgc-sync-server \
  -p 127.0.0.1:8080:8080 \
  -v mtgc-sync-data:/data \
  -e MTGC_PUBLIC_URL=http://localhost:8080 \
  mtgc-sync-server

docker exec -it mtgc-sync-server mtgc-server user add yourname   # prompts for a password
```

Then sign in from the desktop app with `http://localhost:8080`. For more
settings, copy `crates/mtgc-server/deploy/.env.example` to `.env` beside it
(git ignores it) and pass `--env-file crates/mtgc-server/deploy/.env` instead
of the `-e`. Podman takes the same commands.

The container runs as UID 10001. A named volume, as above, picks up the right
ownership by itself; if you bind-mount a host directory instead, `chown 10001`
it first.

In production, put it behind something that terminates HTTPS — the Android
app refuses plain HTTP outside debug builds — and set `MTGC_PUBLIC_URL` to
the `https://` address users reach it at. On Kubernetes that means a
Deployment with **one replica** (it's a single SQLite file, so replicas can't
share it) and a `Recreate` strategy, a PersistentVolumeClaim mounted at
`/data`, a Service on port 8080, and an Ingress for TLS. `GET /healthz`
answers `ok` for probes. Keep `MTGC_OIDC_CLIENT_SECRET` in a Secret. Run the
account commands with `kubectl exec -it deploy/<name> -- mtgc-server user add
<name>`.

To build the image yourself and push it to your own registry:

```bash
DOCKER_REGISTRY=registry.example.com npm run sync-server:build   # → registry.example.com/mtgc/sync-server:latest
DOCKER_REGISTRY=registry.example.com npm run sync-server:push
```

Both call `scripts/sync-server-image.sh`. `IMAGE_TAG` overrides the `latest`
tag, and `CONTAINER_ENGINE=podman` picks podman when docker is also installed.

Configuration is all environment variables:

| Variable | Default | |
|---|---|---|
| `MTGC_PUBLIC_URL` | *(required)* | The `https://` address users reach the server at, exactly as the proxy serves it |
| `MTGC_BIND` | `0.0.0.0:8080` | Listen address |
| `MTGC_DB` | `mtgc-server.db` | SQLite database path |
| `MTGC_LOCAL_AUTH` | `true` | Username/password accounts |
| `MTGC_OIDC_ISSUER` | — | Turns on single sign-on, e.g. `https://auth.example.com/application/o/mtgc/` |
| `MTGC_OIDC_CLIENT_ID`, `MTGC_OIDC_CLIENT_SECRET` | — | A confidential client, with redirect URI `${MTGC_PUBLIC_URL}/auth/callback` |
| `MTGC_OIDC_NAME` | `single sign-on` | Shown on the button: "Sign in with …" |
| `MTGC_OIDC_SCOPES` | `openid email profile` | |
| `MTGC_ALLOWED_EMAILS` | — | Comma-separated allow list of verified emails; unset leaves it to the provider |

With both sign-in methods on, the sign-in page offers both; with only single
sign-on, it goes straight to the provider. Each provider identity and each
local account is its own user with its own library.

Local accounts are managed from the command line; there's no sign-up page, so
a server on the internet can't be filled with accounts by strangers:

```bash
mtgc-server user add <name> [--display-name <text>]   # prompts for a password
mtgc-server user passwd <name>
mtgc-server user remove <name> --yes                  # also deletes their server-side library
mtgc-server user list
```

The server keeps the last 50 versions of each library in its database
(`library_history`) as a safety net for recovering by hand.

## Develop / test

```bash
cargo test -p mtgc-core      # core: db, search, filters, decks, ingest, sync merge + cycle
cargo test -p mtgc           # shell: config, merge-base storage, sign-in listener
cargo test -p mtgc-server    # server: sign-in, compare-and-swap, devices, end-to-end sync
npm run build                # typecheck + build frontend
cargo build                  # build everything incl. the desktop app
```

The sync merge is a pure function over plain structs (`mtgc_core::sync::merge3`),
and the sync cycle runs over a `Remote` trait (`mtgc_core::sync::remote`), so the
cases that matter — concurrent edits, a delete racing an edit, a lost reply, a
lost write race — are unit tests rather than something you have to reproduce
across two devices. `crates/mtgc-server/tests/sync_e2e.rs` then runs two
devices against the real server over HTTP.

To try sign-in by hand, run a server locally (`MTGC_PUBLIC_URL=http://127.0.0.1:8080
cargo run -p mtgc-server`, after `cargo run -p mtgc-server -- user add me`) and
sign in from the app with that address. From the Android emulator, the host is
`http://10.0.2.2:8080`; debug builds allow plain HTTP.

To typecheck the Android Kotlin without building the APK (it doesn't invoke
cargo, so it won't disturb a running dev session):

```bash
cd src-tauri/gen/android && ./gradlew :app:compileUniversalDebugKotlin
```

## Android

The Rust core and frontend are platform-agnostic, so the Android build shares
all app logic with the desktop; only data provisioning and file access differ.

### One-time setup

Install Android Studio and **launch it once** so its wizard downloads the SDK,
then:

```bash
./scripts/android-setup.sh
```

That adds what Android Studio doesn't install by default: the SDK
command-line tools, a pinned stable **NDK**, and the Rust Android targets. It
prints the three environment variables to export (`ANDROID_HOME`, `NDK_HOME`,
`JAVA_HOME`).

> **Why the NDK?** `mtgc-core` builds `rusqlite` with the `bundled` feature
> (compiles SQLite from C) and `rustls` pulls in `ring` (C/asm), so a C
> cross-toolchain is required. The bundled SQLite can't be swapped for
> Android's system libsqlite3 either — the card schema needs FTS5 with the
> `trigram` tokenizer, which platform SQLite often lacks.

> **Why `JAVA_HOME`?** Gradle/AGP reject very new JDKs. The script prefers
> Android Studio's bundled JetBrains Runtime (JDK 21), which needs no extra
> install.

### Build and run

Every Android command needs `ANDROID_HOME` / `NDK_HOME` / `JAVA_HOME`. Source
the helper once per shell — it auto-detects all three:

```bash
source scripts/android-env.sh      # bash / zsh
```

```fish
source scripts/android-env.fish    # fish
```

Only the env helper is shell-specific (it has to mutate the calling shell);
`android-setup.sh` is executed rather than sourced, so it works from any shell.

Then, from the project root:

```bash
cargo tauri android dev --open   # dev server + open in Android Studio
cargo tauri android build --apk  # standalone release APK
```

`src-tauri/gen/android` is committed (unlike the rest of `gen/`) because
`AndroidManifest.xml` is hand-edited — Android permissions have no
`tauri.conf.json` equivalent.

### Working in Android Studio

Use **`cargo tauri android dev --open`** rather than opening
`src-tauri/gen/android` directly. Studio's Run button delegates the Rust build
to `cargo tauri android android-studio-script`, which expects a running Tauri
dev session — it reads the dev-server address from
`/tmp/<identifier>-server-addr`. Open the Gradle project on its own and the
build fails with `failed to read missing addr file`.

With the dev session running, Studio's device dropdown, Device Manager
(emulator), and debugger all work normally.

> **JetBrains Toolbox users:** `--open` finds Studio by scanning XDG data dirs
> for a `.desktop` entry whose `Name` is *exactly* `Android Studio`. Toolbox
> writes a versioned name instead (e.g. `Android Studio Quail 2 2026.1.2 Patch
> 1`), so the lookup misses and the launch fails with a confusing
> `Cmd(["Android Studio"]) ... No such file or directory`. `android-setup.sh`
> drops in a hidden shim entry (`~/.local/share/applications/android-studio.desktop`)
> to fix this; delete that file to undo it.

To build without Studio and without a dev server, use `cargo tauri android
build` — that path needs no addr file.

### Card data on a phone

Downloading card data streams ~740MB of JSON to build a ~73MB database, which
is slow on mobile and may be killed if the app is backgrounded. Faster: copy
`reference.db` from a desktop install onto the device and use **Import card
data…**. The file is validated before it replaces anything.

### Sync on Android

Signing in works as on desktop: the browser opens the server's sign-in page,
and returns to the app through the `mtgc://` URL scheme (registered by the
deep-link plugin from `plugins.deep-link` in `tauri.conf.json`). The app needs
no storage permission — the library lives in its private storage, and syncing
is network only.

## Branding

The logo is an original pirate-ship silhouette in the terracotta brand color
(`#C8553D`) — a nod to the MTG card "Pirate Ship", not a reproduction of its
art. Source: `src-tauri/icons/logo-source.svg`. To regenerate the full
platform icon set after editing it:

```bash
cargo tauri icon src-tauri/icons/logo-source.svg
```