Files
splatoon3.ink/CLAUDE.md
Matt Isenhower 8806239511 Remove the server's scheduler, cache warming and archive uploader
The Worker's lanes, RegionAuth renewals and direct archive writes replace
app/cron.mjs, warmCaches and DataArchiver, which only spectre used. Local
runs keep every updater, social, screenshot and archive tool; there is no
local scheduler, and local snapshots stay in storage/archive/.

ARCHIVE_DATA now has to be "true": any value, including the "false" in
.env.example, used to turn archiving on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 09:51:51 -08:00

5.6 KiB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Splatoon3.ink displays Splatoon 3 map rotations, Salmon Run schedules, SplatNet gear, and more. It has a Vue 3 frontend (src/) and a Node.js backend (app/) in a single repository. The backend fetches data from Nintendo's SplatNet3 GraphQL API (authenticating through the nxapi znca API; app/splatnet/coral.mjs reimplements the nxapi client so it also runs in Workers) and publishes updates to social media (X via Buffer, Mastodon, Bluesky, Threads).

Commands

npm run dev            # Vite dev server with HMR
npm run build          # Production frontend build to dist/
npm run lint           # ESLint check
npm run lint-fix       # ESLint auto-fix
npm test               # Run Vitest once
npm run test:watch     # Vitest in watch mode

Backend commands (require .env configuration):

npm run splatnet:quick # Fast lane data without translations
npm run splatnet       # Fast lane data (schedules, gear, co-op, festivals, stages)
npm run splatnet:all   # Both lanes: also X-Rank and Splatfest rankings
npm run social         # Post status updates to social media
npm run social:test    # Test social posting (writes to files)

Cloudflare Worker (workers/updater/, see its README):

npm run updater:test              # Worker tests in workerd (npm test runs these too)
npm run updater:deploy:dry-run    # Bundle the dev Worker
npm run updater:deploy            # Deploy dev (production: updater:deploy:production)
npm run admin:dev                 # Admin panel with a simulated API (no Worker needed)
npm run admin:build               # Build the admin panel (deploys do this first)
npm run compressor:deploy         # Deploy the dev archive compressor (workers/compressor/, needs Docker)

Architecture

Frontend (src/): Vue 3 + Vue Router + Pinia + Tailwind CSS + vue-i18n (14 languages). Path alias @/ maps to src/. Pinia stores in src/stores/ fetch from /data/*.json endpoints. The useDataStore orchestrates loading schedules, gear, coop, and festival data.

Backend (app/): Node.js CLI dispatched through app/index.mjs. Commands map to actions (splatnet, social, archive tools, etc.).

Data pipeline: NsoClient (Nintendo auth) → SplatNet3Client (GraphQL queries) → DataUpdaters (app/data/updaters/) → storage → Frontend Pinia stores → Vue components. All file access goes through storage() (app/common/storage/), with public (data JSON, images, status screenshots), private (token and state caches), and archive areas keyed like the R2 objects. The Node runner maps them to dist/ and storage/; the Worker will use R2 bindings. Bullet tokens come from auth() (app/splatnet/auth.mjs).

Social media: StatusGenerators (app/social/generators/) create content from data. Clients (app/social/clients/) post to each platform. ScreenshotHelper delegates rendering to drivers in app/screenshots/drivers/: local Node commands capture the built site with an installed Chrome via puppeteer-core; Workers use Cloudflare Browser Run through the BROWSER binding. npm run screenshot and npm run screenshot:cloudflare capture images without running social posting.

Admin panel (workers/updater/admin/): a separate small Vue + Tailwind app (its own Vite config, not part of the public site's bundle), served by the updater Worker on its own hostname behind Cloudflare Access. Its API is workers/updater/src/admin/routes.mjs; admin/mock/api.mjs simulates that API for npm run admin:dev and must be kept in step with it. Pure logic lives in admin/src/lib/ with tests alongside.

Scheduling: In Cloudflare, workers/updater/ runs two Scheduler Durable Object lanes (fast: time-sensitive data + social; slow: X-Rank, rankings, avatars) and one RegionAuth Durable Object per region for Nintendo tokens. workers/compressor/ compresses each finished day of archive snapshots into a tar.zst once a day, running app/data/ArchiveCompressor.mjs in a Cloudflare Container (deploying it needs Docker or OrbStack). Locally there is no scheduler: run npm run splatnet and npm run social by hand.

Code Style

  • ESLint flat config with Vue, JSDoc, and import-alias plugins
  • 2-space indentation, single quotes, semicolons, trailing commas on multiline
  • Shared backend code must also run in Cloudflare Workers: avoid Node-only APIs there. Runtime-specific pieces use package imports with workerd and default conditions (#image-converter, #avatars, #local-screenshot-driver in package.json)
  • In src/ files, use @/ import alias (e.g., import Foo from '@/components/Foo.vue')
  • Vue: multi-word component names not required, up to 4 attributes per single line, self-closing void HTML elements
  • Node.js 24, ESM modules throughout (.mjs extension for backend files, .js/.vue for frontend)

Testing

Tests use Vitest. Test files live alongside source: app/**/*.test.mjs, src/**/*.test.{js,mjs}, and workers/updater/admin/src/**/*.test.js. Worker tests (workers/updater/*.spec.mjs) run in workerd.

Deployment

  • Frontend: built to dist/ and served by Cloudflare Pages
  • Backend: being migrated to Cloudflare Workers; there is no longer a server deployment built from this repo. The only Docker image is the archive compressor's container (workers/compressor/Dockerfile), which wrangler deploy builds and pushes to Cloudflare
  • dist/ is not emptied on build (preserves generated dist/data/ from backend)
  • Local screenshots run on the host with puppeteer-core and an installed Chrome; no separate browser service is needed