Cards Square - Plaza Cartas

AI-powered P2P marketplace for trading collection cards

Comment 1

Inspiration

I have been a long-time Magic: The Gathering player. In Cochabamba, Bolivia, I play with cousins and friends in a local community that meets almost every weekend, and we also take part in games and events at local stores.

Through that experience, I noticed a clear problem: there are many cards available in our community, but no practical, dedicated place to discover them. Most buying and selling happens casually at game tables, through word of mouth, in social-media groups, or by visiting a store. As a result, the local market stays fragmented and largely invisible—even when valuable collections and willing buyers are only a few kilometers apart.

In larger markets, players can rely on platforms such as TCGplayer and Star City Games to search for cards and connect with sellers. However, those platforms are built around established companies, logistics, and centralized payment or escrow systems that are difficult to replicate in smaller and emerging markets.

Plaza Cartas was inspired by the need for a solution designed around local communities in South America and similar regions. The goal is to give collectors, players, and stores a simple way to publish their cards, present a public catalog, and reach people beyond their immediate circle.

Because I cannot operate a centralized escrow service, Plaza Cartas takes a decentralized peer-to-peer approach. Users connect directly to arrange purchases, while a review and reputation system helps make transactions safer over time—similar to trust mechanisms people already understand from marketplaces such as eBay or Mercado Libre.

My vision is to make the hidden card markets that already exist in local communities more visible, organized, and accessible, while leaving room for trusted stores to participate with their own fulfillment and buyer-protection models in the future.

What it does

Plaza Cartas is a peer-to-peer marketplace for collectible cards. It brings together people who want to buy, sell, and collect Pokémon, Magic: The Gathering, Yu-Gi-Oh!, Digimon, and One Piece cards in one local-first platform.

Buyers can search a structured card catalog, filter offers by price, condition, language, finish, availability, and market, and compare listings from multiple sellers. They can save cards to a watchlist or add compatible offers from the same seller and currency to a cart.

Instead of immediately processing a payment, Plaza Cartas turns the cart into a purchase inquiry. This opens a private in-app conversation where buyer and seller can agree directly on payment, delivery, or shipping.

For sellers, Plaza Cartas provides tools to create a profile, select a local market, publish cards individually or in bulk, manage inventory, and receive purchase inquiries. When a seller accepts an inquiry, the relevant units are reserved, helping prevent the same stock from being sold twice. The operation can then be completed or cancelled, with cancelled reservations returning to available inventory.

The platform is intentionally decentralized: it does not hold card-sale payments, process shipping, or act as an escrow service. Instead, it supports safer peer-to-peer coordination through public profiles, transaction-based reviews, reporting tools, moderation, and a clear inquiry history.

Plaza Cartas also generates local market signals from pseudonymous activity such as attributed searches, result impressions, listing views, watchlists tied to a specific offer, cart additions, purchase inquiries, and completed inquiries. An admin-only intelligence panel uses those signals to explain active supply, asking-price ranges, relative buyer interest, liquidity, and the amount of evidence behind each metric. These are operational signals—not guaranteed prices, financial advice, or sale predictions.

The MVP currently supports local markets in Bolivia, Argentina, Chile, and Mexico. Each listing is tied to the seller's country, currency, and location at publication time, so users can discover offers that make sense for their market without mixing currencies or silently moving listings between regions.

In short, Plaza Cartas organizes discovery, listings, inventory reservations, communication, reputation, and local market insight while keeping the final commercial agreement directly between buyer and seller.

How we built it

Plaza Cartas is a full-stack web application built with Next.js 16, React 19, PostgreSQL, and Prisma 7. I chose a modular monolith architecture: the public marketplace, seller dashboards, API routes, authentication, real-time messaging, and core business rules live in one codebase. This makes the product faster to iterate on while keeping each responsibility clearly separated.

The frontend uses React, Tailwind CSS, and TanStack React Query to create a responsive experience for card discovery, filtering, listings, carts, dashboards, and private conversations. Most of the interface is built from custom Plaza Cartas components designed around browsing, inventory management, and peer-to-peer coordination.

At the core, PostgreSQL stores accounts, card references, listings, inventory, purchase inquiries, conversations, reviews, reports, and market metrics. Prisma manages the data model, database queries, and versioned migrations.

The marketplace's most important business rule is inventory consistency. When a seller accepts a purchase inquiry, the server reserves the relevant units inside a controlled database operation. If the inquiry is cancelled, those units return to availability. Prices, quantities, and listing state are checked again on the server instead of trusting stale browser data.

