TL;DR
Threlmark’s local-first design treats disk storage as the real source of truth, making data portable, offline-capable, and easy to sync. This approach simplifies development and enhances privacy, shifting the entire paradigm.
Imagine a project management tool that works perfectly offline, requires no cloud login, and lets you see every change just by browsing files. That’s the core idea behind Threlmark’s approach. It’s built on a simple but radical truth: the disk is the contract.
Instead of relying on a server or a database, Threlmark treats your local files as the single source of truth. This might sound counterintuitive in a world obsessed with cloud sync and databases, but it’s a game-changer for privacy, resilience, and simplicity. Here’s what makes this approach different—and why it could reshape how you build or choose productivity apps.
In this deep dive, you’ll see how the on-disk layout acts as the API, how files are safely written and merged, and why this architecture supports multi-device sync, external tool participation, and even AI automation—all without a central server.
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.
![Free Fling File Transfer Software for Windows [PC Download]](https://m.media-amazon.com/images/I/41Vq6ZqHfjL._SL500_.jpg)
Free Fling File Transfer Software for Windows [PC Download]
Intuitive interface of a conventional FTP client
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-First Apps: Mastering Progressive Web Apps (PWA): Build fast, reliable web applications that work anytime, anywhere (even without internet)
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.
Free Fling File Transfer Software for Windows [PC Download]
Intuitive interface of a conventional FTP client
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.
BusyBox D Digital Smart Sign: Customizable HD Display, App + Voice Control, Stream Deck & IFTTT Compatible, Rechargeable Bluetooth “Do Not Disturb” Light for Calls, Recording & Telehealth Privacy for HIPAA Workspaces
👩💻 [Me Time] Signal Focus, Privacy & Professionalism. Always. Display your status in bright, clear text or animated…
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
- Treat your disk files as the true source of data—don’t rely on a server database for the core state.
- Use atomic writes and conflict-aware merges to ensure data integrity and safety.
- Design your app so that every artifact is inspectable and portable—just files, no lock-in.
- Local-first architecture improves privacy, resilience, and user control, especially for offline use.
- External tools can participate freely by reading and writing files, enabling extensibility.
What ‘Disk Is the Contract’ Really Means
At its core, “disk is the contract” means your data lives on your device’s storage, not on a server. The files are the authoritative source—any tool or app reads or writes to those files directly. Think of it like a shared notebook that’s always up-to-date, no matter where you open it.
Why does this matter? Because it shifts the entire paradigm of data ownership and control. When files are the source of truth, you’re not dependent on external servers or proprietary databases, which can introduce points of failure, privacy concerns, or vendor lock-in. This approach emphasizes local control, making your data inherently more resilient to outages or attacks. Moreover, it simplifies troubleshooting—if something goes wrong, you have direct access to the raw files to diagnose or fix issues. The tradeoff, however, is that managing complex relationships or large-scale data consistency requires careful design—files need to be structured in a way that supports safe concurrent edits and conflict resolution. But when done correctly, this model empowers users with true portability and transparency, fostering a more resilient and privacy-conscious ecosystem.
How Local-First Differs From Traditional Cloud Apps
| Feature | Cloud-First Apps | Local-First Apps like Threlmark |
|---|---|---|
| Data Storage | Primarily on servers, with local cache | |
| Offline Use | Limited or no access without connection | |
| Sync Method | Push/pull to cloud, often with conflicts | |
| Ownership | Cloud provider controls data | |
| Resilience | Dependent on server availability |
In contrast, Threlmark stores everything locally, making it instantly accessible and editable offline. This local storage fundamentally alters the user experience: data is always available, and the app’s responsiveness is limited only by local hardware. Syncing becomes a background process—merging changes seamlessly—reducing the cognitive load on users and developers alike. This design choice also means that data ownership is clearer; users retain full control without vendor dependency. However, it requires meticulous conflict management and careful design of the file structure to prevent data corruption or loss. The tradeoff is increased complexity in handling concurrent edits, but the payoff is a system that is inherently more resilient, private, and user-centric.
How Changes, Sync, and Conflicts Get Resolved Without a Server
In Threlmark, the local files are the source of truth, and sync is a background process. Changes made on one device are stored as separate JSON files. When sync kicks in, it compares files and merges updates.
Why is this significant? Because it decentralizes conflict resolution, giving users and developers more control over data integrity. The merge logic is designed to preserve all updates and resolve conflicts automatically whenever possible, much like a skilled editor balancing overlapping edits. This approach reduces reliance on centralized conflict resolution mechanisms, which can often be slow or opaque. Instead, conflicts are handled locally, with the system intelligently merging changes based on timestamps, content, or custom rules. This local conflict management not only improves responsiveness but also enhances security—since no external server needs to mediate disputes. The tradeoff is that conflict resolution must be carefully engineered to prevent data loss or inconsistency, especially in complex scenarios. Nonetheless, this model promotes a resilient system where data can be safely edited across multiple devices without risking corruption or requiring complex locking mechanisms.
Why Developers Are Embracing This Now — And How It Changes Everything
Developers love this approach because it reduces backend complexity, cuts costs, and improves user privacy. Instead of building and maintaining a server, they focus on local logic and synchronization.
But why is this trend accelerating now? Because modern devices and network environments increasingly favor offline-capable, resilient systems. As users demand faster, more reliable experiences—especially in areas with spotty connectivity—local-first architectures become more attractive. Developers recognize that by minimizing server dependencies, they can create more robust, scalable, and privacy-preserving apps. This shift also enables faster development cycles and easier testing—since local files are straightforward to manipulate and debug. Additionally, the rise of open standards and tools like [Threlmark](https://github.com/MeyerThorsten/threlmark) make implementing local-first patterns more accessible than ever. The tradeoff is that developers need to invest in conflict management and schema evolution strategies, but the benefits in user trust, data control, and resilience are compelling. Ultimately, this approach empowers developers to build apps that are more adaptable, user-centric, and future-proof.
Security, Privacy, and Longevity: What This Architecture Offers
When your data lives primarily on your device, it becomes inherently more private and secure. No central server means fewer attack vectors, reducing the risk of mass data breaches. Plus, your data isn’t subject to third-party breaches or government data requests, which significantly enhances privacy.
Threlmark’s approach further allows for local encryption—users can encrypt files before sync, ensuring that even if data is intercepted, it remains protected. Since files are plain JSON, they’re easy to back up, migrate, and audit, which extends the longevity of your data. This design also simplifies long-term data preservation: as hardware ages or platforms evolve, users can easily transfer files to new devices or formats without vendor lock-in. The durability comes from the fact that the core data is stored in transparent, well-structured files that can be read and manipulated without proprietary tools. This openness fosters a more resilient data ecosystem, where users maintain full control over their data’s security and longevity—key considerations for both individual users and organizations with compliance needs.
Common Pitfalls and How to Avoid Them
Building a system where files are the source of truth isn’t without challenges. The biggest is managing conflicts and ensuring data consistency—without a centralized authority, conflicts can become complex if not handled carefully. Relying solely on file merges can lead to subtle bugs or data corruption if the merge logic isn’t robust or if files become inconsistent due to partial writes or crashes.
Another common pitfall is data loss during unexpected shutdowns or crashes. Threlmark mitigates this risk with atomic file writes—writing to a temporary file and then atomically moving it into place ensures that partial or corrupted files are avoided. However, developers must rigorously test their conflict scenarios and consider edge cases, such as simultaneous edits or schema changes, to prevent data corruption. Schema evolution, in particular, can be tricky; if not managed carefully, updates to data structures may break compatibility or cause data loss. Threlmark addresses this through tolerant normalization—preserving unknown fields and merging updates in a way that allows for backward compatibility. The key takeaway is that careful planning, rigorous testing, and atomic operations are essential to maintain data integrity in a file-based, local-first system.
Tools and Patterns That Make Local-First Possible
Many modern tools now support local-first principles. Threlmark itself is built with simple, robust patterns: atomic file writes, file-based merge, and self-healing boards. For sync, it can integrate with background processes or external sync engines.
Other tools like [IdeaClyst](https://github.com/MeyerThorsten/threlmark) participate by reading or writing files directly, without needing permission. This openness makes the system extensible.
Popular patterns include:
- Atomic file operations
- Content-addressable storage
- Conflict-aware merge strategies
These patterns empower developers to craft resilient, portable apps that work offline and sync seamlessly in the background. They also support extensibility—developers can build plugins or integrations that respect the core principles without sacrificing safety or consistency.
Frequently Asked Questions
What does ‘local-first’ actually mean?
Local-first means your app treats your device’s storage as the primary source of truth. Data lives on your disk, making it accessible offline, easy to back up, and under your control. Cloud or sync is secondary, not the core.
How does sync work if the disk is the source of truth?
Sync happens passively in the background. Changes are stored as files, and sync tools compare and merge these files across devices. Conflicts are resolved locally, without needing a central server.
What happens if two devices edit the same data at once?
The system compares the two versions and merges them intelligently. Most conflicts get resolved automatically, preserving all updates without data loss or corruption.
Is local-first architecture secure?
Yes. With data stored locally, there’s less surface for attacks. Plus, you can encrypt files before syncing. Your data stays under your control, reducing reliance on third-party servers.
Can I build collaborative apps with this approach?
Absolutely. Using conflict-free merge strategies like CRDTs or commit graphs, local-first apps can support real-time collaboration while keeping data decentralized and private.
Conclusion
In a world obsessed with cloud and server dependence, Threlmark shows that the simplest approach can be the most powerful. Making disk the contract turns your device into a fortress of data, resilient and private. It’s a quiet revolution that puts the user back in control, with nothing more than plain files.
Next time you build or choose a tool, ask: is the disk the true contract? If yes, you’re embracing a future where your data is truly yours—portable, secure, and unstoppable.
