MaashkinoozheandClaude Opus 5.5
896726a51b
A switchable trace (DATA/perf/trace.on or PERF_TRACE=1) records every request's phases (stat, open, first read, disk vs network wait), browser resource timings, page-turn waits and flow stalls, a cold storage probe, event-loop lag, scans and scraper calls as JSONL. tools/perf-report.js says which phase slow loads spend their time in; tools/perf-bench.js simulates readers. READ_AHEAD (default on) reads an opened chapter's pages, then the next chapter's, into the OS cache so a NAS's cold reads stop reaching the browser. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.2 KiB
3.2 KiB
Working on MangaCircus
Guide for contributors and coding agents. Users who only want to run it: docs/deployment.md.
Layout
| Path | What |
|---|---|
server.js, library.js |
Reader: HTTP server, accounts, progress, JSON storage; folder scanner and image-size reader |
chapter-identity.js, chapter-dates.js, reading-*.js, catalog.js, backup.js |
Shared modules (chapter keys, chapter dates, reading clock/limits, collections, built-in backup) |
public/ |
The web pages: plain HTML, CSS and JavaScript, no build step |
scraper/ |
Download queue daemon (service.js, daemon.js), source adapters and parsers, the publisher that writes the library, metadata lookups |
peering/ |
Optional server-to-server sharing (gateway, client, adapter) |
runtime/ |
In-container supervisor and configuration |
perf/ |
Switchable performance trace and chapter read-ahead (docs/performance.md) |
discovery/, greatest/ |
Discovery Scout and the Greatest of All Time dashboard |
tools/ |
Demo library, health checks, maintenance tools (dry run by default), UI and Compose test drivers |
deploy/ |
circus.sh operations helper, HTTPS with Caddy |
docs/, vision/ |
Contracts and guides; design notes for planned features |
Rules
- No runtime dependencies. Node.js built-ins only. Playwright is an optional dev tool for UI tests.
- One writer per store. The reader alone writes
DATA(users, progress, catalog). The scraper alone writes the library and its queue. Tools that editchapter.jsonfiles are dry runs by default and need--apply --writers-stopped. - Library writes go through the publisher (
scraper/lib/publisher.js): staging folder, validated images, one atomic rename. The folder contract is docs/scraper-guide.md. - Sources are polite. Sequential requests, persisted per-host delays, stop on 401/403/429, never bypass access controls (scraper/AGENT_RUNBOOK.md).
- No secrets or personal data in the repository: no
.env,.secrets/,data/, libraries, host names, IP addresses or local paths. Tests use disposable fixtures and never a real library or user database. - Keep the docs current in the same change: a new file format field goes into docs/library-format.md, a new setting into the README or docs/deployment.md, an API change into docs/architecture.md.
- Match the surrounding style: small functions, short comments that say why, no framework.
Tests
npm test # reader, scraper, runtime and peering suites (node --test)
Without Node on the machine, run them in Docker (the peering test needs openssl, present in node:24):
docker run --rm -v "$PWD:/app" -w /app node:24 npm test
Browser and Compose acceptance tests (Playwright, disposable data, never the live stack):
npm run test:ui, npm run test:discovery-ui, npm run test:direction-ui, npm run test:peer-ab.
Try changes against demo data: node tools/make-dummy.js library && npm run start:all, or
docker compose -f docker-compose.yml -f compose.dev.yml up -d --build (mounts the editable source).