chore(frontend): validate migration and document development
This commit is contained in:
+111
-9
@@ -1,14 +1,116 @@
|
||||
# Vocero React frontend
|
||||
|
||||
React, TypeScript, Tailwind CSS, and Vite client for the existing `s2s-client` FastAPI backend.
|
||||
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.
|
||||
|
||||
Requires Node.js 22.18+ or 24+ and npm. Run `npm ci`, then `npm run dev`.
|
||||
The frontend listens on `http://127.0.0.1:5173` and proxies backend requests to
|
||||
`http://127.0.0.1:8420`. Copy `.env.example` to `.env.local` to override that target.
|
||||
## Run during development
|
||||
|
||||
`npm run check` runs formatting, strict ESLint, TypeScript, and Vitest checks.
|
||||
`npm run build` typechecks and produces `dist/`. `npm run format` and `npm run lint:fix`
|
||||
apply mechanical formatting and lint fixes.
|
||||
Use Node.js 22.18 or later on the 22.x line, or Node.js 24+. Install dependencies
|
||||
with npm; the lockfile is committed.
|
||||
|
||||
The repository's `start_ui.sh` still serves the original UI. This project is started
|
||||
separately during the frontend migration.
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user