Plywise

Plywise is a free, open-source chess analysis tool for completed games.

Paste a Chess.com game link or PGN, run Stockfish, and review what actually happened. Single-game analysis will stay free. The bigger goal is to build a personal chess intelligence system that remembers your games, finds repeated weaknesses, and gives you useful positions to practice.

What it does

• Imports completed Chess.com games and pasted PGNs.
• Reconstructs and validates games with a C++ chess core.
• Runs Stockfish analysis with real progress and cancellation.
• Explains mistakes, openings, alternatives, and important positions.
• Supports retrying moves and exploring legal variations.
• Builds progress and weakness evidence from analyzed games.

What's done

The local C++ analysis system and React interface are working. Import, analysis, review, variations, practice data, progress, persistence, tests, and the new Home screen are all in place.

We are now moving Plywise from a Mac-first local app to a web-first hybrid product.

Run it locally

Run npm ci --prefix web, then scripts/browser-first-smoke.sh to build the C++ API and start the React dev server against it on loopback. No hosted service or billing account is needed.

Run the API yourself

Vercel only serves the React site. The C++ API runs as a Docker web service. For a free private alpha, Render can run it on its free web-service plan and connect it to Supabase for hosted storage. The free instance sleeps when idle and its filesystem is temporary, so durable user data must stay in PostgreSQL. For a larger or always-on launch, use a Linux host and a TLS reverse proxy in front of port 8787. Tagged releases publish ghcr.io/skcache/plywise-api with an immutable sha-<commit> tag and a content digest. For a local build, run docker compose up --build -d. For a hosted launch, pin the exact content digest and use the checked-in launcher:

export PCT_API_IMAGE=ghcr.io/skcache/plywise-api@sha256:<image-digest>
export PCT_API_DOMAIN=api.example.com
export PCT_POSTGRES_URL='postgresql://...?...&sslmode=require'
export PCT_SUPABASE_URL=https://your-project.supabase.co
export PCT_TRUSTED_HOSTS="$PCT_API_DOMAIN"
export PCT_ALLOWED_ORIGINS=https://plywise-chess.vercel.app
scripts/hosted-api-up.sh

hosted-api-up.sh validates the TLS, identity, storage, origin, and digest requirements before it pulls or replaces a running service. It then waits for the public HTTPS readiness endpoint. It does not print credentials or enable billing.

Keep the previous image digest beside the host's deployment notes. To roll back, replace PCT_API_IMAGE with that last-known-good digest and run scripts/hosted-api-up.sh again; Compose will pull only that API image, leave the TLS edge in place, and wait for readiness before returning. Run scripts/hosted-api-smoke.sh after the rollback with the same API origin, app origin, and short-lived account token used for a normal launch. For a remote authenticated launch, set PCT_POSTGRES_URL, PCT_SUPABASE_URL, PCT_TRUSTED_HOSTS, and PCT_ALLOWED_ORIGINS, then choose one API connection mode in Vercel:

• Direct: set VITE_PLYWISE_API_ORIGIN to the HTTPS API origin and VITE_PLYWISE_EVENT_ORIGIN to its wss:// origin.
• Same-origin proxy: set the non-public PCT_PLYWISE_API_ORIGIN to the HTTPS API origin. Vercel will proxy /api/* through the site, and set VITE_PLYWISE_EVENT_ORIGIN to the API's wss:// origin so live server-job updates do not try to use Vercel's static host.

The checked-in vercel.mjs rejects a production deployment without one of those API modes, keeps API responses out of caches, and builds the CSP from the configured public origins. The service itself refuses to start when the hosted C++ configuration is incomplete.

Render free API

The repository includes render.yaml for a free Render web service. It keeps the service on one small worker, waits for passing checks before auto-deploying, exposes /api/ready as the health check, and never creates a Render database or paid resource. The two values marked sync: false are the Supabase project URL and PostgreSQL connection string; enter them in Render's Environment tab, and include sslmode=require (or stronger verification) in the database URL.

After the service is live, set Vercel's VITE_PLYWISE_API_ORIGIN to the HTTPS onrender.com URL and VITE_PLYWISE_EVENT_ORIGIN to its wss:// origin. Run scripts/hosted-api-smoke.sh with a short-lived account token before inviting anyone else.

For a small always-on Linux host, the checked-in hosted Compose overlay adds a pinned Caddy TLS edge in front of the API. Point DNS for an API hostname at the host, then set the values below (the PostgreSQL URL must include sslmode=require, verify-ca, or verify-full):

export PCT_API_DOMAIN=api.example.com
export PCT_POSTGRES_URL='postgresql://...?...&sslmode=require'
export PCT_SUPABASE_URL=https://your-project.supabase.co
export PCT_TRUSTED_HOSTS="$PCT_API_DOMAIN"
export PCT_ALLOWED_ORIGINS=https://plywise-chess.vercel.app
scripts/hosted-compose-check.sh
docker compose -f compose.yaml -f compose.hosted.yaml --profile edge up -d

Caddy obtains and renews the certificate, forwards WebSocket upgrades, and keeps the C++ port on the private Compose network. This does not create a hosting account or enable billing; you still need an always-on host and DNS record.

Before pointing Vercel at a host, run scripts/hosted-api-smoke.sh with the API URL, app origin, and a short-lived account token. It checks readiness, JSON responses, exact CORS, the unauthenticated boundary, an authenticated game request, and the WebSocket handshake without printing the token.

To exercise the first saved-review path as well, provide a short-lived account token and a completed PGN explicitly. The script imports that PGN, starts server analysis, waits for real job progress, reads the completed review back from the account library, and can check a second account cannot read it. It never prints or stores bearer tokens; use a disposable test game because this adds one record to the account:

PCT_API_BASE_URL=https://your-api.onrender.com \
PCT_APP_ORIGIN=https://plywise-chess.vercel.app \
PCT_API_BEARER_TOKEN="$PCT_TEST_TOKEN" \
PCT_V1_PGN="[White \"Smoke\"]
[Black \"Test\"]
[Result \"1-0\"]

1. e4 e5 1-0" \
scripts/hosted-v1-smoke.sh

Set PCT_V1_SECOND_BEARER_TOKEN to include the cross-account read check. This path is opt-in and does not create a billing resource.

What's left

• Make the current experience work safely on the web.
• Keep free single-game analysis running on the user's device where possible.
• Add optional accounts, saved history, and cross-device sync.
• Build the personal intelligence and practice layer.
• Explore a completed-game browser extension after the Chess.com integration is approved.
• Harden everything for a public open-source release.

Plywise is independent and is not affiliated with or sponsored by Chess.com.