TL;DR
Threlmark’s local-first architecture makes disk storage the single source of truth, enabling offline work, faster interactions, and seamless multi-device sync—all without a central database. This approach simplifies development and puts data ownership back in users’ hands.
Imagine an app where your data lives right on your device. No cloud, no server, no login required. It’s fast, private, and always available—even offline.
That’s the promise of Threlmark’s local-first architecture. Instead of relying on a central database, it treats your disk as the contract—the single source of truth. In this article, I’ll walk you through how this simple idea rewires everything from concurrency to collaboration, and why it might just be the future of smarter, more trustworthy apps.
Disk is the contract: inside a local-first roadmap hub
A Next.js app on top of plain JSON files — no database, no cloud, no accounts. The key decision: the on-disk layout IS the API. Everything else cascades from taking that seriously.
There is no server-of-record — the files are the record
The UI and any external tool reach the same files through the same discipline. The data root defaults to ~/.threlmark — home-based, because it’s a shared hub every one of your apps points at.
Inspectable
Every artifact is a file you can cat, diff, grep, commit.
Portable · no lock-in
Back up with cp, sync with Dropbox / git, migrate trivially.
Interoperable
Any tool in any language joins by reading / writing files.
Restartable
No in-memory state to lose — stateless over the files.
external SSD portable storage
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
Two disciplined patterns instead of a database
“Just use files” is easy to get wrong. These two patterns — ported from a battle-tested sibling app — are what make file-based state sound rather than reckless.
Atomic writes
Write to a temp file in the same dir, then rename() over the target. Rename is atomic on one filesystem — a crash mid-write leaves the complete old file or the complete new one, never a half.
The board heals itself
A single roadmap.json array races when two tools write at once. One file per card makes writes collision-free. Lane order lives in board.json and reconciles on read.
board.json. It writes an item file — the board fixes itself on Threlmark’s next read. Unknown keys are preserved, so the contract is forward-compatible.offline data synchronization device
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
The numbers can’t drift from the files
Anything computable from item state is computed — so the displayed numbers can never disagree with the underlying JSON. Priority is the clearest example: it’s calculated on read, never persisted.
priority — computed on read
Impact weighted heaviest; effort the only axis that subtracts. Reused verbatim from the original tool, so imported cards rank identically.
local data backup drive
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
A handoff is a first-class flow event
The genuinely 2026-shaped part: most building is done by AI agents, so Threlmark closes the loop. Watch a card go from ranked to Done without anyone dragging it.
Handoff → report → self-move
The brief carries a reporting protocol. The agent reports through REST or the filesystem — and a done report moves the card itself.
POST /api/projects/:id/
items/:itemId/reportDirect call. Applied immediately.
drop reports/.json
→ ingested on read Robust even if the server’s down at finish time.
JSON file storage device
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
A small formula, and an honest hosting caveat
Because items are globally addressable (
Portfolio ranking — status-weighted
In-flight work floats to the top; bottlenecks cost the most, so blockers get nudged up.
Static read-only demo
Seeded data, writes to localStorage. Try-before-you-clone.
Personal Node instance
Password-gated, persistent backed-up THRELMARK_DATA_DIR.
Multi-tenant SaaS
Add accounts + per-tenant isolation. A separate build.
src/lib/*/store.ts is the natural seam — the same boundary that keeps the local tool simple is the one you’d extend for multi-tenancy. The architecture doesn’t fight that future; it just doesn’t pay for it until you need it.
Key Takeaways
- Threlmark uses local disk storage as the definitive record, making data portable and transparent.
- Atomic file operations and merge strategies keep data safe and reduce conflicts.
- One file per item prevents race conditions and simplifies concurrency handling.
- The filesystem layout doubles as a human-readable API, easing integration and backups.
- Local-first design reduces backend complexity, enhances privacy, and improves offline resilience.
Why Threlmark’s Disk Is the Contract Changes Everything
Threlmark’s core idea is simple but revolutionary: your device’s storage is the definitive record of your data. This means the file layout isn’t just storage; it’s the API. Every tool, script, or app reads or writes directly to these files, making everything transparent and portable.
For example, a project folder might hold a `threlmark.json` manifest, individual card files under `items/`, and a `ROADMAP.md` mirror. This setup means you can back up, sync, or migrate your data by copying files—no vendor lock-in, no proprietary database.
How Threlmark Keeps Data Safe and Consistent with Files
Threlmark uses two key patterns to keep data safe on disk. First, *atomic writes*—every change writes to a temporary file that then `rename()`s over the original. This guarantees no half-written files, even if your system crashes mid-save.
Second, it employs *read-merge-write* strategies. When updating a card, it reads the current file, merges changes, and writes back atomically. This approach allows multiple tools to update data without clobbering each other, even when working offline.
Imagine editing a task in your app while another device adds a linked note. Both changes merge smoothly without conflicts, because each update respects the existing data structure.
One File Per Card: How Threlmark Handles Concurrency and Repair
Instead of a giant JSON array, Threlmark stores each card in its own file (`items/
The *board* — the visual lanes of your roadmap — is stored in `board.json` but heals itself on each read. If a card disappears or gets misplaced, the system automatically re-syncs, keeping everything aligned.
For example, if you drag a card between lanes, only that card’s file updates, not the entire list. And if a card is deleted, it gets marked as archived rather than lost, preserving history.
The Role of the Filesystem as the API — Real Benefits for You
Using the filesystem as the API means everything is inspectable, modifiable, and portable. Want to see your project’s structure? Just `cat` the files. Need to compare versions? Use `diff`. Want to migrate data? Copy the folder. Learn more about disk-based architectures.
For instance, if you want to integrate Threlmark with a script, just read or write the JSON files directly. No special SDK or database driver needed.
This approach also simplifies backups and restores: just copy your entire data directory. It’s like having a raw, human-readable database in your hands.
Sync, Collaboration, and Conflict Resolution Without a Server
Threlmark handles multi-device sync in the background, using a simple folder of files that all devices can access. Changes are merged automatically, thanks to merge strategies that respect the existing data. For more on sync strategies, see this deep dive.
For example, if two devices update the same card at once, the system merges the changes or flags conflicts. This makes collaboration feel seamless, even when offline or on flaky networks.
In more advanced setups, CRDTs (Conflict-free Replicated Data Types) can be employed to resolve concurrent edits gracefully. The key is that the disk layout and merge logic stay the same, regardless of how complex the sync gets.
Real-World Benefits for Developers and Users
For users, Threlmark means instant access, offline capabilities, and full data ownership. No login, no cloud dependency. Imagine working on your project during a flight, then syncing once back online, with no data loss or conflicts. Discover more about secure data management.
Developers get a simpler backend. No database migrations, no server-side logic. Just files. This reduces bugs, speeds up iteration, and enhances security—since data never leaves your device unencrypted.
For example, teams can share folders through Dropbox or Git, and everyone stays in sync without server complexity. That simplicity can cut infrastructure costs and reduce maintenance headaches.
Hard Problems & Limitations — What You Need to Watch Out For
File-based systems aren’t magic. Sync conflicts, schema migrations, and data corruption can still happen if you’re not careful. Handling conflict resolution requires thoughtful merge strategies, especially for complex data. For insights on managing such issues, visit this resource.
For example, merging two simultaneous edits to a project’s card requires rules—CRDTs or custom logic—to avoid data loss.
Migration is another challenge: updating schemas without breaking existing data demands careful planning and versioning.
Finally, large files or many small files can slow things down—so consider batching or indexing for bigger projects.
The Future of Local-First Apps: More Than Just Files
As tools evolve, local-first architecture is moving beyond simple file layouts. Integrations with IndexedDB, service workers, or even custom databases are making it easier to build scalable, conflict-free apps.
For example, some apps use CRDTs layered on top of local databases, syncing changes via background jobs. Others employ hybrid models—local storage with optional cloud sync.
What’s clear: treating the device’s disk as the contract is just the start. The principles of openness, safety, and offline-first design are shaping the next wave of resilient, user-centric software.
Frequently Asked Questions
What exactly does “local-first” mean, and how is it different from “offline-first”?
Local-first means your device’s storage is the primary source of truth—data lives on your disk and syncs in the background. Offline-first focuses on your app working without internet; local-first ensures your actual data is always on your device, even if offline.
Where is the source of truth in a local-first app like Threlmark?
The source of truth is the files stored directly on your device. Threlmark’s layout makes these files the definitive record, so copying or backing up these files preserves your entire data set.
How does multi-device sync work without a server?
Devices share the same files, often via cloud sync like Dropbox or Git. Changes are merged locally, and conflict resolution strategies ensure data stays consistent across devices. The system is designed to handle concurrent edits gracefully.
What happens if two people edit the same item at the same time?
Threlmark employs merge strategies—either automatic CRDT-based resolution or conflict markers—to reconcile concurrent changes. This keeps everyone’s work safe and consistent without manual intervention.
Are local-first apps more secure and private?
They can be, since data stays on your device and doesn’t rely on a central server. End-to-end encryption is easier to implement, and you control backups and sync. But security depends on proper implementation.
Conclusion
Thinking of disk as the contract rewires how we build and trust apps. It’s a simple shift—your device is the authority, not some remote server—and it unlocks faster, more private, and more resilient workflows.
Next time you pick a tool, ask: does it treat my disk as the source of truth? If it does, you’re probably on the right path.
