Skip to content

Commit 2990d2b

Browse files
lukeocodeslukeocodes
committed
docs: add AGENTS.md and CLAUDE.md for AI coding assistants
1 parent d655a8e commit 2990d2b

2 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# java-flux
2+
3+
Java (Javalin) demo app for Deepgram Flux.
4+
5+
## Architecture
6+
7+
- **Backend:** Java (Javalin) (Java) on port 8081
8+
- **Frontend:** Vite + vanilla JS on port 8080 (git submodule: `flux-html`)
9+
- **API type:** WebSocket — `WS /api/flux`
10+
- **Deepgram API:** Flux v2 Listen (`wss://api.deepgram.com/v2/listen`)
11+
- **Auth:** JWT session tokens via `/api/session` (WebSocket auth uses `access_token.<jwt>` subprotocol)
12+
13+
## Key Files
14+
15+
| File | Purpose |
16+
|------|---------|
17+
| `src/main/java/com/deepgram/starter/App.java` | Main backend — API endpoints and WebSocket proxy |
18+
| `deepgram.toml` | Metadata, lifecycle commands, tags |
19+
| `Makefile` | Standardized build/run targets |
20+
| `sample.env` | Environment variable template |
21+
| `frontend/main.js` | Frontend logic — UI controls, WebSocket connection, audio streaming |
22+
| `frontend/index.html` | HTML structure and UI layout |
23+
| `deploy/Dockerfile` | Production container (Caddy + backend) |
24+
| `deploy/Caddyfile` | Reverse proxy, rate limiting, static serving |
25+
26+
## Quick Start
27+
28+
```bash
29+
# Initialize (clone submodules + install deps)
30+
make init
31+
32+
# Set up environment
33+
test -f .env || cp sample.env .env # then set DEEPGRAM_API_KEY
34+
35+
# Start both servers
36+
make start
37+
# Backend: http://localhost:8081
38+
# Frontend: http://localhost:8080
39+
```
40+
41+
## Start / Stop
42+
43+
**Start (recommended):**
44+
```bash
45+
make start
46+
```
47+
48+
**Start separately:**
49+
```bash
50+
# Terminal 1 — Backend
51+
mvn compile exec:java
52+
53+
# Terminal 2 — Frontend
54+
cd frontend && corepack pnpm run dev -- --port 8080 --no-open
55+
```
56+
57+
**Stop all:**
58+
```bash
59+
lsof -ti:8080,8081 | xargs kill -9 2>/dev/null
60+
```
61+
62+
**Clean rebuild:**
63+
```bash
64+
rm -rf target frontend/node_modules frontend/.vite
65+
make init
66+
```
67+
68+
## Dependencies
69+
70+
- **Backend:** `pom.xml` — Uses Maven for dependency management. Javalin framework for HTTP/WebSocket.
71+
- **Frontend:** `frontend/package.json` — Vite dev server
72+
- **Submodules:** `frontend/` (flux-html), `contracts/` (starter-contracts)
73+
74+
Install: `mvn dependency:resolve`
75+
Frontend: `cd frontend && corepack pnpm install`
76+
77+
## API Endpoints
78+
79+
| Endpoint | Method | Auth | Purpose |
80+
|----------|--------|------|---------|
81+
| `/api/session` | GET | None | Issue JWT session token |
82+
| `/api/metadata` | GET | None | Return app metadata (useCase, framework, language) |
83+
| `/api/flux` | WS | JWT | Advanced real-time transcription with turn-based detection. |
84+
85+
## Customization Guide
86+
87+
### Flux-Specific Parameters
88+
Flux extends live transcription with end-of-turn (EOT) detection. These are passed as WebSocket URL query parameters:
89+
90+
| Parameter | Default | Range | Effect |
91+
|-----------|---------|-------|--------|
92+
| `model` | `flux-general-en` | See below | Flux STT model |
93+
| `encoding` | `linear16` | `linear16`, `opus` | Audio encoding |
94+
| `sample_rate` | `16000` | `8000`-`48000` | Audio sample rate |
95+
| `eot_threshold` | `0.7` | `0.0`-`1.0` | Confidence for end-of-turn detection (higher = more conservative) |
96+
| `eager_eot_threshold` | (disabled) | `0.0`-`1.0` | Threshold for tentative (eager) end-of-turn |
97+
| `eot_timeout_ms` | `5000` | `0`-`30000` | Silence duration (ms) before automatic EOT |
98+
| `keyterm` | (none) | Repeated param | Custom vocabulary hints (can specify multiple) |
99+
100+
### Understanding Turn Events
101+
Flux provides structured turn-based events instead of simple interim/final:
102+
103+
1. **StartOfTurn** — User started speaking (new turn)
104+
2. **Update** — Interim transcript update within the turn
105+
3. **EagerEndOfTurn** — Tentative end detected (user might continue)
106+
4. **TurnResumed** — User spoke again after eager EOT
107+
5. **EndOfTurn** — Confirmed end of turn (final transcript)
108+
109+
### Tuning EOT Behavior
110+
- **Lower `eot_threshold`** (e.g., 0.3): Faster turn endings, but may cut off mid-sentence
111+
- **Higher `eot_threshold`** (e.g., 0.9): Waits longer, better for longer utterances
112+
- **Enable `eager_eot_threshold`**: Shows tentative completions, can resume if user keeps talking
113+
- **Lower `eot_timeout_ms`**: Faster timeout on silence
114+
- **Higher `eot_timeout_ms`**: More patience for thinking pauses
115+
116+
### Adding Keyterms
117+
Keyterms boost recognition of specific words. In the backend, add them as repeated query params:
118+
```
119+
?keyterm=Deepgram&keyterm=Nova&keyterm=Aura
120+
```
121+
122+
The frontend has a comma-separated input field for keyterms.
123+
124+
### Frontend UI Controls
125+
The frontend provides:
126+
- EOT threshold slider (0.0-1.0)
127+
- Eager EOT toggle + threshold slider
128+
- EOT timeout input (ms)
129+
- Keyterm input (comma-separated)
130+
- Theme toggle (light/dark/system)
131+
132+
To add new controls, edit `frontend/main.js` and include values in the `URLSearchParams` when connecting.
133+
134+
## Frontend Changes
135+
136+
The frontend is a git submodule from `deepgram-starters/flux-html`. To modify:
137+
138+
1. **Edit files in `frontend/`** — this is the working copy
139+
2. **Test locally** — changes reflect immediately via Vite HMR
140+
3. **Commit in the submodule:** `cd frontend && git add . && git commit -m "feat: description"`
141+
4. **Push the frontend repo:** `cd frontend && git push origin main`
142+
5. **Update the submodule ref:** `cd .. && git add frontend && git commit -m "chore(deps): update frontend submodule"`
143+
144+
**IMPORTANT:** Always edit `frontend/` inside THIS starter directory. The standalone `flux-html/` directory at the monorepo root is a separate checkout.
145+
146+
### Adding a UI Control for a New Feature
147+
1. Add the HTML element in `frontend/index.html` (input, checkbox, dropdown, etc.)
148+
2. Read the value in `frontend/main.js` when making the API call or opening the WebSocket
149+
3. Pass it as a query parameter in the WebSocket URL
150+
4. Handle it in the backend `src/main/java/com/deepgram/starter/App.java` — read the param and pass it to the Deepgram API
151+
152+
## Environment Variables
153+
154+
| Variable | Required | Default | Purpose |
155+
|----------|----------|---------|---------|
156+
| `DEEPGRAM_API_KEY` | Yes | — | Deepgram API key |
157+
| `PORT` | No | `8081` | Backend server port |
158+
| `HOST` | No | `0.0.0.0` | Backend bind address |
159+
| `SESSION_SECRET` | No | — | JWT signing secret (production) |
160+
161+
## Conventional Commits
162+
163+
All commits must follow conventional commits format. Never include `Co-Authored-By` lines for Claude.
164+
165+
```
166+
feat(java-flux): add diarization support
167+
fix(java-flux): resolve WebSocket close handling
168+
refactor(java-flux): simplify session endpoint
169+
chore(deps): update frontend submodule
170+
```
171+
172+
## Testing
173+
174+
```bash
175+
# Run conformance tests (requires app to be running)
176+
make test
177+
178+
# Manual endpoint check
179+
curl -sf http://localhost:8081/api/metadata | python3 -m json.tool
180+
curl -sf http://localhost:8081/api/session | python3 -m json.tool
181+
```

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

0 commit comments

Comments
 (0)