# Contributing to Voice to Notes

Thank you for your interest in contributing! This guide covers how to set up the project for development and submit changes.

## Development Setup

### Prerequisites

- **Node.js 20+** and npm
- **Rust** (stable toolchain)
- **Python 3.11+** with [uv](https://docs.astral.sh/uv/) (recommended) or pip
- **System libraries (Linux only):**
  ```bash
  sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf xdg-utils
  ```

### Clone and Install

```bash
git clone https://repo.anhonesthost.net/MacroPad/voice-to-notes.git
cd voice-to-notes

# Frontend
npm install

# Python sidecar
cd python && pip install -e ".[dev]" && cd ..
```

### Running in Dev Mode

```bash
npm run tauri:dev
```

This runs the Svelte dev server + Tauri with hot-reload. The Python sidecar runs from your system Python (no PyInstaller needed in dev mode).

### Building

```bash
# Build the Python sidecar (frozen binary)
cd python && python build_sidecar.py --cpu-only && cd ..

# Build the full app
npm run tauri build
```

## Project Structure

```
src/                        # Svelte 5 frontend
  lib/components/           # Reusable UI components
  lib/stores/               # Svelte stores (app state)
  routes/                   # SvelteKit pages
src-tauri/                  # Rust backend (Tauri v2)
  src/sidecar/              # Python sidecar lifecycle (download, extract, IPC)
  src/commands/             # Tauri command handlers
  src/db/                   # SQLite database layer
python/                     # Python ML sidecar
  voice_to_notes/           # Main package
    services/               # Transcription, diarization, AI, export
    ipc/                    # JSON-line IPC protocol
    hardware/               # GPU/CPU detection
.gitea/workflows/           # CI/CD pipelines
docs/                       # Documentation
```

## How It Works

The app has three layers:

1. **Frontend (Svelte)** — UI, audio playback (wavesurfer.js), transcript editing (TipTap)
2. **Backend (Rust/Tauri)** — Desktop integration, file access, SQLite, sidecar process management
3. **Sidecar (Python)** — ML inference (faster-whisper, pyannote.audio), AI chat, export

Rust and Python communicate via **JSON-line IPC** over stdin/stdout pipes. Each request has an `id`, `type`, and `payload`. The Python sidecar runs as a child process managed by `SidecarManager` in Rust.

## Conventions

### Rust
- Follow standard Rust conventions
- Run `cargo fmt` and `cargo clippy` before committing
- Tauri commands go in `src-tauri/src/commands/`

### Python
- Python 3.11+, type hints everywhere
- Use `ruff` for linting: `ruff check python/`
- Tests with pytest: `cd python && pytest`
- IPC messages: JSON-line format with `id`, `type`, `payload` fields

### TypeScript / Svelte
- Svelte 5 runes (`$state`, `$derived`, `$effect`)
- Strict TypeScript
- Components in `src/lib/components/`
- State in `src/lib/stores/`

### General
- All timestamps in milliseconds (integer)
- UUIDs as primary keys in the database
- Don't bundle API keys or secrets — those are user-configured

## Submitting Changes

1. Fork the repository
2. Create a feature branch: `git checkout -b my-feature`
3. Make your changes
4. Test locally with `npm run tauri:dev`
5. Run linters: `cargo fmt && cargo clippy`, `ruff check python/`
6. Commit with a clear message describing the change
7. Open a Pull Request against `main`

## CI/CD

Pushes to `main` automatically:
- Bump the app version and create a release (`release.yml`)
- Build app installers for all platforms

Changes to `python/` also trigger sidecar builds (`build-sidecar.yml`).

## Areas for Contribution

- UI/UX improvements
- New export formats
- Additional AI provider integrations
- Performance optimizations
- Accessibility improvements
- Documentation and translations
- Bug reports and testing on different platforms

## Reporting Issues

Open an issue on the [repository](https://repo.anhonesthost.net/MacroPad/voice-to-notes/issues) with:
- Steps to reproduce
- Expected vs actual behavior
- Platform and version info
- Sidecar logs (`%LOCALAPPDATA%\com.voicetonotes.app\sidecar.log` on Windows)

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).