117 lines
6.1 KiB
Markdown
117 lines
6.1 KiB
Markdown
# Vocero React frontend
|
|
|
|
React 19, TypeScript, Tailwind CSS 4, and Vite 8 client for the existing
|
|
`s2s-client` FastAPI backend. This is a client-side application with React-owned
|
|
rendering and state, including the realtime WebSocket and audio integration.
|
|
|
|
## Run during development
|
|
|
|
Use Node.js 22.18 or later on the 22.x line, or Node.js 24+. Install dependencies
|
|
with npm; the lockfile is committed.
|
|
|
|
1. Start the existing backend using `./start_ui.sh` from your configured S2S
|
|
checkout, or reuse an already-running instance. It normally listens on port
|
|
`8420` and continues serving the original static UI there. Its Python
|
|
environment, `.env`, speech service, and upstream services must be configured
|
|
as before.
|
|
2. In a second terminal, start this frontend:
|
|
|
|
```sh
|
|
cd frontend-s2s
|
|
npm ci
|
|
npm run dev
|
|
```
|
|
|
|
3. Open `http://127.0.0.1:5173`. Add `?debug=true` to access settings, tools,
|
|
and custom RAG context. Existing `phoneNumber` and `episode_id` query
|
|
parameters are supported.
|
|
|
|
Vite serves React and Tailwind with hot updates. It proxies `/api`,
|
|
`/v1/realtime` (including WebSockets), OAuth, and backend documentation routes
|
|
to FastAPI. The browser uses one origin on port `5173`, so there is no separate
|
|
API origin or development CORS setup. The proxy preserves the incoming Host
|
|
header because FastAPI uses it to construct the speech WebSocket URL.
|
|
|
|
For a different backend, copy `.env.example` to `.env.local` and set
|
|
`S2S_BACKEND_URL`. This is a **Vite server** setting. Runtime UI flags, voices,
|
|
reasoning mode, prompts, and the speech URL still come from FastAPI's
|
|
`/api/config`. A backend explicitly configured with `SPEECH_TO_SPEECH_URL`
|
|
continues to return that direct speech endpoint.
|
|
|
|
The Vite configuration reads only this project's environment files. Do not
|
|
copy the repository's backend secrets into this directory or into `VITE_*`
|
|
variables, which are exposed to browser code.
|
|
|
|
For access through a development reverse proxy, set the exact hostname in
|
|
`S2S_DEV_ALLOWED_HOSTS`. Use `npm run dev -- --host 0.0.0.0` only when Vite must
|
|
listen beyond localhost. The browser needs HTTPS for microphone access outside
|
|
localhost, and that proxy must forward WebSocket upgrades for both speech and
|
|
Vite HMR. Wiring the staging entrypoint and launcher is a separate step:
|
|
**this port does not change `start_ui.sh`.**
|
|
|
|
Component and CSS changes use Fast Refresh. Editing the session controller or
|
|
audio modules can require restarting a conversation or a page reload. Teardown
|
|
closes microphone tracks, worklets, sockets, queue tickets, timers, and pending
|
|
requests on session stop or page exit.
|
|
|
|
## Checks and commands
|
|
|
|
The scripts and code style follow `frontend-admin` conventions, with Vite and
|
|
React plugins replacing Next.js-specific tooling. Executable configuration
|
|
files use TypeScript; TypeScript's own project settings use JSON.
|
|
|
|
| Command | Purpose |
|
|
| -------------------- | ----------------------------------------------------------- |
|
|
| `npm run dev` | Vite development server on port 5173, with a fixed port |
|
|
| `npm run check` | Formatting, strict typed ESLint, type checking, and tests |
|
|
| `npm run lint:fix` | Apply ESLint fixes |
|
|
| `npm run format` | Format source and sort Tailwind classes |
|
|
| `npm run typecheck` | Check application, tests, audio worklets, and configuration |
|
|
| `npm test` | Run Vitest and React Testing Library regression tests |
|
|
| `npm run test:watch` | Watch tests while editing |
|
|
| `npm run build` | Typecheck and compile the app and worklets into `dist/` |
|
|
| `npm run preview` | Inspect the compiled output locally |
|
|
|
|
No build step is needed before `npm run dev`. `dist/` is generated and ignored
|
|
by Git. Build output is available for later serving integration; this change
|
|
does not mount it in FastAPI or change the staging launch process.
|
|
|
|
Tests cover session initialization, response sequencing, cumulative transcripts,
|
|
interruptions, queue cancellation, microphone-permission cancellation, tool
|
|
results, external reasoning and `LOG_ONLY`, late-response cleanup, the idle
|
|
timeout, settings, RAG, profiles, and sanitized Markdown/export behavior.
|
|
Vitest handles Node 26's experimental web storage behavior internally.
|
|
|
|
## Source layout
|
|
|
|
- `src/components/`: voice controls, chat, dialogs, profile, and account views.
|
|
- `src/realtime/`: session lifecycle, observable application state, queue and
|
|
budget handling, WebSocket protocol, tools, and external reasoning.
|
|
- `src/audio/`: TypeScript capture/playback worklets, audio graph, PCM codec,
|
|
and visualizer. Vite emits the worklets as separate JavaScript assets.
|
|
- `src/lib/`: validated backend contracts, settings, prompt context, profile
|
|
and report presentation, Markdown sanitization, and conversation exports.
|
|
- `config/backend-proxy.ts`: the shared HTTP/WebSocket development proxy.
|
|
- `src/styles.css`: Tailwind integration and React-specific layout adjustments.
|
|
- `src/styles/legacy-theme.css`: the existing visual styles, retained for
|
|
fidelity to both the white microphone and dark orb themes. The UI is ported
|
|
to React; the full design has not been rewritten as Tailwind utilities.
|
|
|
|
The current Spanish interface, local preference keys, session-only RAG,
|
|
Markdown replies, JSON/TXT exports, optional browser wake word, TALK/TALKFIRST
|
|
startup modes, and optional backend features are retained. Camera controls and
|
|
quick actions remain absent, matching their disabled state in the old UI.
|
|
|
|
Native speech stays at the current project's 16 kHz PCM rate. The backend
|
|
continues to own VAD, transcription, model inference, synthesis, upstream
|
|
credentials, and ApiPilot execution. Browser `SpeechSynthesis` is used only
|
|
when the configured external reasoning service returns an answer instead of
|
|
`log_only`.
|
|
|
|
## References
|
|
|
|
- [Vite getting started](https://vite.dev/guide/)
|
|
- [Vite server and proxy options](https://vite.dev/config/server-options)
|
|
- [Vite features and asset handling](https://vite.dev/guide/features)
|
|
- [Tailwind's Vite integration](https://tailwindcss.com/docs/installation/using-vite)
|