Forem: Kornel Maraz

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.

Privacy-first mind mapping app. Part 4: Zero Knowledge and Private Thought

Kornel Maraz — Sat, 25 Apr 2026 16:37:46 +0000

This chapter explains why zero knowledge is not marketing decoration for MindMapVault. It is a product boundary. It also explains the limits that come with that choice: no admin rescue, no silent recovery, and no backend access to your private thinking space.

Zero knowledge is often discussed like a technical badge.

For this product, it is more practical than that.

It answers a simple question: who is allowed to see the raw material of your thinking?

For MindMapVault, the answer is supposed to be very small by default: you, and only the people you deliberately share with.

That matters because a notes or mind-map vault is not just storage. It is where unfinished thoughts live before they are ready for other people.

What a notes or mind-map vault really is

A personal notes or mind-map vault is not just a database with text attached.

It is an externalized thinking space:

unfinished thoughts
personal beliefs and doubts
raw ideas before they are safe to share
private health, emotional, financial, or creative material

The important property here is psychological safety, not only confidentiality.

In many products, the most relevant observer is not necessarily a hacker. It is the platform itself being able to read, analyze, index, summarize, or repurpose what you wrote.

That is exactly where zero knowledge makes sense.

If the system cannot read the vault content, it cannot quietly become an interpreter of your inner workspace.

Why zero knowledge fits notes and mind maps

Thinking requires freedom from observation

If users know a provider can read their notes, even if the company promises not to, behavior changes.

people self-censor
sensitive thoughts never get written down
creative and analytical depth drops

Zero knowledge changes that condition by making access technically unavailable to the platform rather than merely disallowed by policy.

That difference matters. A promise can change. An architecture boundary is harder to erode casually.

Most note creation starts alone

Notes and mind maps are usually personal first and collaborative second.

That matches the trade-offs of zero knowledge unusually well:

no central recovery by default
no admin access to read content
no implicit sharing model hidden behind team tooling

This is acceptable precisely because authorship and ownership are personal at the moment of creation.

The raw draft stage is where privacy matters most.

Sensitivity is long-lived

The sensitive life of a note is often measured in years, not minutes:

therapy notes
political beliefs
legal planning
business strategy
research ideas that are not ready to leave the notebook yet

Zero knowledge protects not only against current breaches, but also against future breaches, future policy changes, and future business pressure to mine user content.

That is one of the strongest reasons to use it for a personal vault.

Why this matters even more for mind maps

Mind maps are not just notes with boxes.

The structure itself is sensitive.

Relationships between nodes, hierarchy, clustering, and sequence often reveal more than a single paragraph would. The shape of a map exposes what you connect, what you prioritize, what you fear, and what you still have not resolved.

So when I say MindMapVault protects private thought, I do not only mean note bodies.

I mean the broader cognitive structure you are building:

titles
notes
links between ideas
hierarchy and grouping
attachments connected to a map
the evolving graph of what you are trying to understand

For a mind-mapping product, zero knowledge is not only about securing text. It is about securing the structure of thought.

Where zero knowledge adds practical technical value

Zero knowledge becomes especially useful when the product supports features like these:

cross-device sync without server-side content visibility
offline-first creation and later encrypted synchronization
encrypted relationships between notes, maps, and attachments
client-side processing for search, previews, or graph operations when needed

The backend can still do important work: identity, quotas, object versioning, billing boundaries, upload confirmation, ownership checks, and encrypted blob storage.

What it should not do by default is interpret the content of your vault.

That is the core split.

What zero knowledge does not give you

This is the part that many products soften in marketing copy, but it should be said directly.

Zero knowledge removes some kinds of convenience by design.

If the provider does not have the keys, then the provider also cannot magically recover encrypted content for you later.

That means users should not expect:

admin access to unlock their vault
support staff to read content and restore it on request
silent password reset that decrypts old data
organization-wide legal hold or audit visibility for private vault contents
seamless team governance over data the server cannot read

These are not product omissions caused by lack of engineering effort.

They are direct consequences of the trust model.

If a company can always recover your private vault, then the system is not truly zero knowledge in the strongest sense. It means someone, somewhere, holds a privileged path around your control.

