@page quickstart Quick Start Guide

# Quadrix GUI - Quick Start Guide

**Last Updated:** 2025-12-03

This guide gets you up and running with the Quadrix GUI applications in minutes.

---

## Prerequisites

### For Web GUI (Recommended - Start Here!)

**System Dependencies:**
```bash
sudo apt-get update
sudo apt-get install -y libfontconfig1-dev libfreetype6-dev pkg-config
```

**Time Required:** ~5 minutes

### For Tauri Desktop App (Optional)

**Additional Dependencies:**
```bash
sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential \
    libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev
```

**Time Required:** ~15 minutes (first build)

---

## Quick Start: Web GUI (5 Minutes)

### 1. Build the Application
```bash
# From project root
cargo build --bin web_gui --features plotting --release
```
⏱️ Build time: ~12 seconds

### 2. Start the Server
```bash
./target/release/web_gui
```
[DONE] You should see: `Serving web GUI on http://0.0.0.0:3000`

### 3. Open in Browser
Navigate to: **http://localhost:3000**

### 4. Try It Out
Use the sample data provided:

**CSV Path:** `data/test_eigenvalues.csv`
**Title:** `My First Plot`
**Color By:** `species` (optional)

Click **"Generate Plot"** and you're done! 🎉

---

## CSV Data Format

Your CSV files must have these **exact column names**:

```csv
eigenvalue_1,eigenvalue_2,eigenvalue_3,species,region
0.8,0.15,0.05,dendrite_a,cortex
0.7,0.25,0.05,dendrite_a,cortex
```

**Required Columns:**
- `eigenvalue_1` (float)
- `eigenvalue_2` (float)
- `eigenvalue_3` (float)

**Optional Columns:**
- Any metadata for color coding (e.g., `species`, `region`, `type`)

**Example:** See `data/test_eigenvalues.csv`

---

## Quick Start: Tauri Desktop App

### 1. Install Dependencies
```bash
sudo apt-get install -y libwebkit2gtk-4.1-dev libgtk-3-dev \
    libayatana-appindicator3-dev librsvg2-dev
```

### 2. Build & Run
```bash
cd tauri-app
cargo tauri dev
```

The desktop application will launch automatically!

---

## Common Issues

### Web GUI

**Problem:** `cargo build` fails with fontconfig error
```bash
# Solution:
sudo apt-get install -y libfontconfig1-dev
```

**Problem:** Plot generation fails with "Missing eigenvalue_1"
```
# Solution: Check your CSV has columns named exactly:
# eigenvalue_1, eigenvalue_2, eigenvalue_3
```

**Problem:** Cannot access from another machine
```bash
# The server binds to 0.0.0.0:3000, so it should be accessible
# Check firewall: sudo ufw allow 3000
```

### Tauri App

**Problem:** Build fails with webkit error
```bash
# Solution:
sudo apt-get install -y libwebkit2gtk-4.1-dev
```

---

## What's Included

### Web GUI Features
[DONE] Modern, responsive interface
[DONE] Real-time plot generation
[DONE] Configurable dimensions
[DONE] Color mapping by metadata
[DONE] Multi-user support
[DONE] No client installation needed

### Tauri Desktop App Features
[DONE] Native desktop application
[DONE] Beautiful dark mode UI
[DONE] Offline support
[DONE] Fast local processing
[DONE] Cross-platform (Windows/macOS/Linux)

---

## Next Steps

### 📚 Learn More
- **Full Guide:** [GUI_APPLICATIONS.md](./GUI_APPLICATIONS.md)
- **Build Info:** [BUILD_DEPENDENCIES.md](./BUILD_DEPENDENCIES.md)
- **Test Results:** [TEST_REPORT.md](./TEST_REPORT.md)
- **API Docs:** [README.md](./README.md)

### 🔧 Customize
- Modify `src/bin/web_gui.rs` for web interface changes
- Edit `tauri-app/ui/` for desktop UI customization
- Update `tauri-app/src-tauri/src/main.rs` for backend logic

### 🚀 Deploy
- **Web GUI:** Ready for production deployment
- **Desktop:** Build installers with `cargo tauri build`

---

## Performance Notes

**Based on Testing:**
- Plot generation: < 1 second for 20 data points
- Web GUI startup: Instant
- Memory usage: Minimal (~50MB for web server)
- Concurrent users: Supports multiple simultaneous requests

**Recommended for:**
- Small to medium datasets (< 10,000 points)
- Interactive data exploration
- Quick visualizations
- Remote access via web browser

---

## File Locations

```
Project Root/
├── target/release/web_gui     # Web server binary
├── tauri-app/                 # Desktop app source
├── data/test_eigenvalues.csv  # Sample data
└── Documentation:
    ├── QUICKSTART.md          # This file
    ├── GUI_APPLICATIONS.md    # Full user guide
    ├── BUILD_DEPENDENCIES.md  # System requirements
    └── TEST_REPORT.md         # Test results
```

---

## Getting Help

**Documentation Order:**
1. **QUICKSTART.md** (you are here) - Get started fast
2. **GUI_APPLICATIONS.md** - Detailed usage guide
3. **BUILD_DEPENDENCIES.md** - Build troubleshooting
4. **TEST_REPORT.md** - Known issues and solutions

**For Issues:**
- Check TEST_REPORT.md for known issues
- Verify dependencies with `pkg-config --exists fontconfig`
- Ensure CSV format matches requirements

---

## Success Checklist

After following this guide, you should have:

- [DONE] Web GUI server running on port 3000
- [DONE] Sample plot generated from test data
- [DONE] Understanding of CSV format requirements
- [DONE] Optional: Tauri desktop app running

**If you got this far - you're all set!** 🎊

---

**Quick Links:**
- Start Web GUI: `./target/release/web_gui`
- Sample Data: `data/test_eigenvalues.csv`
- Documentation: `GUI_APPLICATIONS.md`
