TL;DR
Threlmark’s architecture centers on storing data directly on disk as JSON files, making the system fast, portable, and resilient. Syncing is a background process, and the design favors local-first workflows over traditional client-server models.
Imagine an app that instantly responds, works offline without a hiccup, and never loses your data — all because it treats your local disk as the ultimate authority. That’s the core idea behind Threlmark’s local-first architecture, where the filesystem isn’t just storage; it’s the contract that defines your app’s brain.
This shift from a server-centric mindset to a disk-centered one changes everything. It’s not just about saving files; it’s about making the files your app’s API, unlocking speed, resilience, and seamless collaboration in ways traditional databases can’t match. Learn more about local-first architectures.
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.
SANDISK 1TB Extreme Portable SSD (Old Model) – Up to 1050MB/s, USB-C, USB 3.2 Gen 2, IP65 Water and Dust Resistance, Updated Firmware – External Solid State Drive – SDSSDE61-1T00-G25
Get NVMe solid state performance with up to 1050MB/s read and 1000MB/s write speeds in a portable, high-capacity…
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.![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.
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.
Scan Reader Pen, 142 Language Scanning Translation 0.3S Recognition Speed, Great Voice Technology 134 Online Languages Support Offline File Convert Cloud Sync Portable for
[Compact and Portable] Smart scanning translator suitable for language learners, reading, and business travel, convenient for on-the-go use.
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.
Local Data Storage in Kotlin: Managing Databases in Android Environments (The Android Developer's Playbook)
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 treats the local disk as the system’s single source of truth, making data transparent and portable.
- Atomic file writes and tolerant merging prevent data corruption and ensure forward compatibility.
- One file per item avoids race conditions and simplifies concurrent updates.
- The architecture favors speed and offline resilience but shifts complexity to sync and conflict resolution.
- Using disk as the contract is ideal for apps needing speed, offline support, and multi-device collaboration.
Why the Disk Is the Heart of Threlmark’s System
In Threlmark, the disk isn’t just where data lives — it’s the single source of truth. All interactions read and write directly to JSON files, making the data transparent, portable, and simple to inspect.
For example, when you update a task card, the app writes a new JSON file in the items/ folder. No server needed. If you open the folder, you see every change, every history, in plain sight. This approach makes troubleshooting as easy as running diff or cat. Read more about local-first design.
This design is rooted in the broader local-first movement, where apps prioritize local storage and sync later, rather than relying on a central server for every operation.
How Threlmark’s File-Based Data Model Keeps Things Safe and Simple
Threlmark uses **atomic writes** and **tolerant merging** to keep data safe. When saving an item, it writes to a temporary file and then moves it over, avoiding partial corruption. This is like changing a page in a book only when the new page is ready.
For example, updating a card involves reading its current file, merging in changes, then atomically replacing it. If your computer crashes mid-save, the file remains either whole or not changed at all — no half-baked states.
Plus, the system preserves unknown fields during saves. That means newer tools can add extra data without breaking older versions that don’t recognize it — future-proofing the system.
One File Per Item: How Threlmark Avoids Race Conditions
Instead of a giant JSON array for all cards, Threlmark creates one file per item, like items/1234.json. This prevents conflicts when multiple tools update different cards simultaneously.
When the app reads the board, it checks each item’s file. If an item is missing or deleted, the board self-heals. This approach keeps everything consistent without locks or complex coordination.
For instance, if you drag a card from ‘In Progress’ to ‘Done,’ it updates just that one file. No need to lock the entire list — just atomic updates on individual files.
How the Board Self-Heals and Keeps Everything Organized
The lane order isn’t stored in a monolithic file but in board.json, which lists item IDs per lane. Every time you view the board, it cross-references each item file. Missing or moved items are automatically corrected.
This means your view always matches reality, even if an external tool modifies files directly or if something goes wrong during editing. It’s like the board has a built-in cleanup crew that keeps everything tidy.
How Threlmark Syncs Data Without Locking Users Out
Sync in Threlmark happens in the background. Changes made on one device are merged into the files, and conflicts are resolved via simple rules. Because each item is a separate file, syncing is just copying files around. Discover more about sync strategies.
Imagine working on your laptop offline. Later, when you connect, your changes merge with those from your phone or tablet. No fuss, no locking, just continuous flow.
This model is perfect for remote teams or fieldwork, where internet connectivity is spotty but the work keeps going.
Tradeoffs: Speed and Simplicity vs Sync Complexity
Using disk as the contract makes the system lightning-fast and straightforward. But it also shifts complexity to sync and conflict resolution. Managing concurrent edits across devices can get tricky.
For example, if two devices edit the same card offline, the system relies on simple merge rules. Sometimes, manual conflict resolution is necessary. But overall, the speed and offline resilience outweigh these challenges.
Traditional cloud systems handle conflicts with complex protocols, but Threlmark’s approach favors transparency and simplicity. See how local-first systems manage conflicts.
Real-World Use Cases: Why This Matters for Your Apps
Think of note-taking apps, creative tools, or internal project boards. They all benefit from fast local access, offline work, and easy collaboration.
For example, a designer working in a remote location can jot down ideas, sync when back online, and have a complete history of changes. Threlmark’s design means no waiting for server responses or risking data loss during connection drops.
This makes it ideal for desktop apps, field tools, or any scenario where speed and resilience matter more than centralized control.
What Are the Main Tradeoffs Compared to Cloud-First Systems?
Cloud systems centralize data and simplify conflict resolution, but they depend heavily on server uptime and network quality. Threlmark’s disk-first approach sacrifices some ease of collaboration for speed, offline support, and data transparency.
For instance, cloud apps often hide the complexity of conflict management. Threlmark exposes it, making conflicts visible and manageable but requiring more user or developer involvement.
In exchange, you gain speed, control, and resilience, especially in disconnected environments.
How To Keep Your Files Safe and Your Data Consistent
Follow these best practices: Learn more about data safety and security.
- Always write files atomically — no partial saves.
- Use tolerant merge strategies to preserve unknown fields.
- Regularly back up your data folder.
- Check for file corruption after crashes.
For example, setting up a simple cron job to copy your entire .threlmark folder nightly keeps your data safe. When you need to recover, just restore from backup, and everything remains consistent.
Frequently Asked Questions
What does ‘disk is the contract’ actually mean?
It means that the filesystem — the JSON files stored on disk — serve as the ultimate source of truth for the app’s data. The app reads and writes directly to these files, making the entire system transparent, portable, and resilient to network issues.
How is this different from a typical client-server setup?
Traditional apps rely on a central server to store and manage data. Threlmark’s approach keeps everything local on disk, with sync happening in the background. No constant server connection is needed, and the system is far more responsive and offline-friendly.
Why choose JSON files over a database?
JSON files are simple, human-readable, and easy to manipulate. They allow direct inspection, manual editing, and straightforward sync. Plus, avoiding a database reduces complexity and lock-in, making your app more flexible and portable.
How does sync work if the data is stored on disk?
Sync is a background process that copies, merges, and resolves conflicts between files across devices. Because each item is a separate file, conflicts are easier to handle, and no central lock is needed.
What happens when two devices edit the same item offline?
The system uses simple merge rules. If conflicts arise, it can flag them for manual resolution or keep both versions with special markers. This keeps the process transparent and manageable.
Conclusion
Choosing a disk-centered, local-first approach isn’t about replacing servers — it’s about empowering your app with speed, resilience, and clarity. When your data lives right on your disk, you hold the reins, not the cloud.
Next time you build or choose an app, ask yourself: does the data’s home matter? If so, you might just find that the disk really is the contract.
