DEV Community: Kornel Maraz

SSO Without Giving the Server Your Keys

Kornel Maraz — Wed, 09 Sep 2026 18:26:21 +0000

Single sign-on is a solved problem. You redirect to an identity provider, it tells you who the person is, you mint a session. Every framework has a library for it.

Then you try it on an app that encrypts everything in the browser, and the whole thing falls over.

The claim that breaks SSO

MindMapVault derives your encryption key from your passphrase, in your browser, and never sends it anywhere:

master_key = Argon2id(passphrase, salt)
auth_token = HKDF(master_key, "crypt-mind-auth-v1")  // the only part the server sees

Everything else hangs off master_key. Your private keys are encrypted under it. Your vaults are encrypted under those. The server stores ciphertext and a hash of auth_token, and that is the entire extent of what it knows.

Now add an identity provider. Entra says this is alice@example.com. Google says the same. Both are telling the truth, and neither one helps, because an OIDC token is an assertion about identity — it is not, and cannot be, the key that decrypts Alice's data.

The key has to come from somewhere. There are exactly three somewheres:

Something the user types — a passphrase.
Something a device holds — a passkey, or a key in browser storage.
Something your organisation holds — escrow.

Option 3 is the one that makes SSO a one-click experience, and it is the one that quietly ends zero-knowledge: if the org can unwrap the key, so can the server, so can a subpoena, so can whoever gets into your KMS. Most products that advertise "SSO with end-to-end encryption" have picked option 3 without saying so.

We picked 1, then made it rare with 2.

What the user sees

First sign-in through the provider. Redirect, consent, back. Then one screen: choose a username and a vault passphrase.

Every later sign-in. Straight through. No passphrase — because the browser already holds a key that can unwrap it.

A new laptop. Passphrase once, then that machine is remembered too.

So the passphrase is typed roughly as often as you buy a computer.

The flow, end to end

The OIDC half is ordinary — authorization code with PKCE, a single-use state, a nonce bound to the request. The interesting part is where it stops:

browser                our server              identity provider
   |                        |                          |
   |  click "Continue"      |                          |
   |----------------------->|  store state+nonce+PKCE  |
   |         307 redirect   |                          |
   |<-----------------------|                          |
   |                        |                          |
   |  authenticate ------------------------------------>
   |  <------------------------------ redirect + code   
   |                        |                          |
   |  code + state          |                          |
   |----------------------->|  exchange code --------->|
   |                        |<-------- id_token (JWT)  |
   |                        |                          |
   |                        |  verify: signature,      |
   |                        |  issuer, audience,       |
   |                        |  expiry, nonce           |
   |                        |  find or create account  |
   |    tokens in fragment  |                          |
   |<-----------------------|                          |
   |                        |                          |
   +-- the server is done here. the vault is unlocked
       locally, with a key the server has never seen.

Two details in that picture are easy to get wrong. The ID token is verified on signature, issuer, audience, expiry and nonce — skip any one and the flow becomes a way to sign in as anybody. And the tokens come back in the URL fragment, not the query string, because browsers never send a fragment to a server: it stays out of access logs, proxy logs and Referer headers, and the page clears it from history immediately.

The account created at the end of that has no password and no keys — it cannot open anything yet. That is what the enrolment screen is nor, and it is why the username is asked for there rather than lifted from a provider claim: a name taken from an IdP can collide with an existing local account, and resolving that collision by merging is an account takeover with extra steps.

The insight that makes it cheap

Here is the part worth stealing for your own app.

We nearly redesigned the whole key hierarchy for this. We did not need to. Look again at what the system actually depends on:

const aesKey = await deriveMasterAesKey(masterKey);

const classicalPriv = await aesDecrypt(aesKey, bundle.classical_priv_encrypted);
const pqPriv        = await aesDecrypt(aesKey, bundle.pq_priv_encrypted);

Nothing here cares how you got those 32 bytes. deriveMasterAesKey just imports them as an AES key. The Argon2 derivation is one way to obtain them, not the definition of them.

So instead of changing the derivation, we store additional encrypted copies of the same master key, one per unlock method:

                  master_key  (32 bytes)
                never leaves the browser
                           ^
         +-----------------+-----------------+
         |                 |                 |
    derived from      unwrapped by      unwrapped by
         |                 |                 |
  +------------+    +-------------+   +-------------+
  | passphrase |    |   device    |   |   passkey   |
  |  (Argon2)  |    |     key     |   |  (WebAuthn  |
  |            |    | (IndexedDB) |   |     PRF)    |
  +------------+    +-------------+   +-------------+
    nothing           server holds      server holds
    stored            ciphertext        ciphertext

One table:

CREATE TABLE unlock_methods (
    id                 TEXT PRIMARY KEY,
    user_id            TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    kind               TEXT NOT NULL,     -- 'device' | 'webauthn-prf'
    label              TEXT NOT NULL,     -- "Chrome on Windows"
    wrapped_master_key TEXT NOT NULL,     -- ciphertext the server cannot open
    created_at         TIMESTAMPTZ NOT NULL,
    last_used_at       TIMESTAMPTZ
);

No migration. No vault re-encrypted. The passphrase path is untouched — it
still derives, exactly as before. Everything else is additive, which is also why adding passkeys later is a second value in kind rather than a rewrite.

Trusting a device

The wrapping key is generated in the browser and never becomes bytes anyone can read:

const key = await crypto.subtle.generateKey(
  { name: 'AES-GCM', length: 256 },
  false,                       // extractable: false - this is the whole trick
  ['encrypt', 'decrypt'],
);

const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = new Uint8Array(
  await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, masterKey),
);

await store.put({ userId, methodId, key });   // IndexedDB holds the CryptoKey

extractable: false means crypto.subtle.exportKey throws. The key can
encrypt and decrypt, and that is all — it cannot be serialised, logged, or
posted to an endpoint, even by code running on the page.

What goes to the server is iv || ciphertext. It is opaque. We assert that in
a test rather than merely believing it:

const bytes = Buffer.from(wrapped_master_key, 'base64');
expect(bytes.length).toBe(12 + 32 + 16);   // nonce + key + GCM tag

Exactly nonce, key and tag — no room for anything in the clear.

Unlocking silently

On load, before showing any prompt:

const record = await loadDeviceRecord(userId);
if (!record) return;                                  // ask for the passphrase

const { wrapped_master_key } = await api.getWrappedMasterKey(record.methodId);
const masterKey = await unwrapWithDevice(record, wrapped_master_key);
if (!masterKey) {
  await forgetDevice(userId);                         // stale - drop it
  return;                                             // ask for the passphrase
}

await openWithMasterKey(masterKey);

Every failure falls through to the prompt. Not being remembered is the normal case, not an error, and a device that cannot unwrap is a device whose local key is now useless — so it is deleted rather than retried on every load.

The two things that will bite you

Rotation invalidates every stored copy. When someone changes their
passphrase, master_key changes, and every wrapped copy becomes undecryptable noise. If you leave those rows, a device trusted yesterday fails today with nothing on screen to explain why. So rotation deletes them all:

// The rotation has already committed, so this cannot abort it. A stale row
// costs one failed silent unlock and a passphrase prompt - the safe direction.
match state.db.delete_all_unlock_methods(&auth.0).await {
    Ok(0) => {}
    Ok(removed) => tracing::info!(removed, "cleared trusted devices after rotation"),
    Err(error) => tracing::warn!(?error, "could not clear unlock methods"),
}

That is also the right behaviour when the rotation happened because the old passphrase leaked.

Never link accounts on email. An OIDC token carries sub and usually
email. It is tempting to match on the address — it is human-readable and
already in your users table. Do not. An address gets reassigned when someone leaves a company, and the next holder of alice@example.com would inherit Alice's vaults. Link on (provider_id, sub), and store the email only when the provider says it verified it:

fn verified_email(claims: &IdTokenClaims) -> Option<String> {
    match (claims.email.as_deref(), claims.email_verified) {
        (Some(email), Some(true)) => Some(email.to_string()),
        _ => None,   // a provider that says nothing has not checked it either
    }
}

What this is not

A trusted device is convenience, not security. Anyone who can use that
browser profile can open the vaults. That is the honest trade, it is why the checkbox is off by default and says so in plain words, and it is no weaker than leaving a session signed in — which is what people do anyway.

And there is no recovery. No passphrase, no admin reset, no escrow. Lose every device and forget the passphrase, and the vaults are gone. That is not a gap we have failed to close; it is the same sentence as "the server cannot read your data", said from the other side.

Where it leaves us

Federated sign-in that authenticates the session, a passphrase that unlocks the data, and a device key that means you rarely type it. Three secrets doing three different jobs, none of them held by the server.

Next is WebAuthn PRF — deriving the wrapping key from a passkey instead of browser storage. With a syncing passkey provider that is genuinely passwordless across devices, and thanks to the table above it is one more row, not another redesign.

MindMapVault is an end-to-end encrypted mind mapping tool. Everything described here — federated sign-in, the enrolment step and trusted devices — ships in the next release of the self-hosted server, which is open source under AGPL-3, so you can read the parts this article only summarises.

Real-time collaboration on a server that cannot read the document

Kornel Maraz — Sat, 05 Sep 2026 10:54:57 +0000

MindMapVault is an end-to-end encrypted mind mapping tool. Maps are encrypted in the browser with a key derived from the user's password; the server stores ciphertext and has never held a key.