MindMapVault deliberately avoids presenting that kind of hidden escape hatch as a feature.

Where zero knowledge is not the right fit

Zero knowledge is weaker as a default model when:

collaboration is the primary mode from day one
an organization requires admin oversight, legal holds, or auditability
account recovery and delegated access are mandatory business features
hand-over and continuity matter more than personal autonomy

That is why many enterprise knowledge platforms do not fully adopt this model.

They optimize for continuity, governance, and administrative control. Those are legitimate priorities, but they are different priorities.

MindMapVault is intentionally optimized for private creation first.

Why I use this model anyway

The short answer is that it matches the job the product is supposed to do.

MindMapVault is meant to hold thoughts before they become presentation material.

At that stage, the most important thing is not collaboration polish. It is freedom to think clearly without platform observation.

That freedom is valuable enough that I accept the cost:

more complex client-side cryptography
fewer recovery shortcuts
stricter limits on backend convenience features
more discipline in how storage and sharing are designed

To me, that is a reasonable trade.

If the product is supposed to protect cognitive ownership, then the provider should not sit inside the room where the thinking happens.

One distinction worth keeping clear

Zero knowledge is not mainly about hiding notes.

It is about protecting the thinking process itself.

Once a thought becomes ready, users can still export it, publish it, share it, or move it into collaborative tools.

But the raw workspace where ideas are born benefits from being cryptographically private.

That is especially true for mind maps, where the structure can be as revealing as the text.

Summary

Zero knowledge makes sense for notes and mind maps because they are not just data stores. They are private cognitive spaces, and removing the platform's ability to observe that space changes how freely people think.

Privacy-first mind mapping app. Part 3: Encryption Model - The Heart

Kornel Maraz — Fri, 24 Apr 2026 17:10:21 +0000

This article describes the encryption model behind MindMapVault — not as a feature list, but as an engineering constraint that shapes every other decision in the system. It assumes familiarity with basic encryption concepts and focuses on boundary decisions, not cryptographic primers.

MindMapVault is not mainly a drawing tool. It is an encryption discipline wrapped in a usable interface.

If this model fails, no amount of UI, performance, or feature depth can compensate. Everything else becomes incidental.

The model is simple to describe and hard to keep clean in real code:

sensitive content is encrypted on the client
the backend stores encrypted payloads and encrypted metadata
plaintext notes and map content are not shipped to the server

That sounds obvious. The hard part is consistency across all features.

Every new capability wants to poke a hole in the model: previews, sharing, search, exports, diagnostics, support tooling. Each one can accidentally reintroduce plaintext handling if you are not careful.

The rule that saved me repeatedly was this:

If a feature needs plaintext, it must be justified at the edge and never become backend default behavior.

In practical terms, that affected route design, payload structures, and attachment workflows. The backend handles version pointers, upload confirmation state, ownership checks, and object metadata. It should not become the place where private thought content is interpreted.

There is also a human reason for this model.

Privacy here is not about hiding wrongdoing. It is about cognitive ownership. Mind maps tend to capture half‑finished ideas, rough drafts, personal plans, and structures that are not yet coherent — and may never be published. Those thoughts should remain under your control unless you explicitly choose otherwise.

This model is stricter than many products, and that raises implementation cost.

I accepted that cost because it is the product promise.

Everything else in this series is connected to this chapter: backend choices, UI speed decisions, coding rules, and even business trade-offs. If the encryption model becomes optional, the project loses its identity.

For the full security model write-up, see the whitepaper: Security Whitepaper

Concrete modules and libraries used

On the TypeScript side, the encryption stack is explicit and modular, not hidden in one giant helper:

Web Crypto API (crypto.subtle) for AES-256-GCM and SHA-256 operations
@noble/curves (x25519) for the classical ECDH part
@noble/post-quantum/ml-kem (ml_kem768) for post-quantum KEM
@noble/hashes (hkdf, sha256) for key derivation and context-separated keys
hash-wasm (argon2id) for passphrase and master-key derivation paths

In practical terms, this is how I used it.

1) AES-256-GCM envelope (nonce + ciphertext+tag)

