feat: rapportage UI refactor, speech streaming, docs & seed data

Rapportage: - Refactor workspace into modular components (quick-actions, timeline-card, timeline-sidebar) - Add updateReport action for inline editing - Improve report timeline with better UX Speech: - Add Deepgram token API endpoint - Add use-deepgram-streaming hook - Add confidence-text component Docs: - Add architecture documentation - Add performance optimization plan - Add speech specs and seed data docs Scripts & Data: - Add seed-reports script and migration - Update AGENTS.md guidelines 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-25 14:07:08 +01:00
parent f7e33d0335
commit dce3943963
25 changed files with 6732 additions and 394 deletions
--- a/docs/specs/speech/analyse-deepgram.md
+++ b/docs/specs/speech/analyse-deepgram.md
@@ -0,0 +1,196 @@
+# Analyse: Migratie naar Deepgram SDK
+
+## Huidige situatie
+
+### Huidige implementatie
+
+- REST API via directe `fetch()` naar `https://api.deepgram.com/v1/listen`
+- Audio wordt opgenomen met `MediaRecorder`, opgeslagen als Blob
+- Na opname wordt het hele bestand geüpload via FormData
+- Server-side route handler (`app/api/deepgram/transcribe/route.ts`) verwerkt de upload
+- Geen streaming; alles gebeurt na de opname
+
+### Componenten betrokken
+
+- `components/speech-recorder.tsx` - Client-side opname component
+- `app/api/deepgram/transcribe/route.ts` - Server-side API route
+
+---
+
+## Impact van Deepgram SDK
+
+### 1. Architectuurwijziging: REST → WebSocket streaming
+
+**Huidige flow:**
+```
+Browser → MediaRecorder → Blob → FormData → POST /api/deepgram/transcribe → Deepgram REST API → Transcript
+```
+
+**Nieuwe flow met SDK:**
+```
+Browser → Microfoon stream → Deepgram SDK (WebSocket) → Real-time transcript chunks → UI update
+```
+
+**Impact:**
+- Streaming vereist een WebSocket-verbinding
+- Real-time updates tijdens opname (niet alleen na opname)
+- Client-side SDK nodig (niet alleen server-side)
+- Server route kan worden vereenvoudigd of verwijderd
+
+### 2. Client-side SDK vereist
+
+**Wat er moet gebeuren:**
+- Deepgram SDK installeren: `@deepgram/sdk` of `@deepgram/browser-sdk`
+- Client-side WebSocket-verbinding opzetten
+- Audio stream direct naar Deepgram sturen (niet via server)
+- Real-time transcript chunks ontvangen en verwerken
+
+**Overwegingen:**
+- **API key:** moet client-side beschikbaar zijn (met `NEXT_PUBLIC_` prefix) of via een proxy/token endpoint
+- **Security:** API key niet direct in client code plaatsen; gebruik een proxy endpoint die tokens uitreikt
+
+### 3. Component herstructurering
+
+**`speech-recorder.tsx` wijzigingen:**
+- Verwijder `MediaRecorder` blob-opslag (of behoud voor lokale backup)
+- Verwijder FormData upload naar `/api/deepgram/transcribe`
+- Voeg Deepgram SDK WebSocket-verbinding toe
+- Implementeer real-time transcript updates tijdens opname
+- Update state management voor streaming chunks
+- Voeg error handling toe voor WebSocket-verbindingen
+
+**Nieuwe functionaliteit:**
+- Real-time transcript updates tijdens opname
+- Mogelijkheid tot pauzeren/hervatten zonder verbinding te verbreken
+- Endpointing (automatische detectie van spraakpauzes)
+- Betere error handling voor netwerkproblemen
+
+### 4. Server-side route aanpassing
+
+**Opties voor `/api/deepgram/transcribe/route.ts`:**
+
+**Optie A: Verwijderen**
+- Als alles client-side gebeurt, is deze route niet meer nodig
+- Vereist client-side API key exposure (niet aanbevolen)
+
+**Optie B: Proxy voor API key security**
+- Route wordt een proxy die tokens uitreikt of de verbinding proxyt
+- Client maakt verbinding via deze proxy
+- API key blijft server-side
+
+**Optie C: Hybride**
+- Streaming via client-side SDK
+- Fallback naar REST API voor batch-verwerking
+- Route behouden voor backward compatibility
+
+### 5. State management wijzigingen
+
+**Huidige state:**
+- `isRecording` - boolean
+- `isUploading` - boolean
+- `error` - string
+- `chunksRef` - Blob array
+
+**Nieuwe state nodig:**
+- `isStreaming` - WebSocket verbinding status
+- `transcriptChunks` - Array van real-time transcript delen
+- `connectionStatus` - 'connecting', 'connected', 'disconnected', 'error'
+- `partialTranscript` - Huidige incomplete transcript
+- `finalTranscript` - Voltooide transcripties
+
+### 6. Error handling uitbreiding
+
+**Nieuwe error scenarios:**
+- WebSocket verbindingsfouten
+- Netwerk onderbrekingen tijdens streaming
+- Deepgram quota/rate limiting tijdens live sessie
+- Microfoon toegang tijdens actieve stream
+- Herverbindingslogica nodig
+
+### 7. UX verbeteringen mogelijk
+
+**Met streaming beschikbaar:**
+- Real-time tekst tijdens spreken
+- Visual feedback per woord/chunk
+- Lagere latency (<500ms per chunk vs 2+ seconden voor hele opname)
+- Mogelijkheid tot directe correcties tijdens opname
+- Pauzeren/hervatten zonder opnieuw opnemen
+
+### 8. Dependencies
+
+**Te installeren:**
+```json
+"@deepgram/sdk": "^latest" // of "@deepgram/browser-sdk"
+```
+
+**Mogelijk te verwijderen:**
+- Geen directe fetch naar Deepgram REST API meer nodig
+- FormData handling kan worden vereenvoudigd
+
+### 9. Configuratie wijzigingen
+
+**Environment variables:**
+- `DEEPGRAM_API_KEY` blijft nodig
+- Overweeg `NEXT_PUBLIC_DEEPGRAM_API_KEY` alleen als je client-side direct verbindt (niet aanbevolen)
+- Beter: proxy endpoint die tokens uitreikt
+
+**Deepgram configuratie:**
+- Model: `nova-2` (blijft hetzelfde)
+- Language: `nl` (blijft hetzelfde)
+- Nieuwe opties: `endpointing`, `interim_results`, `punctuate`, `smart_format`
+
+### 10. Backward compatibility
+
+**Overwegingen:**
+- Bestaande code die `/api/deepgram/transcribe` gebruikt
+- Migratiepad voor andere componenten
+- Fallback mechanisme als streaming faalt
+
+---
+
+## Aanbevolen migratiepad
+
+### Fase 1: Voorbereiding
+1. Deepgram SDK installeren
+2. Proxy endpoint maken voor secure token/key management
+3. Test implementatie maken naast bestaande REST implementatie
+
+### Fase 2: Core streaming
+1. WebSocket verbinding opzetten in `speech-recorder.tsx`
+2. Real-time transcript updates implementeren
+3. Basis error handling toevoegen
+
+### Fase 3: UX verbeteringen
+1. Visual feedback voor real-time updates
+2. Pauzeren/hervatten functionaliteit
+3. Endpointing configureren
+
+### Fase 4: Cleanup
+1. Oude REST API route verwijderen of deprecaten
+2. Code cleanup
+3. Documentatie updaten
+
+---
+
+## Risico's en aandachtspunten
+
+1. **Security:** API key niet direct in client code
+2. **Kosten:** Streaming kan meer API calls genereren
+3. **Netwerk:** WebSocket vereist stabiele verbinding
+4. **Browser compatibiliteit:** WebSocket en MediaStream API support
+5. **Testing:** Complexer dan REST (real-time flows)
+
+---
+
+## Conclusie
+
+De migratie vereist:
+- Architectuurwijziging van REST naar WebSocket streaming
+- Client-side SDK integratie
+- Herstructurering van `speech-recorder.tsx`
+- Aanpassing/verwijdering van server route
+- Uitgebreidere state management
+- Betere error handling
+- Security overwegingen voor API key management
+
+**De belangrijkste winst:** real-time transcriptie tijdens opname in plaats van alleen na opname, wat beter aansluit bij de live transcriptie-vereisten in de documentatie.