# 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.