That design makes one feature genuinely hard: two people editing the same map at the same time. This is how we built it anyway, on Cloudflare, and the parts where the obvious approach had to be thrown away.

Why the standard approach does not work

For collaborative editing, the CRDT you reach for is Yjs.
Two people edit concurrently, both documents converge, no locks and no operational transform server. Yjs has ready-made backends — y-websocket, and y-durableobjects for Cloudflare specifically. Wire one up and you have collaboration in an afternoon.

We could not use any of them, and the reason is one sentence in the Yjs sync protocol: the server computes state vectors and diffs.

When a client connects, the standard protocol has it send a state vector — a summary of what it already has — and the server replies with exactly the updates that client is missing. That is an efficient design and it requires the server to parse the updates. A server that can parse Yjs updates is a server that can read the document.

For most products that is fine. For this one it defeats the entire premise. So the sync protocol had to be replaced with one where the server understands nothing.

The protocol

Every frame is one type byte and an opaque payload. The payload is AES-256-GCM
ciphertext produced with a key the server has never seen.

UPDATE          client → room → everyone else   an encrypted Yjs update, appended to a log
UPDATE_TAGGED   room → everyone else            the same, with the sender's id in front
SNAPSHOT        client → room                   an encrypted consolidated state; replaces the log
AWARENESS       client → room → everyone else   cursors and selections; relayed, never stored
SYNC_REQUEST    client → room                   "I am listening, send me the log"
SYNCED          room → client                   "that is all of it"
RESYNC          room → client                   "somebody compacted; drop what you have"

The room appends UPDATE payloads to a log and fans them out. It never merges anything, because it cannot. A client joining receives the entire log and replays it locally; Yjs converges regardless of order, so this works, but the log obviously cannot grow forever.

Compaction is therefore client-side. Periodically a connected client encodes the whole document as one update, encrypts it, and sends SNAPSHOT. The room replaces its log with that single blob in one transaction, keeps a copy as a checkpoint, and tells everyone else to resync. The server has performed a garbage collection on data it cannot read, by being told the answer.

This is the central trade. The client does the reconciling that a normal collaborative server would do for you. In exchange the server is a dumb pipe that a breach would yield nothing useful from.

The Cloudflare parts, and why each one earns its place

Durable Objects: one room per map

A Durable Object is a single-threaded, globally-unique, addressable object with its own storage. One per map, named by the map id:

const room = env.MINDMAP_ROOM.getByName(mapId);

Every client for a given map reaches the same instance, anywhere in the world. That single sentence removes an entire category of infrastructure: no Redis for fan-out, no lock service, no leader election, no sticky sessions. The room is the coordination point, and it is the only one.

The object holds its own SQLite database, so the encrypted update log lives with the object that serves it rather than in a shared database everything contends for.

WebSocket hibernation: idle rooms cost nothing

The natural worry with an object-per-map is cost. A team leaves a map open over lunch and you are paying for an idle process for an hour.

Hibernation
solves it: the runtime evicts the object from memory while the WebSockets stay open, and revives it on the next frame. You are billed for work, not for waiting.

The catch is real and shapes the code: instance state does not survive hibernation. Anything in a class field is gone between frames. So per-connection state lives on the socket's own attachment:

server.serializeAttachment({ mapId, userId, username, colo,
                             windowStart: Date.now(), framesInWindow: 0 });

Our per-connection frame budget lives there for exactly this reason. A rate limiter kept in a field would silently reset every time the room went to sleep — which is to say, it would not be a rate limiter.

D1: identity, membership, key envelopes

Content is unreadable, but there is metadata a server necessarily has: who exists, who is a member of which map, and each member's wrapped key.

The map key is wrapped separately per member using a hybrid KEM — X25519 and ML-KEM-768 together, so a recording-now-decrypting-later attacker has to break both. D1 stores the envelope; only the member's own private key opens it, and that private key is itself wrapped under a key derived from their password with Argon2id.

R2: durability that needs no key

The room copies its log to R2 hourly. There is nothing to encrypt on the way out — the log already is ciphertext, and the object has no key to add another layer with even if that helped.

Rate Limiting, Analytics Engine, Cron

Native rate limiting bindings on sign-in and invitations. Analytics Engine for delivery metrics — event names, ids, durations, never content. A nightly cron to purge soft-deleted maps.

Each of these would be a service to run. Here they are four lines of config.

Five things that were not obvious

Sync has to be client-initiated. The first version pushed the backlog the moment a socket opened. Across a service binding, frames sent before the client's own listeners are attached are simply lost. One extra round trip — SYNC_REQUEST — removes the race entirely and lets the client decide when it is
ready.

A Yjs type can be integrated in exactly one place. Duplicating a node copied its fields, and one of those fields was a Y.Text holding the node's notes. Setting the source's own instance onto the copy produced a document that looked perfectly correct locally and an update that threw inside Yjs on every other machine. The local editor was the one place the bug was invisible. The fix is
one word — value.clone() — and the lesson is the test:

const remote = new Y.Doc();
Y.applyUpdate(remote, Y.encodeStateAsUpdate(doc)); // must not throw

Assert that an update still applies on a peer, not just that your own document looks right.

Compaction that counts the wrong events never fires. Ours triggered on updates received. A room with one person in it receives nothing, so it never compacted, and a solo editing session grew its log without bound until somebody else happened to join. Own edits count now.

A fixed backup key is not a backup. Writing every hourly snapshot to latest.log means a corrupted log is faithfully copied over the last good copy within the hour. Date the key, keep N, prune.

Authorization checked at connect is not checked again. Removing a member deleted their row and their key envelope, and their still-open WebSocket carried on receiving every edit until they closed the tab. Removal has to close the socket explicitly.

What this architecture genuinely gives up

Being honest about this is more useful than a list of wins.

Metadata is visible. The server knows who is connected to which map, when, and how much traffic there is. It cannot see a title or a single character of content, but the shape of a collaboration is not hidden.

The client does more work. Joining means replaying a log rather than receiving a computed diff. Compaction keeps that log short, but a client that joins a busy room does more than it would against a server that could merge.

No server-side search, no server-side anything. Every feature that would normally be "add an endpoint" is either a client feature or does not exist.

Removal is not retroactive. No re-keying on member removal in v1. What someone already decrypted, they have.

Was it worth it

The feature is indistinguishable from an ordinary collaborative editor when you use it. Cursors move, text merges character by character, someone joins late and sees everything.

The difference only shows when something goes wrong somewhere else. What an operator can hand over is what an operator holds, and here that is encrypted blocks and the knowledge that a session happened.

Cloudflare's primitives are what made the trade affordable. A Durable Object per map with hibernation gave a single coordination point per document that costs nothing while idle — which is precisely the shape a per-document collaboration server wants, and precisely the thing that is tedious to build and operate yourself.

MindMapVault is an end-to-end encrypted mind mapping tool.
Live collaboration is in testing and ships to Cloud accounts alongside SSO — the
announcement for people who use it, rather than build it.

One Backend, Every Screen: I Built a Cross-Platform Audio App the 'Wrong' Way

Kornel Maraz — Fri, 04 Sep 2026 14:58:02 +0000

Every "build in public" thread and every YouTube growth guru tells you the same thing: pick the smallest possible surface, ship the lowest-effort thing that gets the biggest effect, validate, iterate. It's good advice. For this project I did almost the exact opposite — on purpose — and I want to be honest about why, and what it actually cost.

I'm building own.audio: a private home for the audiobooks, music, and podcasts a family already owns, playable on every device they actually use, with a real management story for the one person in the house who ends up being the admin. That product — every device, plus admin — is the reason the low-effort path was the wrong path. This is the long way round, and I'd take it again.

The false start: a web app for a thing nobody uses on the web

I started where a web developer starts: a backend in Rust with Axum, and a React front end on top of it. Clean, familiar, fast to move.

Then it hit me that I was building the wrong surface. This whole product lives on phones and speakers — music and audiobooks get consumed on a mobile device, or at least controlled from one while they play on some speaker across the room. The web app was the thing I knew how to build, not the thing people would actually live in. And as I kept pushing features into the backend, the React front end just fell further and further behind. It was a tax I was paying for a surface that wasn't the point.

The sprawl trap

So I tried to do the sensible unified thing: one app that handled books,
podcasts, and music together. But keeping that coherent turned into a mess — the backend started sprouting separate combinations for books, separate for podcasts, separate for music, and the whole thing got bushy. Too many branches, too much special-casing, no clean spine. That wasn't the way either. I could feel it turning into the kind of codebase you dread opening.

That's the moment I made the call that shaped everything after: do the
thorough thing, not the clever-minimal thing — because a family audio product that has to work on every screen and give the household admin real control doesn't have a lowest-effort version that's actually good.

Mac first — the admin's control room

I started with the Mac app, and starting there was deliberate. It's the control room for the person who manages the family's library: a place to play everything — music, audiobooks, playlists, all of it — and, crucially, to manage it.

That management story is where the interesting work was. The Mac app is also a bridge to the self-hosted world: it connects to Navidrome and Audiobookshelf — play from them, download from them, and upload into the cloud — so someone who has been running their own server, and is tired of it, has a real path to move their collection over instead of starting from zero.

The hard part: the sync client

