bamort/RUNTIME_CONFIG_IMPLEMENTATION.md

# Runtime Configuration Implementation Summary

## What Was Implemented

Enhanced the BaMoRT frontend to support runtime configuration for **both desktop (Wails) and web production** deployments, eliminating the need to rebuild when changing API URLs.

## Architecture

### Desktop (Wails)
- Uses Go bindings to read API URL from `.env` file at runtime
- Method: `window['go']['main']['App']['GetAPIBaseURL']()`  
- Configuration: `desktop/.env` → `API_PORT` variable
- No rebuild needed when changing port

### Web Production (NEW)
Uses a **multi-strategy fallback system**:

1. **config.json** (Priority 1)
   - Loads `/config.json` from web root
   - Can be modified after deployment
   - Example: `{"apiBaseURL": "https://api.yourdomain.com"}`

2. **Auto-detection** (Priority 2)
   - Probes `/api/public/version` at same origin
   - Works automatically with reverse proxy setups
   - Detects if backend and frontend share same domain

3. **VITE_API_URL** (Priority 3)
   - Environment variable at build time
   - Used for development: `VITE_API_URL=http://localhost:8180`

4. **Same Origin Fallback** (Priority 4)
   - Uses `window.location.origin`
   - Assumes backend and frontend on same domain

## Files Modified

### Core Implementation
- `/data/dev/bamort/frontend/src/utils/config.js` - Enhanced with multi-strategy config loading
- `/data/dev/bamort/frontend/src/utils/api.js` - Uses dynamic baseURL (already done for desktop)
- `/data/dev/bamort/desktop/main.go` - GetAPIBaseURL() Go binding (already done for desktop)

### Documentation  
- `/data/dev/bamort/frontend/RUNTIME_CONFIG.md` - Complete web configuration guide
- `/data/dev/bamort/desktop/RUNTIME_CONFIG.md` - Desktop configuration guide (existing)

### Configuration Files
- `/data/dev/bamort/frontend/public/config.json.example` - Template for deployment
- `/data/dev/bamort/frontend/.gitignore` - Excludes `public/config.json` from git

## How It Works

### For Web Development
```bash
cd frontend
VITE_API_URL=http://localhost:8180 npm run dev
```

### For Web Production Deployment

**Option A: Using config.json (Recommended)**
```bash
# 1. Build once
cd frontend && npm run build

# 2. Deploy dist/ to web server

# 3. Create config.json in web root
cat > /var/www/bamort/config.json <<EOF
{
  "apiBaseURL": "https://api.production.com"
}
EOF

# 4. Change API URL anytime without rebuild!
```

**Option B: Reverse Proxy Setup**
 Example nginx configuration:
```nginx
server {
    listen 80;
    server_name yourdomain.com;

    # Frontend
    location / {
        root /var/www/bamort;
        try_files $uri $uri/ /index.html;
    }

    # Backend API
    location /api {
        proxy_pass http://localhost:8180;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```
Frontend auto-detects and uses same origin.

**Option C: Build with Embedded URL**
```bash
VITE_API_URL=https://api.production.com npm run build
```
(Not recommended - requires rebuild for URL changes)

### For Desktop (Wails)
```bash
# 1. Build once
cd desktop && wails build

# 2. Change port in .env (no rebuild!)
echo "API_PORT=9000" > desktop/.env

# 3. Run app - uses new port automatically
./desktop/build/bin/bamort
```

## Verification

Open browser console when loading the app. Look for one of these messages:

**Desktop:**
```
Desktop app using API URL from config: http://localhost:8185
```

**Web:**
```
Loaded API URL from config.json: https://api.yourdomain.com
```
or
```
Detected backend at same origin: https://yourdomain.com
```
or
```
Web app using VITE_API_URL: http://localhost:8180
```
or
```
Web app using same origin: https://yourdomain.com
```

## Benefits

✅ **No rebuild needed** for API URL changes in production web deployments  
✅ **Same build artifact** can be deployed to dev/staging/production  
✅ **Infrastructure-friendly** - works with reverse proxies, Docker, static hosting  
✅ **Flexible** - multiple configuration strategies with sensible fallbacks  
✅ **Dev-friendly** - VITE_API_URL still works for development  
✅ **Desktop-friendly** - reads .env at runtime (already implemented)

## Testing Checklist

- [x] Frontend builds successfully (`npm run build`)
- [x] Desktop app reads runtime config from .env  
- [ ] Web dev mode works with VITE_API_URL
- [ ] Web production with config.json works
- [ ] Web production with reverse proxy auto-detection works
- [ ] Web production with same-origin fallback works

## Migration Path

**For existing deployments:**
1. No changes needed! Current builds continue working
2. To enable runtime config: Just add `config.json` to your web root
3. Old builds with VITE_API_URL still work as fallback

**For new deployments:**
1. Build once: `npm run build`
2. Deploy `dist/` contents
3. Add `config.json` with your API URL
4. Done!