Architecture

How Android, Desktop, Relay, and the shared libs connect, and how device sync works.

Acerola is a monorepo: each platform lives isolated, with its own stack, and none depends directly on another. They all consume the shared libraries in lib/ via a local path dependency — a change in lib/p2p/ already reflects directly in every consumer.

acerola/android

Kotlin + Jetpack Compose

acerola/desktop

Rust + Tauri + Svelte 5

acerola/relay

Remote access service (Rust) — not started yet

lib/p2p

Shared P2P library (iroh / QUIC)

lib/relay

Vendored iroh relay code

How the pieces connect

acerola/android/ and acerola/desktop/ never see each other directly — each implements its own FFI/binding to consume lib/p2p/. All communication between devices is either direct P2P (LAN via mDNS) or through a relay when devices aren’t on the same network.

flowchart LR Android["Android"] --> P2P["lib/p2p shared library"] Desktop["Desktop"] --> P2P P2P --> Relay["Relay remote access, no port forwarding"]

How sync works

Library, history, and reading progress sync directly between the user’s own devices — no account, no central database. How the connection happens depends on where the devices are and what’s been configured:

flowchart TD Start["Two devices want to sync"] --> LAN{"Same local network?"} LAN -->|Yes| MDNS["mDNS discovery free, fully local"] LAN -->|No| Relay{"Relay configured?"} Relay -->|None| NoSync["No remote sync"] Relay -->|iroh's public relay| IrohRelay["iroh's public relay NAT traversal, free"] Relay -->|User's own| UserRelay["User's own acerola-relay self-hosted, MPL-2.0"] Relay -->|Acerola-hosted| PaidRelay["Acerola-hosted relay paid tier"]

The four connectivity modes:

Local discovery (mDNS)

Default and free. Devices find each other on their own on the same Wi-Fi/LAN network — no traffic leaves the local network.

iroh's public relay

When devices aren't on the same network, iroh's public infrastructure enables the connection (NAT traversal). It only forwards end-to-end encrypted QUIC traffic — it never sees the content.

User's own relay

Anyone can run their own instance of acerola-relay (open source, MPL-2.0) on their own VPS. No third-party infrastructure is involved.

Acerola-hosted relay

A paid alternative where the relay infrastructure is operated by the Acerola team — same end-to-end encryption guarantee as the other modes.

In all four cases the handshake and transport are the same (QUIC + TLS 1.3 via iroh) — only who brokers the connection changes when devices aren’t on the same network. Details on what metadata each mode exposes live in the Privacy Policy.