poke-tcg-analyzer

Pokémon TCG Log Analyzer

Parse Pokémon TCG Live battle logs, replay matches turn-by-turn with a reconstructed board, and aggregate meta matchup statistics across many saved games.

What it does

• Parse a raw battle log into a structured event stream (zero unknown lines on the sample log). Handles curly/straight apostrophes, usernames vs. card names that both contain 's, and actions that only appear as indented sub-effects (Rare Candy evolves, X-Boot attaches, Boss’s Orders switches, energy discards on retreat).
• Replay — step/scrub through the game with a board reconstruction (Active/Bench, attached energy, tools, damage counters, prizes) plus a synced, color-coded event timeline. Real card images are resolved per Pokemon (toggleable, hover to enlarge) via the TCGdex API, with a local cache so each card is fetched once. Physical-TCG printings are preferred (Pokemon Pocket cards filtered out) and restricted to the current Standard rotation (regulation H-I: sv05+ and Mega Evolution me* sets) so the copy shown matches the format actually played. Adjust STANDARD_SV_MIN in card_images.py when the format rotates.
• Auto-detect deck archetypes from the key ex / Mega ... ex Pokémon, with a confirm/edit step before saving.
• Meta analytics — per-archetype win rates (sortable columns, deck sprite icons) and a full archetype-vs-archetype matchup matrix with directional W-L-T per cell, site-wide and personal scopes, and a tie-handling selector (ignore / loss / ½ / ⅓ / win). Deck sprites come from PokeAPI (cached).
• Format cycles — every match is auto-assigned to the set-cycle it was uploaded in (set release dates pulled from pokemontcg.io, cached). A cycle selector on the Meta tab filters all stats to All-time or any individual cycle, so the meta “resets” as new sets release while history is preserved.
• Format Meta — the live Standard metagame (deck usage, W-L-T, win rates) scraped from LimitlessTCG’s public meta page, cached daily. Deck names also populate the archetype suggestion dropdown used when logging.
• Tournament logging — self-report in-person matches (no TCG Live log): create an event with your deck + placement, then add rounds (opponent deck, W/L/T, turn order). These feed your record and the meta stats, bucketed into the set-cycle of the event date.
• My Record — designate your username(s) once; get an overall Win-Loss-Draw across every deck you pilot, plus a per-archetype W-L-D (and a vs-opponent breakdown), so switching decks still tracks under “you”. Defaults to your most-played username until set.

Layout

poke-tcg-analyzer/
  backend/
    app/
      parser.py      # raw log -> structured events + match summary
      state.py       # events -> per-event board snapshots (replay)
      archetypes.py  # deck archetype detection (curated + heuristic)
      db.py          # SQLite persistence
      stats.py       # meta analytics (performance + matchup matrix)
      main.py        # FastAPI app + serves the frontend
    tests/           # fixtures + inspection/smoke scripts
    data/matches.db  # created on first run
  frontend/          # vanilla JS single-page UI (no build step)

Run it locally

Clone the repo, then from its folder:

git clone https://github.com/h0ku-lea/poke-tcg-analyzer.git
cd poke-tcg-analyzer\backend
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload

Then open http://127.0.0.1:8000/.

(First-time setup, if the venv is missing:)

cd poke-tcg-analyzer\backend
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Workflow

1. Parse & Save tab → paste a log (or choose a .txt) → Parse log.
2. Review the summary, confirm/rename the two deck archetypes → Save match (or Preview replay to watch it without saving).
3. Replay tab → scrub/step/play through the match.
4. Meta tab → win rates and the matchup matrix across everything saved.
5. Saved Matches tab → reopen or delete past matches.

Extending archetype detection

Add signatures to KNOWN_ARCHETYPES in backend/app/archetypes.py:

"My Deck Name": ["Key Pokemon ex", "Second Signature ex"],

Unrecognized decks fall back to naming after the most prominent ex / Mega ... ex Pokémon, so the tool stays useful for rogue decks.

Tests / dev checks

cd poke-tcg-analyzer\backend
.\.venv\Scripts\python.exe tests\inspect_parse.py   # parser coverage
.\.venv\Scripts\python.exe tests\inspect_state.py   # board reconstruction
.\.venv\Scripts\python.exe tests\api_smoke.py       # full API (server must be running)

Notes for going public later

• The DB layer (db.py) is plain SQL over SQLite and maps cleanly to Postgres.
• The parser/state/archetype modules are pure functions with no I/O, so they’re trivial to unit-test and reuse in a hosted backend or a batch importer.