From adac2a4a991a03001fec78edf288e9a5b0d4faa5 Mon Sep 17 00:00:00 2001
From: Foohoo <foohoo@gmail.com>
Date: Sun, 17 Aug 2025 13:36:00 +0100
Subject: [PATCH] update readme

---
 README.md | 44 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 71e5891..da64b9c 100644
--- a/README.md
+++ b/README.md
@@ -3,10 +3,15 @@
 A Next.js web app to browse every English Magikarp Pokémon card with images, set symbols, search, set filter, and a personal checklist stored in your browser.
 
 ## Features
-- **Checklist**: Mark cards as collected (stored in `localStorage`).
+- **Checklist (variants-aware)**: Track base, holofoil, and reverse holofoil per card. Local persistence with migration from v1 to v2.
 - **Card images**: Uses official images from `images.pokemontcg.io`.
 - **Set symbols**: Displays set symbol and series/name.
 - **Search & filter**: Search by name/number/rarity/set and filter by set.
+- **Totals include variants**: The header and tab badges use variant totals (base + available variants) for collected/uncollected counts.
+- **Sort by release date**: Cards are ordered by set release date (oldest first).
+- **Caching with TTL**: Server route caches card data to `data/cards.json` with a 24h TTL and a manual refresh button.
+- **Cached/Live indicator**: Header shows whether data came from cache or a live fetch, with last updated timestamp.
+- **Non-blocking error toast**: Refresh errors show a short-lived toast without disrupting the current view.
 - **Responsive UI**: Tailwind CSS, mobile-friendly grid.
 
 ## Tech Stack
@@ -63,7 +68,8 @@ magikarp-collection/
 ├─ src/
 │  ├─ app/
 │  │  ├─ api/
-│  │  │  └─ magikarp/route.ts      # API route that fetches cards from Pokémon TCG API
+│  │  │  ├─ magikarp/route.ts      # API route with 24h TTL cache (data/cards.json)
+│  │  │  └─ checklist/route.ts     # Server-backed checklist persistence (optional)
 │  │  ├─ layout.tsx                # Root layout and global wrapper
 │  │  ├─ page.tsx                  # Main page: search, set filter, grid, checklist
 │  │  └─ globals.css               # Tailwind entry + global styles
@@ -75,12 +81,17 @@ magikarp-collection/
 │  │  └─ SetFilter.tsx             # Dropdown to filter by set
 │  ├─ lib/
 │  │  ├─ api.ts                    # Axios client for Pokémon TCG API
-│  │  └─ checklist.ts              # localStorage-backed checklist utils
+│  │  ├─ checklist.ts              # Checklist utils (local + server-backed)
+│  │  └─ currency.ts               # Price formatting + exchange rate hook
 │  └─ types/
 │     └─ pokemon.ts                # TypeScript types for cards/sets
+├─ data/                            # Local cache for cards/checklist JSON (gitignored)
 ├─ next.config.ts                  # Remote image domains, turbopack settings
 ├─ tsconfig.json                   # TS config with path alias '@/*'
 ├─ postcss.config.cjs              # Tailwind v4 PostCSS plugin config
+├─ Dockerfile                      # Multi-stage Docker build (standalone output)
+├─ docker-compose.yml              # Compose with APP_PORT and data volume
+├─ .dockerignore                   # Reduce build context
 ├─ package.json
 └─ .env.local.example              # Example env file
 ```
@@ -91,10 +102,29 @@ magikarp-collection/
   - API key header: `X-Api-Key: <your key>` (automatically added when `NEXT_PUBLIC_POKEMON_TCG_API_KEY` is present)
 
 ## How It Works
-- The client loads data from the internal Next.js route `GET /api/magikarp` (`src/app/api/magikarp/route.ts`).
-- The route proxies to the Pokémon TCG API using `fetchMagikarpCards()` (`src/lib/api.ts`).
-- Cards are displayed in `CardGrid`/`CardItem` with images and set symbols (`SetBadge`).
-- Checklist state is persisted locally via `localStorage` (`src/lib/checklist.ts`).
+- The client loads data from `GET /api/magikarp` (`src/app/api/magikarp/route.ts`).
+- The route proxies to Pokémon TCG API using `fetchMagikarpCards()` (`src/lib/api.ts`), caches the full response in `data/cards.json`, and serves cached data when fresh (<24h) unless `?refresh=1` is provided.
+- Cards render in `CardGrid`/`CardItem`, ordered by set release date.
+- Checklist persists locally (v2 supports variant-level tracking). A server-backed route exists at `api/checklist` if you enable it.
+
+## Docker
+
+Build and run using Docker/Compose. The container listens on port 3000 internally; pick a host port via `APP_PORT`.
+
+### Build and run
+```bash
+# Default host port 3000
+docker compose up --build
+
+# Custom host port
+APP_PORT=8080 docker compose up --build
+```
+
+Open: http://localhost:3000 (or your chosen `APP_PORT`).
+
+### Volumes and data
+- The `./data` directory is mounted to `/app/data` in the container so cached JSON persists between restarts.
+- `data/cards.json` and `data/checklist.json` are gitignored by default.
 
 ## Deployment
 - **Vercel**: Zero-config for Next.js. Add `NEXT_PUBLIC_POKEMON_TCG_API_KEY` in project Environment Variables.