SkyTalk.Website

Three processes that have to move as one

SkyTalk isn't just "an app for practicing phraseology." It's a distributed system in which three parallel processes have to move in lockstep, without losing the pace of live interaction:

• Live voice — direct peer-to-peer audio between tutor and student, with a simulated radio channel.
• A strict lesson state machine — steps, data input (frequency, squawk code, heading, altitude), server-side validation, transitions driven by user actions.
• A reactive instrument panel (PFD) — artificial horizon, speed, altitude, compass — that comes alive as the lesson progresses.

The real engineering difficulty isn't hiding the correct answer — the student is learning, not sitting an exam. It's making all of these components behave as a single organism despite network instability, asynchronous browser APIs, and the need for strict event ordering.

The central architectural question: how do you reconcile two unsynchronized real-time channels, guarantee lesson-state consistency across every participant, and drive instrument animation at the same time — without creating races, desyncs, or data loss?

This page shows how we answered that, and which engineering decisions shaped the system's final shape.

What it must do — and under what conditions

FR	Tutor uploads a lesson file (flight.json) and creates a room; the server validates it against the JSON Schema and returns structured errors. Student joins via a one-time link, no registration — the tutor enters their own room the same way, but only after presenting the shared password used to create it. A direct voice channel between them: the student can only speak while holding push-to-talk. Where the scenario requires it, the student enters exact values (frequency, squawk, heading, altitude) into structured fields, validated against the specification's regexes. Advancing to the next step happens only once the tutor's client confirms it — or through verbal coordination, which the system doesn't force. The cockpit instrument display (PFD) visualizes flight parameters — squawk, COM, altitude, heading, artificial horizon, speed — with state arriving from the server as part of the lesson scenario.
NFR	A dropped WebSocket connection must restore lesson state without losing the step, input index, or attempt count. The two real-time channels — application state and WebRTC signaling — must coordinate correctly despite asynchronous microphone access and peer registration. Browser audio-context restrictions (autoplay policy) must not block the radio-degradation effects. The correct value for any step lives only on the server and never reaches the student's browser — as a natural consequence of an architecture with server-side validation, not as a separate "security feature."
Constraints	Lesson authoring happens outside the system; SkyTalk consumes finished files capped at 256 KB. The formal specification is locked before implementation: normative Annexes outrank the design document, which outranks operational guidance.

Two independent channels, one orchestrator

The pnpm monorepo has three packages. @skytalk/core is pure, I/O-free code holding lesson types, validation regexes, the room state machine, and a role-based state-projection function, viewStepForRole. Both server and web depend on it; it depends on nothing. That function decides what each side sees at any given moment — not for the sake of "secrecy," but for a clean separation of responsibilities.

At runtime the system holds two separate real-time channels:

• The application WebSocket (/ws/rooms/:id) — the single source of truth for the lesson's progress. It carries state snapshots, input results, step transitions, PTT signals, and readiness coordination for the voice call. The server owns the state machine.
• PeerJS signaling + WebRTC — the direct audio channel between browsers. Signaling runs through its own PeerServer on the same host (/peerjs). STUN lives there too, on port 3478. No external service — everything stays on one machine.

These two channels are coordinated by one narrow bridge: a peer_ready message, sent over the WebSocket by whichever client has both gotten microphone access and finished peer registration. The server relays it to the other side, which triggers the call. No protocol mixing — audio goes directly, and all coordination goes through the server.

Only the tutor's outgoing voice passes through the Web Audio chain — the radio-degradation filters — before being sent to the peer. The return channel from the student isn't processed, so the tutor hears exact speech for grading.

Access and room management

The tutor's shared password is needed only to create a room (/api/rooms). Once created, both sides receive unique tokens embedded in their URL: /tutor/{room}?token=… and /student/{room}?token=…. The WebSocket connection authenticates with this token at handshake. One role, one active connection per room — a new connection evicts the old one. A 30-second heartbeat check reclaims any slot that's gone quiet for a minute. Every state change — a transition, an input, a completion — is written to SQLite first, then broadcast to clients. Under any failure, stored state never lags behind what users have already seen.

The state machine and its triggers

The heart of the lesson is the finite state machine in @skytalk/core. It defines the states LISTENING, INPUT_REQUIRED, INPUT_NOT_REQUIRED, READY_TO_ADVANCE, with transitions driven by messages:

