# Development Guide

## 1. Environment Setup

### 📦 Key Dependencies
- `PySide6` (for Native UI)
- `pyqtgraph` (for plotting)
- `numpy`, `pyserial`
- `fastapi`, `uvicorn[standard]` (for Web UI)

---

## 2. Running the Application

### 🖥️ Native UI (PySide6)
Standard desktop implementation.
```bash
export PYTHONPATH=$PYTHONPATH:.
# Generic Demo
python3 -m esp_viewer
```

### 🌐 Web UI (Vue 3 + FastAPI)
Modern browser-based monitoring.
```bash
export PYTHONPATH=$PYTHONPATH:.
python3 -m esp_viewer --web --force --profile assets/examples/multi_plot_demo.json
```
Access at `http://localhost:8080`.

---

## 3. Web Frontend Development

The frontend is located in `esp_viewer/web/` and uses **Vue 3 + Vite**.

### 🛠️ Build Process
Whenever you modify files in `esp_viewer/web/src/`, you **MUST** rebuild the assets:
```bash
cd esp_viewer/web
npm run build
```
The backend serves files from `esp_viewer/web/dist/`.

### 🧠 Why Build?
1. **SFC Compilation**: `.vue` files are converted to JS.
2. **Bundling**: Assets are minified and merged.
3. **Backend Integration**: `web_adapter.py` explicitly looks for the `dist/` folder.

---

## 4. Running Tests

### 🧪 Framework Tests
```bash
# Using unittest
PYTHONPATH=. python3 -m unittest discover tests
# Using pytest
python3 -m pytest esp_viewer/tests/backend/
```

### 🎯 Specific Feature Tests
```bash
PYTHONPATH=. python3 esp_viewer/tests/backend/test_ems_logic.py
```

---

## 5. Troubleshooting

### ❌ Changes not appearing in Web UI?
- **Build**: Did you run `npm run build`?
- **Cache**: Try a hard refresh (Ctrl+F5).
- **Dist Path**: Ensure the backend is serving from the correct `dist/` directory.

### ⚠️ Port 8080 already in use?
- The launcher handles most ghost processes, but you may need to kill it manually:
  ```bash
  fuser -k 8080/tcp
  ```

### 🐍 PYTHONPATH issues?
- Ensure you set `export PYTHONPATH=$PYTHONPATH:.` from the project root before running modules as scripts.