Authentication and sessions are handled with Better Auth. Server-side routes verify identity and permissions before users can publish listings, send purchase inquiries, access private conversations, or perform administrative actions. Zod validates incoming API data, together with rate limiting, role-based access controls, soft-delete rules, secure error handling, security headers, and Cloudflare Turnstile for exposed anti-abuse flows.

For catalog data, Plaza Cartas integrates the Pokémon TCG API and Scryfall for Magic: The Gathering. These services provide structured card metadata and reference images, allowing sellers to start from an identifiable printing and then add local transaction details such as price, condition, language, finish, quantity, and photos of the actual item.

To reduce repeated dependence on free third-party image APIs, Plaza Cartas can rehost reference images in Cloudflare R2. User-uploaded images use controlled storage flows with Cloudinary or R2, while sharp supports server-side validation and optimization where needed.

Private buyer-seller coordination is powered by Socket.IO, running alongside Next.js through a custom HTTP server. Each conversation is tied to a purchase inquiry and restricted to the buyer and seller involved. Web Push notifications and a Service Worker can notify users about new messages even when they are not actively viewing the conversation.

Explainable market intelligence

A separate Python 3.12 market-intelligence worker reads attributed, pseudonymous marketplace activity from PostgreSQL. It groups information by UTC day and exact variant:

(cardReferenceId, countryCode, condition, language, isFoil)

The worker calculates active supply, minimum price, the 25th percentile, median, 75th percentile, unique demand, a weighted demand score, liquidity, and confidence. The demand formula is deliberately transparent:

demand = searches
       + views
       + 4 × watchlists
       + 6 × carts
       + 10 × inquiries
       + 15 × completed inquiries

Liquidity compares observed demand with active supply:

liquidity = min(100, demand / max(1, activeSupply) × 10)

Price percentiles use linear interpolation. Confidence is assigned with deterministic evidence thresholds based on active supply, unique participants, and completed inquiries.

This is an explainable heuristic scoring and aggregation engine, not a trained machine-learning model. It intentionally does not use NumPy, pandas, scikit-learn, or an opaque valuation model. Python uses psycopg 3 to communicate with PostgreSQL and python-dotenv for environment discovery; the calculations use standard-library tools such as Decimal, sorting, sets, dataclasses, and UTC date windows.

The worker writes idempotent daily aggregates back to PostgreSQL. It runs periodically, processes the previous and current UTC days at startup, and listens to PostgreSQL LISTEN/NOTIFY so an administrator can request an immediate recalculation without executing Python inside Next.js. The marketplace continues operating if analytics is restarted or temporarily unavailable.

The admin panel at /dashboard/admin/market-intelligence shows market summaries, country and date filters, price distributions, demand, liquidity, confidence, worker freshness, and an expandable mathematical proof for every row.

The public catalog and landing page use the latest snapshot for the selected country in a Market trends order. To prevent a self-reinforcing position-impression-position loop, this public rank excludes views and uses only active intent:

marketRank = searches + 4 × watchlists + 6 × carts
           + 10 × inquiries + 15 × completedSales

Confidence, total demand, and liquidity resolve ties, while cards without a snapshot remain discoverable afterward in recent-listing order.

Related cards and future recommendations

The current Related cards section is separate from the market-intelligence engine. It uses a deterministic content-based ranking among cards from the same game with active offers in the selected market:

relatedScore = 12 × sameSet
             + 3 × min(3, sharedTypeTokens)
             + 2 × min(3, sharedColorTokens)
             + 1 × sameRarity

Ties are resolved by offer count and then lowest price. This ranking does not currently use demand, liquidity, confidence, or a machine-learning model.

The Market trends discovery order does not change this recommendation architecture. The analytics contract reserves a RECOMMENDATION_CLICKED event, but the current Related cards interface does not yet emit it. Plaza Cartas also does not currently claim an “Others also bought” collaborative-filtering system. The market data is a foundation for a future hybrid recommender, not evidence that such a recommender is already in production.

Deployment

For deployment, I use Docker and Docker Compose to run the Next.js/Socket.IO application and the Python worker as separate, repeatable services. The worker runs as a non-root user and includes a database-backed health check. This keeps real-time marketplace operations responsive while allowing market analysis to run independently in the background.

Challenges we ran into

Building Plaza Cartas was not only about creating a card catalog and allowing users to publish listings. The difficult part was making the marketplace behave consistently when users interact with limited inventory, different local currencies, real-time conversations, external catalog services, and asynchronous analytics.

