One server, one database, every client.

Overview

Three kinds of client, one process, one database.

Every client speaks to the server over HTTPS and one WebSocket. The server keeps the live sockets in memory, writes to PostgreSQL through a single crate, stores bytes through a storage port, and sends push notifications to Apple, Google and browsers itself. The update feed and automation tools such as n8n sit beside it, not inside it.

Four crates, one direction

The server is a Cargo workspace of four crates, and dependencies only point one way. plum-server holds no SQL at all, so the day the database changes shape, one crate answers for it. Lines of Rust under each src/, 5 October 2026:

The stack

Few dependencies, each one chosen on purpose.

The web client's only runtime dependencies are React, React DOM and an emoji data set. Cryptography comes from crates the server already ships, so a feature such as two-step sign-in added no new crypto library and no new licence family.

Two doors, one function

REST and the socket call the very same code.

Everything a person can do arrives through one of two doors: 146 paths under /api/v1, or 20 commands on the WebSocket. The socket handler parses a frame and calls the same block function the REST handler calls, so a behaviour cannot be right on one door and wrong on the other.

The server's code is organised by subject: one file, or one folder, per block (messages, channels, files, calls, tasks, apps, export and so on). A block declares its own routes, and three layers wrap every route, including ones written later: a tracing span, the owner's switches (a part switched off is refused by the server, not only hidden), and an app's scopes.

A request, end to end

• Who is asking is answered in one place. It answers a person, nobody, or trouble; a database failure is kept apart from "nobody" on purpose, because a client signs out on a 401 and a database blip should not sign anybody out.
• The block decides whether this person may do this, in its own words.
• One statement runs in plum-store.
• The result fans out to whoever needs telling, through two functions: to every member of a channel, sender included, or to every device of one person.

Two kinds of work leave the async runtime, because they burn a core rather than wait on one: password hashing (Argon2id, measured at 13.6 ms per verify) and picture decoding. A test runs eight sign-ins on a single-threaded runtime and requires an unrelated request to answer within 100 ms, so the hashing can never drift back onto the runtime unnoticed.

A message's path

Queued, carried, checked, stored once, then told.

The composer hands the text and any file ids to the client library, which keeps an outbox. The socket carries the command; the server checks it, writes it in one transaction, acknowledges it, and tells everybody who should know, each in the frame meant for them.

The protocol is a contract

Version 1 was frozen on 18 September 2026 and only ever gains: a new event, field or endpoint may be added, because a client that has never heard of it ignores it. Renaming or removing anything means version 2. Every frame has the same four fields:

{ "v": 1, "t": "message.send", "cid": "01J8...", "d": { "channel_id": "...", "text": "...", "file_ids": [] } }

• A resend never duplicates. Every command that creates something carries a client-made cid; a cid already handled returns the earlier result.
• One send is one message. Five pictures picked together are one message carrying five files, never five messages.
• Unread is a subtraction, never a count. A channel keeps its total; a member keeps where they read to. Nothing runs COUNT(*) over the messages to find unread.
• The text is plain on the wire. The server reads the marks (bold, italic, strikethrough, code, quotes, lists, links, mentions) into blocks, and every client draws the blocks it is handed, so no two clients read one message two ways. A golden file holds the Rust and TypeScript readers to one answer.

Real time

Sockets kept per person, not per channel.

The hub is a map of open sockets keyed by person. "Tell everyone in this channel" can be done from either shape; "tell every device this person is signed in on" cannot be done from a channel-keyed map, and that second one is what takes the unread badge off the phone the moment you read on the laptop.

