SpeakLink - centralized store announcements and live broadcasting

Loading project

A live announcement system for a retail chain: an announcement spoken or picked at head office reaches the speakers in every store, and a browser link for anyone else who needs to hear it. Built for Rajmandir Hypermarket, then made public and extended with web listeners and chat. FastAPI, React, and a packaged Windows receiver agent per store.

SpeakLink carries announcements from one head office browser to the shops. Someone at HQ speaks into a microphone, or picks a recorded announcement, chooses which stores should hear it, and the audio arrives on the amplifiers in those shops. The same broadcast also opens a listener link, so people who are not standing in a store can hear it in a browser, and a chat panel beside the console lets them write back.

Three programs, on three different machines.

HQ is a FastAPI application that serves the API, the WebSocket endpoints and the built React dashboard from one Uvicorn worker on one origin. One worker is not a default left alone: receiver connections and live broadcast state are held in process memory, and the login rate limiter is per process, so a second worker would give each its own limiter and multiply the allowance.

Each store runs a Windows receiver agent, packaged as an executable with FFmpeg inside it, so the shop computer needs no Python, no Node and no copy of the repository. It starts from a Windows Scheduled Task at user logon, deliberately and not as a service: it plays audio into a user session, and Windows session 0 has no audio device.

What I built

A FastAPI server at head office, a React dashboard, and a packaged Windows agent on each store PC holding an authenticated WebSocket open. HQ pushes audio down that socket; the agent plays it through FFmpeg into the Windows audio device the amplifier is on.

Decisions worth knowing about:

One origin, one worker. The API, the WebSockets and the built React app are served together, so production has no CORS to configure and the same build works by IP, by hostname or through a cloud name. One worker because live broadcast state and receiver connections live in process memory.

The store kit is one executable. Build-SpeakLinkReceiver.ps1 produces a package with FFmpeg inside it, then build_store_installer.py wraps it into a single installer that asks the operator for HQ's address and an enrolment code. The store computer never sees Python, Node or this repository. Every version string is read from tools/speaklink_version.py, because typing it in more than one place is how a build shipped code that disagreed with its own number.

Enrolment is a one-time code, redeemed exactly once - covered by a threaded test where several racing redemptions produce exactly one winner.

Archive, never delete. Users and stores are the authors and subjects of broadcast history, so removing a row would falsify the record. Restoring an archived account returns it to disabled, never straight to active.

Fail closed at startup. ADMIN_USERNAME and ADMIN_PASSWORD create the first administrator only, on an empty database, and are ignored forever after. If they are missing when a database has to be created, startup refuses - there is no default login anywhere in this product. In production APP_ENV=production makes DATABASE_URL mandatory, and the server would rather not start than fall back to a local SQLite file that looks like it works while quietly diverging from the real database.

Dependencies were derived, not frozen. requirements.txt is built from the import statements of backend/, tools/ and scripts/, and split three ways - server, store receiver, test machine - because a till needs no web framework and a server needs no Windows Core Audio bindings.

Later, after the code was made public, the product grew the parts that are not about shops at all: a public listener link so a broadcast can be heard in any browser, and a chat panel next to the console so those listeners can answer back.

What I learned

The expensive ones, with the numbers.

A fresh install had no super administrator, and said nothing about it. The role migration ran before seed_admin, so on an empty database it looked for an account to promote, found none, and the seeded account kept the legacy role 'admin'. Every require_super_admin endpoint then answered 403 to everybody, silently - the system was installed, reachable, and had nobody able to administer it. Both migrations now run again after seeding.

A production bundle told every browser to call its own loopback. Create React App inlines REACT_APP_* at build time, and RC4 shipped with REACT_APP_BACKEND_URL=http://127.0.0.1:8000 baked in. HQ was healthy on 192.168.4.134:8000, the dashboard loaded perfectly, and signing in was impossible on every machine except the server itself. The fix was to derive the backend from window.location - the address the browser had already used to fetch the page.

That fix is still only half done, and I walked into it again taking screenshots for this entry. The bundle takes the hostname from window.location but the PORT from REACT_APP_BACKEND_PORT || "8000". Serving the whole app on port 8077 gave a page that loaded, a login stuck on "Signing in...", and one console line: 127.0.0.1:8000 ERR_CONNECTION_REFUSED.

requirements.txt was a pip freeze, and pip freeze writes down the room rather than the decisions. It carried 140 pins including openai, stripe, pandas, motor, boto3 and huggingface_hub - not one of them imported anywhere in the codebase. They cost nothing on the machine where they were already installed, which is exactly why they survived so long. They stop being free on a 512 MB free-tier host with a build timeout.

psycopg-binary 3.2.3 publishes no wheel for Python 3.13 or 3.14. "Python 3.12" is therefore a hard requirement rather than a preference, and a deployment image that inherits whatever Python the host defaults to fails to install at all.

Plain uvicorn speaks no WebSocket. Leave the websockets package out and the console starts, the pages load, and no shop ever connects.

A secret sat in a gitignored archive and no scan saw it. Every check walked git ls-files, and the file was not in it. The test that catches this now walks the disk instead.

A version typed in three places became three versions. The wizard, the kit package and the installer filename each carried a hand-typed number, and a 1.7.7 receiver shipped inside an installer calling itself 1.7.6. One module owns that string now.

Deep paths break the receiver in a way that looks like something else entirely. Extract the kit somewhere long on a store PC, cross the Windows 260-character path limit, and the symptom is a DLL failing to load.

And a small one that cost an afternoon: which database a local run uses depends on how it was started. The launcher sets SPEAKLINK_DB_PATH to data/speaklink.db; running uvicorn directly lands on backend/speaklink_live.db. Both files are real, and it is easy to spend a while looking at the empty one.

SpeakLink - centralized store announcements and live broadcasting

The problem

What I built

Built with

What I learned

Gallery