const nonce = crypto.getRandomValues(new Uint8Array(12));
const ct = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv: nonce, tagLength: 128 },
    key,
    plaintext,
);

This pattern is used in the frontend crypto module to encrypt map payloads, titles, and attachment-related blobs before upload.

2) Hybrid key encapsulation (X25519 + ML-KEM-768)

const classicalShared = x25519.getSharedSecret(ephPrivate, recipientClassicalPub);
const { cipherText: pqCiphertext, sharedSecret: pqShared } =
    ml_kem768.encapsulate(recipientPqPub);

const combinedKey = hkdf(sha256, concat(classicalShared, pqShared), undefined, 'crypt-mind-dek-v1', 32);

I combine classical and post-quantum shared secrets, derive a 32-byte wrapping key via HKDF, and use that to wrap the random DEK used for the actual vault content encryption.

3) Argon2id for passphrase-bound keys

const result = await argon2id({
    password,
    salt,
    parallelism: params.p_cost,
    iterations: params.t_cost,
    memorySize: params.m_cost,
    hashLength: 32,
    outputType: 'binary',
});

This is used for deriving high-cost keys from user secrets (for example, master key and share-passphrase flows), so brute-force resistance is parameterized and explicit.

How encrypted sharing works without breaking zero knowledge

This was one of the places where the model could have fallen apart very easily.

Sharing is currently implemented as an encrypted export flow, not as live collaborative editing. That distinction matters. The backend can distribute a protected snapshot, but it still should not learn the map content or the share passphrase.

The rough flow looks like this:

Owner browser
    |
    | 1. Serialize current vault snapshot { title, tree, exported_at, source_vault_id }
    | 2. Generate random salt
    | 3. Derive share key with Argon2id(passphrase, salt, params)
    | 4. Encrypt snapshot with AES-256-GCM using that derived share key
    | 5. Upload ciphertext + encryption_meta + checksum + expiry/hint metadata
    v
Backend / object storage
    |
    | Stores only:
    | - encrypted blob
    | - kdf metadata (salt, memory, iterations, parallelism)
    | - checksum, content type, expiry, hint, share id
    | Never stores:
    | - plaintext map
    | - plaintext notes
    | - share passphrase
    | - decrypted attachments
    v
Recipient browser
    |
    | 6. Fetch encrypted blob + encryption_meta by share URL
    | 7. User enters passphrase locally in the browser
    | 8. Derive the same share key locally with Argon2id
    | 9. Decrypt locally with AES-256-GCM
    v
Readable shared vault

That is the important boundary: the server can identify a share, enforce expiry and revocation, and serve encrypted bytes. It cannot unlock the content because it never receives the passphrase-derived key.

The actual frontend share creation code follows that model directly:

const shareBundle = await createEncryptedShareBundle(
    {
        title,
        tree: currentTree,
        exported_at: new Date().toISOString(),
        source_vault_id: id,
        include_attachments: draft.includeAttachments,
    },
    draft.passphrase,
);

Under the hood, that bundle creation does three essential things:

derives a share key from the recipient passphrase using Argon2id
encrypts the exported vault snapshot with AES-256-GCM
returns only ciphertext plus encryptionMeta needed for local unlock later

The backend then stores the encrypted blob and metadata like this:

await encryptedVaultApi.createShare(id, {
    name: draft.name.trim() || `${title || 'vault'}.cmvshare`,
    scope: 'map',
    include_attachments: draft.includeAttachments,
    passphrase_hint: draft.passphraseHint.trim() || undefined,
    expires_at: expiresAt,
    content_type: 'application/vnd.cryptmind.share+json',
    size_bytes: shareBundle.ciphertext.byteLength,
    encryption_meta: shareBundle.encryptionMeta,
});

Notice what is missing there: no plaintext tree, no raw title/notes payload, and no passphrase.

Attachments follow the same rule

Attachments are where many “private” products quietly cheat.

In MindMapVault, if a share includes files, the owner-side client first downloads the already encrypted attachment, decrypts it locally with the owner’s session key, and then immediately re-encrypts that plaintext with the share key before upload. That means the shared attachment is not the original vault attachment reused directly. It becomes a separate ciphertext bound to the share export.

