How krchris/stt_chatbot works
<explanation>
1. Identify the project type and purpose
- This is a small full‑stack, real‑time web application (“stt_chatbot”) that records user audio in the browser, streams it to a Python FastAPI server, runs automatic speech recognition (via Whisper), forwards the transcribed text to ChatGPT (OpenAI API), and streams the text response back to the browser chat UI.
2. Analyze the file structure
- Top‑level files:
• server.py – FastAPI app exposing a GET for the HTML and a WebSocket endpoint for audio streaming.
• chatgpt_client.py – encapsulates OpenAI API calls.
• whisper_stt.py – handles raw audio → .wav conversion and Whisper transcription.
• chatgpt_client.py / whisper_stt.py are imported by server.py to implement the pipeline.
• requirements.txt, .gitignore, LICENSE, README.md – support/config.
- frontend/ directory holds static assets: index.html, style.css, script.js.
3. Examine the README for insights
- server.py serves static HTML (GET) and WebSocket for audio.
- script.js uses MediaDevices to record audio and send it via WebSocket.
- whisper_stt.py produces transcription for ChatGPT.
- chatgpt_client.py sends transcription to ChatGPT and returns the response.
4. Main components & interactions
a. Frontend (Browser)
- Static UI (HTML/CSS)
- Client‑side JavaScript:
• Captures microphone audio chunks via MediaDevices API
• Opens WebSocket to server.py
• Displays streaming chat messages
b. Backend (FastAPI Server)
- HTTP GET / → serves index.html & static assets
- WebSocket /ws → receives audio frames
- whisper_stt module → converts chunks → .wav → Whisper → returns text
- chatgpt_client module → sends transcribed text to OpenAI → receives reply
- Sends response text back over WebSocket
c. External Service
- OpenAI ChatGPT API (HTTPS)
5. Architectural patterns & design principles
- Two‑tier architecture: Browser ↔ WebSocket/API ↔ External AI Service
- Separation of concerns:
• UI layer (frontend)
• Transport/API layer (FastAPI)
• Business logic layer (STT + ChatGPT)
- Asynchronous streaming pipeline using WebSockets
6. Technologies & frameworks
- Frontend: HTML5, CSS3, JavaScript, WebSocket API, MediaDevices
- Backend: Python 3, FastAPI, uvicorn (ASGI server)
- STT: OpenAI Whisper (local audio processing)
- NLU: OpenAI ChatGPT HTTP API
7. Guidelines for the system design diagram
a. Layout
- Left side: Client‑side Browser (blue box)
- Middle: FastAPI Server (green box) subdivided into:
1. WebSocket Listener
2. whisper_stt Processor
3. chatgpt_client Handler
- Right side: OpenAI ChatGPT API (orange cylinder)
b. Data flows
- Use directional arrows:
1. Mic audio → WebSocket → Server
2. Server → whisper_stt → text
3. Text → chatgpt_client → OpenAI API
4. OpenAI response → chatgpt_client → WebSocket → Browser
- Also show HTTP GET flow for initial page load.
c. Color coding & shapes
- Frontend components: blue rectangles
- Backend services/modules: green rectangles (or containers)
- External API: orange cylinder
- Arrows: solid lines for real‑time flows, dashed for one‑time HTTP GET
d. Labels
- Clearly name each box (“Browser UI”, “WebSocket Endpoint”, “whisper_stt”, “ChatGPT Client”, “OpenAI API”)
- Annotate protocols next to arrows (WebSocket, HTTP GET, HTTPS)
8. Tailoring to this full‑stack project
- Emphasize separation of static content delivery vs. real‑time WebSocket streaming.
- Highlight the in‑process STT (whisper_stt) and the external NLU (ChatGPT API) as two distinct modules in the backend.
- Show the async/event‑driven nature of audio chunks and text streams.
9. Diagramming best practices
- Use swimlanes or vertical zones for Browser vs. Server vs. External.
- Keep boxes focused on single responsibilities.
- Add a legend showing color/shape conventions.
- Ensure arrows have direction heads and protocol labels.
- Include brief notes on processing steps (e.g., “Convert chunk → WAV → Transcribe”).
By following this breakdown, you’ll produce a clear, accurate architecture diagram that maps exactly to the project’s structure, data flows, and technology stack.
</explanation>