About CardLedger: Engineering a Modern TCG Platform

CardLedger is a technical showcase of modern full-stack architecture. It solves the challenge of managing large, relationship-heavy datasets (20,000+ cards) with the speed and interactivity of a native application. It serves as both a functional TCG collection manager and a case study in building a high-performance, type-safe, and scalable web application from the ground up.

The Backend & Data Foundation

The foundation of CardLedger is a custom-built Extract, Transform, Load (ETL) pipeline designed to turn raw API data into a high-performance relational asset.

The Ingestion Engine: A Node.js pipeline extracts raw API data and normalizes it into a relational schema, breaking flat responses into distinct entities (Sets, Artists, Rarities). Sequential processing with retry logic and circuit breakers ensures resilience against API rate limits and transient failures, while Prisma's idempotent upserts allow the script to run on a schedule via GitHub Actions without manual intervention.
Prisma & Advanced Filtering: The normalized data is managed by Prisma ORM, which serves as the application's query engine. By leveraging Prisma's powerful relation filtering, the backend can execute complex, multi-parameter queries that would be impossible with the source API alone.
Automation: Fully automated maintenance via GitHub Actions keeps the database synchronized with new card releases and volatile market prices without manual intervention.

The Frontend Architecture: A Hybrid Approach

Delivering nearly 20,000 cards without sacrificing performance required a hybrid rendering strategy:

Local-First Search: The application uses a client-side indexing strategy with a custom versioning protocol to minimize bandwidth while enabling instant, fuzzy-search across the entire 20,000+ card collection. Data is cached locally with IndexedDB and queried via Zustand and Fuse.js, eliminating network latency during browsing.
Optimistic UI Patterns: Collection interactions—adding or removing cards, adjusting quantities—update instantly in the UI while tRPC handles database synchronization in the background. This creates the tactile responsiveness of native desktop software.
Static Site Generation (SSG): For pages with a defined dataset, like an individual set's card list, I leveraged Next.js's SSG. These pages are pre-built on the server at build time, resulting in instant load times and optimal SEO. The user receives a static HTML file with all the card data and images ready to go.
On-Demand Invalidation: To bridge the gap between Static Generation and Real-Time Data, the backend triggers targeted cache purges via a secure API route whenever the ETL pipeline updates prices. This ensures users always see fresh price data without sacrificing the performance benefits of SSG.

Security & Authentication

Transitioning from a read-only viewer to a user-centric application required a robust security layer. I implemented a full authentication system using Better Auth:

Robust Authentication: Security is handled via Better Auth with a multi-strategy approach (Google, Discord, Email). The implementation focuses on Server-Side Authentication to eliminate layout shifts and ensure a premium, flicker-free user experience.

Key Features & Technical Highlights

End-to-End Type Safety: TypeScript is used throughout, enforced by Prisma on the backend, Zod for validation, and shared types for the frontend, eliminating an entire class of potential bugs.
Image Optimization: Card images are processed with Sharp into highly optimized AVIF formats and stored in Cloudflare R2. A custom image loader dynamically serves the optimal resolution based on the user's viewport, significantly reducing load times.
Real-time Search: The header search bar uses tRPC to provide a server-side search experience with tiered priority for card IDs, names, and suggestions.

About the Creator

My name is Viet Le, and I'm a full-stack developer with a passion for building high-quality, performant web applications. CardLedger is my capstone portfolio project, built from the ground up to demonstrate mastery of modern application architecture, from database design to frontend optimization.

vietle.me
@vietle683

About CardLedger: Engineering a Modern TCG Platform

The Backend & Data Foundation

The foundation of CardLedger is a custom-built Extract, Transform, Load (ETL) pipeline designed to turn raw API data into a high-performance relational asset.

The Ingestion Engine: A Node.js pipeline extracts raw API data and normalizes it into a relational schema, breaking flat responses into distinct entities (Sets, Artists, Rarities). Sequential processing with retry logic and circuit breakers ensures resilience against API rate limits and transient failures, while Prisma's idempotent upserts allow the script to run on a schedule via GitHub Actions without manual intervention.

Prisma & Advanced Filtering: The normalized data is managed by Prisma ORM, which serves as the application's query engine. By leveraging Prisma's powerful relation filtering, the backend can execute complex, multi-parameter queries that would be impossible with the source API alone.

Automation: Fully automated maintenance via GitHub Actions keeps the database synchronized with new card releases and volatile market prices without manual intervention.

The Frontend Architecture: A Hybrid Approach

Delivering nearly 20,000 cards without sacrificing performance required a hybrid rendering strategy:

Local-First Search: The application uses a client-side indexing strategy with a custom versioning protocol to minimize bandwidth while enabling instant, fuzzy-search across the entire 20,000+ card collection. Data is cached locally with IndexedDB and queried via Zustand and Fuse.js, eliminating network latency during browsing.

Optimistic UI Patterns: Collection interactions—adding or removing cards, adjusting quantities—update instantly in the UI while tRPC handles database synchronization in the background. This creates the tactile responsiveness of native desktop software.

Static Site Generation (SSG): For pages with a defined dataset, like an individual set's card list, I leveraged Next.js's SSG. These pages are pre-built on the server at build time, resulting in instant load times and optimal SEO. The user receives a static HTML file with all the card data and images ready to go.

On-Demand Invalidation: To bridge the gap between Static Generation and Real-Time Data, the backend triggers targeted cache purges via a secure API route whenever the ETL pipeline updates prices. This ensures users always see fresh price data without sacrificing the performance benefits of SSG.

Security & Authentication

Transitioning from a read-only viewer to a user-centric application required a robust security layer. I implemented a full authentication system using Better Auth:

Robust Authentication: Security is handled via Better Auth with a multi-strategy approach (Google, Discord, Email). The implementation focuses on Server-Side Authentication to eliminate layout shifts and ensure a premium, flicker-free user experience.

Key Features & Technical Highlights

End-to-End Type Safety: TypeScript is used throughout, enforced by Prisma on the backend, Zod for validation, and shared types for the frontend, eliminating an entire class of potential bugs.

Image Optimization: Card images are processed with Sharp into highly optimized AVIF formats and stored in Cloudflare R2. A custom image loader dynamically serves the optimal resolution based on the user's viewport, significantly reducing load times.

Real-time Search: The header search bar uses tRPC to provide a server-side search experience with tiered priority for card IDs, names, and suggestions.

About the Creator