More tests, better functionality, the server serves the dashboard now on configurable ports. websocket stuff fixed, though I dont think data is really being sent / recieved...

2025-06-13 17:09:08 -06:00
parent b373a93f0e
commit d34cccc253
65 changed files with 166413 additions and 1801 deletions
@@ -0,0 +1,138 @@
+# Dashboard Build System
+
+This document explains how to keep the Flutter web dashboard in sync with the server's static files.
+
+## Overview
+
+The XP Nix server serves static files from `xp_server/lib/src/web/static/` directory. The Flutter dashboard is a separate project in `xp_dashboard/` that needs to be built for web and copied to the static directory.
+
+## Build Methods
+
+### Method 1: Using the Server Command (Recommended)
+
+When the server is running, you can use the interactive `build` command:
+
+1. Start the server:
+   ```bash
+   cd xp_server
+   dart run bin/xp_nix.dart
+   ```
+
+2. Type `build` in the server console and press Enter:
+   ```
+   build
+   ```
+
+The server will:
+- Check if Flutter is available
+- Build the Flutter dashboard with `flutter build web --release`
+- Copy all files from `xp_dashboard/build/web/` to `xp_server/lib/src/web/static/`
+- Provide feedback on the build status
+
+### Method 2: Using the Shell Script
+
+For building outside of the running server, use the provided shell script:
+
+```bash
+./build_dashboard.sh
+```
+
+This script:
+- Checks for Flutter availability
+- Builds the Flutter dashboard
+- Clears old static files
+- Copies new files to the static directory
+
+## Build Process Details
+
+### What Gets Built
+
+The Flutter build process creates:
+- `index.html` - Main HTML file
+- `main.dart.js` - Compiled Dart code
+- `flutter.js`, `flutter_bootstrap.js` - Flutter runtime
+- `flutter_service_worker.js` - Service worker for PWA features
+- `assets/` - Flutter assets and fonts
+- `canvaskit/` - CanvasKit rendering engine
+- `icons/` - App icons
+- `manifest.json` - Web app manifest
+- Other supporting files
+
+### File Synchronization
+
+The build process:
+1. **Clears** the existing `xp_server/lib/src/web/static/` directory
+2. **Copies** all files from `xp_dashboard/build/web/` to the static directory
+3. **Preserves** the directory structure including subdirectories
+
+## Development Workflow
+
+### When to Rebuild
+
+Rebuild the dashboard when you:
+- Make changes to Flutter widgets in `xp_dashboard/lib/`
+- Update dependencies in `xp_dashboard/pubspec.yaml`
+- Modify theme or styling
+- Add new features to the dashboard
+
+### Typical Workflow
+
+1. Make changes to the Flutter dashboard code
+2. Test locally if needed: `cd xp_dashboard && flutter run -d web-server`
+3. Build and deploy: Use either the server `build` command or `./build_dashboard.sh`
+4. Refresh your browser to see the changes
+
+## Troubleshooting
+
+### Flutter Not Found
+```
+❌ Flutter is not available in the system PATH
+```
+**Solution**: Ensure Flutter is installed and added to your PATH.
+
+### Build Failed
+```
+❌ Flutter build failed
+```
+**Solution**: Check the error output, usually related to:
+- Dart compilation errors
+- Missing dependencies (`flutter pub get`)
+- Invalid Flutter code
+
+### Files Not Copied
+```
+❌ Build output directory not found
+```
+**Solution**: The Flutter build didn't complete successfully. Check the build output for errors.
+
+## File Structure
+
+```
+xp_nix/
+├── xp_dashboard/           # Flutter dashboard source
+│   ├── lib/               # Flutter source code
+│   ├── web/               # Web-specific files
+│   └── build/web/         # Build output (generated)
+├── xp_server/
+│   ├── lib/src/web/static/ # Static files served by server
+│   └── lib/src/build/      # Build system code
+├── build_dashboard.sh      # Standalone build script
+└── BUILD_DASHBOARD.md      # This documentation
+```
+
+## Advanced Usage
+
+### Custom Build Options
+
+To modify build options, edit the Flutter build command in:
+- `xp_server/lib/src/build/dashboard_builder.dart` (for server command)
+- `build_dashboard.sh` (for shell script)
+
+Current build command: `flutter build web --release`
+
+### Development vs Production
+
+- **Development**: Use `flutter build web` (debug mode, faster builds)
+- **Production**: Use `flutter build web --release` (optimized, smaller files)
+
+The current setup uses `--release` for optimal performance.