The centerpiece of the Mac app, and the single hardest thing I've built for this project, is the sync client. The home admin can sync the entire collection on their own terms, and "on their own terms" is doing a lot of work in that sentence. It meant:

Bandwidth throttling, so syncing a large library doesn't strangle the household's connection.
Resumable uploads, so a transfer picks up where it left off instead of starting over.
Robustness across reconnects — the whole thing hardened so that when the connection drops and comes back, it recovers and keeps going rather than giving up.

On top of transfer, it had to understand the files: metadata lookup for music, identification for audiobooks, artist images pulled from Wikipedia (with proper sourcing), and finally the AI pieces — narrating a book, or translating a podcast episode into a narrated version. None of that is glamorous, and all of it is the difference between "a folder of files" and "a library."

Here's the honest bit: sync was miserable until it wasn't. Once it actually worked — reliably, resumably, politely — everything after it was a joy. The hard foundation is what made the rest fun.

Why backend-first paid off

I didn't touch iOS until the Mac client was done and every feature — including full offline playback — worked against the Rust/Axum backend. That patience was the whole point. Because when I finally started the iPhone apps, I could reuse the shared backend code I'd already written for the Mac app. The iOS apps ride on the same backend brain. The thorough, slow foundation turned the second platform from "build it again" into "put a native face on what already works."

One brain, different faces — on purpose

This is the design decision I'm most sure about: the shared backend is one brain, but each app wears a different face, and it should.
You don't listen to music the way you listen to an audiobook, so the apps don't pretend you do. I ended up building two entirely different kinds of player: one for podcasts and audiobooks, and a separate one for music — because music needs FLAC and lossless playback, an advanced equalizer, and crossfade that mixes the last five seconds of one track into the first five of the next. That's not a skin on the same player; it's a different player. Across the three audio apps — books, podcasts, music — the interface genuinely differs, and only the brand ties them together.

That's the opposite of forcing one uniform UI everywhere, and I think it's the honest choice: consistent identity, deliberately native and content-appropriate interfaces.

iPad and iOS: where the platform gives back

Extending to iPad was, thanks to SwiftUI and native components, mostly a matter of fine-tuning details rather than rebuilding. And the advanced testing and automation you get in the Swift world genuinely make this a pleasure — for a developer, it's a treat. Apple's platform gives back the effort you put into learning it.

Android: everything works, and I don't love it

Then Android. And I'll be candid, because pretending otherwise helps no one: the fragmentation — of the libraries and of the language itself — is its own extra adventure. Building and compiling feel, to me, a couple of generations behind iOS. Everything can be done, it just takes longer, and I don't enjoy it as much.

Keeping the design consistent with iOS using standard libraries is genuinely hard, and I refused to go into exotic-library territory to force it. So the Android UI ends up different from the iOS one. I don't love that either — but I believe Android users will appreciate what they get in exchange: reliability, native libraries, and consistency with the other Android apps already on their phone. Fighting the platform to match iOS pixel-for-pixel would have served my sense of tidiness, not the person holding the phone.

The chapter that wrote itself: cars and voice assistants

CarPlay and Android Auto deserve their own chapter, except the chapter is short: Apple and Google have caught this so beautifully that the developer does almost nothing. The same goes for Siri and Gemini. Every so often the platform just hands you a hard problem, already solved. Good job, both of you — genuinely.

And then the web app was easy

Having built all of that, I came back around to a React app on the Rust
backend — and after everything else, it was basically child's play. The surface I started with, and abandoned as the wrong first move, became the easy last one once the brain behind it was solid.

That's where I stand now. The plan is to get it into production before the end of the year.

Would I do it the "wrong" way again?

Yes. For a lot of products, the guru advice is right — find the smallest surface, ship it, learn. But when the product's whole promise is "your audio, on every screen your family uses, managed properly," there isn't a lowest-effort version of that promise worth shipping. The thorough path — one shared Rust backend, a Mac control room first, a hard-won sync client, and native, deliberately different faces on every platform — wasn't the efficient way to a demo. It was the only honest way to the actual product.

I'm building own.audio solo — a private home for the audiobooks, music, and podcasts you actually own. It's pre-launch; I'm aiming to ship before year-end, and writing the build up as I go.

Translating any podcast episode for about a dollar: the architecture, and the one rule that shaped it

Kornel Maraz — Thu, 03 Sep 2026 17:05:15 +0000

A friend of mine doesn't speak English. I do most of my podcast listening in English. Every so often I hit an episode worth passing on — an interview, some strange little history segment — and I want to send it to her, and I can't. A summary isn't the episode. A translated transcript isn't something you listen to on a walk.

It turned out I'd been sitting on the pieces to fix this for months. This is the architecture I landed on, and the one design rule that shaped everything else. No code — just the shape of the thing and the decisions that mattered.

The insight: it wasn't a new feature

I'm building a personal audio library as a side project. One thing already shipped was AI-narrated audiobooks: take a manuscript, translate it if needed, run it through a neural text-to-speech voice, stitch the result into a real audio file. Two managed services doing the heavy lifting — machine translation on one side, neural TTS on the other — with my own orchestration in between.

A podcast episode is, structurally, a much shorter audiobook. That's the whole thing. I didn't need to build "podcast translation." I needed to point a pipeline I'd already written at a different kind of input.

That reframing is the most useful architectural move I know: before building a feature, check whether it's a new shape or just a new input to a shape you already have. This was the second.

The pipeline, end to end

 Podcast RSS feed
      │
      ▼
 Find <podcast:transcript>  ──►  no transcript?  ──►  feature not offered
      │                                                (hard stop — see below)
      ▼
 Fetch the podcaster's own transcript text
      │
      ▼
 Machine translation  (per-character, managed service)
      │
      ▼
 Neural TTS  (per-character, managed voice)
      │
      ▼
 Stitch → single playable audio file
      │
      ▼
 Store in the requester's own library (household-scoped)

Everything interesting is in two places: the hard stop near the top, and the scope at the bottom.

The one rule: never run speech-to-text

The obvious architecture is: transcribe the audio with speech-to-text, translate that, narrate the result. I deliberately did not do that, and it's the single decision I actually agonized over.

Speech-to-text makes mistakes, and translation compounds them. A mis-heard word becomes a mistranslated sentence becomes a confidently narrated line that is simply wrong — with nothing in the output pointing back at where it broke. For a toy, that's an annoyance. For something a person might rely on to understand what someone actually said, it's a trust problem, and it gets worse the more the feature is used.

So the rule is: this only works on episodes that publish a transcript. Podcasting 2.0 added a <podcast:transcript> tag to the RSS spec a few years ago, and a meaningful and growing minority of shows already attach one. If a transcript exists, I translate the podcaster's own published words. If it doesn't, the feature isn't offered for that episode. No guessing, ever.

Architecturally this is a quality gate placed at the input, not the output. Instead of building elaborate confidence-scoring and error-handling downstream to cope with bad STT, I refuse the bad input at the door. The system can only be asked to do the thing it can do well. That single constraint deleted an entire category of downstream complexity — and it's why I trust the output enough to ship it.

The cost model, and why it's quoted up front

Managed translation and TTS both bill per character, so the unit economics are legible: cost is translation-per-character plus narration-per-character, marked up enough to be sustainable, and capped so it never exceeds the up-front quote.

A real measurement, not a round marketing number: one episode of a (faintly ridiculous) British royal-gossip podcast that happened to be in my test feed — 8,570 characters of transcript, English to German — landed at 90 cents. A typical 5–15 minute episode comes out around a dollar.

The architectural point: because the price is derived from the transcript length before any paid API call runs, I can show the user the exact cost and get consent before spending anything. No surprise bills, no "estimated." The quote is the cap.

Latency, measured honestly

I timed it from the database row's own timestamps rather than a stopwatch, because I wanted a number I could stand behind: a 9-minute episode, translated, narrated, and assembled into a playable file, in 93 seconds.

That number changes the UX category. At 93 seconds, "translate this episode" stops being a batch job you plan around and becomes something you kick off while still looking at the episode list.

The boundary is part of the design

Two scope decisions are deliberately baked into the architecture:

It's one voice. Host, guest, narrator — all the same TTS voice. It won't catch tone shifts, and niche names occasionally come out wrong. It is not a dub and was never meant to be.
It's strictly personal. The translated audio is a derivative work of someone else's content, generated on request, and it stays in the requester's own library — scoped to their household, not redistributed to the world. (An early version had a scoping bug that locked it to just the one requester; the fix widened it to the household, which is the correct boundary — not wider.)

That personal scope isn't a limitation I'm apologizing for; it's the line that makes the feature defensible to build at all.

What I'd take to the next feature

Four things generalize well beyond this:

New input, not new system. The cheapest powerful feature is an existing pipeline pointed somewhere new. Look for that before building.
Put the quality gate at the input. Refusing bad input is often simpler and more trustworthy than tolerating it downstream. "We don't do that case" beats "we do it badly."
Derive the price before you spend. If you can quote the cost up front from cheap inputs, you can get real consent and cap the risk.
Measure the real numbers. "A few minutes" is a hand-wave; "93 seconds, from the timestamps" is something you can design a UX around.

The result is what I've started calling an 80% solution, on purpose: one voice, transcript-only, personal-scope. If the alternative is not understanding the episode at all, 80% is a genuinely good outcome — and it's the difference between hearing something today and never hearing it, because nobody commissions a real translation for one podcast episode.

