TL;DR
Threlmark’s local-first architecture treats disk storage as the single source of truth, enabling offline use, easy sync, and user ownership. It’s a simple yet powerful way to manage project data without a cloud or database.
Imagine working on your project, making changes, and never worrying about losing data—even if your internet drops or your server goes offline. That’s the promise of local-first architecture, and Threlmark embodies it perfectly.
At its core, Threlmark turns the idea of a database upside down. Instead of a cloud server holding the truth, your disk becomes the single source of truth. It’s a simple idea with big implications: your data is portable, conflict-resistant, and accessible anytime, anywhere.
.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.
Samsung T7 Portable SSD, 1TB External Solid State Drive, Speeds Up to 1,050MB/s, USB 3.2 Gen 2, Reliable Storage for Gaming, Students, Professionals, MU-PC1T0T/AM, Gray
MADE FOR THE MAKERS: Create; Explore; Store; The T7 Portable SSD delivers fast speeds and durable features to…
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.
NEWQ 2TB External Hard Drive for iPhone, USB-C & Lightning Compatible Photo Storage Device, One-Click Backup Photos/Videos to Free Up Phone Space, Offline Transmission Support, No Computer Required
2TB Large Capacity One-Click Backup, Instantly Free Up Your Phone Storage: Running out of phone storage often forces…
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.
![WavePad Audio Editing Software - Professional Audio and Music Editor for Anyone [Download]](https://m.media-amazon.com/images/I/B1fcLEGCs6S._SL500_.png)
WavePad Audio Editing Software – Professional Audio and Music Editor for Anyone [Download]
Full-featured professional audio and music editor that lets you record and edit music, voice and other audio recordings
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.
Real-World Android App Projects with Kotlin and Jetpack Compose: Build Production-Style Android Apps with Modern Architecture, API Integration, State Management, Local Data Storage, Practical Projects
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’s architecture treats disk storage as the single source of truth, making data portable and transparent.
- Using one file per item and atomic writes prevents race conditions and keeps data consistent.
- Background sync and conflict resolution allow seamless multi-device workflows without a central server.
- Designing with files as the contract simplifies backup, migration, and interoperability.
- While powerful, local-first systems require careful handling of conflicts and security considerations.
Why Threlmark’s Disk-First Approach Changes Everything
Threlmark’s choice to make the disk the contract means your data lives where you can see it, edit it, and back it up with a simple copy. No server, no cloud, no lock-in. This design keeps your project portable and your data under your control.
For example, your roadmap is just a folder of JSON files on your machine. When you add a new card, it’s just a new file—no database, no API call. This simplicity makes it easy to understand, backup, and migrate.
More deeply, this approach emphasizes transparency and resilience. By making data accessible as plain files, you reduce complexity and dependency on external systems, which can introduce points of failure or obscure data integrity. It also means that you inherently gain control—you’re not at the mercy of a cloud provider’s policies or outages. However, this simplicity also means developers and users need to be aware of how to handle conflicts and ensure data consistency, especially when working across multiple devices or users. The tradeoff is that while this approach offers maximum control and transparency, it requires careful management of concurrent changes and understanding of file-based workflows.
How the File Layout Acts Like a Contract You Can Read
Every piece of data in Threlmark lives in a specific file, from project metadata to individual cards. This file structure is more than just organization; it’s a contract that anyone can read, modify, or extend.
For example, if you want to see all your cards, just open the `items/` folder and read the JSON files. Want to add a new status? Just add a key in the relevant file. No special tools needed.
Understanding this as a contract means recognizing that the data format is both a schema and a communication protocol. It’s flexible enough to be extended or adapted, but structured enough to maintain consistency. This transparency enables easier debugging, manual edits, and integration with other tools. The tradeoff, however, is that this openness can lead to inconsistencies if users or tools modify files without coordination, which is why careful merge strategies and validation are essential for maintaining data integrity across multiple sources.
Making File Operations Safe: Atomic Writes and Merge Strategies
Writing data to disk can be risky—crashes or interruptions might corrupt files. Threlmark solves this with atomic writes: it writes to a temp file and then renames it. This guarantees that your data is never half-written.
When updating, it merges changes carefully—preserving metadata like creation dates and unknown fields. This makes updates safe, even if multiple tools or devices modify data at once.
Beyond the technical safeguards, these strategies have important implications for user trust and system resilience. Atomic writes prevent corruption that could otherwise lead to data loss or inconsistent states, especially during unexpected shutdowns or crashes. Merge strategies that preserve metadata and unknown fields reduce the risk of overwriting important information, ensuring that updates are additive and non-destructive. The tradeoff is that complex merge logic can sometimes lead to conflicts that require manual resolution, and developers must carefully design these strategies to balance safety with usability.
Single Files Per Item? Yes, and It’s Brilliant
Instead of one big JSON list, Threlmark keeps each roadmap card in its own file. This approach prevents race conditions and makes it easy to update individual items without touching the whole list.
Imagine editing a task on your phone while someone else updates a different task on your laptop. Because each file is atomic, both changes can happen without clobbering each other.
This design simplifies concurrency management because it localizes potential conflicts. Instead of dealing with complex diffing of large datasets, the system only needs to handle conflicts at the file level, which is easier to resolve and reduces the chance of errors. The tradeoff, however, is that managing many small files can become cumbersome in very large datasets, and users or developers need to implement efficient file handling and indexing strategies to keep performance optimal.
How Threlmark Syncs Data Without a Central Server
Threlmark doesn’t rely on a cloud to sync. Instead, it uses background processes that copy files across devices or to shared folders. When two devices are online, they compare their files, merge changes, and keep everything up to date.
For example, if you update a task on your laptop and then open Threlmark on your phone, it’ll automatically sync the latest files when connected to the same folder via Dropbox or Syncthing.
This peer-to-peer synchronization approach reduces reliance on centralized servers, which can be points of failure or introduce latency. It also enables more control over data flow, as users can choose their sync methods and locations. However, it requires robust conflict detection and merging logic, especially when multiple devices modify the same data simultaneously. The tradeoff is that while this decentralization increases resilience and privacy, it can be more complex to set up and troubleshoot compared to traditional cloud sync solutions.
Conflict? Threlmark Handles It Gracefully
When two devices change the same card differently, Threlmark’s merge logic kicks in. It combines the changes, preserves metadata and unknown fields, so nothing gets lost.
For example, if you move a task from ‘In Progress’ to ‘Done’ on your desktop, but your phone later shifts the same task back to ‘In Progress,’ Threlmark intelligently merges both updates.
This conflict resolution is vital for maintaining data integrity and user trust in a decentralized environment. It allows users to work freely across devices without fear of losing changes or creating inconsistent states. The tradeoff, however, is that complex conflicts may sometimes require manual intervention, especially in edge cases, which emphasizes the importance of designing merge strategies that are both robust and user-friendly.
Real-World Example: Managing a Multi-Device Roadmap
Imagine you’re working on a project with your laptop at home and your tablet on the go. Both devices read and write directly to the same folder of JSON files.
You update a card on your laptop, then walk into a coffee shop. When your tablet connects, it automatically syncs and merges changes. No cloud needed. Your project stays seamless and consistent across all your devices.
Why Developers Are Moving Toward Local-First Architectures
Local-first isn’t just about offline use; it’s about reducing backend complexity and giving users control over their data. Developers see it as a way to build faster, more resilient apps that respect user ownership.
According to recent trends, tools like CRDTs and sync infrastructure make real-time collaboration easier, pushing local-first into mainstream development.
By shifting to local-first, developers can also improve privacy and security, since data remains on devices rather than passing through centralized servers. This reduces attack surfaces and compliance burdens. The tradeoff is that building and maintaining conflict-free synchronization and user-friendly offline workflows requires more sophisticated design and testing, but the benefits in resilience and user trust are significant.
Tradeoffs and Limitations: What You Need to Know
While local-first is powerful, it’s not perfect. Sync conflicts can get complex, and large datasets may slow down file operations. Also, security depends on device encryption, not a central server.
For example, if your disk gets stolen, your data is only as secure as your device’s encryption. Plus, without a central server, sharing large files or multi-user editing can be tricky.
Additionally, as datasets grow, file-based systems may face performance bottlenecks, and managing consistency across many devices becomes more challenging. These limitations highlight that local-first systems excel in resilience and control but require careful planning, especially for large-scale or collaborative applications. Tradeoffs include increased complexity in conflict resolution, potential performance issues, and the need for robust security measures tailored to each device.
Frequently Asked Questions
How does Threlmark handle conflicting edits on different devices?
Threlmark uses merge logic that combines changes, preserves metadata, and keeps unknown fields intact. It ensures that edits from multiple devices are integrated smoothly, preventing data loss and keeping your project consistent.
Is local-first architecture secure if data is stored on my device?
Yes, but security depends on device encryption. Since data resides on your disk, using full-disk encryption or secure storage methods is crucial. Threlmark itself doesn’t add encryption but relies on your device’s security features.
Can I still work offline with Threlmark?
Absolutely. All operations happen directly on your disk, so you can add, edit, or move cards without an internet connection. Syncs happen automatically once you’re back online.
What happens if Threlmark’s developer stops maintaining it?
Since all data lives on your disk in plain files, you can migrate or back it up easily. You’re not locked into a proprietary database or cloud service, so your project remains accessible and portable.
Conclusion
Threlmark’s local-first design proves that simplicity can be a superpower. Your data lives on your disk—clear, portable, and under your control. It’s a reminder that sometimes, the best architecture isn’t the most complex.
Next time you think about data storage, ask yourself: what if the disk truly *is* the contract? The future of resilient, user-owned software might just be right there, waiting for you to take control.
