plexus / messenger
CASE STUDY — PERSONAL PROJECT, BUILT FROM SCRATCH

A messenger whose server
cannot read your mail

Plexus is an encrypted messenger — direct and group chats, voice and video calls, files, voice messages and live location — running on a Spring Boot core with three satellite services. The same backend hosts an AI assistant that replies inside the chat and by e-mail. Direct chats can be sealed end-to-end: what the database stores is ciphertext it cannot unwrap.

Java 21 · Spring Boot 4 PostgreSQL 18 · Flyway Kafka event bus Vue 3 + TypeScript WebCrypto · AES-256-GCM Android · Kotlin Compose WebRTC Docker · Caddy
your device→ encrypt→ plexus-core→ decrypt→ their pocket
SCROLL ↓
01 — The idea

Chat is solved.
Trust is not.

Every messenger routes messages; the question is who can read them along the way. Plexus draws the line in the architecture itself: in sealed chats the server only ever transports envelopes — the keys never leave the devices. And because a messenger also wants to be useful, the same backend runs an AI assistant that answers where plaintext legitimately exists: its own chat, group mentions and e-mail.

You write a messageweb app or Android
The device seals itfresh AES-256-GCM key per message
The server routes envelopesstores ciphertext, sees metadata
Their devices unwrap itone wrap per recipient device
"Hello" appearsread receipts travel the same way
// The interesting engineering is the honesty of the boundary. Sealed direct chats are end-to-end — the server holds envelopes it cannot open. Member and assistant chats are encrypted at rest, server-readable by design — that is exactly what lets the AI reply, transcribe voice notes and summarise attachments. Two different trust levels, each implemented in code, not promised in marketing.
02 — What the user sees

A messenger that does messenger things

The UI looks familiar on purpose. The unusual parts live underneath.

Plexus messenger chat list and conversation

Direct and group chats

Real-time messaging with Telegram-style delivered/read ticks, replies, pins, reactions, scheduled messages, drafts with files — and two-scope deletion: for everyone or just for me.

delivered_at / read_at receipts · message_hides tombstones · unread counters
sealed chat · e2e1
see you at eight✓✓
9f3a…b7c1
only if it stops raining

End-to-end sealed chats

Direct chats can be sealed: messages, attachments and even shared coordinates leave the device as ciphertext. Devices are verified and new ones linked by scanning a QR code.

ECDH P-256 device keys · AES-256-GCM · per-device key wraps
A
L
V
D
+2
mesh · media never crosses the server

Voice and video calls

One-to-one calls and group conferences up to six participants in a client-side mesh. Media is encrypted per frame; a TURN relay waits for the networks that refuse peer-to-peer.

WebRTC · insertable-streams AES-GCM · TURN behind a role grant
@ai can you summarise this lab report?
HbA1c is 6.4% — slightly elevated…
in German please✓✓

An AI that lives in the chat

The assistant answers in its own chat, replies by e-mail and can be @-mentioned inside group conversations. Voice notes arrive already transcribed.

reply_jobs queue · pull-worker protocol · per-chat model picks
discharge-summary.pdf · 2.1 MB
voice-note.ogg · 0:42
encrypted blobs · resume mid-chunk

Files and voice

Attachments and voice notes, drag-and-drop drafts and a media gallery per chat. Blobs are stored as chunked ciphertext — a Range request decrypts only the chunks it covers.

enc2 chunked AES-GCM · 256 KB chunks · Range reads
Live location shared as a map message in chat

Live location

A share streams position ticks to every member until it expires — peers watch the marker move on the map. In sealed chats even the ticks stay ciphertext.

live-location SSE ticks · geoLiveUntil expiry · author-only stop
@pollbot friday 19:00?✓✓
[poll created · 3 votes]
bot:<uuid> · chat-scoped token

Bots inside group chats

Owners can attach bots: external ones poll and reply through a chat-scoped bearer token; internal ones are @-mentioned and answer through the AI pipeline — quoting the mention.

