DEV Community: Boitumelo Phetla

Introducing Andika Library

Boitumelo Phetla — Thu, 22 Oct 2026 09:51:48 +0000

We are building a house consciously, with intention, purpose and a philosophy behind every brick. Today we released Andika Library.

Library is a home for scattered documents, research, files and an organisation's collective knowledge. It is meant for an individual making sense of years of information, and for an enterprise managing thousands of assets.

Governance is part of the architecture, not an afterthought. Library comes with mutually exclusive permissions, intended to set clear boundaries around ownership, access and control.

Every asset in your Library can be brought into your Workspaces and Workbooks, so documents, research and information become part of the work you write, without compromising the permissions that protect them.

The Library is presented like a library of books.

One Library. Connected knowledge. Governance by design.

Originally published on the Andika journal: https://andika.work/blog/dd4d6274-2cd9-44ed-ac6f-45e1167536fd. Adapted for DEV with AI assistance.

Tasks where the work lives: why colocation beats features

Boitumelo Phetla — Tue, 20 Oct 2026 15:20:09 +0000

Most teams keep their knowledge in one tool and their tasks in another. The document says what needs doing; the task tracker says who is doing it; and the link between the two is a paste of a URL that nobody clicks.

The idea: put tasks next to the work

Kanban-style task management is well understood: cards, columns, a visible flow from todo to done. What changes when the board lives inside the same workspace as the documents, research, and notes is not the mechanics but the distance. The task that says "update the methods section" can sit one click from the methods section. Assignment, status, and context stop being three different apps.

Colocation also lowers the bar for personal tasks. Assigning something to yourself in a heavyweight project tracker feels absurd; assigning it where your notes already live feels like leaving yourself a bookmark with a deadline.

The trade-offs

A built-in board will never match a dedicated tracker feature for feature: no Gantt charts, no sprint analytics, no automation rules. For large teams running formal processes, a real project-management tool wins. The integrated board wins on a different axis: adoption. The tool people actually open every day beats the tool with more features that nobody checks.

How we approached it at Andika

Andika is a knowledge workspace, and the task feature arrived the way most of our features do: someone asked. A colleague mentioned how useful it would be to assign tasks to yourself and your teammates, and we built it in about four hours. Our engineers immediately started creating and assigning tasks among themselves, which gave us a clearer way to coordinate work without leaving the workspace.

It follows a simple Kanban framework. Earlier feedback in the same spirit led to private document views alongside shareable, view-only links, so you control who sees and who edits.

The lesson we keep relearning: the fastest way to build the right thing is to stay close enough to users that a conversation on Monday can be a feature by Monday afternoon.

Adapted from a post on the Andika blog.

A bibliography is a list: mapping the constellation around a paper

Boitumelo Phetla — Tue, 20 Oct 2026 14:13:12 +0000

A research paper looks like a self-contained unit. It is not. It cites earlier work, those papers cite others, and the idea you are reading about has been shaped by authors, institutions, and disciplines over years. A bibliography compresses all of that into a flat list at the back.

The idea: make the citation network navigable

Citation data is public and structured - projects like OpenAlex index hundreds of millions of works and their references. The raw material for seeing a paper's neighborhood already exists. What is usually missing is the interface: a way to stand on one paper and look around.

An evidence-map view changes the questions a researcher can ask. Instead of only "where is this paper?", you can ask:

What is this paper connected to?
Which work influenced it?
What other research sits around this idea?
Where does this argument fit in the wider body of evidence?

These are not exotic needs. Literature reviews, replication checks, and defending a claim to a skeptical supervisor all reduce to navigating exactly this graph. Doing it by hand means dozens of tabs and a spreadsheet you abandon by week two.

The trade-offs

Citation graphs are easy to render and hard to make useful. More nodes and edges quickly become a hairball that looks impressive and answers nothing; the value is in ranking, filtering, and letting the reader expand from a paper outward in the direction they care about. Citation links also say nothing about why something was cited - agreement, rebuttal, or ritual - so a map supports judgment; it does not replace reading.

