Skip to content
yoyopod vision

Architecture at a Glance

The three-box picture — device, backbone, parent app — and what flows between them.

Overview

Section titled “Overview”

The software has two sides and a backbone. On the device side there are two layers: yoyoOS, the Linux image (Raspberry Pi OS Lite today; later a Yocto- or Buildroot-built minimal image with only what the device needs), and yoyocore, the Rust application that runs on top and handles everything — the runtime supervisor, the domain workers, and the UI. On the parent side there is the yoyopod app, the parent mobile app for iOS and Android. Between them sits yoyocloud, the backend backbone: it speaks MQTT with the device, receives location and telemetry, and routes them to the parent app — whether we build it or adopt an open-source solution is a deliberately open decision.

Two sides and a backbone the device software, the parent app — and yoyocloud routing between them The device yoyocore the Rust device application runtime · workers · UI — it handles everything runs on yoyoOS the Linux image — RPi OS Lite today → Yocto/Buildroot later yoyocloud the backend backbone MQTT broker + routing location · telemetry · provisioning build, or adopt open-source — decision open the yoyopod app parent mobile app iOS + Android contacts · content controls · location view MQTT commands routes commands The parent app never talks to the device directly. The device publishes location and telemetry to yoyocloud over MQTT; yoyocloud routes them to the parent app — and parent commands (like remote playback) travel back down the same road.

The device stays useful on its own: the media worker plays from the local music library via mpv, the voip worker carries calls and voice notes via liblinphone, and location reporting stays live-ish by design, never real-time.

Key components

Section titled “Key components”

The naming canon — these four names are used across the docs:

Name What it is Today
yoyoOS the Linux image the device boots Raspberry Pi OS Lite; target: a Yocto/Buildroot-minimal custom image
yoyocore the Rust device application on top of yoyoOS: device/runtime/ supervising the domain workers and the UI host (device/ui/), one process tree, surfaced as four peer engines — UI, Media, VoIP, Speech real and documented in depth — see The yoyocore Runtime
yoyocloud the backend backbone: MQTT broker + routing, provisioning, telemetry the device-side MQTT link and provisioning exist (device/cloud/); the backbone itself is build-or-adopt, decision open — see Cloud & Provisioning
the yoyopod app the parent mobile app, iOS + Android future — planned apps/ (the app) and packages/ (shared contracts); see App Platform

Around the boxes sit cli/ (the Rust operator CLI, rebuilding in rounds) and deploy/ (systemd units, installer scripts, slot/release packaging).

Interfaces & contracts

Section titled “Interfaces & contracts”
  • Inside yoyocore — every message is one newline-framed JSON envelope with a strict schema stamp; mismatched peers fail closed at the first line. No sockets, no bus daemons — the process tree is the architecture.
  • Device ↔ yoyocloud — MQTT from device/cloud/ to the backbone, over the cellular modem owned by device/network/.
  • The yoyopod app ↔ yoyocloud — the parent app never talks to the device directly; everything routes through the backbone (protocol TBD, see open questions).
  • Boundary rules — device runtime code must never depend on apps/; shared contracts should flow through packages/contracts/ when that package exists (it is intended, not guaranteed present).
  • Configuration — authored config is split by ownership under config/ and composed into one typed runtime model, with an explicit secret boundary (tracked config may never contain SIP credentials) and board overlays (the only supported board is rpi-zero-2w).

Today vs. target

Section titled “Today vs. target”
  • Today: yoyocore and the device-side cloud link are real — runtime, workers, UI, MQTT transport, and provisioning all exist and are documented in depth in the as-built engineering docs (docsite/website/ in the repository).
  • Today: yoyoOS is stock Raspberry Pi OS Lite — the custom minimal image (Yocto or Buildroot) is target-state.
  • Today: the yoyopod app is future work by design — apps/ and packages/ are planned monorepo boundaries with their rules already written down; yoyocloud’s build-vs-adopt decision is open.
  • Hardware underneath: the V0 “Dawn” off-the-shelf rig — see Device Overview & Specs.
  • Target: the same picture with every box real — a minimal yoyoOS, yoyocore unchanged, a chosen yoyocloud, and the yoyopod app shipping on both stores.

Open questions

Section titled “Open questions”
  • Which protocol the yoyopod app speaks to yoyocloud (REST, MQTT, something else)?
  • Yoyocloud build-vs-adopt — which open-source backends are candidates, and what would disqualify them?
  • Yocto or Buildroot for the custom yoyoOS image — and what is the minimal package set?
  • Where does the whitelist live authoritatively — device, yoyocloud, or both?