Keeping peer-to-peer inventory reliable

Many collectible-card listings have only one available unit. If two buyers send an inquiry for the same card at nearly the same time, the browser alone cannot be trusted to determine whether that card is still available.

I addressed this by modeling each purchase inquiry as a server-controlled lifecycle: pending, accepted, completed, or cancelled. When a seller accepts an inquiry, the corresponding inventory is reserved in the database. If it is cancelled, that inventory becomes available again. Prices, quantities, and listing availability are checked again on the server before the action is confirmed.

Why it mattered: this reduces overselling and makes stock reflect what is actually available.

Supporting local markets without mixing currencies

Plaza Cartas is designed for local markets rather than one global checkout flow. Each country has different currencies, price formats, locations, and buyer expectations.

The challenge was ensuring that listings remain tied to the market in which they were created. Listings inherit the seller's country, currency, and location at creation time, and carts are limited to compatible offers from the same seller and currency. This prevents older listings from silently changing market or currency when a seller later edits a profile.

Designing a useful but safe P2P chat

Because Plaza Cartas does not process card payments or shipping itself, buyer-seller communication is central to the product. At the same time, private chat introduces risks involving unauthorized access, spam, reports, and indefinite message storage.

I tied every conversation to a specific purchase inquiry and restricted access to its buyer and seller. The system validates messages, limits image categories, supports reporting and moderation workflows, and provides scheduled cleanup. Push notifications are an optional enhancement rather than a dependency: the marketplace still works when they are disabled.

Building a sustainable card catalog

A card is more than a name: it may have a specific set, collector number, rarity, finish, and artwork. Entering that information manually for every listing would make publishing slow and error-prone.

Plaza Cartas integrates the Pokémon TCG API and Scryfall to retrieve structured metadata and reference images. However, relying on external images on every search would create slow pages, fragile links, and unnecessary usage of third-party APIs.

The platform can therefore rehost reference images in Cloudflare R2 while keeping a controlled fallback. Catalog imagery identifies a printing; seller photographs represent the actual item being offered.

Adding market intelligence without slowing down the marketplace

Market signals are useful, but calculating them during a user's search would hurt performance. I separated this work into an independent Python process that aggregates events in the background and writes daily snapshots back to PostgreSQL.

The difficult part was not only the formula. Event attribution had to retain the exact card, country, condition, language, and finish so activity would reach the correct variant. The UTC day window also had to match PostgreSQL's timestamp representation; otherwise, session-time-zone conversion could silently exclude late-day events. Manual recalculation required a safe control channel that would not couple Python execution to an admin HTTP request.

The final design uses attributed pseudonymous events, naive UTC database windows, idempotent upserts, and PostgreSQL LISTEN/NOTIFY. This keeps the calculation reproducible and allows every result to be inspected in the admin panel.

Maintaining security without creating friction

A marketplace handles accounts, inventory, conversations, and actions that affect other users. Security could not be added as an afterthought, but it also could not make ordinary actions frustrating.

The platform uses Better Auth for sessions, Zod for strict server-side validation, role-based permissions, rate limiting for sensitive actions, security headers, soft-delete protections, and Cloudflare Turnstile to reduce automated abuse. These protections are built into registration, listing creation, inquiries, messaging, analytics, and moderation.

Making deployment reproducible

Plaza Cartas combines Next.js, Socket.IO, PostgreSQL, Prisma, Python, and external catalog APIs. Making it work locally was only the first step; the same system also needed to build and run predictably in production.

I standardized the environment with Node.js, pnpm, Docker, and Docker Compose. The web application and market-intelligence worker run as separate services with health checks and a controlled startup sequence. This reduced differences between local development and deployment while keeping the real-time marketplace responsive.

Accomplishments that we're proud of

One of the accomplishments I am most proud of is designing a marketplace model that can work for small sellers without charging a commission on every card sale.

Traditional marketplaces often rely on centralized payments, escrow, commissions, and shipping workflows. That model can work for large companies, but it is expensive and difficult to operate for an early-stage platform focused on local trading communities. I designed Plaza Cartas around a decentralized peer-to-peer flow instead: the platform organizes discovery, listings, stock reservations, communication, reputation, and market insight, while buyers and sellers agree on payment and delivery directly.

