ServerBox is a cross-platform Flutter application that provides comprehensive server monitoring, management, and administration capabilities for Linux, Unix, and Windows servers. This page provides an architectural overview of the application, its core components, and technology foundations.
For specific implementation details:
Sources: README.md1-89 lib/data/res/build_data.dart1-9
The following diagram maps high-level system concepts to their concrete implementations in the codebase:
This architecture implements a clean separation of concerns with Flutter widgets in the presentation layer, Riverpod providers for business logic, Hive for persistence, and specialized infrastructure for SSH/terminal functionality.
Sources: lib/main.dart1-117 lib/view/page/home.dart1-304 lib/view/page/setting/entry.dart1-158 lib/data/store/setting.dart1-284
| Component | Technology | Key Files/Packages |
|---|---|---|
| Framework | Flutter 3.41.0+ | pubspec.yaml7-8 |
| Language | Dart 3.11.0+ | pubspec.yaml7 |
| State Management | Riverpod 3.0+ | flutter_riverpod, pubspec.yaml23 |
| Persistence | Hive CE | hive_ce_flutter, pubspec.yaml30 |
| SSH/SFTP | dartssh2 (custom fork) | packages/dartssh2, pubspec.yaml42-43 |
| Terminal Emulator | xterm.dart (custom fork) | packages/xterm, pubspec.yaml46-47 |
| Data Models | Freezed + JsonSerializable | pubspec.yaml27 pubspec.yaml32 |
| Dependency Injection | GetIt | pubspec.yaml28 |
| HTTP Client | Dio | pubspec.yaml17 |
| Charts | fl_chart | pubspec.yaml26 |
| Localization | flutter_localizations | pubspec.yaml13-14 |
| Build System | fl_build (custom tool) | packages/fl_build, pubspec.yaml83-84 |
The application uses Git submodules for dartssh2 and xterm to maintain custom patches, and relies on code generation (build_runner, freezed, hive_ce_generator) for boilerplate reduction.
Sources: pubspec.yaml1-121 pubspec.lock1-1500
The initialization process follows a strict sequence:
Sources: lib/main.dart21-117
The following table maps functional areas to their primary implementations:
| Functional Area | Primary Code Entity | Description |
|---|---|---|
| Application Root | app.dart::MyApp | Material app wrapper with theme and routing |
| Home Navigation | home.dart::HomePage | Tab-based navigation with PageController |
| Server Management | serversProvider (Riverpod) | Global server state and auto-refresh logic |
| Settings System | store/setting.dart::SettingStore | 50+ persistent properties via Hive |
| Server Data | model/server/server_private_info.dart::Spi | Server configuration model with Freezed |
| SSH Sessions | ssh/session_manager.dart::TermSessionManager | Terminal session lifecycle management |
| Backup System | view/page/backup.dart::BackupPage | WebDAV, iCloud, Gist, file backup sources |
| Localization | generated/l10n/l10n.dart | Generated from 12 .arb files |
| Build Metadata | data/res/build_data.dart::BuildData | Version info injected by make.dart |
Sources: lib/main.dart1-117 lib/view/page/home.dart19-304 lib/data/store/setting.dart11-284 lib/view/page/backup.dart21-28
ServerBox runs on five platforms with platform-specific integrations:
Platform-specific features are abstracted through conditional compilation (isIOS, isAndroid, isDesktop) and platform channels. The iOS/macOS builds include home widgets (StatusWidget) and Apple Watch support via watch_connectivity, while Android provides foreground service support for background SSH sessions.
Sources: ios/Runner.xcodeproj/project.pbxproj1-800 macos/Runner.xcodeproj/project.pbxproj1-500 .github/workflows/release.yml1-204
The build process uses a custom tool (fl_build) with pre/post-build hooks:
Build Data Generation: make.dart1-34 calculates the script modification count from Git history (make.dart26-33) and generates more_build_data.json. This is consumed by fl_build to populate lib/data/res/build_data.dart1-9 with BuildData.build (commit count) and BuildData.script (script commit count).
Platform Build Commands:
dart run fl_build -p android → produces 3 APKs (arm64/arm/amd64)dart run fl_build -p linux → produces AppImagedart run fl_build -p windows → produces ZIP archiveThe CI/CD pipeline (.github/workflows/release.yml1-204) runs these builds in parallel on tag push (v*) and uploads artifacts to GitHub Releases.
Sources: make.dart1-34 lib/data/res/build_data.dart1-9 .github/workflows/release.yml1-204
ServerBox persists data using Hive with three primary boxes:
| Store | Box Name | Key Model | Purpose |
|---|---|---|---|
SettingStore | 'setting' | String keys | 50+ app settings (theme, locale, SSH config, etc.) |
ServerStore | 'server' | Server ID | Spi (ServerPrivateInfo) collection |
| Snippet Store | 'snippet' | Snippet ID | Automation script templates |
| Private Key Store | 'private_key' | Key ID | Encrypted SSH private keys |
The SettingStore provides type-safe property accessors via propertyDefault() and listProperty() helpers (lib/data/store/setting.dart17-283), such as:
timeout: Server connection timeout (default 5s)themeMode: Light/dark/AMOLED theme selectionserverOrder: User-customized server list orderhomeTabs: Customizable home page tabsAll stores are initialized in Stores.init() before the app starts, ensuring data availability throughout the application lifecycle.
Sources: lib/data/store/setting.dart11-284 lib/main.dart51-67