That extra step matters for two reasons:

the recipient only needs the share passphrase, not the owner’s vault keys
the backend still never needs access to attachment plaintext during sharing

So the sharing model is not “backend mediates decryption.” It is “owner creates a new encrypted package for recipients.” That is a much safer design.

Public link does not mean public plaintext

The share URL itself is public in the same sense that any capability URL is public: if you know the identifier, you can ask the backend for the encrypted bundle. But what you get back is still ciphertext plus KDF metadata and optional hint text.

The recipient page then performs local unlock in the browser:

const ciphertext = await encryptedVaultApi.downloadUrl(share.download_url);
const unlockedBundle = await unlockEncryptedShareBundle(
    ciphertext,
    passphrase,
    share.encryption_meta,
);

Again, the trust boundary is explicit:

backend verifies that the share exists, is not revoked, and is not expired
backend returns encrypted bytes
browser derives the key and decrypts locally

That is how zero knowledge is preserved while still allowing practical sharing.

The main point here is not novelty or cryptographic cleverness. Every primitive used is well‑understood. The value is in how responsibilities are split, keys are scoped, and plaintext is prevented from leaking into default backend paths.

Privacy-first mind mapping app. Part 2: Rust Backend - Why the Pain Is Worth It

Kornel Maraz — Thu, 23 Apr 2026 15:39:13 +0000

Choosing Rust for a backend can feel irrational at first.
If your short‑term goal is raw development speed, Rust does not win. The compiler is unforgiving, type design takes real thought, and compile cycles can test your patience. On this project, there were phases where a full rebuild felt endless—and that kind of friction is emotionally expensive when all you want is to ship something that works.

But I still chose Rust for two reasons:

reliability under pressure
predictable resource usage

This backend handles encryption‑related workflows, file metadata, quota enforcement, and versioned storage paths. I wanted something that stays lean, stable, and boring under load. Rust makes that possible—after you push through the painful parts.
Once the architecture settles, the payoff is real: a compact server binary that runs consistently and fails loudly when something is wrong.

A Simple Architecture, on Purpose

The guiding rule for this backend: do not outsmart yourself.
The overall structure is deliberately conservative:

Axum router composition by feature
Explicit state objects per route group
Trait‑based storage abstractions
Strict model separation between API and persistence layers

Server startup is intentionally boring:

Router::new()
    .route("/health", get(health))
    .nest("/api/auth", auth_sql_router(auth_state))
    .nest("/api/mindmaps", mindmaps_sql_router(mindmaps_state))
    .nest("/api/public", public_router(public_state.clone()))

Each feature owns its routes, its state, and its responsibilities. There is no global god‑object, no implicit shared context, and no “we’ll refactor this later” escape hatch.

Capability‑Driven State, Not Concrete Dependencies

Route handlers depend on what they need, not how it is implemented.
Here is the state injected into mind‑map routes:

pub struct MindMapsSqlState {
    pub db: DynSqlStore,
    pub minio: MinioClient,
    pub jwt: Arc<JwtService>,
    pub diagnostics_enabled: bool,
}

The important detail here is not the fields themselves—it’s that persistence is expressed through traits. Handlers care about capabilities (load, update, store) rather than concrete database implementations.
This is not about abstraction for abstraction’s sake. It keeps the surface area of each feature honest.

Fetching a Mind Map: Ownership First, Then Data

async fn get_mind_map(
    State(state): State<MindMapsSqlState>,
    user: AuthenticatedUser,
    Path(id): Path<String>,
) -> Result<Json<MindMapDetail>, AppError> {
    let map = find_owned(&state.db, &id, &user.0).await?;
    Ok(Json(to_detail(map)))
}

Nothing fancy here—and that is the point.
Ownership checks happen before transformation. Models coming out of storage are never leaked directly to the API layer. Every conversion is explicit.
Rust’s type system makes cutting corners uncomfortable, which is exactly what you want when dealing with encrypted artifacts.

Key Distribution (Encryption Happens in the Browser)

This system performs client‑side encryption. The backend never sees plaintext content.
The backend’s job is to distribute encrypted key material safely and consistently:

