card-grader/CLAUDE.md

# Card Grader

Self-hosted web app that estimates PSA trading card grades from photos, using
vision-capable LLMs (Claude and/or GPT) as the grading engine. Runs as a
single Docker container on the user's Unraid home server, exposed at
`hippofam.com/cards` through Nginx Proxy Manager.

No framework: the whole backend is Python stdlib
(`http.server.ThreadingHTTPServer`) plus `sqlite3`. Optional third-party
packages are `anthropic`, `openai`, and `Pillow` (image processing only —
never required for the server to boot).

## Architecture

- **`app.py`** — HTTP routing/handlers. Reads Basic Auth username forwarded
  by the reverse proxy for *attribution only* (who graded what), never for
  access control — auth itself is enforced by Nginx Proxy Manager in front
  of the container via htpasswd. Admin-only settings are gated by
  `ADMIN_USERNAME` (`CARD_GRADER_ADMIN_USER` env var). Request bodies are
  capped (`MAX_BODY_BYTES`); oversized/malformed bodies get a 413 and the
  connection is closed rather than trusting a client-supplied length.
- **`vision.py`** — Provider abstraction over Anthropic and OpenAI vision
  APIs (`_call_anthropic` / `_call_openai`, dispatched from a common
  entrypoint). `MODELS` holds per-model pricing/capabilities.
  `GRADING_SYSTEM` is the large system prompt encoding PSA's actual grading
  rubric (centering tolerances, corner/edge/surface criteria, qualifiers —
  MC/OC/PD/ST/MK, half-grades, Altered Authentic) — verified against
  psacard.com, beckett.com, and cgccards.com, not guessed. Self-reported
  "high" confidence is capped to "medium" when neither centering nor edge
  whitening was independently measurable from the image geometry.