• start_lesson → LISTENING
• ptt (by tutor, pressed: false) → INPUT_REQUIRED or INPUT_NOT_REQUIRED, depending on whether the step defines required inputs
• submit_input (student only) → validated, a result returned; once attempts are exhausted or the input is correct → INPUT_NOT_REQUIRED
• skip_step, repeat_step, end_lesson — only from the tutor

Important: the tutor releasing PTT is the one domain event "grounded" in an observable signal. The specification described it as "the tutor finished speaking" without specifying how to determine that. Reusing an already-existing voice-channel gesture gave a precise trigger without any extra machinery. Other transitions, where the specification deliberately left verbal coordination in place — the final step transition — remain unenforced by software.

The instrument panel as a state consumer

The student's PFD isn't just decoration. It subscribes to the lesson's current step and extracts parameters from it: COM frequency, squawk code, assigned heading, altitude, speed, artificial-horizon angles. This data arrives as part of state_snapshot or step_changed and is reflected immediately on the animated instruments. Because step state is part of the model the server broadcasts to everyone, the PFD is always in sync with the scenario, with no separate control channel required. This reflects a deliberate framing: not "lesson control plus a picture," but a single reactive view over shared state.

Five decisions that shaped the system

Each names what the decision cost — a trade-off you don't acknowledge is a trade-off you didn't see.

Role-based views, not a hidden answer

A room's SQLite row holds: the validated lesson, tutor and student tokens, an expiry time, the current step, input index, attempt and reset counters, and the machine's state. @skytalk/core operates on this row as pure logic.

The session_events table logs every meaningful transition — state change, step change, input, completion — tagged with the initiating role and a full JSON payload. Frequent, low-information events (PTT toggles and repeat signals) are excluded, so the log doesn't get bloated.

Splitting visibility by role isn't about "hiding the answer" — it's about each role seeing its own interface. The tutor gets the full step, including the expected readback and value, and also sees exactly what the student typed. The student sees only their own input and the result — correct or incorrect — not the reference value. This projection is implemented by a single function, viewStepForRole, which rules out permission checks scattered across the codebase.

The microphone-vs-signaling-readiness race

Scenario: the student enters the room, and the browser asynchronously requests getUserMedia (microphone) and registers an identifier with PeerJS. Neither action waits for the other. An early version sent peer_ready immediately after peer registration, before the microphone had been granted. As a result, the tutor's call arrived at a peer with no media stream, and ICE negotiation failed. The failure showed up simply as "the call won't connect," with no visible cause.

Fix: peer_ready is sent only once both flags are up — peerReady && micReady. A simple but critical gate, without which the system was unusable on slow devices or whenever microphone permission was delayed. The fix deserves an explicit code comment so a future refactor doesn't remove it by accident.

Automatic retry of the first call

Even with correct synchronization, the first call attempt can still fail from network jitter or signaling delay. The system retries automatically — up to three attempts with a short interval — before surfacing an error. Otherwise any transient instability would look like the system had failed outright.

Reconnecting without losing progress

When the WebSocket drops, the client reconnects and receives a state_snapshot with the current step, input index, and attempt count. This guarantees an accidental disconnect never turns into having to restart the lesson. It's implemented by keeping all state on the server and sending a fresh snapshot at every new handshake.

The architecture checked against its own claims

• The input validator accepts and rejects values strictly per the normative table (Annex C): frequencies, codes, flight levels.
• Invalid JSON on the WebSocket is ignored without dropping the connection; unrecognized messages return a validation_failed error carrying the original sequence ID.
• The role gate blocks commands from the wrong side: the student can't start, skip, or end the lesson; the tutor can't submit input.
• A student's PTT release doesn't trigger a transition out of LISTENING; the tutor's does — exactly per specification.
• On a WebSocket drop and reconnect, state is restored exactly.
• The database write always happens before the client receives the corresponding event.

If we built it again

• Add a TURN relay from the start, to avoid potential NAT problems on difficult networks.
• Replace the tutor's shared password with individual credentials, as soon as the number of tutors stops being "a small trusted circle."
• Turn the peer_ready gate into a regression test with simulated microphone delay, to prevent the fix from being accidentally rolled back.
• Document the required_inputs (array) divergence from the idealized JSON Schema (single input) more explicitly in the specification itself, not just in code comments.