I am also proud of the product's visual design. The landing page combines custom generated artwork with Three.js and React Three Fiber effects to create an immersive identity for a collectible-card marketplace. That attention continues through browsing, offer comparison, inventory publishing, the cart, and transaction coordination.

Another major accomplishment was implementing a subscription payment path in a country where mainstream processors are difficult to access. The USDT-based flow required a secured regional proxy because the provider imposed geographic restrictions on server-to-server requests. This gave Plaza Cartas a viable subscription path without changing the decentralized card-sale model.

The AI-assisted batch card detector addresses another practical problem. Collectors often photograph an entire binder page containing 12, 15, or 16 cards. Instead of searching and publishing every card manually, the vision-assisted flow identifies multiple candidates and lets the seller continue from verified catalog matches. This reduces one of the most repetitive parts of listing a collection.

Finally, the market-intelligence panel turns raw marketplace activity into a result that can be challenged and verified. Rather than displaying an unexplained “AI score,” it exposes every input, weight, percentile, formula, confidence label, and update time. That transparency is especially important in a young, low-volume market.

Together, these accomplishments represent the product I wanted to create: not only a visually polished marketplace, but a platform adapted to the real limitations and habits of collectors in emerging local markets.

What we learned

Building Plaza Cartas taught me how different a public peer-to-peer marketplace is from the business software I had built before.

My previous projects were mainly enterprise tools, where workflows are controlled by a company and its staff. Plaza Cartas required me to think about a more open environment: independent sellers, limited inventory, direct buyer-seller coordination, reputation, moderation, local currencies, and the possibility of abuse. I learned how to design a P2P architecture so stock, transaction states, permissions, and communication remain consistent even when many users interact independently.

I also learned how to design integrations around real infrastructure constraints in Bolivia. A service that works from a laptop is not necessarily available from the production server's region. Payment and catalog integrations require secure proxies, signatures, controlled error handling, caching, and fallback behavior.

The card detector showed me that AI vision can solve a practical and measurable problem: reducing the effort required to turn a binder photograph into multiple potential listings. The important lesson was not simply calling a model, but combining uncertain detection with catalog verification and a human review step.

Market intelligence taught me a different lesson: not every useful intelligent system needs machine learning. With limited early-stage data, transparent heuristics, robust aggregation, and honest confidence labels are more valuable than an opaque model. The current Related cards feature uses deterministic catalog similarity, while daily demand and liquidity are calculated separately. A hybrid recommendation system should be introduced only after click and completed-inquiry data are sufficiently reliable.

Working with GPT-5.6 through Codex also changed my development process. I used Codex inside the real repository to inspect architecture, trace failures across frontend, API, PostgreSQL, Prisma, Python, and Docker, implement coordinated changes, and refine the product through repeated feedback. It was most valuable as a persistent engineering collaborator rather than a code-snippet generator.

The main lesson is that building with AI is not just about generating code faster. It is about exploring solutions, challenging product claims, diagnosing full-system behavior, overcoming local infrastructure limitations, and turning a complex community problem into a usable product.

What's next for Plaza Cartas

Plaza Cartas launched recently, so the next challenge is no longer only building features—it is building adoption.

As a solo developer, I have been responsible for product design, engineering, infrastructure, branding, and the business model. The next stage requires shifting more attention toward community growth, marketing, seller onboarding, and helping collectors understand why the platform is useful.

The platform is active in Bolivia, with MVP market support for Chile, Argentina, and Mexico. In the short term, I will focus on reliability, UI and UX improvements, early-user feedback, and making card publishing, discovery, and P2P coordination as dependable as possible.

For recommendations, the next step is to connect recommendation impressions and clicks, then build a hybrid ranker that can combine catalog similarity with confidence-aware demand and liquidity. An “Others also bought” feature should only be added after there are enough completed inquiries to calculate meaningful co-purchase relationships without exposing individual behavior or overfitting sparse data.

In the longer term, I want Plaza Cartas to expand beyond its first markets and become a global public card library and marketplace. The vision is that a collector in Japan, the United States, Argentina, Bolivia, or any other country can publish a collection, share a public catalog, discover hard-to-find cards, and connect directly with another collector.

Another important future direction is support for graded cards. These cards can carry significantly higher value and will require stronger listing verification, better documentation, clearer shipping flows, and more specialized protection mechanisms. That step will require greater revenue and a stronger operational team.

My goal is to grow Plaza Cartas from a solo-built product into a sustainable company with marketing, operations, customer support, and logistics capabilities while continuing to lead the software architecture and product direction.

Built With

Share this project:

Updates