# Design: Embedded Backend Packaging

## Context
Meeting Assistant uses a three-tier architecture: Electron Client → FastAPI Middleware → MySQL/Dify. For enterprise deployment, administrators want to distribute a single executable that users can run without additional setup. The backend must still connect to remote MySQL and Dify services (no local database).

**Stakeholders:**
- Enterprise IT administrators (simplified deployment)
- End users (double-click to run)
- Developers (maintain backward compatibility)

## Goals / Non-Goals

### Goals
- Package backend as a sidecar executable using PyInstaller
- Electron manages backend lifecycle (start on launch, stop on close)
- Single `config.json` for all configuration (frontend, backend, whisper)
- Health check ensures backend is ready before showing UI
- Backward compatible with existing separate-deployment mode
- Show Whisper model download progress to improve UX

### Non-Goals
- Embedding MySQL database (still remote)
- Embedding LLM model (still uses Dify API)
- Removing external authentication (still requires company SSO)
- Pre-bundling Whisper model (user downloads on first run)

## Decisions

### Decision 1: Use PyInstaller for Backend Packaging
**What:** Package FastAPI + uvicorn as standalone executable using PyInstaller `--onedir` mode.

**Why:**
- Consistent with existing transcriber sidecar approach
- `--onedir` provides faster startup than `--onefile`
- Team already has PyInstaller expertise

**Alternatives considered:**
- Nuitka: Better optimization but longer build times
- cx_Freeze: Less community support for FastAPI

### Decision 2: Configuration via Extended config.json
**What:** Add `backend` section to existing `config.json` with database, API, and auth settings.

**Why:**
- Single configuration file for users to manage
- Runtime modifiable without rebuilding
- Consistent with existing whisper config pattern

**Schema:**
```json
{
  "apiBaseUrl": "http://localhost:8000/api",
  "backend": {
    "embedded": true,
    "host": "127.0.0.1",
    "port": 8000,
    "database": { "host": "", "port": 33306, "user": "", "password": "", "database": "" },
    "externalApis": { "authApiUrl": "", "difyApiUrl": "", "difyApiKey": "", "difySttApiKey": "" },
    "auth": { "adminEmail": "", "jwtSecret": "", "jwtExpireHours": 24 }
  }
}
```

### Decision 3: Health Check Before Window Display
**What:** Electron polls `/api/health` endpoint before creating main window.

**Why:**
- Prevents "connection refused" errors on startup
- Provides clear feedback if backend fails to start
- Maximum 30 attempts with 1-second intervals

### Decision 4: Backward Compatibility via Feature Flag
**What:** `backend.embedded: false` (default) preserves existing behavior; `true` enables embedded mode.

**Why:**
- Existing deployments continue working unchanged
- Gradual migration path for enterprises
- Same codebase supports both deployment models

### Decision 5: Huggingface Hub Progress Callback for Model Download
**What:** Intercept huggingface_hub download progress and emit JSON status messages.

**Why:**
- faster-whisper uses huggingface_hub internally
- Can emit progress without modifying faster-whisper source
- JSON format consistent with existing sidecar protocol

## Risks / Trade-offs

| Risk | Impact | Mitigation |
|------|--------|------------|
| PyInstaller hidden imports missing | Backend fails to start | Comprehensive hidden-import list; test on clean Windows |
| Config file contains sensitive data | Security exposure | Document security best practices; consider encryption |
| Backend startup timeout | Poor UX | Increase timeout; show loading indicator |
| Port 8000 already in use | Backend fails | Allow configurable port; detect and report conflicts |

## Migration Plan

### For New Deployments (All-in-One)
1. Build with `--embedded-backend` flag
2. Configure `config.json` with database/API credentials
3. Distribute single exe to users

### For Existing Deployments (Separate Backend)
1. No changes required
2. Ensure `backend.embedded: false` in config
3. Continue using existing backend deployment

### Rollback
- Set `backend.embedded: false` to disable embedded backend
- Deploy backend separately as before

## Open Questions
- Should we add config validation UI on first startup?
- Should backend port be auto-discovered if 8000 is in use?