Skip to content

features.md

Latest commit

 

History

History
241 lines (197 loc) · 10.6 KB

features.md

File metadata and controls

241 lines (197 loc) · 10.6 KB
Raw

ManaVault Feature Reference

This reference names the product concepts and workflows that appear across the app. It is intentionally more detailed than the README.

Core Concepts

  • Card identity - the game object shared by all printings of a card. ManaVault stores this using Scryfall's oracle_id and card-level fields such as name, type line, mana cost, oracle text, colors, and color identity.
  • Printing - a specific physical or digital release of a card, keyed by Scryfall id. Printings carry set code, collector number, language, rarity, finishes, images, release date, and price data.
  • Collection item - a stack of physical cards you own that share the same printing, condition, finish, language, purchase price, notes, and storage location. Quantity lives here.
  • Location - a real storage place such as a box, binder, deck box, list, folder, or other container.
  • Deck - a named list with format/status metadata and deck-card rows for requested cards, quantities, zones, finishes, commander flags, tags, and preferred printings.
  • Deck allocation - a reservation connecting one deck card to one collection item. Allocations bridge decklists and physical inventory.
  • Missing cards - deck demand that remains after allocated and available collection copies are counted. Missing-card exports can be tuned by printing mode and basic-land inclusion.

Card Catalog

ManaVault syncs Scryfall bulk data into the local database. Card search uses that local catalog and supports structured filters shared with collection search.

Card detail pages show:

  • oracle text and mana symbols
  • Scryfall oracle tags, deck category, and deck themes
  • format legalities
  • rulings
  • all synced printings with set, collector number, language, rarity, finishes, release date, images, and prices
  • full-screen printing previews
  • add-to-collection and add-to-deck actions from exact printings

Collection

The collection has two primary views:

  • Locations - storage containers with counts, cover cards, value summaries, and per-location item lists.
  • All cards - a filterable, sortable inventory list across locations.

Collection items track:

  • exact printing
  • quantity
  • condition
  • finish (nonfoil, foil, or etched when available)
  • language
  • purchase price and current value gain/loss
  • location
  • notes
  • allocated quantity

Collection workflows include:

  • single-card add/edit/delete
  • location create/edit/delete
  • TXT/CSV import preview and commit, with an optional default purchase price
  • CSV/TXT export for the current filters
  • Android/iOS share/open-with import handoff from native shells
  • search, sort, and structured filters for color, type, rarity, price, year, finish, and other card fields
  • persisted collection view state so back navigation restores the previous tab, filters, search, and sort
  • bulk selection for loaded or matching items, with add-to-deck, add-to-list, move, and delete flows

Decks

Decks model requested cards separately from owned collection items. A deck card can point at a preferred printing and finish while still being resolved against available collection copies.

Deck workflows include:

  • create, edit, and delete decks
  • import and export decklists
  • mainboard/commander/considering zones - a segmented Mainboard/Considering toggle (plus Commander for Commander decks) picks the zone when adding or moving cards. Considering replaced the old sideboard and maybeboard zones; a migration merged existing rows, and decklist import still accepts SB:, Sideboard, Maybe, and Maybeboard headings, mapping them all to Considering. Exports emit a Considering heading.
  • commander selection for Commander decks
  • quantity, zone, tag, finish, and preferred-printing edits
  • deck grouping by theme/category and zone tables
  • bulk deck-card selection and movement
  • public share links with owner controls to rotate the bearer link or disable sharing immediately
  • read-only shared deck pages with copy/export/playtest actions
  • user-initiated AI analysis of goals, themes, game plan, tuning options, and consistency, saved with the deck below its primer
  • one-off AI questions about card fit, cuts, matchups, and deck changes, with answers shown in a private dialog rather than saved to the deck

AI analysis currently supports OpenRouter. The owner configures and validates an API key and model ID in Settings; the key is encrypted at rest and is never returned through GraphQL. Deck data is sent only when the owner explicitly runs an analysis or asks a question. Commander results keep the guideline bracket separate from the estimated practical play bracket, so labels can communicate distinctions such as Bracket 3 (plays like Bracket 2). The saved label appears on deck cards, the deck header, and shared preview images.

Trade