- **`cardimage.py`** — Pillow-based image pipeline: card boundary detection,
  corner/edge/surface crop generation, centering/edge-whitening/aspect-ratio
  measurement from pixels (not just left to the model's eye). Includes
  holder/toploader-aware detection (`detect_card_box`): a combinatorial
  search over candidate edge positions constrained to standard card aspect
  ratios, so the app can locate the actual card inside a slab/toploader
  rather than just detecting the holder's outline. When a holder is
  detected, edge-whitening measurement is refused (the holder's own inner
  edge corrupts that specific measurement) but centering still runs
  (border-width geometry, unaffected by clear plastic), and aspect-ratio
  measurement deliberately uses the *unrefined* box to avoid circularity
  (refinement selects for standard-ratio rectangles, so measuring the
  refined box's ratio would trivially always look "normal").
- **`store.py`** — SQLite (WAL mode) persistence. `grades` and
  `grade_events` tables, JSON columns for structured data, schema
  migrations via idempotent `ALTER TABLE` in `store.init()`. List/detail
  API responses explicitly exclude `source_images_json` to keep payloads
  small. DB path overridable via `CARD_GRADER_DB_PATH`.
- **`static/`** — Vanilla JS/CSS/HTML frontend, PWA-enabled (manifest,
  service worker). "PSA slab" visual theme. `__BASE__` is templated at
  request time so the app works correctly when served from a sub-path
  (`/cards`) behind the proxy.

## Local development

```bash
python3 app.py
```

Needs `ANTHROPIC_API_KEY` and/or `OPENAI_API_KEY` in the environment to
actually grade; the server itself has no required third-party deps. A local
`grades.db` is gitignored and is scratch/test data only — it is **not** the
production database (that lives on the server, see below).

## Deployment

**Target:** Unraid server, container path `/mnt/user/appdata/card-grader`,
built from `Dockerfile` / `docker-compose.yml` in this repo. Non-root
container user (`99:100` / `nobody:users`), healthcheck, log rotation,
`init: true`. Reverse-proxied by Nginx Proxy Manager at `hippofam.com/cards`
with per-user HTTP Basic Auth.

**Current deploy mechanism (live as of 2026-08-25): Forgejo push-to-deploy.**
Self-hosted Forgejo (soft-fork of Gitea) runs as its own container on the
same Unraid box (`/mnt/user/appdata/forgejo`), proxied at
`https://git.hippofam.com` via Nginx Proxy Manager (wildcard Let's Encrypt
cert issued via Porkbun DNS-01 challenge — Cox blocks inbound port 80, so
the default HTTP-01 challenge doesn't work on this network; DNS challenge
sidesteps that entirely). Forgejo Actions is enabled instance-wide, with a
self-hosted runner (`/mnt/user/appdata/forgejo-runner`, container name
`forgejo-runner`) registered **globally** (not repo-scoped — see tradeoff
below).

This repo has a `forgejo` remote (`https://git.hippofam.com/ninja_hippo/card-grader.git`,
HTTPS not SSH — see note below) and pushing to `main` triggers
`.forgejo/workflows/deploy.yml`, which rsyncs the checkout into
`/mnt/user/appdata/card-grader` (excluding `.git`, `.env`, `data/` — those
stay server-side only) and runs `docker compose up -d --build`. Typical
deploy completes in well under a minute.

**Why HTTPS, not SSH, for git:** Forgejo's git-SSH listens on host port
`2222` (port 22 was already taken by Unraid's own sshd), but the router
only forwards 80/443 to this box — 2222 was never opened externally, and
setting that up requires the user's own router admin access, which Claude
doesn't have. Git auth instead uses a Forgejo access token stored in macOS
Keychain via `git config --global credential.helper osxkeychain` — pushing
just works, no per-push prompt.

**Runner internals, only useful if the pipeline breaks:** the runner's job
containers are the `catthehacker/ubuntu:act-latest` image (has git/Node
bundled for the `actions/checkout` JS action, but *not* rsync — installed
as an explicit workflow step each run) with the host Docker socket
automounted (`container.docker_host: automount` in the runner's
`config.yaml`) and `/mnt/user/appdata` bind-mounted into every job
container at the identical path (`container.options`), which also required
adding `/mnt/user/appdata` to `container.valid_volumes` (empty by default —
Forgejo silently drops any bind mount not explicitly allow-listed there,
with only a debug-log line, no visible job failure). The identical-path
mount trick matters because `docker compose`'s relative volume paths are
resolved by the *host* daemon (Docker-outside-of-Docker via the automounted
socket), so a mismatched path silently bind-mounts the wrong location.

**Known tradeoff, accepted, not yet resolved:** the runner is registered
globally rather than scoped per-repo, and it has full Docker socket access
— a workflow file pushed to *any* repo on this Forgejo instance can control
any container on the box, not just its own. The access boundary is "who
can push a workflow file to a repo on this instance," not anything
narrower. This runner also now serves three other projects on the same
box — `lunch-notifier`, `n64-tracker`, `arr-summary` — each with the
identical deploy pattern (see their own `CLAUDE.md`s). Revisit with a
`docker-socket-proxy` (scoped per compose project) if this needs tightening
later; not done yet because the basic pipeline mattered more first.

**Superseded, fully torn down: git-shell restricted deploy.** A
`carddeploy` service account (login shell `git-shell`, one bare repo, a
`post-receive` hook triggering a single root-owned deploy script via one
narrowly-scoped `sudo` rule) was built, tested, and verified working
end-to-end — then explicitly torn down in favor of Forgejo. Nothing from it
remains: account, sudoers rule, bare repo, `/boot/config/go` persistence
block, and the `sshd_config` `AllowUsers` addition were all removed and
verified reverted. If this pattern (restricted git-shell account +
sudo-scoped deploy script) is useful as a reference for scoping *other*
access requests later, it's a solid model — abandoned for tooling reasons
(moving to a real git host), not because it didn't work.

All server access for this migration was narrowly scoped and time-boxed: a
temporary root SSH key was generated solely to do the Forgejo/runner/NPM
setup work above, then removed from the server's `authorized_keys` and
deleted locally once the pipeline was verified end-to-end working — checked
by confirming the key no longer authenticates. Treat that as the standing
expectation for any future server-access ask on this project — default to
the smallest scope that does the job, time-box it, and confirm
teardown/persistence explicitly rather than leaving it open-ended.

## Conventions and constraints established for this project

- PSA grading rules must be verified against a real source (PSA's own site,
  Beckett, CGC) before being encoded into `GRADING_SYSTEM` — this rubric has
  had real accuracy bugs (e.g. a self-contradictory centering tolerance, a
  missing 5% front-centering leeway rule for grades 7+) found and fixed
  through actual verification, not assumption.
- The vision prompt's `cannot_assess` escape hatch is deliberately narrow:
  surface condition genuinely can't be separated from dust/scratches on a
  toploader/slab's plastic, so it keeps the escape hatch. Corner and edge
  geometry (sharpness, whitening, chipping) **does** read through clear
  plastic and must be judged normally — an earlier prompt version gave the
  model an escape hatch for corners/edges too, which caused false
  "cannot tell from photo" results on cards that were plainly visible
  through the holder. Don't reintroduce that.
- No pre-flight/"precheck" step before a paid grading call. This was tried
  and explicitly rejected by the user — their workflow is screenshots that
  can't be pulled out of the toploader, so a pre-check step doesn't fit and
  was reverted.
- No browser automation (Playwright or otherwise) to scrape eBay listings.
  Tried a plain `curl`-based fetch once (not Playwright) and got an
  immediate 403; iterating on headers/fingerprinting to get past that would
  be bot-detection evasion regardless of which tool performs it, and is
  out of scope. This feature is paused; if revisited, the legitimate path
  is a client-side bookmarklet/extension that uses the *user's own*
  authenticated browser session rather than a server-side fetch.
- Never trust the reverse proxy's forwarded auth header for anything beyond
  attribution (whose name to log against a grade) — access control is the
  proxy's job, not the app's.