How we approached it at Andika

Andika is a knowledge workspace with a research focus, and its new Evidence Map lets researchers explore a paper alongside the constellation of work connected to it: citation relationships, related papers, authors, communities, and the surrounding evidence. We built it on our own model over OpenAlex data, and the goal is practical: make research easier to navigate, understand, and defend.

A bibliography is a list. A research constellation shows the thinking behind it.

Adapted from a post on the Andika blog.

Let the workspace remember: knowledge graphs for your documents

Boitumelo Phetla — Tue, 20 Oct 2026 13:09:00 +0000

You come back to your desk after a week away and stare at three files: final.pdf, final_final.pdf, final_final_v2.pdf. You created all of them. You have no idea what any of them mean anymore.

That moment is a knowledge-management problem, and most tools answer it with search. Search helps when you remember the words. It fails when what you actually remember is the relationship: the diagram that went with the proposal, the paper that backed up the argument, the note that explained why the file exists.

The idea: store relationships, not just documents

A knowledge graph treats the things in a workspace as connected entities rather than isolated files. Documents link to their attachments, notebooks, projects, and sources. The links carry meaning, not just pointers.

The interesting design question is where that meaning comes from. One option is inference: feed everything to a language model and let it rediscover context on demand. That works, but it re-derives what the author already knew, spends tokens doing it, and can misread the intent. Another option is to capture the relationship at the moment it exists. When someone attaches an image to a document, ask two cheap questions: what does this asset contain, and why is it attached here? Those two answers, recorded once, are worth more than a hundred re-analyses later.

The trade-offs

Explicit relationship capture adds friction to the writing flow, and relationships go stale as documents evolve. Inference scales without asking anything of the author but inherits the model's misunderstandings. Most real systems end up hybrid: automatic structure where it is reliable (this file belongs to this project), human-supplied context where it matters (this image is the evidence, not decoration).

How we approached it at Andika

Andika is a knowledge workspace, and its assets are not treated as files with filenames alone. When you attach something, the platform asks what it contains and why it is attached, creating an explicit relationship between the asset, the document, and your intent. Connected AI tools receive that grounding directly instead of re-inferring it, which cuts token usage and keeps human meaning at the center.

On top of that, Andika automatically builds relationships between documents, pages, attachments, notebooks, and projects, so the workspace itself remembers what connects to what when your own memory fails. Under the hood we are building the AND model, intelligence designed to help you recall what you worked on and how your information connects. And if you do not want to wait for it, you can connect your own LLM: Andika's MCP layer gives it structured, read-only access to navigate the workspace with you.

You should not have to remember where your knowledge lives. Your workspace should remember for you.

Adapted from posts on the Andika blog.

Provenance beats detection: recording AI's role in writing

Boitumelo Phetla — Tue, 20 Oct 2026 12:02:42 +0000

"Was this written by AI?" is the question schools, publishers, and teams keep asking, and the honest answer from detection tools is usually a shrug dressed up as a percentage. There is a more reliable approach available to anyone building writing software: stop guessing, and start recording.

The idea: provenance beats detection

AI-text detectors try to infer authorship from statistical fingerprints in the final text. They are unreliable in both directions: they flag careful human writers and miss polished machine output. The deeper problem is conceptual. They are trying to reconstruct history from a single artifact.

Revision provenance takes the opposite path. If the writing environment saves every revision and knows which saves involved AI assistance, then the history is not inferred at all. It is recorded. Questions like "what did this document look like before the AI pass?" or "which passages did the assistant rewrite?" become lookups, not guesses.

That shift enables better features:

Contribution maps. Show exactly which passages were rewritten, added, or removed in an AI-assisted revision, with before-and-after comparisons.
Honest attribution. Instead of "this document is 37% AI" (a meaningless claim), you can say how much of the measurable improvement happened during AI-assisted saves versus human ones.
Defensible records for students and researchers. A writer can show their original questions, arguments, and groundwork existed before any AI refinement, and a supervisor can discuss writing development without relying on an opaque detector score.

The trade-offs

Provenance only works inside the system that recorded it. Paste in text from outside and the chain breaks. It also requires the platform to be trustworthy about its own records, and it produces developmental analytics, not verdicts: a revision history cannot tell you whether assistance was appropriate, only where it happened. Treating it as a disciplinary instrument would repeat the detector mistake with better data.

How we approached it at Andika

Andika, the knowledge workspace we are building, keeps a full revision history per document, and AI-assisted saves are marked as such in that history. Two features build on it:

Document History now includes a contribution map for AI-assisted revisions: passages rewritten, added, or removed, each with a before-and-after comparison you can inspect.

Grade Me compares the original draft with every saved revision and reports how language, structure, and ideas evolved: voice retention, semantic similarity, intent and entity preservation, lexical diversity, and reading-grade estimates. The report separates improvement from human revisions from improvement during recorded AI-assisted saves, and every AI-assisted revision is explainable: pick it on the timeline and see the exact passages that changed.

We are deliberate about what this is not. It is not a plagiarism verdict, an institutional mark, or a claim that some percentage of a document "belongs to AI." It is developmental analytics, built on recorded history rather than text statistics. AI should not erase the author from the page; it should help the author see where their work became stronger.

Adapted from posts on the Andika blog.

Discussing documents where the discussion belongs

Boitumelo Phetla — Tue, 20 Oct 2026 11:00:45 +0000

A comment thread at the bottom of a long document is where feedback goes to lose its context. "This paragraph needs a source" forces the reader to hunt for which paragraph, on which page, in which version. The alternative is anchoring the discussion to the thing it discusses.

The idea: anchor conversations to content

Most writing tools treat comments as a single stream attached to the document as a whole. Anchored annotation works differently: a discussion thread attaches to a specific section, sentence, or element. The context travels with the comment.

This changes a few things in practice:

Feedback becomes actionable. The reader sees exactly what the comment refers to, and the writer can resolve threads one by one without archaeology.
Navigation and discussion reinforce each other. If your document has a real section structure, anchored tags double as a map: jump to a section, see its open threads.
Documents become reference material. Attachments and related documents can live next to the work itself, at workspace or document level, instead of in a separate folder system people forget to check.

There are design costs. Anchors break when the anchored text is deleted or heavily rewritten, so the system has to decide: orphan the thread, re-anchor it, or mark it stale. Fine-grained anchoring also raises the permission question: if you can hide a document from specific people, do its threads inherit that? (They should.)

How we approached it at Andika

Andika is a knowledge workspace built around Markdown documents, and several recent additions came directly from user requests:

A tagging system on top of documents. You can tag a specific section and start a focused discussion thread on it, rather than collecting all feedback in one stream.
Document attachments at both workspace and document level, with the option to hide specific documents from specific people.
Section navigation in the Markdown editor and preview, plus copy buttons on code blocks in the preview, so reference documents are easier to move through and reuse.
Reader summaries on the same page, and the option to send a document to a large language model for summarization when you want a machine-generated first pass.

None of these is a headline feature on its own. Together they move a document from "a page of text" toward "a place where reading, discussing, and referencing happen in one spot."

Adapted from posts on the Andika blog.

OAuth sign-in: letting users bring an identity they already trust

Boitumelo Phetla — Tue, 20 Oct 2026 09:52:52 +0000

Every new product asks for a new password, and every new password is one more thing to forget, reuse, or lose. Delegated sign-in exists to break that pattern: instead of trusting every app with its own credential database, you let an identity provider you already use vouch for you.

The idea: delegate authentication

OAuth 2.0, usually paired with OpenID Connect for sign-in, lets an application ask a provider like Google, Microsoft, or Apple to authenticate the user on its behalf. The flow in brief:

The app redirects you to the provider.
You sign in there (or are already signed in) and approve the request.
The provider sends the app back a token asserting who you are.

The important property is what the app never sees: your password. The provider handles the credential, the second factor, the suspicious-login checks. The app receives a stable identity reference and builds its own profile on top of that.

This changes where the security burden sits. A small team no longer has to store password hashes, build reset flows, and get credential-stuffing defense right. It inherits the provider's investment in account security instead.

The trade-offs

Delegated sign-in is not free:

You depend on the provider's availability and policies. If Google sign-in has an outage, your users do too.
Account linking is a design problem. If someone signs up with email, then later clicks "Sign in with Google" using the same address, is that the same account? Getting this wrong creates duplicate identities or, worse, account takeover paths.
Institutional users bring their own identity systems. Universities and enterprises often already run Microsoft Entra ID. Supporting only one provider means telling those teams to maintain a parallel identity just for your product.
Authentication is not authorization. Proving who someone is says nothing about what they may access. That part stays in your application, and it is where most real access-control work lives.

How we approached it at Andika

Andika, the knowledge workspace we are building, now supports Google, Microsoft and Apple sign-in alongside email and password. When someone signs in with Google, Google handles authentication and Andika never receives or stores the Google password. We create an application profile in our own database linked to the provider's stable identity reference, and manage workspaces, permissions, invitations and preferences on top of that.

We rolled this out in stages: Google sign-in was configured and working first, while Microsoft Entra registration and Apple Developer enrolment were still in progress. Microsoft support mattered to us specifically because universities and enterprises, the organisations we want to serve, commonly manage identities through Entra ID already.

One boundary we keep explicit: authentication stays separate from connected storage. Signing in with an external identity provider does not hand over your documents or infrastructure. Identity is verified before access is granted, and each organisation keeps control of where its information lives.

Easier to enter, without weakening the parts that keep knowledge safe.

This post is adapted from announcements on the Andika blog. All product sketches are hand-drawn by Andika's founder on a tablet before rendering.

Putting an API gateway in front of everything

Boitumelo Phetla — Tue, 20 Oct 2026 08:47:04 +0000

As a product grows past a handful of endpoints, API security stops being a feature of individual services and starts being an architectural question. Where do policies live? Who enforces them? How do you know the same rules apply to endpoint number fifty as to endpoint number five?

Our answer, on Andika, was to put an API gateway in front of everything: Kong, running on top of Nginx, as the single entry layer for API traffic before it reaches our services.

What a gateway actually buys you

It's tempting to see a gateway as a fancy reverse proxy. The real value is centralisation of policy:

One enforcement point. Authentication expectations, rate limits, request constraints, and access rules are applied consistently, before traffic touches application code. A service behind the gateway doesn't each have to reinvent its own perimeter.
One place to change the rules. When a policy needs tightening, you change it once. You don't go on a scavenger hunt through a dozen services hoping you found every copy of the logic.
Reduced blast radius for sloppy requests. Malformed, unauthorized, or abusive traffic gets stopped at the edge, where it's cheap to reject, rather than deep in the system, where it's expensive.

The other half: visibility

Blocking bad traffic is only half the job. The other half is seeing what's happening at all.

We paired the gateway with monitoring across API activity and infrastructure behaviour, because policies without observation are just hopes. Watching traffic patterns at the edge is what lets you notice a credential-stuffing attempt as a shape in the data rather than as a postmortem. Earlier detection is the difference between "we rate-limited an odd burst" and "we found out from a user."

The honest trade-off

A gateway is also a single point of failure and a latency hop, and pretending otherwise is how architectures get cargo-culted. You take on operating it properly: redundancy, careful rollout of policy changes, and accepting that every request pays a small toll at the door.

For us, the trade is worth it. Centralised, consistently applied policy plus real visibility beats a scattered set of per-service defences that drift out of sync with each other over time. Security posture you can reason about beats security posture you merely assume.