I write about building own.audio, a personal library for audiobooks, music, and podcasts you actually own. It's a pre-launch side project; the fuller write-up of this feature, with screenshots, is on the blog. The product-design side of this same decision — why shipping something deliberately imperfect was the right call — is a separate piece.

What maintaining react dependencies costs

Kornel Maraz — Sat, 08 Aug 2026 15:11:59 +0000

Serious software doesn’t collapse because of a missing feature.
It collapses because someone skipped a year of boring dependency maintenance.

A CI job called Security Guard went red this week. It runs pnpm audit on every push, and it had found seven vulnerabilities in one of our frontends. That sounds like a small problem. It took most of a working day to close properly, and the shape of that day is worth describing, because it is the recurring cost of building on the React ecosystem and almost nobody budgets for it.

What the audit actually said

The first surprise was that the failing job was not the whole picture. The report I was looking at came from our admin frontend and listed seven findings. The main application, audited the same way, had thirty.

Thirty sounds alarming until you split them by where they live:

Build toolchain: vite, postcss, nanoid, @babel/core, brace-expansion, fast-uri. These run on my machine and in CI. They never reach a user's browser.
Runtime: dompurify, pdfjs-dist, react-router. These are compiled into the bundle that every user downloads and executes.

That distinction matters more than the severity labels. pnpm audit reported four "high" findings in the build toolchain and ten "low" and "moderate" ones in dompurify. But dompurify is the HTML sanitizer we use when rendering notes. A sanitizer bypass in a note-taking application is cross-site scripting in the user's own content. Ten moderate findings there deserved more of my attention than four high ones in a dev server I run locally.

An audit tool cannot make that judgement for you. It does not know which packages you ship. That first triage is human work, and it is the part that decides whether the rest of the day is spent well.

The trap of upgrading to latest

My first instinct was the obvious one:

pnpm up vite@latest

That moved Vite from 6.4.2 to 8.2.1. The build still passed, which was almost the worst outcome, because it made the change look safe. It was not: the patched version I actually needed was 6.4.3. I had accepted two major versions of behavioural change to fix a security advisory, and I would have found out what broke somewhere later, in a context with no obvious connection to this afternoon.

I reverted it and moved to minimum patched versions instead. Slower, and much easier to reason about when something misbehaves next month.

The same trap caught me again a step later. @vitejs/plugin-react@latest resolved to 6.0.5, which declares vite@^8.0.0 as a peer dependency. With Vite pinned back to 6.4.3, the install produced an unmet peer warning. The fix was version archaeology: version 5.2.0 of the plugin supports vite@^4 || ^5 || ^6 || ^7 || ^8. Not the newest, but the one that fits the rest of the tree.

This is the actual work. Not "upgrade the packages" but "find the combination of versions that are simultaneously patched, mutually compatible, and stable for a while".

The migration that was not a migration

The finding I dreaded was react-router. The advisory said the patched version was >=7.18.0, and we were on 6.30.4. There is no patched release in the 6 line, so the only route to a clean audit was a major version upgrade — the kind of change that usually means a day of testing on its own.

Two checks turned that around in about ten minutes.

First, the peer dependencies of react-router@7:

{ react: '>=18', 'react-dom': '>=18' }

React 7 does not require React 19. We could stay on 18.3.1. No React upgrade, no ripple through every component.

Second, our own codebase already contained the answer. Our open source desktop build had been moved to react-router-dom@7 earlier, and it still imports from the same package name with the same API surface:

import { BrowserRouter, Navigate, Route, Routes } from 'react-router-dom';

All twelve call sites in the application use BrowserRouter, Routes, Route, Navigate, Link, useNavigate, useParams, useSearchParams and Outlet. Every one of those is unchanged between v6 and v7. The "migration" was a single line in package.json. Type check passed, build passed, three advisories disappeared.

I want to be honest about the lesson here, because it cuts both ways. The upgrade was easy because we had done it once already elsewhere and because we had never reached for the exotic parts of the router. Projects that use data loaders, deferred routes or the framework mode would have had a real migration. Restraint in what you adopt is what makes upgrades cheap later.

Dependencies you never chose

That left ten findings in packages nobody on the team had ever typed:

.>vite-plugin-pwa>workbox-build>glob>minimatch>brace-expansion
.>vite-plugin-pwa>workbox-build>ajv>fast-uri

You cannot upgrade these directly. You either wait for the maintainers above them to release, or you override the resolution yourself. We already had a small pnpm.overrides block for exactly this, so I extended it.

The subtlety is in the ranges. brace-expansion had two versions installed at once, 2.1.0 and 5.0.6, needed by different parts of the tree. A blanket override to the newest would have forced 5.x onto packages written against 1.x. The override has to name the range:

"brace-expansion@<2.1.4": "2.1.4",
"brace-expansion@>=5.0.0 <5.0.9": "5.0.9",
"fast-uri@>=3.0.0 <3.1.5": "3.1.5"

Overrides are a debt of their own. Each one is a note saying "I know better than the resolver", and each needs removing when the upstream package catches up. They should be narrow and few.

The ledger

At the end of it: thirty findings to zero in the main app, seven to zero in the admin app, both verified the way CI does it, with rm -rf node_modules and a frozen lockfile install. Type check and build green in both.

Time spent: roughly half a day, most of it reading advisories, checking peer dependency tables and undoing one upgrade that went too far.

And here is the part I keep coming back to. Almost everything in that day was given to me for free. I did not write a router, a PDF renderer, an HTML sanitizer or a build tool. Someone else maintains all of them. Someone else runs the infrastructure that discovered these vulnerabilities, wrote them up, assigned severities and published them in a machine-readable form that my CI could consume without me configuring anything. The advisory database, the audit tooling, the packages themselves — all of it arrives at no cost.

What is not free is the fit. The ecosystem hands you a pile of excellent, independently maintained parts, and the work of holding a particular combination of them together, on your project, on a version of React you have chosen, remains yours. It is not hard work. It is not even especially interesting work. But it is real, it does not go away, and it lands about once a quarter.

Half a day every three months is a genuinely good deal for what you get back. It stops being a good deal the moment you decide it is not work, skip it for a year, and then face twelve months of accumulated major versions in a single sitting — usually because something has already gone wrong.

It could have gone worse, and elsewhere it has

I should be careful not to make this sound universal, because the same job on our Rust backend is open on my machine as I write this, and it is not going to be an install command.

cargo audit flagged quick-xml (RUSTSEC-2026-0195 and RUSTSEC-2026-0194, both denial of service) and rgb. We do not depend on any of them. The chain is:

pprof (feature "flamegraph") → inferno → quick-xml

We use pprof to profile the backend. Its flamegraph feature pulls in inferno to render the SVG, and inferno uses an XML writer to produce it. The vulnerability is three levels below anything we chose, in a component whose only job is writing the tags of a picture.

There is no version to bump here. quick-xml had not published a fix we could take, and the crate was only present because of one feature flag. So the fix was to stop pulling that branch of the tree in at all:

-pprof = { version = "0.15", features = ["flamegraph"] }
+pprof = { version = "0.15", features = ["protobuf-codec"] }

The version did not change. Nine crates left the lockfile. And that is where the cost showed up, because the feature does not just add a renderer, it decides which API exists. report.flamegraph(&mut file) was simply gone. The profiler now hands back a protobuf message that you serialise yourself:

