CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project overview
6 
7JHenTai is a Flutter app for browsing E-Hentai / EXHentai, targeting Android, iOS, Windows, macOS, and Linux. Version `8.0.14+328` (from pubspec.yaml).
8 
9## Build & dev commands
10 
11```bash
12# Get dependencies
13flutter pub get
14 
15# Run code generation (Drift DB, etc.) — required after editing any @DriftDatabase tables/queries
16dart run build_runner build
17 
18# Run code generation in watch mode during active DB work
19dart run build_runner watch --delete-conflicting-outputs
20 
21# Run app on a connected device
22flutter run
23 
24# Lint
25flutter analyze
26 
27# Run tests
28flutter test
29```
30 
31No test directory files are present, so `flutter test` is purely for when new tests are added.
32 
33## Architecture
34 
35### Dependency framework: GetX
36State management, routing, dependency injection, and i18n all use GetX. Widgets use `GetBuilder<T>` (manual `update()`), not reactive `.obs` streams. Pages use `.obs` for settings that must broadcast changes across views.
37 
38### Lifecycle: `JHLifeCircleBean` pattern
39 
40Every singleton service and setting implements `JHLifeCircleBean` from `lib/src/service/jh_service.dart`:
41 
42- `initBean()` — async init (called before `runApp`)
43- `afterBeanReady()` — post-runApp setup
44- `initDependencies` — list of other beans this one needs initialized first
45 
46All beans are registered in a topological-sorted list in `lib/src/main.dart` and initialized in order. **Adding a new service/setting requires inserting it into this list with the correct `initDependencies` ordering** — out-of-order registration will cause init failures. Three mixins simplify common patterns:
47- `JHLifeCircleBeanErrorCatch` — wraps init/ready in try/catch with logging; subclasses override `doInitBean()` / `doAfterBeanReady()` instead
48- `JHLifeCircleBeanWithConfigStorage` — adds JSON serialize/deserialize to the `local_config` DB table via `applyBeanConfig()` / `getBeanConfig()`
49- Service beans live in `lib/src/service/`; settings singletons live in `lib/src/setting/`
50 
51### Logging
52 
53Uses the `logger` package via the global `log` singleton (`lib/src/service/log.dart`). Four tiered outputs:
54- Console logger (dev: colored + method info; prod: plain with timestamp)
55- Verbose file logger (trace-level, `verbose/`)
56- Warning file logger (warn+, `warning/`)
57- Download-specific file logger (`download/`)
58 
59Call `log.trace/debug/info/warn/error(msg, e, stack)`. Errors in `JHLifeCircleBeanErrorCatch` mixin are automatically logged.
60 
61### Supporting directories
62 
63- `lib/src/config/` — app-level configuration (theme, UI constants, Sentry, API secrets)
64- `lib/src/enum/` — enums shared across the app (`EHNamespace`, `ConfigEnum`, `ConfigTypeEnum`)
65- `lib/src/extension/` — extension methods on framework types (DioException, String, List, Directory, Widget, GetLogic)
66- `lib/src/mixin/` — reusable page mixins: scroll-to-top, double-tap-refresh, login-required guard, animation, window-widget
67- `lib/src/model/` — data classes: `Gallery`, `GalleryTag`, `GalleryImage`, `GalleryComment`, `SearchConfig`, `SearchHistory`, and per-endpoint response models in `model/jh_response/` and `model/archive_bot_response/`
68- `lib/src/utils/` — 30+ utility files for parsing (eh_spider_parser, jh_spider_parser), IO, date, crypto, proxy, version, etc.
69- `lib/src/exception/` — custom exception classes (`EHSiteException`, `NotUploadException`)
70 
71### Routing
72 
73All routes are defined in `lib/src/routes/routes.dart` as static const strings on `class Routes`. The `EHPage` class extends `GetPage` and adds:
74- `side` — `left`/`right`/`fullScreen` (tablet layout uses left/right split)
75- `offAllBefore` — whether previous right-side routes are popped
76 
77Nested settings routes use a `settingPrefix` convention (`/setting_*`).
78 
79### Page pattern
80 
81Pages follow a consistent GetX structure in `lib/src/pages/`:
82 
83- `*_page.dart` — Widget
84- `*_logic.dart` — `GetxController` subclass (business logic)
85- `*_state.dart` — Mutable state object
86 
87The base class is `BasePageLogic` (`pages/base/base_page_logic.dart`) which handles gallery-list pages: pull-to-refresh, pagination (prev/next gid), search config persistence, and tag blocking/filtering. Subclasses override `getGalleryPage()` to provide page-specific API calls.
88 
89### Network layer (`lib/src/network/`)
90 
91Uses a custom Dio fork (`dio` from `jiangtian616/dio` at `append-mode` ref). Main request classes:
92- `EHRequest` — all E-Hentai API calls, with cookie management, caching, domain fronting for EX
93- `JHRequest` — backend API calls (tag translations, app update checks, built-in block lists)
94- `ArchiveBotRequest` — archive.org resolution
95 
96Parsers for HTML responses live in `lib/src/utils/eh_spider_parser.dart`.
97 
98### Database (`lib/src/database/`)
99 
100Drift (SQLite) at schema version 24 with heavy migration chain. Tables in `database/table/`, DAOs in `database/dao/`. The global `appDb` singleton is declared at the bottom of `database.dart`. Generated code is in `database.g.dart` — re-run `dart run build_runner build` after any schema change and add a migration step in `MigrationStrategy.onUpgrade`.
101 
102### Services (`lib/src/service/`)
103 
104Independent singletons that manage core features:
105- `gallery_download_service.dart` / `archive_download_service.dart` — download engine with parallel queue, resume, priority
106- `tag_translation_service.dart` — fetches and caches tag translations from EhTagTranslation
107- `local_block_rule_service.dart` — user-configured gallery blocking rules
108- `cloud_service.dart` — config sync
109- `storage_service.dart` — JSON/GetStorage NoSQL persistence
110- `super_resolution_service.dart` — image upscaling metadata tracking
111- `path_service.dart` — platform-aware directory resolution
112 
113### Settings (`lib/src/setting/`)
114 
115Each setting module is a standalone singleton (e.g., `ehSetting`, `styleSetting`, `preferenceSetting`) using `JHLifeCircleBeanWithConfigStorage`. Settings are serialized as JSON and stored in the `local_config` DB table. Reactive `.obs` values are used when settings need to trigger UI rebuilds across the app.
116 
117### Layout system (`lib/src/pages/layout/`)
118 
119Three layout modes:
120- `mobile_v2` — bottom navigation bar with tab-style pages
121- `tablet_v2` — master-detail split (left/right route sides)
122- `desktop` — sidebar navigation with persistent detail panel
123 
124The home page (`home_page.dart`) selects the layout based on screen width.
125 
126### i18n (`lib/src/l18n/`)
127 
128Custom translation system via `LocaleText` (GetX `Translations`). One `.dart` file per language with key-value pairs. Adding a new language requires: the locale file, an entry in `locale_text.dart`, and an entry in `locale_consts.dart`.
129 
130### Widget library (`lib/src/widget/`)
131 
132Reusable widgets prefixed `eh_` — dialogs, cards, image components, tag displays, etc. The `app_manager.dart` widget wraps the entire app for global concerns. The `loading_state_indicator.dart` provides a standard loading/error/empty/idle state widget.
133 
134### Key dependencies (beyond Flutter standard)
135 
136- `get` 4.6.6 — state management, routing, i18n, NoSQL storage
137- `dio` (custom fork) — HTTP client
138- `drift` 2.21.0 — SQLite ORM
139- `extended_image` — image loading with cache
140- `photo_view` / `zoom_view` (custom forks) — reading page image viewer
141- `desktop_webview_window` — desktop webview for cookie login
142