Kiosk Technical Documentation

Engineering reference for the Family Pocket kiosk system.

Release Workflow

Step-by-step guide for shipping a new kiosk APK to the fleet. Covers version bump, CI, phased rollout.

Provisioning Guide

How to set up a new Telpo T10 kiosk device: NFC provisioning, school resolution, device registration.

OTA Update System

Architecture deep dive: rollout gating, resumable downloads, SHA-256 verification, safe install windows.

Device Unlock

How to unlock a locked kiosk for maintenance: NFC cards, PIN fallback, anti-brute-force.

Fleet Monitoring

Health checks, telemetry events, heartbeats, and alerting for 10,000+ devices.

Storage Migration

Playbook for migrating APK storage from GitHub Releases to Cloudflare R2 with zero device impact.

Service Map

Kiosk Device  -->  cdn.familypocket.io  -->  authentication (SAAS DB)
                                         -->  api.familypocket.io (Tenant DBs)
                                         -->  GitHub Releases (APK storage)

Key Constants

Constant	Value	Why
Update check interval	4 hours	Balance between freshness and battery
Safe install window	22:00 - 03:00	Trips start at 04:00
Telemetry flush	60 seconds	Near-real-time without hammering server
Heartbeat interval	15 minutes	Fleet-level visibility
Rollout day 0	5%	Catch issues before full fleet impact
Lockout threshold	5 fails / 10min	Anti-brute-force on unlock
Lockout duration	30 minutes	Cool-down period

Quick Links

CDN Health/api/health
GitHub Releasesgithub.com/.../releases