vocero-client/frontend-s2s/README.md

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:

   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
• Vite server and proxy options
• Vite features and asset handling
• Tailwind's Vite integration