Skip to main content
pokemon-tcgnextjspostgresclaude-codeai-collaboration

Building Gumdex, a Living Dex Tracker for Pokémon Cards

Why I built a species-first Pokémon TCG collection tracker that puts English, Japanese and Chinese prints on one timeline, and what building it with Claude Code taught me.

Stuart•

A Living Dex is a collecting goal: one card for every Pokémon species. It sounds simple until you try to track it. Every tool I found was organized by set, which is how the cards are sold, and a Living Dex doesn't care about sets. Any Pikachu fills the Pikachu slot, whether it came from Base Set in 1999, a Japanese promo, or a Chinese 25th anniversary print.

So I built Gumdex, a Living Dex tracker that starts from the Pokémon instead of the set.

Species first

The core screen is the Dex: a grid of every Pokémon in National Pokédex order, each tile either filled with a card you own or waiting for one. Open a Pokémon and you get one timeline of every card ever printed for it, oldest first, across all three languages. You can filter by language, but a Japanese Pokémon card or a Chinese print counts exactly as much as an English one.

That decision shaped most of the data model. Cards map to species, and progress is the number of species with at least one owned card. Each Pokémon also gets a primary card, the one you'd put in the binder, and it comes first everywhere that Pokémon appears.

What grew around it

Once the Dex worked, the rest followed from how people actually collect.

Some collectors keep a Japanese-only Dex or a binder of Eeveelutions next to their main one, so lists are independent collections, each with its own scope, progress and wishlist. A list can be shared read-only with a link or an email invite, and the viewer never sees your notes, the condition of your cards or what you paid.

When you're sorting a pile of fresh packs, typing printed numbers beats browsing, so every set has a checklist mode. There's also a card art search over the illustrations themselves: search by place, by theme, or for a Pokémon hiding in the background of another one's card. I use it for themed binder pages, and for finding that card with the kitchen in it that I half remember. Pages for more than 400 card illustrators let you collect by the people who drew the cards.

Plenty of older and regional cards have no good image online, so collectors can upload a photo of their own copy. It goes live after review.

Gumdex also has a connector for Claude and ChatGPT. You photograph a stack of cards, the assistant reads each one, and you confirm the exact print before anything is added. I kept the assistant from adding cards by itself on purpose, because picking the right print out of a dozen near-identical ones is exactly where it would get things wrong.

Building it with Claude Code

I built Gumdex with Claude Code. The parts that went well had one thing in common: the decision was written down before the code was.

The repo has an architecture decision record for nearly every choice that wasn't obvious, like why lists are independent collections, why digital-only sets are hidden instead of deleted, and why the art search reads its own materialized views. Agents working in separate sessions stayed consistent with each other by reading those records. When an agent proposed something that contradicted one, the record won, or we wrote a new one to replace it.

A few things I'd carry into the next project:

  1. Write the boring constraints down. "Never name the data source in user-facing copy" or "a card's printed number is text, never cast it" are easy for me to remember and easy for an agent to forget. Putting them in the repo's instructions file fixed whole categories of bugs.
  2. Make derived state explicit. Progress counts, card stats and the art search index are all derived tables, each with one documented way to refresh it. Once every writer had to say what it changes, the "why is this count wrong" bugs went away.
  3. Design for a small database. Gumdex runs on a small Postgres instance, and precomputed counts did more for page speed than anything clever in the app layer. Row-level security on every table means none of that speed work can leak one collector's data to another.
  4. Keep the review. The agents wrote most of the code, but deciding what to build, reading every diff and turning down things that didn't fit stayed with me.

Try it

Gumdex is free at gumdex.app. If you're working on a Living Dex, or just want to see every print of your favorite Pokémon in one place, have a look. The project page has more on how it's built.