CardMystic

🧙‍♂️ Check it out: https://cardmystic.com

Magic: The Gathering is a complex and intricate game, but finding cards shouldn't be. Our developers decided that traditional keyword search engines fall short. They require exact wording and an intimate knowledge of Magic terms.

CardMystic makes card discovery effortless with natural language search. Just type what you're thinking: “a blue creature that draws cards” or “a cheap red burn spell” and let CardMystic handle the rest. Whether you're a seasoned deckbuilder or brand new to the game, CardMystic helps you find the perfect card without the guesswork.

This project uses Vue & Nuxt as well as the Vuetify component library.

✨ Features

• AI / Semantic search for MTG cards: Find cards using natural language queries
  • Example Query: X Spell Board Wipes
• Similarity search: find cards similar to a given card
  • Example Query: Lightning Bolt
• Commander search: AI search specifically for legendary creatures
• Keyword search: traditional text-based card search
• Deck Recommender (ALS): Paste a decklist and/or select a commander to get AI-powered card recommendations
• Platform-specific search: search filtered to Arena, MTGO, Modern, or Paper cards
  • Example: Arena AI Search
• Card Lists: Create and manage custom card collections with commander designation
• User accounts with authentication (Supabase)
• Filter by colors, types, converted mana cost, power/toughness, etc.
• View card details including different printings, price, and legality
• Frontend & Backend caching
• Example queries to help you get started
• View Top Searches of the week
• Report issues or suggest features directly from the app
  • Report incorrect search results
• Link directly to TCGPlayer to purchase cards
• Extensive data validation

🛣️ Roadmap

• Image-based search
• Browser Extension

🤝 Contributing

We welcome pull requests and feedback!
Please read CONTRIBUTING.md for setup instructions and coding guidelines.

🖥️ Server

The CardMystic server code is not contained in this repository. Instead, the frontend connects to the public API through the proxy defined in server\api\proxy\[...path.ts]

API Documentation

🤖 Models

The models used for this project are our "Secret Sauce" and will be kept private. Extensive research and iterations have gone into creating the models that power CardMystic's search capabilities.

• ColBERT: Powers the AI / semantic search and commander search
• ALS (Alternating Least Squares): Powers the deck recommendation system, suggesting cards based on your decklist and/or commander

🛠️ Setup

Make sure to install dependencies:

# npm
npm install

# pnpm
pnpm install

# yarn
yarn install

# bun
bun install

Configure environment variables (and edit as needed):

cp .env_defaults .env

Development Server

Start the development server on http://localhost:3000:

# npm
npm run dev

# pnpm
pnpm dev

# yarn
yarn dev

# bun
bun run dev

Production

Build the application for production:

# npm
npm run build

# pnpm
pnpm build

# yarn
yarn build

# bun
bun run build

Locally preview production build:

# npm
npm run preview

# pnpm
pnpm preview

# yarn
yarn preview

# bun
bun run preview

Check out the Nuxt deployment documentation for more information.

Updating Card Data

Card data files (card-names.min.json, commanders.min.json, card-ids.min.json) are generated by the backend and served via the /bulkdata API endpoints. The frontend fetches these using TanStack Query composables in composables/useBulkData.ts with a 24-hour stale time, so data stays fresh without manual updates.

• card-names.min.json: Autocomplete suggestions in search
• commanders.min.json: Autocomplete suggestions for legal commanders
• card-ids.min.json: Used by components for card ID lookups

A static copy of card-ids.min.json is kept in public/ only for sitemap generation (server/routes/sitemap.xml.ts), which imports it at build time for SEO purposes.

When new Magic sets release or card data updates, the backend data files are updated automatically. The static public/card-ids.min.json should be refreshed periodically to keep the sitemap current.

Database

The database is hosted on Supabase and stores:

• User accounts: Authentication and profile data
• Card lists: User-created card collections with metadata
• Card list items: Individual cards in each list, including commander designation (is_commander)
• Search history: User search and card view history
• Card feedback: User feedback on search results for model improvement

Generate Supabase Database Types

To generate the Supabase database types (when the schema changes) run:

npm run gen:types

🙏 Acknowledgements

• Scryfall for card data
• Moxfield for deck data