-if let Ok(mut file) = File::create("/tmp/backend-flamegraph.svg") {
-    let _ = report.flamegraph(&mut file);
+if let Ok(profile) = report.pprof() {
+    if let Ok(bytes) = profile.write_to_bytes() {
+        if let Ok(mut file) = std::fs::File::create("/tmp/backend-profile.pb") {
+            let _ = file.write_all(&bytes);

Eleven lines rewritten, the imports changed, and the output is no longer an SVG I can open in a browser. It is a .pb file for go tool pprof or speedscope. A working habit changed because of a denial-of-service bug in an XML writer we never asked for.

That is the difference in one picture. On the JavaScript side, closing thirty findings meant editing a manifest and choosing versions carefully. On the Rust side, closing three meant reading someone else's feature flags, understanding why a crate was there at all, and then rewriting our own code and changing how we profile.

The compiler does at least tell you. In JavaScript the upgrade usually installs cleanly and the surprise arrives later, at runtime, in front of a user. In Rust it arrives immediately, as a wall of red text, and nothing ships until it is dealt with. I would rather have the wall of red text. But it is not half a day, and it is worth knowing which of the two you are signing up for.

Put it in the calendar. Ninety minutes of triage, deciding what actually ships to users. A couple of hours of finding versions that agree with each other. A clean install and a real build to prove it. Then close the laptop and go back to the product.

Mobile-First Mind Mapping in 2026: PWA, Dark Mode, and Leaving Java Desktop Behind

Kornel Maraz — Sat, 11 Jul 2026 17:20:13 +0000

The first mind mapping tool I ever used was FreeMind. I wrote about this in Part 0 — it left a strong impression. Keyboard-first, offline, fast. But it ran on Java, on a desktop, and only on a desktop.

In 2026, that is not enough.

This part is about how MindMapVault handles the shift from desktop to everywhere. The mobile experience, the PWA implementation, the dark/light mode, and what we learned from building it with React rather than reaching for a native mobile SDK.

The honest picture first

Desktop is not dead. If you work on a large mind map for an hour, you want a big screen and a real keyboard. That has not changed.

But the way people use apps has changed. The majority of internet usage is now on mobile. For productivity apps specifically, the pattern is: think on the train, elaborate on the laptop, review on the phone, act wherever. A product that only exists on a desktop loses people at every gap.

FreeMind and Freeplane — tools I have genuine respect for — have no mobile story. They are Java desktop applications. You cannot install them on an iPhone. You cannot open your maps on an Android device. The .mm file on your laptop is invisible to your phone unless you sync the file manually to some cloud folder, and even then you have no editor to open it.

WiseMapping solved the desktop part — it is browser-based — but it has no PWA and no mobile-optimized layout. It also runs server-readable (the database holds plaintext maps), which is a different kind of problem.

The requirement we set for MindMapVault: it has to work, without compromise, on desktop and mobile, with the same encryption model on every platform.

Why PWA, not native apps

The first question in most mobile discussions is: should you build native apps? App Store listing, native UI components, push notifications, the whole ecosystem.

Our answer was no, not yet, and here is why.

PWA solves the real gap for most users. The main friction is not "I need a native feel." It is "I need to be able to open my mind map on my phone." A Progressive Web App — installable from the browser with "Add to Home Screen" — solves that completely. No store review. No 200 MB download. No update lag.

App stores add overhead that does not benefit the user. Every release goes through a review queue. Approval can take days. You cannot ship a critical encryption fix on a Friday afternoon without waiting. With a PWA served from your own infrastructure, the user gets the update the next time the service worker refreshes — typically within 24 hours, silently.

The codebase stays unified. One React codebase, one set of components, one encryption implementation. The alternative — maintaining a web app, an iOS app, and an Android app — would triple the surface where encryption bugs could live. For a security-sensitive product, that is a serious risk.

The PWA implementation

MindMapVault's frontend is built with React 18, TypeScript, Vite 6, and Tailwind CSS. The PWA layer uses vite-plugin-pwa and Workbox.

// main.tsx — PWA registration
import { registerSW } from 'virtual:pwa-register';
registerSW();

That one line, plus the vite-plugin-pwa configuration, handles:

Generating the manifest.webmanifest with the correct app name, icons, and display mode
Generating a sw.js service worker via Workbox
Caching the app shell, assets, and pre-cached routes
Background sync and update checking

The manifest.webmanifest controls how the app appears after installation: name, icon, theme color, whether it opens with a browser chrome or full-screen. Users who tap "Add to Home Screen" on iOS Safari or Chrome on Android get a full-screen experience identical to a native app.

What Workbox does for you

Workbox is Google's service worker library. It handles the parts that are genuinely complex to do by hand:

Precaching the built assets (JS bundles, CSS, icons) with content hashes. The service worker knows exactly which files are stale after a new build.
Runtime caching for API calls and dynamic resources.
Background sync so actions that happen offline are retried when connectivity returns.
Update flow notifying the running app when a new service worker is ready to activate.

For a security-sensitive app, one thing matters: the service worker should not cache authentication credentials or decryption keys. The MindMapVault encryption model already handles this correctly — the server only ever sends ciphertext, and decryption happens entirely in JavaScript. No sensitive plaintext ever passes through the service worker cache.

Dark/light mode — the right way

Every modern application in 2026 must support dark and light mode. This is not aesthetic preference. It is accessibility and system integration.

Here is how we implement it:

// main.tsx — applied synchronously before first render
(function applyStoredTheme() {
  try {
    const raw = localStorage.getItem('mindmapvault-theme');
    if (!raw) return;
    const { state } = JSON.parse(raw) as { state: { mode?: string } };
    if (state?.mode === 'light') document.documentElement.classList.add('light');
  } catch { /* ignore */ }
})();

This runs before createRoot — before React renders anything. That is the key. If you apply the theme inside a React effect or even a component, you get a Flash of Unstyled Content (FOUC): the page loads dark, flickers white, then goes dark again. That is jarring on any platform and is particularly bad on mobile OLED screens where the flash literally causes a brightness spike.

The pattern: read from localStorage, synchronously apply a class to <html>, then let React render with the correct theme already set.

The CSS side uses class-based switching:

/* Default: dark */
:root {
  --bg: #0f172a;
  --text: #f8fafc;
}

/* Light override */
:root.light {
  --bg: #f8fafc;
  --text: #0f172a;
}

This cooperates naturally with Tailwind: dark utilities (dark:bg-slate-900) work alongside the class-based approach via Tailwind's darkMode: 'class' config.

The user can also set a custom accent color, which is applied the same way — as a CSS custom property set synchronously before render.

Responsive layout with Tailwind

The mind map canvas itself is @xyflow/react — a React component for node-based interactive diagrams. It handles pan and zoom natively on both mouse (wheel + drag) and touch (pinch + drag). No extra touch event handling needed for the canvas.

The surrounding UI — vault list, toolbar, settings, node editing panels — is built with Tailwind responsive utilities:

<!-- Sidebar: full width on mobile, fixed width on desktop -->
<aside class="w-full md:w-64 lg:w-72">
  ...
</aside>

The window.matchMedia('(max-width: 900px)') check we use in the FOSS demo (to adjust the initial canvas zoom and pan position for small screens) is the one place where we make a JavaScript decision based on screen size rather than a CSS decision. On a phone, the initial canvas view zooms out and centers so the root node and first level of branches are visible without scrolling.

What this means for product builders in 2026

A Java desktop application in 2026 is not wrong — it is just narrow. It reaches exactly one kind of user in exactly one context.

The React + PWA stack we describe here reaches the same user on their desktop, their phone, and their tablet, with the same code, the same encryption, and the same zero-knowledge model. The overhead of maintaining one additional layer (vite-plugin-pwa + Workbox) is low. The reach multiplier is real.

The concrete lesson:

Ship PWA before native apps. It covers 90% of the mobile use case with 10% of the cost.
Apply dark/light mode synchronously, before first render. FOUC is a worse experience on mobile than on desktop.
Do not cache sensitive data in the service worker. Review what Workbox precaches and what it does at runtime.
Let the responsive CSS framework handle most of the layout adaptation. Reserve JavaScript media query checks for canvas-specific adjustments.
Desktop is not dead; it just cannot be the only target anymore.

MindMapVault is a privacy-first mind mapping application with zero-knowledge encryption. Try it at https://www.mindmapvault.com.
The FOSS offline only edition is open-source at https://github.com/mindmapvault/mindmapvault-foss
Server self hosted edition is open sourced at https://github.com/mindmapvault/mindmapvault-server

Want to try the mobile canvas on your phone right now? Open
https://mindmapvault.github.io/mindmapvault-foss/mobile-demo/
- no install, no account, works as a PWA.

Modernize or Fade Away: A Builder's Field Guide to Core Rewrites

Kornel Maraz — Sat, 30 May 2026 08:43:16 +0000

If you have worked on a long-lived product, you probably know this feeling:

"We can still ship, but every release hurts more than the last one."

That is usually not a team problem. It is a core architecture problem.

At some point, modernization stops being a nice-to-have refactor and becomes a survival decision. Not because rewrites are fun. Because the current system keeps multiplying cost in every direction: infra, feature delivery, onboarding, incident response, and roadmap confidence.

The Pattern You Have Seen Before

Across open source and enterprise software, the same sequence repeats:

The product grows feature by feature and accumulates architecture debt.
The core becomes a risk hotspot where simple changes require heavy ceremony.
New requirements arrive: scale, integrations, cloud-native ops, lower latency.
The old core can handle them, but only by adding expensive layers.
A cleaner alternative appears and moves faster with fewer people.

Postponing modernization does not avoid cost. It delays and compounds it.

Nextcloud as a Real-World Example

Nextcloud is successful, useful, and widely adopted. That is exactly why it is a useful case study.

It also carries the weight of a mature PHP monolith, strict backward compatibility pressure, and assumptions built for older infrastructure eras (POSIX-first storage, WebDAV-centricity, heavier metadata paths).

The project has mostly evolved by adding layers instead of replacing core boundaries. That is understandable, but it creates a familiar tradeoff:

Short term: feature continuity and ecosystem stability.
Medium term: rising operational complexity and slower delivery.
Long term: exposure to competitors built around modern primitives from day one.

This is not "monolith bad, microservices good." It is about architecture-requirement mismatch over time.

What "Not Modernizing" Really Costs

Avoiding deep core work can look roadmap-friendly, but the bill shows up everywhere:

Ops overhead: more RAM, more sidecars, more tuning, more runbooks.
Dev velocity drag: each feature collides with legacy constraints and migration baggage.
Integration friction: modern API/event/object-storage patterns are awkward to bolt on.
UX degradation: latency and responsiveness drift under real traffic.
Strategic risk: enterprise buyers compare TCO and reliability, not nostalgia.

If roadmap items keep being split, delayed, or overstaffed because of architecture constraints, that is your modernization signal.

RAM Comparison Snapshot

Below is a practical comparison for small production deployments. Numbers are representative ranges from real setups; exact values vary by workload and enabled modules.

Component	Nextcloud Typical Small Deployment	ownCloud Infinite Scale Typical Small Deployment
Web / PHP processes	500–1500 MB	40–80 MB
Database server	300–800 MB	not required (KV stores / embedded)
Cache (Redis)	50–200 MB	optional, low
Background jobs / cron	50–150 MB	30–60 MB per service
Storage service (S3/MinIO)	external; variable	100–300 MB for MinIO
Total small deployment	~1.2–3 GB RAM	~0.25–0.6 GB RAM

Takeaway: core architecture decisions directly shape hosting cost, performance predictability, and scaling headroom.

A Practical Modernization Playbook

You do not need a big-bang rewrite to modernize seriously. You need staged execution and explicit boundaries.

Replace one core boundary first Pick the area with the highest pain and lowest coupling (for example sync path, metadata indexer, storage adapter).
Put compatibility ahead of replacement Keep old and new paths running in parallel while migrating traffic gradually.
Instrument before and after Track p95 latency, memory per tenant/user, error rates, and lead time to production.
Design migration as product work Build migration tooling with rollback checkpoints and observable progress.
Invest in dev ergonomics early Cleaner runtime architecture that is harder to work on will still fail adoption internally.

Five Rewrite Triggers to Watch

If several of these persist for 2+ quarters, you are likely beyond "incremental cleanup":

Infra spend grows faster than user value delivered.
"Simple" features repeatedly need cross-team firefighting.
Performance regressions return after partial fixes.
New engineers need months to safely touch core areas.
Competitive gap is architecture-driven, not feature-driven.

The Product Angle Most Teams Miss

Modernization is not only engineering hygiene. It is a trust and product decision.

Users feel architecture through:

speed,
reliability,
migration friction,
and confidence the product will still be viable in 3–5 years.

If modernization is framed as cleanup, it is deprioritized.
If it is framed as delivery capacity + reliability + user trust, it gets funded.

Final Note

The market rarely kills products overnight. It slowly rewards teams that modernize before they are forced to.

Modernize early enough and you keep optionality.
Modernize too late and the rewrite still happens, just under pressure.

Part 8: Free Self-Hosted Mind Mapping for a Home Lab: Why I Put a Significant Part of MindMapVault on GitHub

Kornel Maraz — Fri, 29 May 2026 20:07:55 +0000

When people say they build a privacy-first product, I ask one simple question:

How much of the implementation story is publicly verifiable?

For MindMapVault, I decided to put a significant part of the project in public repositories because I do not want trust to depend only on polished copy.

Short background

Since my university studies, free and open-source software shaped how I learn and build.

I learned from maintainers I never met. I used products I could inspect, fork, and improve. That openness gave me a practical education I could never get from closed products.

Open sourcing this project is also a thank-you to that ecosystem.

Why this is important for private-thinking software

Mind maps are not harmless doodles.

They often contain strategy, unfinished research, priorities, and personal structure. If a product claims privacy, users should be able to evaluate whether boundaries are real.

Open repositories allow people to inspect:

architecture decisions
release history
deployment options
public issue and maintenance patterns

That does not guarantee perfection. But it does remove the black box.

For developers and operators, this also answers a practical question: can you run a self-hosted mind mapping app for free in a home lab and still evaluate the trust boundaries? In this case, yes.

Public links

Repositories

MindMapVault FOSS: https://github.com/mindmapvault/mindmapvault-foss
MindMapVault Server: https://github.com/mindmapvault/mindmapvault-server

Container images

GitHub Container Registry (MindMapVault Server): https://github.com/mindmapvault/mindmapvault-server/pkgs/container/mindmapvault-server
Docker Hub image: https://hub.docker.com/r/kornelko2/mindmapvault-server

Why home lab users care about this

When you run a free self-hosted mind mapping app in a home lab, you are not only looking for features.

You are also checking:

can I inspect the code path I am deploying?
can I follow release history and rollout changes safely?
can I keep infrastructure ownership without hidden lock-in?

Open-source repositories and public image links make those checks possible.

Practical outcomes of building in public

Better engineering hygiene

Public changes force clearer commits, documentation, and compatibility handling.

Better technical conversations

Feedback can be concrete because people can reference real files and real history.

Better trust posture

Users and teams can evaluate what is implemented instead of trusting only messaging.

Better self-hosted operations

Home lab and self-hosted users can review deployment docs, compare tags, and plan upgrades with fewer surprises.

What open source is not

Open source is not a license to expose secrets.

We keep a hard boundary between transparent implementation and private operational data. No private keys, tokens, or user data belong in public code.

Closing

I want this project to be understandable to people who care enough to inspect it.

Not because it is perfect, but because trust grows faster when code, decisions, and trade-offs are visible.

If that resonates, check the repositories, open issues, and challenge assumptions.

If your specific goal is a free self-hosted mind mapping app for your home lab, start with the public repos and container image links above, then verify the architecture against your own privacy requirements.

That is the kind of software culture I learned from, and the one I want to contribute back to.

Privacy-first mind mapping app. Part 7: Owning Your Workflow

Kornel Maraz — Mon, 11 May 2026 19:07:21 +0000

Most posts about self‑hosting or indie projects drift into marketing speak. This one doesn’t. This is simply how I build and ship MindMapVault — the real workflow, the real tools, and the real reasons behind them.

This chapter is about ownership. Not in the corporate sense, but in the “I want to understand and control my own tools” sense. If you’re building something solo, or experimenting with automation, or trying to level up your confidence as a developer, this might resonate.

Why I Self‑Host My Git Forge

I run a self‑hosted Forgejo instance on my NAS with a runner. Not because GitHub or GitLab are bad — they’re great — but because I know myself.

Sometimes I move fast.

Sometimes I forget things.

Sometimes I push .env values straight into a repo.

Keeping the forge and runner physically close to me solves that. It gives me:

control (no accidental secrets leaving my network)
convenience (fast CI, predictable environment)
confidence (I can experiment without worrying about leaking something)

And honestly? I just like the project. Forgejo is clean, lightweight, and fits the “local‑first” philosophy behind MindMapVault.

What I use it for

another Git remote
CI/CD workflows
automated checks
release builds
experiments that I don’t want to run on a public cloud

It’s not about paranoia. It’s about craftsmanship. When you own the forge, you own the workflow.

Automation Makes You a Better Developer (Especially Solo)

When you’re working alone, automation isn’t a luxury — it’s a survival mechanism.

My Forgejo runner handles:

type‑checking
offline‑parity checks
desktop build pipelines
release asset uploads
version bumping
changelog generation

This means I can focus on the actual product instead of the glue.

And here’s the interesting part:
AI tools like GitHub Copilot Agents changed the way I commit.

Not by writing code for me — but by making me more disciplined:

commits became larger but more coherent
changelogs became more structured
documentation became essential, not optional
project planning became a real process, not a TODO file

When AI helps you move faster, the meta‑work (planning, documenting, structuring) becomes even more important. Otherwise you drown in your own velocity.

Production Hosting: Simple, Predictable, Mine

I host production on a Czech community VPS: vpsFree.cz. It’s stable, affordable, and gives me the right balance of control and simplicity.

The setup is intentionally minimal:

backend (Rust)
Postgres
MinIO
Cloudflare Tunnel
Cloudflare Pages for the frontend

All running via a single docker-compose.yml, all credentials in a single .env file. when you are ready zyou just run docker compose up -d and in 6 seconds the new version, fix is up in production.

# ─────────────────────────────────────────────────────────────────────────────
# MindMapVault — local dev compose
# Manages the backend plus the local RustFS and PostgreSQL dependencies.
# Use `docker compose up` / `docker compose up --build`.
# ─────────────────────────────────────────────────────────────────────────────
services:
  minio:
    image: minio/minio:latest
    container_name: mindmapvault-minio
    restart: unless-stopped
    networks:
      - cryptmind
    ulimits:
      nofile:
        soft: 65535
        hard: 65535
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY:-minioadmin}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY:-minioadmin}
    ports:
      - "${MINIO_API_PORT:-9000}:9000"
      - "${MINIO_CONSOLE_PORT:-9001}:9001"
    volumes:
      - minio-data:/data
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:9000/minio/health/live >/dev/null || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 10s

  postgres:
    image: postgres:16
    container_name: mindmapvault-postgres
    restart: unless-stopped
    networks:
      - cryptmind
    ports:
      - "${POSTGRES_PORT:-5432}:5432"
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
      POSTGRES_DB: ${POSTGRES_DB:-cryptmind}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-cryptmind}"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 10s

  backend:
    build:
      context: .
      dockerfile: backend/Dockerfile.local
    container_name: mindmapvault-backend
    restart: unless-stopped
    networks:
      - cryptmind
    depends_on:
      minio:
        condition: service_healthy
      mongodb:
        condition: service_healthy
      postgres:
        condition: service_healthy
    ports:
      - "${BACKEND_PORT:-8090}:8090"
    volumes:
      - stoolap-data:/data
    environment:
      HOST: "0.0.0.0"
      PORT: "8090"
      MALLOC_ARENA_MAX: "2"
      MALLOC_TRIM_THRESHOLD_: "131072"
      MALLOC_MMAP_THRESHOLD_: "131072"
      MALLOC_CONF: ${MALLOC_CONF:-background_thread:true,narenas:1,dirty_decay_ms:0,muzzy_decay_ms:0,metadata_thp:disabled}
      DB_ENGINE: ${DB_ENGINE:-mongodb}
      POSTGRES_DSN: postgresql://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@postgres:5432/${POSTGRES_DB:-cryptmind}
      MINIO_ENDPOINT: http://minio:9000
      MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY:-minioadmin}
      MINIO_SECRET_KEY: ${MINIO_SECRET_KEY:-minioadmin}
      MINIO_BUCKET: ${MINIO_BUCKET:-mindmapvault-maps}
      MINIO_PUBLIC_ENDPOINT: ${MINIO_PUBLIC_ENDPOINT:-http://127.0.0.1:9000}
      MINIO_REGION: ${MINIO_REGION:-us-east-1}
      MINIO_PRESIGN_EXPIRY_SECS: ${MINIO_PRESIGN_EXPIRY_SECS:-3600}
      JWT_SECRET: ${JWT_SECRET}
      JWT_ACCESS_EXPIRY_SECS: ${JWT_ACCESS_EXPIRY_SECS:-900}
      JWT_REFRESH_EXPIRY_SECS: ${JWT_REFRESH_EXPIRY_SECS:-2592000}
      STRIPE_SECRET_KEY: ${STRIPE_SECRET_KEY:-}
      STRIPE_PUBLISHABLE_KEY: ${STRIPE_PUBLISHABLE_KEY:-}
      STRIPE_WEBHOOK_SECRET: ${STRIPE_WEBHOOK_SECRET:-}
      STRIPE_PRICE_PAID_YEARLY_ID: ${STRIPE_PRICE_PAID_YEARLY_ID:-}
      STRIPE_CHECKOUT_SUCCESS_URL: ${STRIPE_CHECKOUT_SUCCESS_URL:-https://mindmapvault.com/vaults}
      STRIPE_CHECKOUT_CANCEL_URL: ${STRIPE_CHECKOUT_CANCEL_URL:-https://mindmapvault.com/vaults}
      STRIPE_PORTAL_RETURN_URL: ${STRIPE_PORTAL_RETURN_URL:-https://mindmapvault.com/vaults}
      DISABLE_APP_LOGIN_TURNSTILE: ${DISABLE_APP_LOGIN_TURNSTILE:-false}
      ENABLE_DIAGNOSTICS_ROUTES: ${ENABLE_DIAGNOSTICS_ROUTES:-false}
      ENABLE_PPROF: ${ENABLE_PPROF:-false}
      PPROF_DURATION_SECS: ${PPROF_DURATION_SECS:-90}
      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-http://localhost:5173,http://tauri.localhost,https://tauri.localhost}
      RUST_LOG: ${RUST_LOG:-backend=info,tower_http=info}
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:8090/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 10s

cloudflared:
    image: cloudflare/cloudflared:latest
    container_name: mindmapvault-cloudflared
    restart: unless-stopped
    command: tunnel --no-autoupdate run
    depends_on:
      backend:
        condition: service_healthy
    environment:
      TUNNEL_TOKEN: ${TUNNEL_TOKEN}
    networks:
      - mindmapvault-network

volumes:
  minio-data:
    name: cryptmind-minio-data
  postgres-data:
    name: cryptmind-postgres-data

networks:
  cryptmind:
    name: cryptmind-network

then the docker ps looks like this:

CONTAINER ID   NAME                       CPU %     MEM USAGE / LIMIT   MEM %     NET I/O           BLOCK I/O   PIDS
468768ef5c79   mindmapvault-backend       0.00%     31.55MiB / 4GiB     0.77%     26.7MB / 4.73MB   0B / 0B     9
06c14906524a   mindmapvault-postgres      0.00%     31.82MiB / 4GiB     0.78%     2.17MB / 28.7MB   0B / 0B     7
d52f573bcdef   mindmapvault-minio         3.68%     86.56MiB / 4GiB     2.11%     3.65MB / 10.7MB   0B / 0B     13
27fcb47af8c7   mindmapvault-cloudflared   0.19%     16.31MiB / 4GiB     0.40%     132MB / 212MB     0B / 0B     13

No Azure.

No Firebase.

No vendor lock‑in.

Just a clean, reproducible, auditable setup.

Open‑Sourcing the Local‑First Version

And when I have what to show then I pushed the FOSS version of MindMapVault here:

https://github.com/mindmapvault/mindmapvault-foss

It’s a local‑first, privacy‑focused, offline‑capable mind‑mapping desktop app.

No cloud.
No telemetry.
No account.

If you review the code and see weak spots, please comment directly. I welcome criticism — it’s the only way a solo project grows.

GitHub Wiki & Pages — Free Tools Many Developers Underuse

The GitHub Wiki is a perfect home for these research notes once they mature.
It’s Markdown-native, versioned, and acts as a clean documentation hub.
I even use it as a lightweight blog for deeper technical posts.
GitHub Pages hosts the interactive MindMapVault demo — free, fast, and frictionless.
Together, Wiki + Pages + Actions + runners make GitHub a full publishing and documentation platform.

What this gives you for free:

Wiki for architecture docs
Pages for interactive JS demos
Actions for CI
Runners for automation
A complete developer ecosystem

Research First — Write It Down Before You Build

Before implementing any feature, I create a small Markdown mockup in research/ or notes/.
It’s not a spec — just a quick outline of goals, constraints, and what “good” looks like.
This keeps the project coherent and gives Copilot the right context.
Even a rough sketch prevents future architectural mistakes.
For MindMapVault, every complex feature starts as a simple .md file.

Why this helps:

clarifies goals early
reduces rework
gives Copilot better context
documents decisions
keeps ideas discoverable

Goals
- Allow arbitrary file attachments (many per map) without transferring plaintext to server in encrypted mode.
- Use per-map buckets or per-map prefixes to keep attachments discoverable and scannable.
- Lazy-download UX: file blobs are fetched only when the user requests/downloads them.
- Provide secure presigned URLs for direct client upload/download while the server maintains metadata, access control, and versioning.

High-level design
- Storage layout (S3/MinIO recommended):
  - Bucket-per-map: `cryptmind-<map-id>` OR
  - Single bucket + prefix: `maps/<map-id>/attachments/<attachment-uuid>` (preferred if many buckets are undesirable)
- Object keys: `attachments/<attachment-uuid>/<sanitized-filename>` or `attachments/<timestamp>-<uuid>-<name>`
- Versioning: enable S3 versioning where possible; store `s3_version_id` in DB on complete.

Security & encryption
- Encrypted mode (server never sees plaintext or DEKs):
  - Client-side: encrypt attachment (AES-GCM or AES-SIV) on the client using the same client-side DEK management as mindmaps.
  - Send `encrypted: true` and minimal `encryption_metadata` (algorithm, non-secret IV/nonce, tag if detached) to server when initiating upload. Do NOT send DEKs.
  - Server returns presigned upload URL or accepts proxied upload; backend stores opaque object and writes metadata to DB.
  - On download, server issues presigned GET; client downloads then decrypts locally.
- Plaintext mode: files uploaded without encryption; server may perform virus scanning or content checks per policy.

Database schema (maybe)
- attachments
  - id: UUID (PK)
  - map_id: UUID (FK)
  - node_id: UUID (nullable) — attach to a node/note if applicable
  - name: TEXT (original filename)
  - sanitized_name: TEXT
  - content_type: TEXT
  - size_bytes: INTEGER
  - s3_key: TEXT
  - s3_version_id: TEXT (nullable)
  - uploaded_by: UUID (user id)
  - uploaded_at: TIMESTAMP
  - encrypted: BOOLEAN
  - encryption_meta: JSON (algorithm, iv, tag — non-secret values only)
  - checksum_sha256: TEXT (optional)
  - status: ENUM('pending','available','deleted')

Example: A Real Changelog Entry

This is what a typical release looks like now — structured, explicit, and automation‑friendly:

**[0.3.27] – 2026‑05‑03**

**Changed**
- Editor UX / Node Icons — Restored full node icon workflow in `MindMapEditor.tsx`:
  - toolbar icon picker
  - context‑menu icon action
  - keyboard shortcut `I`
  - inline icon rendering
  - multi‑select icon toggling
  - help panel + status bar hints
- Editor Components — Added reusable icon picker infrastructure (`MindMapIconPicker.tsx`, `DynamicLucideIcon.tsx`).
- CI / Release Automation — Modernized `.github/workflows/desktop-build.yml`:
  - upgraded actions
  - replaced deprecated upload steps
  - switched to Corepack for `pnpm`
  - kept `$GITHUB_OUTPUT` usage

**Validation**
- `pnpm exec tsc --noEmit` → clean
- `node scripts/check_frontend_offline_parity.mjs` → passed

This is the kind of detail that makes automation reliable and future‑you grateful.

Try the MindMapVault FOSS Interactive Canvas (Privacy‑First, Local‑Only Mind Mapping)

Kornel Maraz — Wed, 06 May 2026 07:01:00 +0000

MindMapVault FOSS is a privacy‑first, local‑only mind‑mapping app with a minimalist canvas and zero cloud dependencies. No accounts, no telemetry, no lock‑in.

This is a standalone post focused purely on the tool and your hands‑on experience.

This is a direct invitation from an engineer building in public: open the live demo, test it hard, and tell me what you think.

Try the interactive demo

Interactive canvas demo: https://mindmapvault.github.io/mindmapvault-foss/demo/
Project website: https://www.mindmapvault.com/
Full FOSS repository: https://github.com/mindmapvault/mindmapvault-foss

Why I am sharing this now

I wanted to ship a teaser that people can click and try immediately.

No fake screenshots. No slide deck. No polished sales theater.

Just the real UI running in the browser, so you can feel how the app behaves and judge it by yourself.

Full naked FOSS, by design

MindMapVault FOSS is built with a simple idea: keep it open, local-first, and privacy-first.

full open-source codebase
no hidden lock-in logic
no fake "community" shell over closed internals
practical architecture shaped by real engineering constraints

The interactive demo is not a mockup — it’s the real thing. What you see and feel there is exactly how the app behaves in everyday use.

I want your real feedback

If something is confusing, slow, ugly, or annoying, tell me directly.

If something feels good, tell me that too.

I am sharing this for real community feedback, not only compliments.

What works?
What breaks your flow?
What should be simpler?
What should be faster?

If you like it, please support the project

If the idea makes sense to you and you want to support independent privacy-first FOSS work:

Try the demo.
Share your thoughts and critiques.
Give the repo a star if you think it deserves it: https://github.com/mindmapvault/mindmapvault-foss

That signal helps more than people think.

Thanks for checking it out and helping shape it in public.

Privacy-first mind mapping app. Part 6: Maintainability and Coding Rules

Kornel Maraz — Wed, 29 Apr 2026 21:00:49 +0000

This is the chapter where I admit something simple: clean code talks are nice, but products are built in history, not in slides.

When MindMapVault was small, I could hold most of it in my head. Then the project grew into frontend work, desktop work, encryption flows, uploads, backend routes, different database paths, deployment scripts, release notes, and a lot of "just fix this one thing" days.

That is when coding rules stopped being theory and became survival.

The rules I kept coming back to were not fancy:

keep changes small
do not refactor the whole house when the sink is leaking
be extra careful in crypto, auth, and storage code
keep frontend and backend contracts aligned
prefer readable code over clever code

That sounds obvious. It is also the difference between a project that can still move and a project that starts breaking under its own weight.

The code has a visible history, and that is normal

You can see the project history in the codebase. I actually think that is healthy to admit.

MindMapVault started with MongoDB. Later I added Stoolap. Later I added SQL-oriented paths and those _sql.rs files. If you do not stop everything and rewrite the whole project from zero every time the architecture evolves, signs of the older path stay visible.

That is not a moral failure. That is what real software looks like.

You can often read the timeline directly from the repo:

frontend_app/        hosted app UI, editor, crypto helpers, vault flows
frontend_www/        marketing site, release notes, public blog
desktop/src-tauri/   local desktop shell and native packaging
backend/src/         auth, routes, storage, DB adapters, upload flows
scripts/             regression runners, banner rendering, deployment helpers

Then inside the backend there is another layer of history:

older MongoDB-oriented paths
later SQL and Stoolap paths
route files that had to stay practical while the storage model evolved

You can absolutely see that evolution if you read the repo for long enough. I am fine with that. Every long-running project carries some residue of its earlier decisions.

Practical first, perfect never

I like practical things. I like jobs done.

That preference is visible in the code.

Some parts are tidy and stable. Some parts are tactical. Some parts are not how I would design them in a greenfield rewrite. But a real product is not rebuilt from first principles every Tuesday morning.

There is a version of software advice that pretends all good code emerges from calm, linear planning. That is not how most product work happens.

Real code grows under pressure from:

feature delivery
production bugs
changed infrastructure
new storage backends
packaging and deployment headaches
the need to keep existing users working while the internals evolve

So yes, theoretically clean code and real-life code are often different things.

The goal was never to make MindMapVault look like a textbook. The goal was to keep it understandable enough, safe enough, and changeable enough while the product kept moving.

Where the rules were bent

There are places where the project is cleaner than average, and places where it absolutely is not.

The most visible compromises are usually these:

Boundaries are not always perfect

Some concerns leak across layers because the fastest safe fix was not always the prettiest abstraction.

React hygiene is not always textbook

There are places with deliberate lint-rule exceptions or dependency-array compromises because stable behavior in a real flow mattered more than satisfying the purest interpretation of the rule.

Style consistency is uneven

Some modules were written during calmer phases. Others were written during "let me finally this *** and go to the bed" phases. That difference is visible.

I would rather say that openly than write fake architecture prose around it.

Copilot changed the texture of the code too

Another honest point: code does not look like it did five years ago.

This project carries signs of Copilot use and, more broadly, LLM-assisted development. That is real now. We should stop pretending otherwise.

Sometimes that means faster scaffolding. Sometimes it means a strange but useful first draft. Sometimes it means the code gets a little more chaotic or stylistically mixed than it would with one human colleague writing every line in one voice.

But there is another side to that trade-off.

LLMs are also good at searching through that mess, finding the right file, spotting a broken path, or repairing a repeated pattern faster than a human might. In that sense, the code is not only written differently now. It is also maintained differently now.

I think we have to accept both sides:

the Copilot touch is visible
some generated structure is less elegant than an ideal hand-crafted version
but the same tooling also makes large, messy codebases easier to search, patch, and recover
and different coding styles are visible in a single project even one man´s hand (and a robot´s hand)

That is part of modern software reality now.

What actually kept the project under control

The workflow was practical, not ceremonial.

tsc and production builds were the first fast safety net.
backend regression runs through WSL and Python scripts were the real "did I break the product" check
dependency audits were hygiene, not proof of quality
security-sensitive changes were validated by behavior, not by vibes

On the Python side I leaned on repeatable checks like:

scripts/backend_regression_test.py
scripts/attachement_regression_test.py
scripts/shared_regression_test.py
scripts/production_functional_test.py

For burst and stress behavior I also used helpers like:

scripts/load_test_stoolap.py
scripts/production_burst_test.py
scripts/crud_burst_runner.py

That does not make the project magically clean. It just means there were repeatable ways to keep reality in view.

Passing lint does not prove good architecture. A green build does not prove good UX. An audit does not prove safe design.

But together, those checks helped keep the project from drifting too far into chaos.

The maintainability standard I actually believe in

For me, maintainability is not "could this win a code-style argument on the internet?"

It is more practical:

can I still understand this at 2 AM during a bug
can I change one thing without breaking five others
can I trace a storage or auth path end to end
can I ship a fix without turning it into a rewrite

That is the bar I care about.

MindMapVault is not pristine, and I do not need to pretend it is. It is a real product with a real timeline, visible scars, and a codebase that shows both human shortcuts and AI-era development habits.

I am okay with that.

What matters is that the important parts stay understandable, the dangerous parts stay guarded, and the project keeps moving without collapsing under its own history.

Privacy-first mind mapping app. Part 5: UI / Keyboard First

Kornel Maraz — Sun, 26 Apr 2026 12:51:19 +0000

Part 0 explained the feeling I wanted to recover: thought velocity.

This chapter is where that feeling turns into UI decisions.

I did not optimize for feature count first. I optimized for interruption cost. Every extra click, hidden mode, or ambiguous icon steals cognitive bandwidth from the idea itself.

So the UI direction was keyboard-first and friction-minimal:

common actions reachable without mouse travel
fast node creation and editing loops
predictable, stable interaction patterns
visual structure that supports scanning, not decoration

A keyboard-first interface is not nostalgia. It is a throughput strategy.

When a person is deep in a problem, they should not negotiate with the UI. The interface should be almost mechanical, so attention stays on thinking.

There is always tension here.

Modern apps reward adding controls, toggles, and contextual actions everywhere. Some are useful. Too many create noise. For this product, I repeatedly chose less surface area when that preserved speed.

The second tension is accessibility versus complexity.

Keyboard-first does not mean mouse-hostile. It means every key path should be meaningful, discoverable, and reliable. It also means visual focus states, labels, and interaction feedback must stay clear.

The frontend backbone we built on

The core model for the editor is built on the React Flow ecosystem (@xyflow/react). For this project, it was the most reliable and practical foundation I found for a mind-map-style UI.

Project link: https://reactflow.dev/

This mattered a lot because the whole frontend editor is effectively built around that graph viewport model. In simple terms, the canvas/viewport layer handles the graph rendering and interaction surface, and most of our product-specific work sits on top of it.

In practice, a big part of the app is then "buttons and keyboard actions talking to the graph canvas":

creating and deleting nodes
connecting and re-ordering structure
focusing, selecting, and navigating
applying styling and metadata actions

That may sound obvious, but this choice was a huge helper. It gave the project a stable backbone early, so I could spend energy on product behavior (keyboard speed, encryption-aware flows, vault UX) instead of rebuilding graph rendering primitives from scratch.

In practical product terms, this chapter connects directly to trust:

fast interaction encourages regular use
regular use creates real workflow dependence
dependence only happens when the tool gets out of the way

That is still the bar for MindMapVault.

If a user has to think about the interface more than the idea, the product failed for that moment.

Thanks and credits

This part of the project also sits on top of a lot of other people's work.

Huge thanks to the maintainers, contributors, communities, and companies behind React, React Flow, Tauri, TypeScript, Vite, Tailwind, Zustand, the Rust ecosystem, and the many smaller libraries that made this UI direction realistic for an independent product.

React Flow deserves a specific mention here because it gave the editor a serious, practical backbone early. That let me spend time on keyboard speed, interaction clarity, and product behavior instead of rebuilding graph rendering and viewport interaction from zero.

There is a fuller acknowledgement and licensing summary here: MindMapVault credits and licenses.