MTG App 🧙‍♂️

A full-stack Magic: The Gathering card search application powered by AI-assisted natural language queries, the Scryfall API, and a React frontend.

Type something like "4 mana blue flying creature" or "Teferi, Hero of Dominaria" — the app translates your query into a Scryfall search string using GPT-4 and displays the matching cards.

🌐 Live Demo: damora-code.github.io/MTG-APP

---

✨ Features

• 🔍 Natural Language Search — Describe cards in plain English; GPT-4 converts your query into a precise Scryfall filter
• 🃏 Card Grid — Browse search results as animated card thumbnails
• 🖼️ Card Profile Modal — Click any card to view its full details: mana cost, oracle text, flavor text, rarity, set, and artist
• 🔄 Double-Faced Cards — Flip DFC cards (e.g. transform cards, modal double-faced cards) with a single click
• 🔎 Card Preview on Hover — Hover over a card in the grid to see a large preview follow your cursor
• 🎨 Mana Symbol Rendering — Mana costs are rendered as visual mana symbols

---

🛠️ Tech Stack

Frontend

Technology	Purpose
React 19	UI framework
Axios	HTTP client
GitHub Pages	Static hosting

Backend

Technology	Purpose
Node.js + Express 5	REST API server
OpenAI GPT-4	Natural language → Scryfall query translation
Scryfall API	Card data source
Heroku	Backend hosting

---

🗂️ Project Structure

MTG-APP/
├── backend/
│   ├── api/
│   │   └── scryfall.js        # Scryfall API client
│   ├── routes/
│   │   ├── ai.js              # POST /api/ai  — GPT-4 query translation
│   │   └── cards.js           # GET  /api/cards — card search
│   └── index.js               # Express server entry point
│
└── frontend/mtg-app/
    └── src/
        ├── api/
        │   ├── ai.js          # Frontend AI API calls
        │   └── cards.js       # Frontend cards API calls
        ├── components/
        │   ├── card/          # Card thumbnail component
        │   ├── cardlist/      # Grid of card results
        │   ├── cardpreview/   # Hover preview tooltip
        │   ├── cardprofile/   # Full card detail modal
        │   └── searchbar/     # Search input + submit
        ├── pages/
        │   └── Home.jsx       # Main page
        └── utils/
            ├── cardData.js    # Card data helpers
            ├── manaConverter.js  # Mana symbol renderer
            └── stringUtils.js # String helpers

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 18
• An OpenAI API key (GPT-4 access required)

1. Clone the repository

git clone https://github.com/damora-code/MTG-APP.git
cd MTG-APP

2. Set up the backend

cd backend
npm install

Create a .env file in the backend/ directory:

OPENAI_API_KEY=your_openai_api_key_here
LOCAL_ORIGIN=http://localhost:3000
PROD_ORIGIN=https://damora-code.github.io
PORT=5000

Start the backend server:

npm start
# Server running on http://localhost:5000

3. Set up the frontend

cd frontend/mtg-app
npm install
npm start
# App running on http://localhost:3000

---

🔌 API Endpoints

GET /api/cards?q=<query>

Searches Scryfall for cards matching the given query string (Scryfall syntax).

Example:

GET /api/cards?q=type:creature+cmc=4+o:flying

POST /api/ai

Translates a natural language prompt into a Scryfall-compatible query using GPT-4.

Request body:

{ "prompt": "4 mana blue flying creature" }

Response:

{ "query": "type:creature cmc=4 c:u o:flying" }

---

🃏 How It Works

User types query
       │
       ▼
  POST /api/ai  ──► GPT-4 interprets prompt
       │              and returns Scryfall query
       ▼
  GET /api/cards?q=<scryfall_query>
       │
       ▼
  Scryfall API returns matching cards
       │
       ▼
  React renders card grid
       │
       ▼
  Click card → Full card profile modal

---

🚢 Deployment

• Frontend is deployed to GitHub Pages via npm run deploy (uses gh-pages).
• Backend is deployed to Heroku. The root package.json includes a heroku-postbuild script that installs backend dependencies automatically.

---

📄 License

This project is open source. Card data is provided by Scryfall and is subject to their terms of service. Magic: The Gathering is property of Wizards of the Coast.