sunnymh/CLAUDE.md

CLAUDE.md

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

Repository layout

sunnymh is the umbrella repo for the 晴天漫画 · Sunny MH product. Each sub-project is its own git repo with its own remote on Gitea (gitea.04080616.xyz/yiekheng/sunnymh-*). The umbrella ties them together via git subtree so a single clone contains the whole system, while the sub-repos remain independently pushable.

Path	Role	Remote	Detailed guide
manga-dl/	Python TUI scraper — downloads manga from m.happymh.com, writes WebP to Cloudflare R2 + rows to Postgres	sunnymh-manga-dl.git	manga-dl/CLAUDE.md
manga-site/	Next.js 16 App Router reader — signed R2 URLs, placeholder-based reader, iOS Safari tuned	sunnymh-manga-site.git	manga-site/CLAUDE.md

More sub-projects may be added over time. Always read the sub-project's own CLAUDE.md before touching its code — the two stacks have very different invariants (Playwright/CDP anti-bot in manga-dl; placeholder-shift invariants in manga-site/PageReader.tsx).

Subtree workflow

The sub-dirs currently still hold their own .git (independent clones). To convert a sub-dir into a tracked subtree of this umbrella:

# one-time, per sub-project — run from sunnymh root
git remote add manga-dl-origin   https://gitea.04080616.xyz/yiekheng/sunnymh-manga-dl.git
git remote add manga-site-origin https://gitea.04080616.xyz/yiekheng/sunnymh-manga-site.git

# archive the existing working copy, then subtree-add from the remote
mv manga-dl manga-dl.bak && rm -rf manga-dl.bak/.git   # keep local-only files like .env, .browser-data
git subtree add --prefix=manga-dl manga-dl-origin main --squash
# then copy .env / .browser-data / cookies.txt / debug/ back into manga-dl/

Day-to-day:

# pull upstream changes for one sub-project
git subtree pull --prefix=manga-dl manga-dl-origin main --squash

# push umbrella-side edits back to the sub-repo's remote
git subtree push --prefix=manga-dl manga-dl-origin main

Local-only files that must NOT be pushed to the sub-repo remote (already in each sub-repo's own .gitignore): .env, manga-dl/.browser-data/, manga-dl/cookies.txt, manga-site/node_modules/, manga-site/.next/, manga-site/tsconfig.tsbuildinfo.

Cross-project invariants

These two sub-projects share infrastructure — changes on one side often require a matching change on the other.

• Shared Postgres schema: Manga, Chapter, Page (camelCase identifiers, Prisma-style). manga-dl/manga.py writes raw SQL via psycopg2; manga-site/prisma/schema.prisma reads via Prisma. When the Prisma schema changes, update every INSERT INTO "Page" / "Chapter" / "Manga" site in manga.py too. Likewise when manga.py adds a column, update schema.prisma and run npx prisma db push + npx prisma generate.
• Shared R2 layout (populated by scraper, consumed by site):
  • manga/<slug>/cover.webp
  • manga/<slug>/chapters/<chapter_number>/<page_number>.webp
• Page.width / Page.height are load-bearing: the scraper writes them on insert; manga-site/components/PageReader.tsx uses them for aspect-ratio placeholders to avoid iOS Safari scroll-anchor bugs. Dims=0 causes layout shift on image load.
• Shared .env keys: both sides read DATABASE_URL, R2_ACCOUNT_ID, R2_ACCESS_KEY, R2_SECRET_KEY, R2_BUCKET, R2_PUBLIC_URL. Each sub-repo has its own .env — keep the values in sync.

Common commands

Run these from the respective sub-directory:

# manga-dl (python, no tests/lint)
cd manga-dl && python manga.py

# manga-site (Next.js 16)
cd manga-site && npm run dev
cd manga-site && npm run build
cd manga-site && npm run lint
cd manga-site && npx prisma db push   # this repo uses db push, NOT migrate dev

Deployment

Only manga-site is deployed (Proxmox VM → Docker → Portainer, behind aaPanel Nginx at www.04080616.xyz → 127.0.0.1:3001). manga-dl is an operator-run local tool — it's not containerised and intentionally not headless (Cloudflare fingerprints real Chrome). See manga-site/CLAUDE.md for the full deploy flow.