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 submodules — the umbrella pins a commit SHA per sub-project, and cd-ing into a sub-dir gives you that sub-repo's own .git, history, and branch.

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).

Submodule workflow

First clone — must recurse, otherwise the sub-dirs come up empty:

git clone --recurse-submodules https://gitea.04080616.xyz/yiekheng/sunnymh.git
# or, after a plain clone:
git submodule update --init --recursive

Day-to-day inside a sub-project:

cd manga-dl
# sub-dir has its own .git file pointing to ../.git/modules/manga-dl/
# `git log`, `git status`, `git commit`, `git push` all talk to the sub-repo's remote (sunnymh-manga-dl.git)
git pull origin main
# edit, commit, push — this goes to the sub-repo's remote, NOT the umbrella

After a sub-repo is updated, bump the pinned SHA in the umbrella:

cd ..   # back to umbrella root
git add manga-dl           # stages the new submodule SHA
git commit -m "Bump manga-dl to <short-sha>"
git push

Pull upstream updates that bumped submodule SHAs:

git pull
git submodule update --recursive   # check out the SHAs the umbrella now points at

Local-only files inside each submodule (gitignored at the sub-repo level, never pushed anywhere): .env, manga-dl/.browser-data/, manga-dl/cookies.txt, manga-site/node_modules/, manga-site/.next/, manga-site/tsconfig.tsbuildinfo, manga-site/.claude/, manga-site/.agents/, manga-site/reference/.

The umbrella also has a root-level .env — shared R2 + DB credentials, single source of truth. It's untracked (not in a remote). Sub-projects currently still read their own .env copies; see the migration note in MEMORY.md / conversation history.

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.