• Catching up is the client's job. The handshake sends the client's last message id in each channel; the server answers with what was missed, or a refetch flag when it is too much to push through one frame.
• Two keep-alives, for two reasons. The client sends ping and expects pong, which proves both applications are alive; the server sends a WebSocket Ping frame every 25 seconds, under the 30 to 60 seconds an idle flow survives on a phone network.
• Presence is one answer for all of a person's devices: online while any is in use, away when every one is idle, offline once the last closes.
• The counts above the rooms follow the socket. Activity, Threads and Kept counts arrive as views.changed, so a message no longer costs every client a request.
• Three clocks run in the process for what must happen with nobody asking: due work every minute, messages sent later every five seconds, reminders every fifteen. Each claims its rows with UPDATE ... RETURNING, so a restart mid-pass cannot send anything twice.

Storage

PostgreSQL for the record, a readable tree for the bytes.

Thirty tables hold everything that is not a file. Primary keys are UUIDv7, which already sort by time, and paging is keyset paging on them, never OFFSET. Nothing is removed with DELETE: a message gets a deletion time, so the trail keeps its record and sync learns what disappeared instead of finding a silent gap. The server holds a pool of eight connections.

Files go through a port of seven operations in plum-storage, and three places sit behind it: a folder on the server, a mounted volume, or any S3-compatible bucket (AWS, Cloudflare R2, Backblaze B2, Wasabi, MinIO and others). Moving between them is a copy and one setting, because the database stores a key, never a path.

channels/<channel id>/2026/09/<file id>_drawing-a3.pdf
channels/<channel id>/2026/09/thumb/<file id>_<size>
direct/<conversation id>/2026/09/<file id>_IMG_1234.jpg

Folders are ids, never names, because renaming a folder on object storage means copying every byte under it. Year and month let one month be restored on its own, or a lifecycle rule move a year to colder storage without reading a database.

The mount that did not mount. The store keeps a marker file at its root. A root that has files but no marker stops the server, and an install with a mounted volume can require the marker outright, so a volume that failed to mount is a loud failure at start, not a weekend of files written to the wrong disk.

Search

Type without accents, find the accented word.

Typing tien finds tiền, and san xuat finds sản xuất. Search runs inside PostgreSQL, over two GIN indexes on the folded text of every message:

• Accents folded by unaccent, wrapped in an immutable function so it can be indexed. Its stock rules cover the whole Vietnamese alphabet, including đ and the vowels with a horn and a tone, so nothing custom has to be installed in a self-hoster's database.
• The simple text-search configuration, not english. Once Vietnamese loses its accents, words such as in (printing), do (to measure) and on (stable) collide with the English stop-word list and vanish. Vietnamese does not inflect, so there is nothing to stem either.
• Whole words in any order from a full-text index, and fragments of a word from a trigram index; the two plan as one bitmap OR, measured at 0.687 ms for a two-word query on a real workspace's data shape.
• Only rooms the reader is in. Membership is written into the single search statement with no branch that can skip it, alongside both soft-delete filters.

A search can be narrowed by sender, room, date range and whether the message carried a file. Filenames are searched the same way, accents optional.

Files and previews

The original is never touched.

An upload names the channel it is for, and only a member may upload into it. The server takes up to 100 MB a file by default; the owner can set a lower limit and refuse file types from the console. The original is stored as it arrived and is never an input to anything that writes.

• Two previews per picture, 128 and 640 pixels on the longest edge by default, never larger than the original. JPEG at quality 82, or PNG when the picture has transparency, so a logo does not turn into a white box.
• Upright. A phone stores a photo as the sensor reads it; the server applies the EXIF orientation before it scales, so portraits are not drawn on their side.
• Bounded. Only a file whose first bytes say it is an image is read into memory, decoding runs on the blocking pool, and a decoder may not allocate more than 512 MB, the guard against a tiny file that unpacks into gigabytes.
• The server does not decode HEIC, because HEVC is patent-encumbered. An iPhone converts its photos before they upload; from Android a HEIC photo arrives as a file to download.
• Link previews are made by the server, after the message is sent: only the page's head, at most 512 KB and six seconds, no images from strangers, and every address checked to be public before it is fetched, redirects included.

Calls

WebRTC between the two ends, signalling over the socket.