/api/bot/chats/{id}/** · SHA-256 token digests · no user session
03 — From idea to system

It started as a mail assistant.
It became a messenger.

Each layer exists because the one before created a real need — not because the diagram looked nice.

STEP 01

An assistant that answers e-mail

The project began as an AI helper for a physician, reachable by ordinary e-mail. A Spring Boot core, a Postgres database and a Vue chat view — the messenger skeleton was there before the messenger was.

STEP 02

Chat becomes real-time

SSE streams per user, presence pings, delivered/read receipts — real-time without polling or page refreshes. The Vue SPA grows into a real messenger client — sessions, contacts, named chats.

STEP 03

The encryption layer arrives

Device keys, sealed envelopes, verification, QR linking — the e2e1 spec is written once and implemented byte-exactly twice: WebCrypto in the browser, Kotlin on Android.

STEP 04

Calls arrive

WebRTC signaling moves into the core: 1:1 calls, then mesh conferences up to six. Media frames get their own AES-GCM transform — the call server never hears a word.

STEP 05

The edge splits into satellites

Mail ingest, push delivery and every AI provider key leave the monolith for three small services. The core keeps a token-guarded internal API; satellites hold the credentials.

STEP 06

Production gets redundant

Kafka fans user events out to every node, a second core goes live behind the load balancer, deploys become rolling restarts — and a nightly age-encrypted backup quietly does its job.

04 — System architecture

One core, three satellites,
two security perimeters

Browsers, Android phones and plain e-mail all converge on a pair of identical core nodes. The core speaks two dialects: a public session API for clients and a token-guarded internal API that only satellites may reach — each key opens just its own subtree.

Browser
Vue 3 SPA
Vite · TypeScript
served by the core
Android
Plexus app
Kotlin · Compose
byte-exact e2e1
E-mail
Assistant by mail
ordinary SMTP/IMAP
no client at all
Caddy edge
plexus.ing / messenger.* / :8080
TLS · security headers · internal listener · LB to two cores
plexus-core ×2 · Spring Boot 4
/api sessions + /internal tokens
chats · auth · crypto registry · assistant · calls · admin
data
PostgreSQL 18
Flyway · 134 migrations
enc1 + enc2 at rest
events
Kafka 4
plexus-user-events
cross-node fan-out
separate deploy
plexus-ai
stateless pull worker
holds provider keys
separate deploy
plexus-mail
IMAP ingest + Gmail egress
owns mail credentials
separate deploy
plexus-push
Kafka → FCM
dead-token feedback
external
Providers · Gmail · FCM
the only credential holders
besides the database

Dashed border = its own deployment, reachable only through the internal API or Kafka. The two core nodes are interchangeable — a rolling restart never takes the service down.

05 — Inside the backend

Feature-first modules, one deployable core

A deliberate monolith at the centre — cheap to run, easy to reason about. The sharp boundaries are inside it, and at the satellites' token doors.

chat

public API
  • Direct + group chats, members, named history
  • Receipts: delivered/read, unread counts, pins, reactions
  • Scheduled messages, drafts with files, media gallery
  • Two-scope delete — hard delete vs. hide-for-me tombstones
Every member message emits an event that internal bots can pick up — a mention becomes an AI reply job quoting the message.

auth + registration

public API
  • Magic-link e-mail, password, Google sign-in, QR device login
  • Self-registration with mailbox verification — no admin approval
  • Session cookie; AccessGuardFilter re-checks rights on every call
  • Roles → permissions; new accounts start role-less, AI needs a grant
Login throttles see the real client IP — X-Forwarded-For honoured only from trusted proxy ranges.

crypto

public API
  • Device key registry — public halves only (base64 SPKI)
  • QR linking: a trusted device seals identity for a new one
  • Key backup, key wrap + proof-of-possession for device provisioning
  • Verification state per device pair, fingerprint change tracking
The server is a key directory, not a key holder — private halves are non-extractable and never uploaded.

assistant + ai gateway

public + internal
  • reply_jobs queue — replies decoupled from the request thread
  • Pre-flight intent classifier routes trivial asks to a cheap model
  • Model function tools: document memory, UpToDate search
  • Per-user+day usage metering, per-role model grants
Every provider call goes through AiGatewayClient to plexus-ai — the core itself holds zero AI keys.

realtime + presence

SSE streams
  • /api/events — one Server-Sent-Events stream per user
  • Two presence signals split: app-on-screen vs. reachable
  • Events fan out via Kafka so any node can answer any client
  • me-updated pushes grant changes live — no re-login needed
last_alive ≠ last_seen: a device can be ringable without looking "online".

call + conference

signaling only
  • WebRTC SDP/ICE relayed — media stays peer-to-peer
  • 1:1 calls and mesh conferences up to six participants
  • TURN relay config gated behind the USE_TURN role
  • Ring escalation: push → 15 s ack → invite mail → missed
A data push wakes a dormant app, which acknowledges /ringing — the mail fallback only fires when nobody acks.

admin + analytics

admin API
  • User/role grants, model grants, usage inspection
  • Hosted Android APK — content-addressed, immutable URL
  • First-party landing analytics, no third-party trackers
  • Feedback relayed to an inbox — nothing stored in the DB
Analytics join visits to users in memory only, via a TTL'd IP map — never persisted.

mail + push + feedback

internal API
  • plexus-mail owns IMAP + Gmail; core answers /internal/mail/*
  • plexus-push consumes Kafka, resolves targets via /internal/push/targets
  • Dead FCM tokens reported back and deleted
  • Each satellite's token opens only its own subtree — fail-closed
Dormant accounts (no app-on-screen for 14 days) get no message pushes — call rings bypass that end to end.
06 — Where data lives

One database, two kinds of ciphertext

Postgres is the only system of record; Flyway owns the schema. What sits inside depends on the chat's trust level: at-rest envelopes everywhere, end-to-end envelopes where chats are sealed.

PostgreSQL — the server

134 Flyway migrations · ddl-auto=validate · enc1/enc2 at rest
usersuser_rolespush_devices chatschat_memberschat_bots assistant_messages (enc1)e2e envelopes message_hidesmessage_files (enc2)message_audio (enc2) chat_draftsscheduledlive_peers user_device_keyscrypto_link_sessions reply_jobsai_usageanalysis_documents login_tokensaltcha_spent

enc1 = AES-256 column encryption on message text; enc2 = chunked AES-256-GCM (256 KB blocks) on blobs — a Range request decrypts only the chunks it touches. Sealed-chat payloads arrive as ciphertext already; the at-rest key just adds a second skin.

The device — yours

IndexedDB on web · Kotlin stores on Android
ECDH private keytrusted device map verified fingerprintssession cache chat list cachedraft state key backup blob

The non-extractable private key never leaves the device — WebCrypto marks it unexportable at creation. Lose the device without a backup, and its wraps are unrecoverable by design.

07 — How things talk

REST in, events out, one clever inversion

No websockets in the critical path. The twist is direction: satellites pull work out of the core — the core never pushes into them.

client → core

HTTPS · JSON
  • REST with a session cookie; CSRF token on mutations
  • Presence pings every ~30 s mark the device reachable
  • Bot tokens open only /api/bot/chats/{id}/** — stateless

core → client

SSE /api/events
  • One long-lived stream per user per connected device
  • message-posted, -delivered, -read, presence, me-updated
  • Held connections ride a dedicated LB policy so streams never starve a node

node ↔ node

Kafka fan-out
  • Topic plexus-user-events — every event, every node
  • One consumer group per node id, offset=latest
  • plexus-push rides the same topic — no extra bus

satellite → core

pull · internal
  • AI worker long-polls /internal/ai/jobs/claim?wait=≤30
  • Progress + results POST back to /internal/ai/jobs/{id}/events
  • Push resolves recipients via /internal/push/targets
  • Mail relays outbound via /internal/mail/send
// Why pull? A satellite needs no inbound surface beyond its token calls, can crash without losing jobs — unclaimed work is re-queued — and provider credentials never have to sit next to user data.
08 — Follow one message

"See you at eight" — eleven hops later

A sealed chat, an offline recipient, one short sentence. This is the actual path it takes through the system.

Device · compose

You hit send

The UI builds the payload — text, quote, attachment descriptors — as UTF-8 JSON. Nothing has left the device.

Device · seal

A fresh key per message

WebCrypto mints a 256-bit content key K and AES-256-GCM-encrypts the payload under a random IV.

Device · wrap

One wrap per recipient device

For each of their devices: wrapKey = SHA-256(ECDH(myPriv, theirPub) ‖ "plexus-e2e-wrap" ‖ ids), then AES-GCM-seal K under it. Phone and tablet each get their own copy.

Device → Core

POST /api/chats/{id}/messages

The envelope — {v, s, c, w{…}} — goes up over the session. Attachments travel as separately keyed blobs (plexus-e2e-file-v1 AAD).

Core · store

Ciphertext meets ciphertext

The row lands in assistant_messages under the at-rest enc1 key — a second envelope around an envelope the server already cannot open.

Core · fan-out

The event hits Kafka

A message-posted user event lands on plexus-user-events; both core nodes consume it, so the recipient's node can answer regardless of which one took the POST.

Core → Device

SSE delivers in real time

Any connected device gets the envelope on its /api/events stream — delivery and later read receipts return along the same path.

Push satellite

The offline phone wakes

plexus-push sees the event on the topic, asks /internal/push/targets who to wake — dormant accounts skipped, dead tokens reported back — and FCM delivers a silent data push.

Their device · unwrap

ECDH produces the wrap key

Their device recomputes ECDH(theirPriv, yourPub), unwraps K from its personal w[device] entry — a key that exists nowhere else.

Their device · read

"See you at eight"

AES-256-GCM verifies and decrypts; the bubble renders — and your ticks flip to delivered, then read.

Everywhere else

What travelled on the wire

The Caddy edge, the database, Kafka, the push satellite — all saw the same thing: an envelope, sizes and timestamps.

09 — End-to-end encryption

The envelope is the only thing
the server ever sees

The e2e1 spec is written once and implemented twice — byte-exact across WebCrypto and the Android client — so a phone can unwrap what a browser sealed. This is what one envelope looks like on the wire, and what your message becomes as it leaves the device:

{
  "v": 1,    // spec version
  "s": "dev-a7",  // sender device id
  "c": "iv‖AES-256-GCM(K, payload)",  // the ciphertext
  "w": {                    // K, wrapped per device
    "dev-b2": "iv‖GCM(wrapKey_b2, K)",
    "dev-b9": "iv‖GCM(wrapKey_b9, K)"
  }
}
stored verbatim in assistant_messages — inside its own enc1 at-rest wrap
what actually left your device See you at eight — bring the good umbrella.
setup

Each device brings its own key

An ECDH P-256 pair is generated locally; the public half registers at /api/crypto/keys, the private half is non-extractable and never uploaded.

link

New devices are adopted, not trusted

Scan a QR code on an already-trusted device — it seals your identity for the new device through a short-lived link session. No account password can mint a trusted key.

verify

Fingerprints, remembered

Each device pair caches the peer's fingerprint; a changed key raises a verify dialog instead of silently re-sealing. Recovery keys ride a separate backup blob.

scope

Sealed means sealed

Attachments get their own content key and integrity hash; shared coordinates travel inside the same envelope — the server learns that something moved, never what.

10 — Trust model

Who can see what

The design goal isn't "encrypt everything" — it's not needing to trust the server with the readable form in the first place, while staying honest about the chats where plaintext exists by design.

On the device — yours // never uploaded

  • Message, file and voice plaintext
  • Shared coordinates inside sealed chats
  • ECDH private keys — created non-extractable
  • Trusted-device fingerprints and session state

On the server — only what it needs

  • Accounts, roles, chat membership, unread counts
  • Ciphertext envelopes + wrapped keys it cannot unwrap
  • enc1/enc2 at-rest envelopes around everything stored
  • Delivery metadata: who, when, how large — not what

The server deliberately cannot

  • Read a sealed message, attachment or coordinate
  • Impersonate a device — it never holds the private half
  • Call an AI provider — the keys live in plexus-ai
  • Hear a call — media is encrypted per frame, peer to peer

And where plaintext exists — on purpose

  • Assistant chats: the AI needs context to answer
  • Group chats with internal bots — same reason
  • Voice-note transcripts feeding the assistant
  • These rows are enc1-sealed at rest instead — stated, not hidden
11 — Calls

The server arranges the call,
then steps out of the room

Signaling goes through the core — that's unavoidable, someone has to introduce the peers. The conversation itself is peer-to-peer, encrypted frame by frame.

signaling

CallService
  • SDP offers/answers and ICE candidates relayed via REST
  • 64 KB payload cap; call events ride the same SSE/Kafka fan-out
  • Invite → ringing → accepted/declined/missed lifecycle
Ring escalation: a data push wakes the app → 15 s ack window → invite e-mail → missed. A dormant phone still rings.

media

peer to peer
  • WebRTC mesh — media never crosses the server
  • callE2e.worker: insertable-streams AES-GCM per frame
  • Counter IVs; a failed decrypt drops the frame, not the call
  • Conferences: up to 6 participants, same transform
TURN relay config is handed out only to accounts holding USE_TURN — relays cost money, so they're a permission.
12 — Production

One host, every piece accounted for

A single docker-compose file is the whole production topology: edge, two cores, database, broker, three satellites, monitoring and a nightly encrypted backup — rebuilt and rolled forward by one deploy script.

git push
feature → PR → squash
→
./mvnw package
frontend built in-image
→
docker compose
image → VPS
→
rolling restart
core-a, then core-b
→
healthchecks
/actuator/health gates traffic

the edge

Caddy 2
  • TLS + HSTS preload, scoped CSP per site, nosniff, CORP
  • /internal/** and /actuator/** 404 on the public side
  • A separate :8080 listener is the satellites' only door
  • LB: round_robin for REST, random for held SSE streams
least_conn would count every SSE stream as a connection and starve a node — measured, so stream traffic gets its own policy.

the base

data + ops
  • Postgres 18 + Kafka 4 in the same compose network
  • Prometheus + kafka-exporter scrape the fleet
  • Nightly pg_dump → age-encrypted backup file
  • The age private key lives off-host — a restore needs it
Two core nodes behind health-checked LB retries mean a deploy is a rolling restart, not downtime.
13 — The final system

Every piece, one picture

The tour, assembled. Clients above, perimeters in the middle, credentials only at the edges.

Browser
Vue 3 SPA
REST + SSE
WebCrypto e2e1
Android
Plexus app
Kotlin Compose
same envelopes
E-mail
Mail users
assistant replies
by SMTP
Bots
Chat bots
chat-scoped tokens
or @mention → job
edge
Caddy
TLS · headers · LB
:8080 internal listener
plexus-core ×2
Spring Boot 4 · Java 21
chat · auth · crypto registry · assistant gateway
calls · presence · admin — 134-migration schema
store
PostgreSQL 18
enc1 columns
enc2 chunked blobs
bus
Kafka
plexus-user-events
every node consumes
satellite
plexus-ai
claims jobs, POSTs events
provider keys live here
satellite
plexus-mail
IMAP cursor + Gmail
mail credentials live here
satellite
plexus-push
topic → FCM
FIREBASE_CREDENTIALS here
ops
backup + metrics
nightly age-encrypted dump
Prometheus scrapes
// Read it like a trust diagram: clients and satellites hold secrets, the centre holds ciphertext and metadata, and every cross-perimeter hop runs through a token that opens exactly one door.
14 — Technical details

For those who read the footnotes

Backend
Java 21 · Spring Boot 4feature-first modules · JPA + Flyway
Frontend
Vue 3 · Vite · TypeScriptbuilt into the jar · self-hosted fonts
Mobile
Android · Kotlin · Composebyte-exact e2e1 · FCM · QR sign-in
Database
PostgreSQL 18134 Flyway migrations · ddl-auto=validate
Events
Kafka 4 · plexus-user-eventsSSE /api/events fan-out per user
Sealed chat
ECDH P-256 · AES-256-GCMper-device wraps · QR linking · backups
At rest
enc1 AES-256 · enc2 AES-GCM256 KB chunks · range-aware decrypt
Calls
WebRTC · mesh ≤6insertable-streams AES-GCM · TURN role
AI
plexus-ai pull workerclaim/events protocol · function tools
Satellites
plexus-mail · plexus-pushper-subtree internal tokens · fail-closed
Edge
Caddy 2 · rolling 2-node corehealthchecks · split SSE/REST LB
Ops
Docker Compose · Prometheusnightly age-encrypted pg_dump