From efc0315c931b416bfc4a73c5aa8f7ea966d51082 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?lollipopkit=F0=9F=8F=B3=EF=B8=8F=E2=80=8D=E2=9A=A7?=
 =?UTF-8?q?=EF=B8=8F?= <10864310+lollipopkit@users.noreply.github.com>
Date: Mon, 1 Sep 2025 23:32:44 +0800
Subject: [PATCH] new: `CLAUDE.md`

---
 CLAUDE.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..beca8746
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,89 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development
+
+- `flutter run` - Run the app in development mode
+- `flutter test` - Run all tests
+- `dart run fl_build -p PLATFORM` - Build the app for specific platform (see fl_build package)
+
+### Code Generation
+
+- `dart run build_runner build --delete-conflicting-outputs` - Generate code for models with annotations (json_serializable, freezed, hive, riverpod)
+  - Every time you change model files, run this command to regenerate code (Hive adapters, Riverpod providers, etc.)
+  - Generated files include: `*.g.dart`, `*.freezed.dart` files
+
+### Testing
+
+- `flutter test` - Run unit tests
+- `flutter test test/battery_test.dart` - Run specific test file
+
+## Architecture
+
+This is a Flutter application for managing Linux servers with the following key architectural components:
+
+### Project Structure
+
+- `lib/core/` - Core utilities, extensions, and routing
+- `lib/data/` - Data layer with models, providers, and storage
+  - `model/` - Data models organized by feature (server, container, ssh, etc.)
+  - `provider/` - Riverpod providers for state management
+  - `store/` - Local storage implementations using Hive
+- `lib/view/` - UI layer with pages and widgets
+- `lib/generated/` - Generated localization files
+- `lib/hive/` - Hive adapters for local storage
+
+### Key Technologies
+
+- **State Management**: Riverpod with code generation (riverpod_annotation)
+- **Local Storage**: Hive for persistent data with generated adapters
+- **SSH/SFTP**: Custom dartssh2 fork for server connections
+- **Terminal**: Custom xterm.dart fork for SSH terminal interface
+- **Networking**: dio for HTTP requests
+- **Charts**: fl_chart for server status visualization
+- **Localization**: Flutter's built-in i18n with ARB files
+- **Code Generation**: Uses build_runner with json_serializable, freezed, hive_generator, riverpod_generator
+
+### Data Models
+
+- Server management models in `lib/data/model/server/`
+- Container/Docker models in `lib/data/model/container/`
+- SSH and SFTP models in respective directories
+- Most models use freezed for immutability and json_annotation for serialization
+
+### Features
+
+- Server status monitoring (CPU, memory, disk, network)
+- SSH terminal with virtual keyboard
+- SFTP file browser
+- Docker container management
+- Process and systemd service management
+- Server snippets and custom commands
+- Multi-language support (12+ languages)
+- Cross-platform support (iOS, Android, macOS, Linux, Windows)
+
+### State Management Pattern
+
+- Uses Riverpod providers for dependency injection and state management
+- Uses Freezed for immutable state models
+- Providers are organized by feature in `lib/data/provider/`
+- State is often persisted using Hive stores in `lib/data/store/`
+
+### Build System
+
+- Uses custom `fl_build` package for cross-platform building
+- `make.dart` script handles pre/post build tasks (metadata generation)
+- Supports building for multiple platforms with platform-specific configurations
+- Many dependencies are custom forks hosted on GitHub (dartssh2, xterm, fl_lib, etc.)
+
+### Important Notes
+
+- **Never run code formatting commands** - The codebase has specific formatting that should not be changed
+- **Always run code generation** after modifying models with annotations (freezed, json_serializable, hive, riverpod)
+- Generated files (`*.g.dart`, `*.freezed.dart`) should not be manually edited
+- AGAIN, NEVER run code formatting commands.
+- USE dependency injection via GetIt for services like Stores, Services and etc.
+- Generate all l10n files using `flutter gen-l10n` command after modifying ARB files.