This post was adapted, with AI assistance, from an article on the Andika blog, where we build a collaborative writing and knowledge platform.

Permissions that actually enforce, not just hide

Boitumelo Phetla — Tue, 20 Oct 2026 08:46:30 +0000

There's a quiet failure mode in collaborative software: permissions that hide things in the interface but don't actually protect them.

The document disappears from the sidebar, so everyone assumes it's private. Then someone pastes a direct link into chat, and it opens. The hiding was cosmetic. The authorization was never real.

We recently reworked access control in Andika, and the guiding rule was simple: access has to be enforced everywhere the data can be reached, not just where it's displayed.

Default open, precisely closed

The collaboration model starts permissive on purpose. When you invite someone to a workspace, they can see and work in it. That's what makes sharing low-friction.

The control comes from exceptions. Workspace owners and administrators can restrict individual notebooks, documents, and attached files, so sensitive research, contracts, or internal drafts stay protected without forcing you to create a whole separate workspace every time something confidential comes up.

This "default open, precisely closed" shape matters. If privacy requires restructuring your entire workspace hierarchy, people won't use it, and the sensitive material ends up in the shared space anyway.

Enforcement means every surface

The part that does the actual work is unglamorous: every way a piece of content can be reached has to check the same rule. When someone is excluded from a document in Andika, that means it's gone from:

navigation and search results
knowledge maps and analytics
notifications and mentions
direct links (the important one)
revision history and discussions
AI-assisted features that read workspace content
attachments and live collaboration sessions

That last category is easy to forget and dangerous to forget. An AI feature that cheerfully summarizes a document the requester can't read is an authorization bypass with good branding. Any feature that retrieves context on a user's behalf, whether it's search, an LLM integration, or an export, has to evaluate the same permissions as the page view.

Revocation has to be just as thorough. If access is withdrawn while someone is mid-edit in a live collaboration session, the session closes immediately. A permission change that only takes effect "next login" is a permission change that didn't happen.

The takeaway

If you build or buy collaborative software, the test isn't "does the hidden thing disappear from the menu?" It's "enumerate every path to the data and check the lock on each one." Links, APIs, exports, search indexes, AI retrieval, live sessions. The count of paths is always bigger than you first think.

Privacy that lives only in the UI is a vibe. Privacy that lives in the data layer is a property.

This post was adapted, with AI assistance, from an article on the Andika blog, where we build a collaborative writing and knowledge platform.

Designing a read-only MCP server first: least privilege for AI context

Boitumelo Phetla — Tue, 20 Oct 2026 08:46:17 +0000

Giving an AI application access to your users' knowledge is a trust decision before it's an engineering decision.

At Andika we recently shipped our first Model Context Protocol (MCP) connection, and we made a choice that shaped the whole design: the first release is read-only. Here's the reasoning, and the specific controls that fell out of it.

What MCP gives you, in one paragraph

MCP is a standard interface between applications and LLM clients on one side, and systems that hold context and tools on the other. Depending on what the server exposes, a connected client can read resources, call tools, and take actions. Instead of copy-pasting documents into a chat window, a user can connect a tool to their workspace and let it work with their documents through a governed channel.

The power is obvious. So is the risk: you've just built a machine-consumable pipe into people's private knowledge.

Why read-only first

The protocol supports far more than reading, and that's exactly why we started with less. Write access is where the irreversible mistakes live. A connected application that can edit, publish, delete, or invite members can do real damage with a single bad call, and "the model did it" is not an acceptable incident report.

So our first MCP release draws the line firmly: connected applications can discover workspaces, search documents, read pages, examine revisions, and retrieve asset knowledge. They cannot edit, publish, delete, invite members, or change permissions. That's a scoping decision we made for this release, not a limitation of MCP itself. Expanding the boundary later is a deliberate project, not a toggle.