The Trade tab connects owned inventory to trading with other players:

  • Binder - the collection grid with a centered circular glass toggle on each tile that marks a collection item up for trade, plus an only-for-trade filter and a flagged count. Items stored in list-kind locations never count as tradable copies. The binder is shareable like the want list: a share token backs a public read-only page at /share/binder/... showing each for-trade printing with finish and condition. The share dialog can rotate the link or disable sharing.
  • Wants - a card-search-backed want list with quantities. Wants are either generic ("any printing") or pinned to an exact printing via the opt-in printing picker or the Add to wants action on a card detail printing. The want list is shareable: a deck-style share token backs a public read-only page at /share/wants/...; its share dialog can rotate the link or disable sharing.
  • Matches - paste list text or a supported link, declare whether the list is the partner's haves or wants, and see the overlap: cards you have up for trade that they want, or cards they have that are on your want list. Unrecognized lines are reported.

Both share pages offer copy-to-clipboard (with a plain-http fallback) and .txt download of the list as standard decklist text, ready to paste into any ManaVault Matches tab or other deck tools.

Deck detail pages additionally offer a Compare decklist action that diffs an external list against the open deck as adds, cuts, and quantity changes (considering piles excluded on both sides - the diff compares the actual deck), with a copyable +/- text diff. Basic lands are compared by name and only appear when the two sides disagree on the count - equal counts cancel instead of showing paired add/cut rows. Diff rows are actionable: adds can be added to the deck's Considering pile (individually or all at once), and cuts or downward quantity changes can tag the matching deck cards as consider-cutting.

Supported link sources are Moxfield and Archidekt deck URLs (fetched server-side from their public APIs with strict id validation, no redirects, and size/time caps) plus ManaVault /share/decks/..., /share/wants/..., and /share/binder/... links from any instance: relative links resolve locally by share token, and absolute links are fetched from that link's origin through its public /share/graphql endpoint. Public Internet destinations work by default. Private, loopback, link-local, and other non-public destinations are blocked unless the operator explicitly allows the intended hostname or network with MANAVAULT_REMOTE_SHARE_ALLOWLIST; this preserves opt-in LAN sharing between self-hosted friends without making internal services generally reachable. DNS results are policy-checked and the validated address is pinned for the request. Every request remains bounded (fixed path, fixed query body, no credentials, no redirects, time and size caps), and its response is only ever shown to the owner who pasted the link. Moxfield's API only serves approved clients, so those fetches may fail with a hint to paste the export text instead; ManaBox has no public URL API and is supported through its plain-text export (its CSV export remains a collection-import format, not a trade-match input). Any standard decklist text (quantities, optional set and collector number, *F* finishes, SB: prefixes, section headings) parses.

Legality, Stats, Tokens, and Playtest

Deck detail pages include:

  • format legality status and issue details
  • mana curve, average/median/total mana value, land/nonland counts
  • mana cost versus mana production comparison with source-card highlighting
  • token summaries derived from Oracle text
  • an in-browser playtest table with draw, shuffle, mulligan, move, exile, graveyard, command zone, and library interactions

Allocation and Missing Cards

Allocation compares deck demand against collection supply:

  • Allocated - a collection item is reserved for a deck card.
  • Available - matching owned copies exist and are not reserved elsewhere.
  • Allocated elsewhere - matching owned copies exist but are committed to other decks.
  • Missing - remaining demand after owned and available copies are counted.

Allocation actions include reserving one card, deallocating, proxy marking, choosing candidate collection items, and bulk allocation preview/commit. Missing-card views and exports can target exact printings or matching printings and can include or exclude basic lands.

EDHREC

Commander decks can open EDHREC-powered views for:

  • recommendations
  • cuts
  • commander pages
  • related commanders
  • themes and page stats
  • optional land exclusion

EDHREC cards can be previewed in ManaVault, returned to the same EDHREC scroll position, and added directly to mainboard, maybeboard, or sideboard.

Mobile and Native Shells

The web UI is responsive and installable as a PWA. Optional Capacitor shells add:

  • first-launch server URL configuration
  • native back/app control behavior
  • Android text/CSV Share, Open with, and file intents
  • native import handoff into the collection import dialog
  • Android release update checks
  • iOS project sync for Xcode builds

Android release signing, App Links, and custom-domain builds are documented in android.md.

Backups and Admin

ManaVault supports:

  • local backup zip creation with SQLite VACUUM INTO, excluding replaceable Scryfall catalog rows
  • local restore with pre-restore safety backup
  • pre-migration backup before release migrations
  • cloud backup settings for Google Drive and S3-compatible storage
  • scheduled UTC CRON backups
  • staged cloud restores applied on restart
  • built-in owner password authentication with failed-login rate limiting and permanent client bans

Self-hosting and backup operations are documented in self-hosting.md.