async fn get_keys(
    State(state): State<AuthSqlState>,
    user: AuthenticatedUser,
) -> Result<Json<KeyBundleResponse>, AppError> {
    let db_user = state
        .db
        .load_user_by_id(&user.0)
        .await?
        .ok_or_else(|| AppError::NotFound("user not found".to_string()))?;

    Ok(Json(KeyBundleResponse {
        classical_public_key: db_user.classical_public_key,
        pq_public_key: db_user.pq_public_key,
        classical_priv_encrypted: db_user.classical_priv_encrypted,
        pq_priv_encrypted: db_user.pq_priv_encrypted,
        key_version: db_user.key_version,
    }))
}

Every field in this response is intentionally named and versioned. There is no “future me will remember what this blob means.”
Discipline here prevents silent cryptographic foot‑guns later.
And upload a blob to S3 endpoint with authentication, quora check and versioning.

Uploading Encrypted Blobs with Quotas and Versioning

Uploading a mind‑map snapshot involves more than just dumping bytes to object storage:

async fn upload_blob(
    State(state): State<MindMapsSqlState>,
    user: AuthenticatedUser,
    Path(id): Path<String>,
    body: Bytes,
) -> Result<Json<ConfirmUploadResponse>, AppError> {
    if body.is_empty() {
        return Err(AppError::BadRequest("blob is required".to_string()));
    }

    let map = find_owned(&state.db, &id, &user.0).await?;
    let subscription_tier = load_effective_subscription_tier(&state.db, &user.0).await?;
    let current_total_bytes = load_storage_usage_total_bytes(&state.db, &state.minio, &user.0).await?;
    let projected_total_bytes = current_total_bytes + body.len() as i64;
    let plan_limit_bytes = subscription_tier.storage_limit_bytes();
    if projected_total_bytes > plan_limit_bytes {
        return Err(storage_quota_exceeded_error(
            &subscription_tier,
            projected_total_bytes,
            plan_limit_bytes,
        ));
    }

    let version_id = state
        .minio
        .upload_blob(&map.minio_object_key, body.to_vec())
        .await?;

    let mut version_history = map.version_history.clone();
    version_history.push(VersionSnapshot {
        version_id: version_id.clone(),
        eph_classical_public: map.eph_classical_public.clone(),
        eph_pq_ciphertext: map.eph_pq_ciphertext.clone(),
        wrapped_dek: map.wrapped_dek.clone(),
        saved_at: Utc::now(),
    });

    if let Err(error) = state
        .db
        .update_mind_map_upload(&id, &user.0, &version_id, version_history)
        .await
    {
        if let Err(cleanup_error) = state.minio.delete_version(&map.minio_object_key, &version_id).await {
            tracing::error!(
                ?cleanup_error,
                map_id = %id,
                user_id = %user.0,
                version_id = %version_id,
                "failed to roll back uploaded version after metadata update error"
            );
        }
        return Err(error);
    }

    let prune_key = map.minio_object_key.clone();
    let prune_limit = map.max_versions;
    let minio = state.minio.clone();
    tokio::spawn(async move {
        if let Err(e) = minio.prune_versions(&prune_key, prune_limit).await {
            tracing::warn!("Failed to prune old versions for {prune_key}: {e}");
        }
    });

    Ok(Json(ConfirmUploadResponse { version_id }))
}

async fn get_mind_map(
    State(state): State<MindMapsSqlState>,
    user: AuthenticatedUser,
    Path(id): Path<String>,
) -> Result<Json<MindMapDetail>, AppError> {
    let map = find_owned(&state.db, &id, &user.0).await?;
    Ok(Json(to_detail(map)))
}

Before the upload even happens, several constraints are enforced:

request body must exist
user must own the mind map
storage quota must not be exceeded
projected usage must include the new blob

Only after all guards pass does the upload occur.
Versioning metadata is recorded atomically with cleanup logic in case persistence fails. If the database update errors out, the uploaded object version is explicitly deleted. If that fails, the error is logged loudly.

Finally, old versions are pruned asynchronously.

This is not clever code. It is defensive code.