Voice and video calls between two people go browser to browser over WebRTC. The server carries the signalling (offer, answer, candidates) over the socket each client already holds, and never a second of sound or picture. No outside service is involved: no hosted relay, and no public STUN server handed out.

• A relay of your own, when the ends cannot meet. The server hands out short-lived TURN credentials in coturn's shared-secret scheme: the username says when it expires, the password is an HMAC of it, good for twelve hours. With no relay configured, calls still connect wherever the two ends can reach each other.
• Every device rings; the first to answer takes the call and the others stop. A call that rings 40 seconds becomes a missed call, which leaves a line in the conversation and raises the callee's unread count in the same transaction.
• Video is the same call with pictures. The caller always offers a video line, so turning the camera on or off, or to the other camera, swaps a track without a second negotiation.
• On a locked phone, a call is a phone call. An iPhone is woken by a PushKit VoIP push and the call is reported to CallKit; an Android phone gets a call screen over the lock screen. The phone's native code picks the earpiece, the loudspeaker, a headset or Bluetooth, which a web page cannot.

Push notifications

The server talks to Apple and Google itself, with the text inside.

Most self-hosted chats route phone notifications through the vendor's gateway, and that is where they meter them. Plumspace's server holds the keys and sends directly. The notification carries the message's text, so the phone shows it without first waking the radio to call back and ask, which is the step that loses notifications on a factory floor.

• Web Push is composed from primitives rather than taken from a push crate: RFC 8291 for the key agreement, RFC 8188 for the aes128gcm layout, RFC 8292 (VAPID) for the signature. A test reproduces the RFC's published example byte for byte.
• FCM is HTTP v1 with a service account: a JWT signed RS256 is traded for an access token, kept for most of its hour, so a busy channel costs one trade an hour rather than one per phone. It sends a data message, so the app draws the notice itself and stays quiet when that room is already open.
• APNs uses token authentication: a JWT signed ES256 with a .p8 key, renewed every fifty minutes, over HTTP/2. Notices are grouped by room. A VoIP push goes only to a token registered for calls, and only for a call, because iOS ends an app woken by VoIP that reports none.
• Dead tokens are retired as soon as Apple or Google says so, and tokens are registered again at every app start.
• Read anywhere clears the phone. When a room is read on another device, a silent push takes its notice off the phone, at normal priority so Android does not count it against the app.
• The rules live in one place. A browser notice, a phone and the in-app sound obey the same rule, and unread counts move whether or not anybody is woken.

The phone apps

A native shell that draws the server's own web client.

The Android and iPhone apps ask for the workspace's address once, check it, then draw the page that server serves in a WebView. Every screen the web has, the phone has the same day, at the version of the server it talks to. What stays native is only what a page cannot do on a phone: being woken by push, ringing a call, choosing where sound plays, saving a file into the phone, the back gesture, links that open in the phone's browser, and updating itself.

• One app for every workspace. There is no build per company: every install asks for its address, which is also why the shell registers push tokens under the page's own session.
• It feels like the phone's own app. The page follows the system text size as a whole (0.85 to 1.3, so Vietnamese marks never overlap the next line), paints the system bars in its own colours, shrinks for the keyboard, and lays out two panes from 640 pixels wide on an opened folding phone.
• Android updates itself from the publisher's signed list: the APK is hashed in native code, a block at a time, before Android's installer sees it. The Google Play build leaves updates to Play, and an iPhone updates through TestFlight; both say when a newer build is waiting.
• Battery savers: the downloadable Android app asks once to be left out of battery optimisation, the most common reason notifications go missing on some Android brands.

The desktop app

Electron, one window, the address you type.

The Mac and Windows app is the web client in one Electron window, with its own menu, a frame that follows light and dark, a drawn title bar on Windows and none on a Mac, and an offline page that retries. The Mac build is signed with a Developer ID and notarised by Apple. The Windows installer is not code-signed, so Windows shows its SmartScreen notice once, on the first install; updates after it are protected by the publisher's own signature.

