Listam is a React Native shopping list app where the visible UI is deliberately thin. The durable list state lives in a Bare worklet that runs inside the app process, writes to Corestore/Autobase, and synchronizes peers over Hyperswarm. The same backend is planned to power desktop and headless surfaces.
The README frames the database as the source of truth and networking as opportunistic. That design appears in the code: UI actions optimistically change React state, then send RPC commands to the backend for canonical log append and replication.
README.md
The mobile app starts a packed Bare bundle using react-native-bare-kit.
That bundle creates its own RPC server, Corestore, Autobase, Hyperswarm, and blind
pairing state.
Header, list/grid views, join dialogs, loyalty cards, paywall
app/index.tsx
Owns mutable list state, writer membership, networking, persistence
backend/backend.mjs
Local Hypercore storage under app documents
Encrypted append log plus materialized JSON view
DHT discovery and peer replication
Invite-based writer onboarding
Frontend files never open Corestore directly. They read/write through numeric RPC commands defined in rpc-commands.mjs.
React Native stays focused on interaction and rendering, while the Bare runtime can run Node-like P2P libraries that are a poor fit for normal RN components.
The RPC command numbers are a shared ABI, short for Application Binary Interface: the
low-level contract that lets separately built pieces of software call each other
correctly. In Listam, that contract is the fixed numeric vocabulary both runtimes use
to understand each other over bare-rpc. The symbolic names in
rpc-commands.mjs make the code readable, but the
value that crosses the React Native/Bare boundary is the number itself. If
RPC_ADD stopped meaning 2 in one bundle while the other side
still dispatches command 2 as "add item," the frontend and backend would no
longer agree on what request was sent. Treat existing numbers as stable, append new
commands with new values, and rebuild/update both sides together when the table changes.
ListEntry{
text: string
isDone: boolean
timeOfCompletion: EpochTimeStamp
}
This is the public frontend item type. The backend appends richer items with
id, listId, updatedAt, and
timestamp, but the UI only relies on these three fields.
{ type: "add", value: item }
{ type: "update", value: item }
{ type: "delete", value: item }
{ type: "add-writer", key: hex }
Operations are appended to Autobase, then the apply function materializes
them into a JSON view and notifies the frontend.
{
id: hex,
invite: hex,
publicKey: hex,
expires: number
}
Blind pairing invites are encoded with z32 for sharing. A runtime invite
is reused up to ten times before rotation.
text, not id. Add/update/delete logic
filters and maps by text, so duplicate grocery names collapse into one item. This is simple
and human-friendly, but it makes quantities or duplicate stores hard to model later.
Corestore is a storage manager for Hypercore feeds. In this project it is the durable home for the local writer core, the Autobase system cores, the materialized view, and any peer cores that are opened by key.
The app needs offline-first data that survives restarts. Corestore gives Autobase a single local storage root under the app document directory, so the backend can rebuild the list from persisted operations without a server.
initAutobase creates new Corestore(`${storagePath}-local`).baseDir from Expo FileSystem and derives storagePath from it.store.get({ key: peerKey }).Autobase is the multi-writer append log. Devices do not call a central API to change the list. They append operations to their local writer, replicate those operations, and let Autobase produce a deterministic view.
A shopping list is a good fit for an operation log: add item, update item, delete item, add writer. That log can be replayed after a restart and merged with peer logs when the network becomes available.
valueEncoding: 'json', encrypt: true, and the saved or paired encryption key.open function returns a JSON view named test.apply function reduces add, update, delete, and add-writer operations.autobase.writable is true.Hyperswarm is the peer discovery and connection layer. It finds other devices that are interested in the same discovery topic, then gives the backend live connections that can be handed to Autobase replication.
The project goal is no central sync server. Hyperswarm lets devices discover each other by topic and replicate directly when both sides are online.
autobase.discoveryKey, not the raw base key.autobase.replicate(conn).server and client modes are enabled for the topic.BlindPairing is the controlled first-contact mechanism. A new device starts with only an invite code. The host uses that invite to decide whether to reveal the base key, encryption key, and writer permission path.
A collaborator cannot replicate a private encrypted Autobase without the right base and encryption credentials, and the host must add the collaborator as a writer. BlindPairing provides that join handshake without a Listam-owned server.
BlindPairing.createInvite(autobase.key) and shares it as z32 text.userData.{ type: 'add-writer', key: writerKeyHex } when writable.autobase.key and autobase.encryptionKey.{document}/lista-local.add-writer, making the guest writable after replication.During joining, the temporary Hyperswarm connection is intentionally kept alive after blind pairing. The code comments explain that closing it would kill the live Noise connection that can immediately bootstrap replication while the main DHT swarm is still finding peers.
When the guest joins a host base, initAutobase clears local-core user data
like autobase/encryption and autobase/boot if the stored
referrer does not match the new base key. That prevents the guest from accidentally
using an old encryption key for a new base.
The guest may receive credentials before it is actually writable. The backend polls
autobase.update() for up to 120 seconds, syncs any replicated items along
the way, and only declares join success once write access or peer connection criteria are met.
The view stores entries with op fields and reconstructs the current list
with a Map keyed by item text. This keeps rebuild logic small, but it also
means duplicate item names collapse into one logical item.
encrypt: true.remove-writer, so a peer cannot be removed once joined.add-writer in apply; there is no owner-only membership authority.listam.ch/join?invite=) auto-join with no confirmation and tear down the current base.expires) is stored but never enforced; lista-invite.json is persisted but never read back.add-writer to an owner key, signature-verified in apply.lista-invite.json persistence.no-console lint rule, a CI secret-grep gate, and automated redaction tests.react-native-svg and qrcode-terminal, then add an undeclared-import check.