Tooling Helps—But Discipline Matters More

rust-analyzer in VS Code can absolutely make your life easier. It can also overwhelm you with diagnostics if your mental model is fuzzy.

The important part is discipline.
Two patterns became essential in keeping this codebase sane:

State Segregation per Route Area Each domain owns its state:

auth
admin
mind maps
billing
public endpoints

No shared mutable mega‑state. No “just add it here for now.”

Strongly Typed Data Contracts Models like StoredMindMap, NewMindMap, and update‑specific structs force explicit mappings. Field drift becomes visible immediately instead of months later through corrupted data.

The Emotional Reality of Rust

Developing in Rust is harder, at least compare to Python.
Sometimes it feels like trying to speak while a grammar teacher interrupts every sentence. But once the code compiles and the model fits, the confidence is different.

Fewer runtime surprises
Clearer failure modes
Stronger guarantees under refactoring

That is why this “crazy” idea stayed.
In the next part of this series, I’ll dive into how encryption boundaries shaped both the frontend and storage layout—and how Rust made those edges explicit rather than implicit

PS: A Note on Cognitive Load: Rust’s Memory Model Is Not Free

It would be dishonest to talk about Rust without calling out the extra cognitive complexity its memory model imposes on the developer.
Ownership, borrowing, and lifetimes are not just compiler mechanics—they shape how you think. Every non‑trivial data flow forces you to reason about who owns what, for how long, and under which constraints. This is especially noticeable when designing API boundaries, async flows, or shared state. Even when the compiler eventually guides you to a correct solution, getting there can be mentally expensive.
In practice, this means Rust demands more upfront thinking than garbage‑collected languages. The friction is real, and it slows you down early—sometimes significantly. There were moments in this project where the hardest part was not the business logic, but expressing it in a way that satisfied ownership rules without distorting the design.
The trade‑off, however, is intentional pressure. Rust pushes complexity from runtime into design time. Once the code compiles, entire classes of memory bugs, data races, and lifetime errors simply stop being possible. The cognitive load doesn’t disappear—but it pays off by converting uncertainty into explicit structure.
Rust does not make you faster by default. It makes you more precise, and precision has a cost.

For readers less familiar with Rust, some of this complexity shows up very visibly in the code itself: frequent symbols like &, *, ', < >, ::, and others. These are not decoration—they encode rules about ownership, borrowing, lifetimes, and type relationships. Even simple operations often carry extra markers that force the developer to be explicit about how memory is accessed and shared. This makes Rust code denser and harder to read at first glance for newcomers, but it is exactly this explicitness that allows the compiler to catch entire classes of errors before the program ever runs.

For me personally, the most effective way to get over Rust’s initial hurdle was Rust Essential Training by Barron Stone on LinkedIn Learning, which helped solidify ownership and borrowing concepts early on.

Privacy-first mind mapping app. Part 1: Constraints Before Tech

Kornel Maraz — Wed, 22 Apr 2026 20:40:36 +0000

I started with a romantic idea: build the entire product in Rust, with Rust‑first tools, end to end.
I still like that idea philosophically. In practice, it was too much for one person and too far removed from the real goal.

The real goal was simple and already described in Part 0: a fast, practical, keyboard‑friendly app that is online and privacy‑respecting. Not a technology demo. Not a purity contest.
At first, I treated the tech stack as if the technology choices were the product.

For the backend, I settled on combo Rust with Tokio and Axum. I genuinely love FastAPI — it’s the framework I trust the most — but early in the project I wanted to keep operational costs low. Python frameworks tend to have a higher memory footprint, which isn’t ideal for a small, long‑running SaaS.
On the desktop side, I chose Tauri. It allowed me to reuse the web frontend while keeping the application lightweight, secure, and fast. Rust on the backend and Tauri on the desktop ended up being a natural pairing.
This was my final compromise — the last remaining piece of the original Rust‑first dream. Enough Rust to matter, without turning the project into an experiment.

I tried RustFS as object storage. Under load, it quickly became clear that it wasn’t stable enough for my needs. Around the 200‑concurrent‑user mark, things started to fall apart. The project is still in alpha, so that’s no surprise. Maybe it’s a better fit for a future project.