• It checks for updates fifteen seconds after start and every four hours, from the publisher's feed and then from the workspace server's own mirror, comparing build numbers.
• It downloads in the background, checks the size and SHA-512 the signed list gives, then hands the file to the system: on a Mac to Squirrel, which also refuses an app not signed by the same Developer ID; on Windows to the installer, run silently.
• Only then is the person asked: Restart to update, or Later, which installs when the app quits.

Offline and start-up

It opens with no network, and starts small.

A service worker of about 120 hand-written lines keeps the build, never the server's answers: the page, the start-up scripts, the stylesheet and the fonts, in one cache per build. Opening the page is network first; the kept copy is drawn only when the network fails, answers with an error, or has not answered in four seconds. A new deploy replaces the cache whole.

• The page keeps the newest messages in IndexedDB, one database per signed-in person: the 20 most recently opened rooms, 50 messages each, at most 256 KB a room, written only from what the server said in this session.
• Drawn first, replaced by the server. With the server stopped, the first saved message was drawn 34 to 35 ms after navigation in a measured run. It is read only and says so; nothing written against a possibly stale copy is sent later behind the person's back.
• Signing out wipes it before anything else, and the worker's cache holds only the build, the same bytes for everybody.
• Where it runs: browsers, the desktop app and Android. An iPhone's WebView gives a service worker only to a fixed list of domains, which a one-app-for-every-workspace build cannot write, so the iPhone app does not open offline.

A budget the build cannot pass

Anything not on the first screen (the console, a person's pages, the picture viewer, a call's video screen, most sheets) is a file of its own, fetched when first drawn. The path that answers a ringing call stays in the first file on purpose. A gate follows index.html to every script loaded before the first paint and fails the commit above 620,000 raw bytes; on 5 October 2026 it was 615,078 raw, 162,453 as brotli. Every text asset is precompressed as brotli and gzip, and hashed assets are cached for a year as immutable.

Security

Every limit counted on the key it can trust.

Running it

One image, one database, a small machine.

The server ships as a container image with the web client of the same commit inside it, so one pull moves both halves together. It is built on distroless (glibc, the CA roots, no shell, no package manager), runs as an unprivileged user, and weighs 39.6 MB to pull and 91 MB unpacked. A compose file runs it beside PostgreSQL; a deploy is a database dump, a pull, a migration and an up, and a rollback is the previous version number. Each release also publishes the binaries as a tarball for a host without Docker.

• Sized for two cores. The design was sized on a machine with 2 cores and 7.9 GB of memory. In production on 20 September 2026 the process used 30 MB of memory and no measurable CPU for a 21-person workspace.
• A health check that asserts a value. /healthz returns the PostgreSQL version and the number of tables it counted, and answers 503 without its database, because a probe that only says "ok" lets an empty database pass for healthy.
• Nothing happens at start but starting: no cache to warm, no index to build, no migration run as a side effect. Migrations are a separate command and safe to repeat.
• Settings are environment variables, one table of them, and a misspelled storage setting stops the server with the variable named rather than quietly writing to the wrong place.
• Push keys belong to whoever runs the server: a VAPID key for browsers (one command prints it), and the app publisher's APNs key and Firebase service account for phones.

Releases and updates

One version for everything, every list signed.

The server, the web client and every app carry one version number, moved together at each release. A tag on main starts two workflows side by side: one builds the server image and the release, the other builds the apps. Installers are published to a beta channel first and promoted to stable by hand, by copying the beta list's exact bytes and signature.

• Why a raw Ed25519 signature rather than minisign's format: the apps check one key that never changes, in four lines with Node's own crypto on the desktop and a small audited library on the phone, and the same bytes can be checked by hand with the publishing script.
• Builds are never overwritten. Every installer lives under its version and build number for good; a platform with no new build keeps its entry, and rolling back is promoting the older version, after which no further app moves to the bad one.
• An app too old for its server says "Update needed". The server names the oldest app build it works with; the page compares at start and at every reconnection and offers the update instead of half working.