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## Commands
6 
7### Development
8 
9- `flutter run` - Run the app in development mode
10- `flutter run --release -PallowDebugReleaseSigning=true` - Run Android release locally with explicit debug-signing fallback for verification only
11- `dart run fl_build -p PLATFORM` - Build the app for specific platform (see fl_build package)
12- `dart run build_runner build --delete-conflicting-outputs` - Generate code for models with annotations (json_serializable, freezed, hive, riverpod)
13  - Every time you change model files, run this command to regenerate code (Hive adapters, Riverpod providers, etc.)
14  - Generated files include: `*.g.dart`, `*.freezed.dart` files
15 
16### Testing
17 
18- `flutter test` - Run unit tests
19- `flutter test test/battery_test.dart` - Run specific test file
20 
21## Architecture
22 
23This is a Flutter application for managing Linux servers with the following key architectural components:
24 
25### Project Structure
26 
27- `lib/core/` - Core utilities, extensions, and routing
28- `lib/data/` - Data layer with models, providers, and storage
29  - `model/` - Data models organized by feature (server, container, ssh, etc.)
30  - `provider/` - Riverpod providers for state management
31  - `store/` - Local storage implementations using Hive
32- `lib/view/` - UI layer with pages and widgets
33- `lib/generated/` - Generated localization files
34- `lib/hive/` - Hive adapters for local storage
35 
36### Key Technologies
37 
38- **State Management**: Riverpod with code generation (riverpod_annotation)
39- **Local Storage**: Hive for persistent data with generated adapters
40- **SSH/SFTP**: Custom dartssh2 fork for server connections
41- **Terminal**: Custom xterm.dart fork for SSH terminal interface
42- **Networking**: dio for HTTP requests
43- **Charts**: fl_chart for server status visualization
44- **Localization**: Flutter's built-in i18n with ARB files
45- **Code Generation**: Uses build_runner with json_serializable, freezed, hive_generator, riverpod_generator
46 
47### Data Models
48 
49- Server management models in `lib/data/model/server/`
50- Container/Docker models in `lib/data/model/container/`
51- SSH and SFTP models in respective directories
52- Most models use freezed for immutability and json_annotation for serialization
53 
54### Features
55 
56- Server status monitoring (CPU, memory, disk, network)
57- SSH terminal with virtual keyboard
58- SFTP file browser
59- Docker container management
60- Process and systemd service management
61- Server snippets and custom commands
62- Multi-language support (12+ languages)
63- Cross-platform support (iOS, Android, macOS, Linux, Windows)
64 
65### State Management Pattern
66 
67- Uses Riverpod providers for dependency injection and state management
68- Uses Freezed for immutable state models
69- Providers are organized by feature in `lib/data/provider/`
70- State is often persisted using Hive stores in `lib/data/store/`
71 
72### Build System
73 
74- Uses custom `fl_build` package for cross-platform building
75- `make.dart` script handles pre/post build tasks (metadata generation)
76- Supports building for multiple platforms with platform-specific configurations
77- Many dependencies are custom forks hosted on GitHub (dartssh2, xterm, fl_lib, etc.)
78 
79### Important Notes
80 
81- **Never run code formatting commands** - The codebase has specific formatting that should not be changed
82- **Always run code generation** after modifying models with annotations (freezed, json_serializable, hive, riverpod)
83- Generated files (`*.g.dart`, `*.freezed.dart`) should not be manually edited
84- AGAIN, NEVER run code formatting commands.
85- USE dependency injection via GetIt for services like Stores, Services and etc.
86- Generate all l10n files using `flutter gen-l10n` command after modifying ARB files.
87- USE `hive_ce` not `hive` package for Hive integration.
88  - Which no need to config `HiveField` and `HiveType` manually.
89- USE widgets and utilities from `fl_lib` package for common functionalities.
90  - Such as `CustomAppBar`, `context.showRoundDialog`, `Input`, `Btnx.cancelOk`, etc.
91  - You can use context7 MCP to search `lppcg fl_lib KEYWORD` to find relevant widgets and utilities.
92- USE `libL10n` and `l10n` for localization strings.
93  - `libL10n` is from `fl_lib` package, and `l10n` is from this project.
94  - Before adding new strings, check if it already exists in `libL10n`.
95  - Prioritize using strings from `libL10n` to avoid duplication, even if the meaning is not 100% exact, just use the substitution of `libL10n`.
96- Split UI into Widget build, Actions, Utils. use `extension on` to achieve this
97- Android release signing:
98  - Normal release builds must use the real release keystore from `key.properties`.
99  - Debug-signing fallback is for local verification only and must be enabled explicitly with `-PallowDebugReleaseSigning=true`.
100  - Do not use debug-signing fallback for formal release artifacts.
101- Android release artifacts:
102  - CI release builds for Android are split per ABI, not a single fat APK.
103  - Do not judge release size from a local `flutter build apk --release` fat APK.
104  - To reproduce CI-style Android artifacts locally, use `dart run fl_build -p android` or `flutter build apk --release --split-per-abi`.
105