I spent a lot of time trying to make SurrealDB work smoothly in this setup, but I never reached a level of confidence that matched my timeline. Maybe it was the documentation, maybe a skill issue.
MongoDB — a personal favorite — turned out not to be the right fit either, mostly due to its memory footprint. Stoolap was explored and used in early phases, but maintaining multiple database experiments during an early‑stage product simply didn’t make sense.

For the frontend, I experimented with Rust web UI approaches and Rust‑adjacent options. The biggest issue I ran into was the lack of a proper mind‑mapping canvas component. This canvas is the heart of the UI, and I didn’t feel confident enough to start developing something that complex from scratch.

So I changed my approach:

MinIO for object storage — boring, but reliable
Rust for the backend — the last practical remnant of my original Rust‑only dream
PostgreSQL as the current backend storage baseline — a boring, proven, and hard to get wrong
React + TypeScript for the frontend — chosen for iteration speed and mature tooling, with no need to reinvent anything
Tauri for desktop apps — lightweight, secure, and a natural fit with Rust

At the beginning, my decisions were more ideological. Over time, I became pragmatic. I like things that get done, and there are always options to choose from.

I wanted an offline‑first feeling, with encrypted persistence to the database and S3‑compatible storage. I wanted the app to feel objectively responsive and immediate. If a thought appears, I should be able to capture it in a fraction of a second — not after waiting for framework ceremonies.

The key lesson of this chapter is simple: constraints come before tools.

When your constraints are clear, technology becomes a means. When your constraints are blurry, technology becomes a trap. I lost time learning this lesson. I don’t regret the learning, but I wouldn’t repeat the same order again.

MindMapVault exists because I finally prioritized the goal over the stack fantasy.

Privacy-first mind mapping app. Part 0: Motivations and Mind Maps

Kornel Maraz — Mon, 20 Apr 2026 22:21:45 +0000

Before MindMapVault, I used FreeMind a lot.

I loved it because it was fast, reliable, and easy to use. It respected keyboard-heavy work. I could stay focused on the idea itself instead of hunting for the right button, menu, or floating panel. I could move quickly, write down thoughts with typos if necessary, and keep going while the idea was still alive in my head.

That mattered more than it may sound.

With many modern applications, a surprising amount of attention gets wasted on the interface itself. You stop thinking about the problem and start thinking about the tool. You search for the correct icon. You look for the hidden command. You try to remember which mode you are in. That interruption is expensive. Sometimes the original thought is already weaker by the time you find what you needed.

FreeMind was different for me.

It felt simple in the best possible way. I did not need setup. I did not need to configure the whole universe before I could begin. I installed it and started working. That was it.

I could use the workflow almost mechanically:

F3 to edit a node
F4 for alternating colors
Insert for a new node right
double Enter new node underneath
mostly keyboard, minimal friction

I was very effective with that style of work. The application got out of the way.

But it had one major weakness: it was an offline app.

The map was always on the wrong computer when I needed it. It did not matter whether I tried to soften that with OneDrive sync or a similar workaround. The real problem remained the same. The tool I liked best was tied to one machine at the exact moment when I wanted access from somewhere else.

What I wanted was not a giant reinvention.

I wanted a quick and dirty web UI with the same spirit. Something fast. Something direct. Something that would let me capture the thought immediately and keep moving. I did not want a bloated collaboration platform pretending to help me think. I wanted the practical feeling I had with FreeMind, but available from wherever I was.

I also wanted that accessibility without broadcasting my notes. In practice that meant an online tool where I remained in control of who sees my thoughts — convenient access without making personal notes public by default. Privacy here is about minimizing accidental exposure and keeping ownership and control over what I write, not about hiding anything questionable.

I searched for that for a long time.

I did not find what I wanted.

That gap is one of the main reasons MindMapVault exists.

This blog series is an honest account of how I built it: the parts that worked, the parts that were painful, the mistakes, the redesigns, and the decisions that still feel right.

If you have ever felt that older tools were somehow more efficient, more focused, and less eager to interrupt your thinking, you will probably understand the motivation behind this project.