IELTS: Code Structure

Fri, 30 Oct 2026 00:00:00 +0000

IELTS is a tool I built for practising IELTS speaking and writing, and it recently gained a mock-interview mode. The code is on GitHub; the newest branch is desktop-realtime-voice. This post takes the current code as the baseline and walks through three questions: who does the work and when, what the data looks like and where it lives, and why it is split this way. Section 5 lists the current problems; how they came about is in the retrospective.

IELTS: Retrospective

Fri, 30 Oct 2026 00:00:00 +0000

This is the retrospective for IELTS. What the code looks like now and what is wrong with it is listed in section 5 of the structure post; this post is about how those problems came about and what I would do next time. The conclusions first:

Reuse the threading model, not just the classes. The IELTS command-line version reused RealtimeClient and the audio classes but not the microphone and playback threads or the state machine, so the examiner’s audio is sent and never played.
Get one simple end-to-end path working before polishing a layer. native_voice, written in early October, has a clean device layer and no network, recognition or synthesis, so it could not go into the product. At the end of October the approach changed: fix the old prototype’s connection layer first, then write a layer on top that only “reads one thing and listens to one thing”. It was in the desktop shell the next day.
Every shortcut has a cost; write it down. Half duplex keeps echo out at the cost of interruptions; using the dialogue model as a reader saved a speech-synthesis integration at the cost of having no way to check it reads verbatim. The new engine uses Volcengine’s given-text interfaces, which settles the second one.
A parameter in an API document counts only once it has been measured. The end-of-speech window needs a separate switch to take effect, and a required field was never sent by the old code; both turned up only by checking the document field by field and then measuring.
Three from the website: the slow part was the call path, not the logic; get evidence before fixing a bug; only one place may decide that something has failed.

1. Seven months, four shapes

When	Shape	What happened
March	C++/Qt desktop prototype	Job-interview simulator: read a CV PDF, LLM-generated questions, Volcengine’s real-time dialogue service for the conversation; finished with a pass of cppcheck and ASan
Early May	C++ command line	Became the three parts of IELTS speaking, with scoring through Codex, the OpenAI API or Claude
Mid May	Single-file Python site	Recording in the browser, reports, a wallet; scoring calibration and an unattended long-run audit
Mid to late May	Django	Moved to Django and retired the old server; streamed HTTP follow-ups, WASM audio preprocessing, live recognition
June to September	Features and wrap-up	Corpus, Takeaway, spaced spelling review, public-network speed-ups, onboarding, P3 bank progress, deployment docs
October	Qt desktop shell	QtWebEngine around the web app; interview mode and an AI assistant; the new `native_voice` device layer; an audit of the old C++ voice code
Late October to early November	Real-time voice in the shell	One I/O thread owns the connection; a new content-free `VoiceSession`; the interview’s pressure mode becomes real-time voice, and the other practice pages use it for captions

By month: 13 commits in March, 406 in May, 143 in June, 25 across July to September, 156 in October and 1 in November up to the 1st. From May on, most code came from the same loop: I wrote a spec, Codex or Claude Code implemented it, and I accepted it or not.

Projects on Jasper

IELTS: Code Structure

IELTS: Retrospective

1. Seven months, four shapes