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>
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
workerdanddefaultconditions (#image-converter,#avatars,#local-screenshot-driverin 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 (
.mjsextension for backend files,.js/.vuefor 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), whichwrangler deploybuilds and pushes to Cloudflare dist/is not emptied on build (preserves generateddist/data/from backend)- Local screenshots run on the host with puppeteer-core and an installed Chrome; no separate browser service is needed