TL;DR
Threlmark’s local-first design treats the on-disk JSON files as the primary record of truth. This approach boosts reliability, offline access, and interoperability, making it ideal for modern, flexible workflows.
Imagine a project management tool that works perfectly offline—no servers, no cloud, just plain files sitting on your disk. That’s the heart of Threlmark’s approach: the disk is the contract. It’s a bold idea that flips traditional app architecture on its head and offers a new way to think about data ownership, reliability, and collaboration.
This article peels back the layers of Threlmark’s local-first architecture. You’ll see how treating the disk as the single source of truth creates a resilient, flexible system that’s easy to inspect, migrate, and extend—without sacrificing speed or safety.
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.
Information Technology Project Management (Mindtap Course List)
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.
KALIM 2 Sets Carbon Steel File and Diamond File(Total 12pcs), Suitable for Metal, Wood, Jewelry, Model, DIY and Nearly All Uses, Packed in A Carry Bag.
PACKAGE INCLUDE: 6 Piece Carbon Steel File Set + 6 Piece Diamond File Set + 1 Storage Bag
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.
eufy Security eufyCam S330 (eufyCam 3) 4-Cam Kit, Security Camera Outdoor Wireless, 4K with Integrated Solar Panel, Face Recognition AI, Expandable Local Storage, Spotlight, No Monthly Fee
Crystal-Clear Night Surveillance: Achieve superior night vision with the eufy 4k camera's Starlight system, delivering 4K quality and…
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.
Lovell DESTRUCT PRO – USB Hard Drive Eraser & Data Destruction Tool – 3 Phase Crytopgraphic Wipe – Super Fast SMART Technology – Multi-Drive Compatibility – Works With HDD, SSD, & External Hard Drives
PERMANENT DATA DESTRUCTION: Factory resetting is a flawed process that isn’t enough to keep deleted data from being…
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 the on-disk JSON layout as the single source of truth to build resilient, portable apps.
- Use atomic writes and merge strategies to keep data safe and consistent, even during crashes.
- One file per item simplifies concurrency and makes the system self-healing on each read.
- Local-first architecture ensures offline access, speed, and data ownership without relying on the cloud.
- Sync is about eventual consistency, conflict resolution, and gentle merging—not real-time locking.
Why Your Data Should Live on Disk, Not Just in the Cloud
When most apps talk about “the cloud,” they treat it as the primary place data lives. Threlmark challenges that. It says: your disk is the real deal. It’s where the truth resides, and cloud sync is just a layer layered on top.
For example, if your laptop crashes, your data isn’t lost—it’s still safe on your local disk. You can keep working without internet. This is core to the local-first architecture: speed, resilience, and data ownership are baked in, not afterthoughts.
Inside Threlmark’s File Layout: The Real Contract
Threlmark’s architecture centers around a structured folder of JSON files. The root holds a manifest (`threlmark.json`) and links (`links.json`). Each project gets its own folder with metadata, lanes, and the most crucial part: one file per roadmap card in items/.
For instance, a card about launching a new feature might be `items/feature123.json`. External suggestions go into `suggestions/`, and completed work moves to `archive/`. This setup makes every piece of data inspectable, portable, and easy to backup or migrate.
This layout isn’t just about organization; it’s about ensuring that the data’s structure aligns with the real-world workflows. By making each item a standalone file, the system reduces complexity, enhances modularity, and allows for granular control. It’s a tradeoff—while it increases the number of files, it greatly simplifies conflict resolution, versioning, and recovery, especially in scenarios where data integrity is paramount.
How Files Become Safe and Reliable: Atomic Writes & Merge Strategy
Writing data safely on disk is tricky. Threlmark uses atomic writes: files are first written to a temporary file, then renamed over the original. This simple step ensures that crashes or interruptions never corrupt the data—a nightmare avoided.
Updates aren’t just overwriting blindly. They read the current file, merge changes with defaults, bump timestamps, and write atomically. It’s like editing a document in a word processor—safe, consistent, and forward-compatible.
This approach means that even if a process is interrupted mid-write, the integrity of the data remains intact. The system can detect incomplete writes or corrupt files during startup or sync, and then repair or discard them as needed. The tradeoff is that this method requires careful handling of merge conflicts and versioning, especially when multiple devices modify the same item offline. However, the benefits—robustness and safety—outweigh these complexities, especially when combined with the system’s self-healing capabilities.
One File Per Item: How It Solves Concurrency and Keeps Things Simple
Traditional apps often store all data in one big JSON array. That’s risky when multiple tools try to update it simultaneously. Threlmark sidesteps this by giving each roadmap card its own file. No locks, no conflicts. Learn more about file-based data management.
When a user or tool updates a card, it’s just a single file change. The system reads all files, then reconciles the lane order in `board.json` against the actual items. On every read, it heals itself—missing or orphaned cards disappear, and consistency is restored.
This design simplifies concurrency because each file can be independently updated without risking corruption or conflicts. It also enhances scalability—adding or removing items doesn’t require rewriting large data structures. The tradeoff is that managing many files can become cumbersome at scale, but for most use cases, the benefits in simplicity and reliability outweigh this concern. It allows the system to be almost self-healing, reducing manual intervention and making data integrity easier to maintain across devices and sessions.
Sync Without Locking: How Threlmark Keeps Multiple Devices in Harmony
Syncing in a local-first system isn’t about real-time updates. It’s about eventual consistency. Changes made offline are stored as individual files. When devices connect, a sync process compares files, resolves conflicts, and merges updates.
Imagine editing a task on your phone and your laptop. When they reconnect, Threlmark reconciles both versions—no data lost, no lock conflicts. It’s a gentle, reliable dance that keeps everyone on the same page.
This approach means that conflicts are inevitable but manageable. Threlmark’s conflict resolution strategies—like timestamp-based merging and manual prompts—are designed to prioritize user intent and minimize data loss. The tradeoff involves a slight delay in achieving perfect sync, but this is balanced by increased resilience and offline capability, especially in environments with intermittent connectivity.
Why JSON Files Over Traditional Databases? The Simplicity and Power
Choosing JSON files over a traditional database might seem odd. But it offers real benefits. Files are human-readable, inspectable, and portable. You can open them in any editor, diff them, or back them up with simple copy commands. For more on this approach, see this article.
For example, if you want to migrate data to a new system, just copy the files. No migration scripts needed. Plus, your app doesn’t rely on a specific database engine or server—just the local file system.
This simplicity also means fewer points of failure. Unlike databases that require complex setup, backups, and maintenance, JSON files can be managed easily by users and developers alike. The tradeoff is that handling schema evolution and large datasets may require additional tooling, but for most local-first applications, this tradeoff favors flexibility and robustness over complexity.
Real-World Benefits: Speed, Offline Access, and Data Ownership
With Threlmark’s approach, you get instant access to your data—no waiting for network calls. You can work offline, make changes, and trust that everything is stored securely on your disk.
For instance, during a flight or in a remote cabin, your project plans stay fully accessible. When you reconnect, syncing happens seamlessly. Plus, you own your data—no third-party server controls it.
How This Changes Collaboration and Multi-Device Work
Collaboration in Threlmark hinges on where the data lives—on your disk. Changes are saved locally, then synchronized across devices when possible. Conflicts are resolved through simple merge rules, or in some cases, manual intervention.
Imagine a team working on the same roadmap from different laptops. Each makes local edits. When they connect, Threlmark’s sync engine reconciles differences, ensuring everyone sees the latest updates without losing work.
What Makes Threlmark’s Approach Different from Cloud-Only Apps?
Most apps depend on centralized servers—think Google Docs or Trello. Threlmark flips that idea: data is primarily stored locally, and the cloud is just a sync layer.
This means more control, fewer dependencies, and better resilience. If the cloud service goes down, your work doesn’t stop. Your data remains accessible, editable, and safe on your disk.
Key Challenges and How Threlmark Overcomes Them
Handling conflicts, ensuring data integrity, and avoiding corruption are tough in a file-based system. Threlmark’s atomic writes and self-healing reads address these head-on. It’s like having a built-in safety net for your data.
However, it’s not perfect. Complex multi-user conflicts may require manual resolution, but the system’s design minimizes these issues significantly.
Frequently Asked Questions
What does ‘local-first’ mean in practice?
It means your app stores and operates on data locally first, allowing you to work offline and ensuring that your data remains accessible even without internet. Syncing happens afterward, making the system resilient and fast.
How does Threlmark handle conflicts when multiple devices edit the same item offline?
Threlmark reconciles differences using simple merge rules during sync. It compares file versions, merges changes, and sometimes prompts manual resolution if conflicts are complex. This keeps data consistent without locks.
Why choose JSON files over a traditional database?
JSON files are human-readable, easily portable, and don’t lock you into a specific database engine. Backups, migrations, and inspection are straightforward. It’s a simple, robust approach for local-first apps.
Can this architecture support real-time collaboration?
While primarily designed for eventual consistency, Threlmark can support near-real-time collaboration through frequent syncs and conflict resolution. However, it excels in offline resilience and asynchronous updates.
What are the main tradeoffs in using this approach?
It simplifies data management and improves resilience but may introduce conflicts in multi-user scenarios. Manual conflict resolution can be necessary for complex edits, and schema migrations require careful handling.
Conclusion
Threlmark proves that the disk can be the contract—no server needed. This approach makes apps more reliable, private, and adaptable. It’s a reminder that sometimes, the simplest solution—treating files as the record—yields the most power.
Next time you think about data architecture, ask yourself: could the disk really be the single source of truth? The answer might just transform how you build, collaborate, and own your work.