The controls that made it shippable

Named, expiring, revocable tokens. A user creates a connection token for a specific application, with a name they'll recognise later ("my research assistant") and an expiry. The raw token is shown once and stored as a hash, the same discipline as API keys and passwords.
The connection acts as the user who created it. Not as the platform, not as a superuser. It inherits exactly that user's permissions: organisation boundaries, workspace membership, group access, page and asset restrictions, deleted content, account status. If the user can't see it, the connection can't see it. Notably, even a platform administrator doesn't automatically get access to another organisation's private workspace, and the connection respects that too.
A dedicated audit trail. Every MCP operation is recorded. Sensitive search text is hashed rather than copied into audit records, because an audit log that leaks the very queries it protects is a liability wearing a costume.
Revocation is a first-class feature. The moment a connection feels wrong, the user kills it, and it dies completely.

What this means for ML tooling

The interesting engineering question in LLM tooling right now isn't "how do we give the model more context?" It's "how do we give it the right context, under governance the user can actually reason about?"

A read-only, permission-inheriting, audited context channel is a foundation you can build on. When we do open write capabilities, the plan is granular scopes, explicit confirmation for consequential actions, optimistic revision checks so a stale client can't silently overwrite newer work, and a complete OAuth authorization flow.

The broader lesson applies beyond MCP: treat every integration that touches user knowledge as a privilege negotiation, not a feature flag. Start with the smallest capability that delivers value, instrument it, and earn the right to expand.

This post was adapted, with AI assistance, from an article on the Andika blog, where we build a collaborative writing and knowledge platform.

Why we moved file storage out of PostgreSQL blobs into object storage

Boitumelo Phetla — Tue, 20 Oct 2026 08:46:10 +0000

Every side-project-turned-real-product has a moment where an early shortcut starts sending you invoices. Ours was storing uploaded files as blobs in PostgreSQL.

It worked. It was simple. And then it started getting in the way.

This is the story of why we moved Andika's file storage out of the database and into dedicated object storage, and what changed when we did.

The shortcut that got us here

When you're moving fast, putting file bytes in the database next to everything else is tempting. One system to back up, one connection to manage, no extra infrastructure. PostgreSQL will happily store binary data, and for a while the numbers are small enough that you never think about it.

The problems arrive gradually:

The database becomes a file server. Every upload and download is a round trip through the same engine that's supposed to be answering queries. Large files hold connections open and chew through memory.
Backups get heavy. Your careful backup strategy now includes gigabytes of immutable file bytes that never change but get carried along anyway.
Scaling gets awkward. You can scale a database, but you really don't want to scale it because someone uploaded a 40 MB PDF.
The data model lies to you. A row that says document_id, filename, bytes hides the truth: the bytes are not relational data. They're cargo.

None of this is PostgreSQL's fault. It's a brilliant database. It's just not a blob store.

What we moved to

We migrated uploaded files and document assets to dedicated object storage (DigitalOcean Spaces, which speaks the S3 API). The division of labour is now clean:

Object storage holds the bytes. PDFs, images, Word documents, presentations. Immutable, addressable, cheap to store, straightforward to cache and serve.
PostgreSQL holds the truth about the bytes. Metadata, provenance, ownership, workspace relationships, permissions, revision history.

Every stored object is organised under unique organisation and workspace identifiers. That naming scheme prevents key collisions between tenants and keeps each customer's objects grouped under their own prefix. One thing worth being precise about: the prefix layout is organisation, not authorization. Who may read or write an object is still decided by the platform's permission checks on every request; the layout just means a bug or a bad guess at a key can't wander into another customer's namespace by accident.

What changed for us

The database went back to doing what it's good at: structured queries over structured information.
File delivery no longer competes with query traffic.
Database backups no longer carry immutable file bytes, and object storage has its own durability model.
Capacity planning became two independent conversations instead of one panicked one.

The lesson I'd hand to my earlier self

