# keithtkh/qfwork architecture

> Architecture diagram of the GitHub repository keithtkh/qfwork, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keithtkh/qfwork
- Repository: https://github.com/keithtkh/qfwork

## Overview

QFwork.ai lets professionals rehearse workplace-English conversations with an AI video partner and receive a report combining transcript-based coaching, measured voice metrics, and camera-presence observations. The main path is access check, scenario selection, live session and parallel microphone recording, then session analysis and report delivery. The README documents four scenario rubrics, trial tiers, and optional analysis layers. Some server routes and frontend pages are only partially sampled; those links follow the documented architecture where noted.

Main entry points: [`server.js`](https://github.com/keithtkh/qfwork/blob/main/server.js) (API server), [`public/exam.html`](https://github.com/keithtkh/qfwork/blob/main/public/exam.html) (Live practice), [`public`](https://github.com/keithtkh/qfwork/tree/main/public) (Practice website), [`public/pcm-worklet.js`](https://github.com/keithtkh/qfwork/blob/main/public/pcm-worklet.js) (Microphone capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Practice experience"]
  node_web["Practice website"]
  node_exam["Live practice<br/>[exam.html]"]
  node_audio["Microphone capture<br/>[pcm-worklet.js]"]
  node_booking["Booking pages<br/>[book.html]"]
end

subgraph group_access["Access and trials"]
  node_gate["Browser access gate<br/>[access-gate.js]"]
  node_accesslogic["Trial access control<br/>[access.js]"]
  node_codeissue["Trial code issuance<br/>[server.js]"]
end

subgraph group_session["Session services"]
  node_server["API server<br/>[server.js]"]
  node_voicebuffer[("Temporary audio buffer<br/>[server.js]")]
  node_tavusadapter["Video session adapter<br/>[tavus.js]"]
end

subgraph group_coaching["Coaching analysis"]
  node_voiceanalysis["Voice metrics<br/>[voice-metrics.js]"]
  node_feedback["Coaching report engine<br/>[feedback.js]"]
  node_report["Structured report"]
end

node_professional(("Professional"))
node_tavus["Tavus video service"]
node_whisper["Groq speech recognition"]
node_groqllm["Groq language model"]

node_professional -->|"visits"| node_web
node_web -->|"loads"| node_gate
node_professional -->|"chooses scenario"| node_exam
node_gate -->|"redeems and verifies"| node_server
node_server -->|"checks session"| node_accesslogic
node_server -->|"issues code"| node_codeissue
node_professional -->|"books"| node_booking
node_exam -->|"starts session"| node_server
node_server -->|"creates and polls"| node_tavusadapter
node_tavusadapter -->|"requests session data"| node_tavus
node_tavus -->|"streams video conversation"| node_exam
node_exam -->|"captures microphone"| node_audio
node_audio -->|"sends audio blocks"| node_exam
node_exam -->|"uploads recording"| node_server
node_server -->|"holds audio temporarily"| node_voicebuffer
node_server -->|"analyzes recording"| node_voiceanalysis
node_voiceanalysis -->|"requests word timings"| node_whisper
node_server -->|"supplies transcript and metrics"| node_feedback
node_feedback -->|"generates report"| node_groqllm
node_server -->|"returns result"| node_report
node_report -->|"displays coaching"| node_exam
node_server -->|"limits report by tier"| node_accesslogic

click node_web "https://github.com/keithtkh/qfwork/tree/main/public"
click node_exam "https://github.com/keithtkh/qfwork/blob/main/public/exam.html"
click node_audio "https://github.com/keithtkh/qfwork/blob/main/public/pcm-worklet.js"
click node_booking "https://github.com/keithtkh/qfwork/blob/main/public/book.html"
click node_gate "https://github.com/keithtkh/qfwork/blob/main/public/access-gate.js"
click node_server "https://github.com/keithtkh/qfwork/blob/main/server.js"
click node_accesslogic "https://github.com/keithtkh/qfwork/blob/main/access.js"
click node_voicebuffer "https://github.com/keithtkh/qfwork/blob/main/server.js"
click node_tavusadapter "https://github.com/keithtkh/qfwork/blob/main/tavus.js"
click node_voiceanalysis "https://github.com/keithtkh/qfwork/blob/main/voice-metrics.js"
click node_feedback "https://github.com/keithtkh/qfwork/blob/main/feedback.js"
click node_codeissue "https://github.com/keithtkh/qfwork/blob/main/server.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_exam,node_audio,node_booking toneBlue
class node_gate,node_accesslogic,node_codeissue toneAmber
class node_server,node_voicebuffer,node_tavusadapter toneMint
class node_voiceanalysis,node_feedback,node_report toneRose
class node_professional,node_tavus,node_whisper,node_groqllm toneIndigo
```

## Components

### Practice experience

- [Practice website](https://github.com/keithtkh/qfwork/tree/main/public): `public`
- [Live practice](https://github.com/keithtkh/qfwork/blob/main/public/exam.html): `public/exam.html`
- [Microphone capture](https://github.com/keithtkh/qfwork/blob/main/public/pcm-worklet.js): `public/pcm-worklet.js`
- [Booking pages](https://github.com/keithtkh/qfwork/blob/main/public/book.html): `public/book.html`

### Access and trials

- [Browser access gate](https://github.com/keithtkh/qfwork/blob/main/public/access-gate.js): `public/access-gate.js`
- [Trial access control](https://github.com/keithtkh/qfwork/blob/main/access.js): `access.js`
- [Trial code issuance](https://github.com/keithtkh/qfwork/blob/main/server.js): `server.js`

### Session services

- [API server](https://github.com/keithtkh/qfwork/blob/main/server.js): `server.js`
- [Temporary audio buffer](https://github.com/keithtkh/qfwork/blob/main/server.js): `server.js`
- [Video session adapter](https://github.com/keithtkh/qfwork/blob/main/tavus.js): `tavus.js`

### Coaching analysis

- [Voice metrics](https://github.com/keithtkh/qfwork/blob/main/voice-metrics.js): `voice-metrics.js`
- [Coaching report engine](https://github.com/keithtkh/qfwork/blob/main/feedback.js): `feedback.js`
- **Structured report**

### Other components

- **Professional**
- **Tavus video service**
- **Groq speech recognition**
- **Groq language model**

## Connections

- Professional → Practice website: visits
- Practice website → Browser access gate: loads
- Professional → Live practice: chooses scenario
- Browser access gate → API server: redeems and verifies
- API server → Trial access control: checks session
- API server → Trial code issuance: issues code
- Professional → Booking pages: books
- Live practice → API server: starts session
- API server → Video session adapter: creates and polls
- Video session adapter → Tavus video service: requests session data
- Tavus video service → Live practice: streams video conversation
- Live practice → Microphone capture: captures microphone
- Microphone capture → Live practice: sends audio blocks
- Live practice → API server: uploads recording
- API server → Temporary audio buffer: holds audio temporarily
- API server → Voice metrics: analyzes recording
- Voice metrics → Groq speech recognition: requests word timings
- API server → Coaching report engine: supplies transcript and metrics
- Coaching report engine → Groq language model: generates report
- API server → Structured report: returns result
- Structured report → Live practice: displays coaching
- API server → Trial access control: limits report by tier