Repository navigation
Development Guide
A focused contributor's manual: how to get a working dev environment, which scripts do what, and the conventions that keep the codebase predictable.
-
Node.js ≥ 22 — for ESM main bundle +
node:test-style globals. - npm 10+ — bundled with Node 22.
- Python 3.10+ — for the wake-word runner (only required if you enable wake-word mode in dev).
- macOS 12+ (recommended) — for testing the microphone permission flow. Linux works for everything except TCC-specific code paths.
A working Hermes bridge somewhere is optional — many integration tests inject fakes.
git clone https://github.com/VivaldiCode/voice-gateway
cd voice-gateway
npm installThe post-install rebuilds native modules (none required today, but the pipeline is in place).
| Command | What it does |
|---|---|
npm run dev |
electron-vite dev: HMR on the renderer, main restarts on TS change. |
npm test |
vitest run — all unit + integration tests, no E2E. |
npm run lint |
ESLint over src/ and tests/. |
npm run typecheck |
tsc --noEmit — full TS strict check. |
npm run build |
electron-vite build && electron-builder — current host's target. |
npm run build:mac |
macOS arm64 .dmg. |
npm run build:linux |
AppImage. |
npm run build:win |
nsis installer. |
npm run test:e2e |
Playwright against the packaged app — needs build:mac first. |
The CI gate is npm run lint && npm run typecheck && npm test. Failing
any of those should block a PR.
src/
├── shared/ # ESM-only, no Node deps. Importable from any process.
├── main/ # Node-only. Owns services + IPC handlers + windows.
├── preload/ # CommonJS. Tiny: just exposes vg.* via contextBridge.
└── renderer/ # Sandboxed React. No node-fs, no node-child_process.
If you find yourself reaching for node:fs in the renderer, you're
going the wrong way — move the logic to main and expose it via IPC.
Use the path aliases set up in
tsconfig.json:
| Alias | Resolves to |
|---|---|
@shared/* |
src/shared/* |
@main/* |
src/main/* |
@preload/* |
src/preload/* |
@renderer/* |
src/renderer/* |
Relative imports within a folder are fine. Crossing folder boundaries should always use the alias — makes refactors trivial.
-
strict: trueis on. Don't add// @ts-ignore— fix the type. - Prefer
interfacefor object shapes,typefor unions and tuples. - Avoid
any. Useunknownand a type guard when validating external data. - Explicitly type all exported functions' return types (eslint will remind you).
The project distinguishes three error tiers:
-
Fatal pipeline error — dispatched as the FSM
ERRORevent, emitted to the renderer overvg:conv:error. UI shows red orb. Examples: STT failed, WS auth failed, Hermes 401. -
Recoverable hint — emitted as a
warningevent (orchestrator has dedicatedwarningchannel). UI flashes a toast, FSM stays usable. Example: capture too short. -
Programmer error —
throw new Error(...)with a useful message. Surfaces in dev console; should never reach a user.
Always prefer Portuguese for messages the user will see directly.
Internal log strings (log.info('[VG] xyz')) stay in English.
-
electron-log/mainin main, with file transport atinfolevel and console atdebug. - Prefix every log message with
[VG]for grep-ability. - Settings and TTS/STT lifecycle changes log INFO; per-chunk activity logs DEBUG.
Log files on macOS: ~/Library/Logs/Voice Gateway/main.log.
- Implement
SttAdapter. - Extend
SttProviderinsrc/shared/types.ts. - Wire
createSttAdapter(). - Add a card in Reconhecimento in
SettingsPanel.tsx. - Add tests in
tests/integration/stt-service.test.ts.
See Speech-To-Text#adding-a-new-stt-provider for the full checklist.
- Add the discriminant to
ClientMessageorServerMessageinsrc/shared/protocol.ts. - Update the matching
parseClientMessage/parseServerMessagecase. - Bump the version note in Protocol and document the new event.
- Wire emission in the bridge (
server.py) and consumption inHermesClient+Orchestrator. - Add round-trip tests in
tests/unit/protocol.test.ts.
- Edit
src/shared/state-machine.ts. -
Always add at least one case to
tests/unit/state-machine.test.tscovering the new transition AND the invalid-event-stays-same-ref contract for it. - Update the diagram in State-Machine — the diagram is the source of truth users will read.
We don't tag automatically. To cut a release:
# 1. Bump CLIENT_VERSION in src/shared/constants.ts AND
# server/hermes-voice-bridge/src/hermes_voice_bridge/__init__.py
# 2. Update CHANGELOG.md
git commit -am "release: 0.2.0"
git tag v0.2.0
git push --tags
npm test
npm run build:mac
gh release create v0.2.0 release/*.dmg --generate-notesThe bridge isn't packaged separately — users get the new version on
next install.sh run (the script is idempotent and auto-upgrades the
PyPI package).
- Comments explain why, not what. The diff already shows the what.
- Multi-line strings use template literals; never
\nconcatenation. - One
console.error-equivalent per fatal path — duplicates clutter the log. - Imports ordered: node built-ins, third-party,
@shared/@main/ etc, relative. ESLint enforces this. - Tests use Vitest's
it('asserts X', () => …)nottest('X', …)for consistency with the rest of the suite.
Sequence to try, in order:
rm -rf node_modules dist out release && npm installnpm run typecheck && npm run lint && npm test- Check
~/Library/Logs/Voice Gateway/main.log— every fatal path logs there. - Troubleshooting — covers user-visible symptoms.
- Open an issue on the tracker.
Voice Gateway — VivaldiCode/voice-gateway. MIT licensed. Wiki sources live under docs/; run ./docs/sync-wiki.sh to publish.
Getting started
Architecture
- Architecture — system overview
- State-Machine — conversation FSM
- Conversation-Orchestrator — main glue
- WebSocket-Client — Hermes connection
- IPC-Layer — main ↔ renderer
- Settings-And-Storage — config persistence
Audio
- Audio-Pipeline — capture & playback
- Speech-To-Text — STT adapters
- Text-To-Speech — TTS adapters
- Wake-Word-Detection — openWakeWord
Server
- Hermes-Voice-Bridge — Python bridge
- Protocol — WebSocket spec
Platform
- Build-And-Packaging — electron-builder
- macOS-Permissions — TCC, signing
- Renderer-UI — React components
Project
- Testing-Guide — unit, integration, E2E
- Development-Guide — contributing
- Glossary — terms