Homemade Alexa Webapp

User interface for the voice assistant system. React + TypeScript + Vite. Communicates with the backend via REST (/api/public/stt) and WebSocket (/ws/public).

Requirements

• Node.js ≥ 18
• running Homemade Alexa Server

Installation

npm install

Development mode

npm run dev

The Vite dev server starts on http://localhost:5173 by default. Requests to /api/public/* and WebSocket /ws/public are proxied to the backend.

The default backend address is http://YOUR_SERVER_IP:8080. To override it without editing the file:

ALEXA_SERVER=http://other-host:8080 npm run dev

Production build

npm run build

Output goes to dist/. To serve the app under a path other than / (e.g. /alexa/), set the VITE_BASE variable:

VITE_BASE=/alexa/ npm run build

The built dist/ should be copied as webapp_dist/ next to the server's src/ directory — FastAPI serves it statically under the path configured in config.toml ([webapp] base).

Environment variables

Variable	Default	Description
ALEXA_SERVER	http://YOUR_SERVER_IP:8080	Backend address (dev proxy only)
VITE_BASE	/	Base URL of the app in the production build
VITE_API_URL	(none — uses location.origin)	Overrides the base URL for API calls and WebSocket at runtime

Architecture

src/
├── main.tsx          # entry point, mounts <App>
├── App.tsx           # main component; auth state handling, login screen
├── useAuth.ts        # JWT token in localStorage; login / logout
├── useAlexa.ts       # recording logic, VAD, STT, WebSocket
└── LoginScreen.tsx   # login screen

User flow

1. On first open, the app checks localStorage for the alexa_token key. No token → login screen.
2. Login: POST /api/public/auth/login with password → JWT saved in localStorage.
3. After login, the webapp connects to WebSocket /ws/public?token=<jwt>.
4. User clicks the button → browser records audio via Web Audio API with VAD detection (300 ms silence or 5 s timeout).
5. 16-bit 16 kHz PCM sent to POST /api/public/stt with header Authorization: Bearer <token>.
6. Server returns {command, next, audio_b64} — app plays TTS audio and optionally starts the next recording (next === "listen").
7. On HTTP 401, the token is cleared and the app returns to the login screen.

Backend endpoints (consumed by the webapp)

Method	Path	Auth	Description
POST	/api/public/auth/login	no	{password} → {token}
POST	/api/public/stt	Bearer	PCM audio → {command, next, audio_b64}
WS	/ws/public?token=	token in URL	server-pushed commands