"Boring" architectural decisions compound in both directions. Storing blobs in the database is a reasonable day-one choice and an expensive day-hundred choice. The earlier you separate bytes from metadata, the cheaper the separation is.

It's the same principle behind a lot of good system design: put each kind of data in the place that's shaped like it. Files are shaped like object storage. Relationships are shaped like a relational database. Forcing one to be the other works right up until it really doesn't.

This post was adapted, with AI assistance, from posts on the Andika blog, where we build a collaborative writing and knowledge platform.

Idempotency: the small idea that stops your app from doing things twice

Boitumelo Phetla — Tue, 20 Oct 2026 08:45:59 +0000

You hit "submit" on a form. The spinner turns. Nothing happens. You hit it again. And again.

If the backend isn't designed for that moment, you just created three submissions. Or three charges. Or three identical comments on someone's post.

The idea that prevents this is called idempotency, and it's one of those concepts that sounds academic until the day it saves your production database.

What idempotency actually means

An operation is idempotent when performing it once has the same effect as performing it many times. The first request does the work; every identical retry produces no new effect.

This matters because duplication pressure is normal behaviour, not an edge case. Users double-click and refresh. Networks time out mid-request, leaving the client unsure whether the server did the work. Load balancers, gateways, and retry policies in client libraries can all cause the same request to arrive more than once. If your API treats every arrival as a brand-new instruction, duplicates are a question of when, not if.

HTTP already gives you hints

The HTTP verbs encode this idea:

GET, HEAD, PUT, and DELETE are designed to be idempotent. Deleting a resource twice has the same end state as deleting it once: it's gone.
POST is not idempotent by convention. Each POST is, by default, a new "create" instruction.

That "by default" matters. A POST endpoint can absolutely be designed to behave idempotently. That's exactly what the idempotency-key pattern does, and it's why the duplicate-submission problem almost always gets solved on the POST endpoints: creating comments, processing payments, submitting assignments.

The idempotency-key pattern

The standard fix for non-idempotent endpoints is the idempotency key:

The client generates a unique key for one logical operation (a UUID works fine).
The client sends it with the request, usually as an Idempotency-Key header.
The server records the key when it processes the request and treats later arrivals of the same key as duplicates of the first, skipping the side effects.
Many implementations also store the first response and replay it to the retrying client, so a retried request gets the original answer back instead of an error. Storing and replaying the response is a design choice on top of the core guarantee, not a requirement for idempotency itself, but it makes retries behave the way users intuitively expect.

Change anything meaningful about the request and it becomes a new operation with a new key. Stripe popularised this pattern for payments, and it's the reason retrying a payment request doesn't charge a customer twice.

Implementation details worth thinking about:

Enforce uniqueness with a database constraint, not application logic alone. Race conditions laugh at if (!exists) checks.
Scope keys per user or tenant so one user's key can never mask another's request.
Give keys a sensible expiry. You need them long enough to cover realistic retry windows, not forever.

Why this matters beyond payments

Once you see the pattern, you see the problem everywhere: webhook receivers, queue consumers (most queues guarantee at-least-once delivery, which means duplicates by design), sync engines, form submissions, file uploads.

We ran into the submission version of this while building Andika. A reply or an assignment that a user submits should exist exactly once, no matter how many times the request arrives. So requests carry a unique key, the first one is processed, and matching duplicates are recognised and ignored. It's a small amount of code that removes an entire category of bugs and support tickets.

For software engineering generally, idempotency is really about a mindset: assume every request may arrive more than once, and design the system so that's safe. Retries become harmless. Recovery becomes boring. Boring is good.

For machine learning pipelines the same principle shows up in data ingestion and training jobs: reprocessing a batch should not double-count it. Deterministic keys and dedupe at the write boundary keep datasets honest.

It's not glamorous. It's just correct.

This post was adapted, with AI assistance, from an article on the Andika blog, where we build a collaborative writing and knowledge platform.