tri-pi/docs/ARCHITECTURE.md

tri-pi Architecture

Goal

Turn a Raspberry Pi into a headless Triangles node appliance with:

• Tor hidden service exposure
• safe defaults for staking
• a local status surface
• reproducible build and test workflows

High-Level Layout

+---------------- Raspberry Pi ----------------+
|                                              |
|  trianglesd <--> Tor <--> onion service      |
|      ^                                       |
|      | RPC                                   |
|      v                                       |
|   tri-pi backend <--> tri-pi frontend        |
|      ^                                       |
|      | systemd / file state                  |
|      v                                       |
| config, logs, backups, health checks         |
+----------------------------------------------+

Why This Mirrors velxio

The inspiration from velxio is structural rather than product-level:

• keep runtime orchestration separate from the core executable
• use a dedicated backend/frontend split
• make local development reproducible
• reserve QEMU for realistic target validation

tri-pi does not need a browser IDE, device simulator, or circuit canvas.

Main Components

Backend

The backend is the control plane for the appliance. It should:

• read node state from trianglesd RPC
• read service state from systemctl
• surface onion address and health checks
• serve a small local HTTP API

Frontend

The frontend is a local dashboard, not a wallet. It should show:

• sync height
• peer count
• staking state
• Tor hidden service address
• service health and recent errors

Setup

Provisioning scripts install:

• OS dependencies
• Tor
• config templates
• systemd units
• backend/frontend runtime files

Build

Build scripts support:

• local development against ../triangles
• ARM cross-builds
• QEMU smoke tests against Raspberry Pi OS images

Boundaries

tri-pi should not:

• carry protocol logic
• fork trianglesd behavior
• become a general wallet UI

It should remain an appliance layer around a separate daemon.