Knock System Architecture & Telephony Engine
Deep technical blueprint mapping Knock's Hybrid Dual-Route calling engine (WebRTC vs Switch Telecom GSM), 16kbps Opus zero-rated audio codecs, Bi-Directional Voice Activity Detection (Bi-VAD), and automated escrow settlement.
Normalizes raw input (082 123 4567, +2782...) into standard E.164. Detects network carrier based on prefix matching for Vodacom, MTN, Cell C, and Telkom.
// Returns: { cleanLocal, cleanIntl, carrier: 'VODACOM' }
If destination is registered and online (active1to1Rooms.has(target)), resolves to Route C. Direct P2P audio/video with zero carrier bill and unlimited talk minutes.
costZar: 0.00, // 100% Free R0.00
action: 'INITIATE_P2P_WEBRTC'
If recipient is offline or has no app, routes over Switch Telecom wholesale SIP trunk (sip.switchtel.co.za) to ring their cellular phone. Hard-capped at 120 seconds.
maxDurationSeconds: 120,
action: 'INITIATE_WHOLESALE_SIP'
Subsequent dials to an offline number that has already used its courtesy call hit OPTION_B_LOCKED. Prompts a viral 1-tap WhatsApp invite link to onboard the contact.
action: 'PROMPT_APP_INVITE',
whatsappShareUrl: 'https://api.whatsapp.com/...'
Users make additional cellular calls using their earned GSM Minutes Bank. Funded by retail sponsor vouchers (+5m), daily wheel spins (+3 to 15m), and Capitec bank passes (+30m).
wallet.earnedMinutes += 5; // per completed call
claimReward(handle, 'rew_nandos_01');
After an Option B call ends, an automated SMS invite is fired via SMSPortal. A strict 30-day deduplication filter ensures numbers are never messaged twice, saving R0.24 per repeat call.
return { sent: false, savedZar: 0.24 };
}
| Scenario | Recipient State | Resolved Route | Carrier / Protocol | Max Duration | Platform Cost | User Action / Conversion |
|---|---|---|---|---|---|---|
| Registered Host Online | Active WSS Socket | OPTION_C | P2P HD WebRTC (Opus 16kbps) | Unlimited | R0.00 | Direct zero-cost voice/video call |
| First-Time Offline Number | Offline / Not on App | OPTION_B | Switch Telecom SIP ➔ GSM Cellular | 120s (2 min cap) | ~R0.18/min (Sponsor funded) | Courtesy call + Automated viral SMS invite |
| Repeat Call (No Banked Mins) | Offline / Courtesy Used | OPTION_B_LOCKED | Blocked (403 Forbidden) | N/A | R0.00 | WhatsApp invite prompt + Spin Lucky Wheel |
| Repeat Call (With Banked Mins) | Offline / Has Minutes | DIRECT_GSM | Switch Telecom SIP ➔ GSM Cellular | Exact Bank Balance | Deducted from user bank | Free cellular call using earned minutes |
| Peak Trunk Traffic (4 Lines Busy) | Offline / Lines Full | OPTION_B_BUSY | Capacity Limit (503) | N/A | R0.00 | "Lines busy" modal + WhatsApp skip queue |
Single-use calling links (knock.at/profile). Guests tap once to call via mobile browser. No cell phone numbers are revealed to either party.
Gated by PayShap / Capitec Pay / Card. Locks call action until consultation fee clears into escrow. Protected by the 2-Minute Grace Cancellation window.
Multi-peer audio rooms (/room/:id). Anonymous retro avatars with real-time glowing green speaking rings and floating haptic reaction emojis.
Renders camera stream to HTML5 Canvas in real-time. Injects verified badge and promo watermark into video frames before saving to disk.
Web Audio AnalyserNode tracks host vs guest speech volume in real time. If host stays silent for 60s, triggers a 30s auto-refund warning.
Real-time text chat over encrypted RTCDataChannel. The moment either party hangs up, the chat array is wiped from memory with zero trace.
Knock operates as an Event-Driven Modular Monolith. High-level feature sets never invoke each other directly; they subscribe to asynchronous events emitted by the core WebRTC engine on the EventBus.
│ KNOCK CLIENT LAYER │
│ • Host Dashboard PWA • Guest Web Caller • Anonymous Group Mesh │
└───────────────────────────────────┬────────────────────────────────────┘
│
┌─────────────────────┴─────────────────────┐
▼ (HTTPS REST / 3001) ▼ (WSS WebSockets)
┌──────────────────────────────┐ ┌──────────────────────────────┐
│ EXPRESS REST API │ │ WSS SIGNALING MESH ENGINE │
│ • Payment & Escrow Checkout │ │ • SDP / ICE Candidate Relay │
│ • Link & Availability Store │ │ • Room State & Host Register │
│ • Telemetry Audit Engine │ │ • VAPID Push Wakeup Dispatch │
└──────────────┬───────────────┘ └──────────────┬───────────────┘
│ │
▼ ▼
┌──────────────────────────────┐ ┌──────────────────────────────┐
│ SUPABASE POSTGRESQL POOLER │ │ COTURN NAT RELAY (3478) │
│ • hosts, links, transactions │ │ • STUN / TURN UDP & TCP │
│ • contacted_recipients (SMS) │ │ • Cellular CGNAT Traversal │
└──────────────────────────────┘ └──────────────────────────────┘
If a client feels unsatisfied or called by mistake, they can tap [ End & 100% Refund ] within 120 seconds. The escrow hold releases funds back to the client immediately with zero creator fee.
Calls terminating under 30 seconds trigger AUTO_REFUNDED_CALL_TOO_SHORT. Prevents bad cellular connections from eating user funds.
If call duration is ≥ 60s but the host's Web Audio decibel energy account for less than 8% of the time, the escrow is paused with FLAGGED_ABSENTEE_HOST for dispute audit.
Funds clear instantly into Host Wallet. The server mints an immutable cryptographic token: knk_proof_... stored in the PostgreSQL ledger.