TL;DR
Threlmark uses a disk-based, JSON-on-disk data model that makes the app fast, resilient, and portable. It sidesteps traditional databases, focusing on local storage as the source of truth, enabling offline use and easy sync.
Ever wish your project management tool was faster, more resilient, and didn’t lock you into a cloud? Threlmark turns that dream into reality. Its secret? Everything lives on your disk, in plain JSON files, acting as the single source of truth. No servers, no cloud dependency, just your files. It’s a fresh take that puts control back in your hands — and it’s simpler than you think.
If you’re tired of fragmented roadmaps, inconsistent data, or waiting on network responses, this architecture might change your workflow. We’ll explore how Threlmark’s disk-centered design works, why it’s a game-changer, and how it handles common challenges like sync, conflicts, and recovery.
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.USB flash drive for data backup
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]](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.
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 AI with VS Code: Mastering Private, Offline LLM Development: Run Open-Source Models Securely with Ollama, Continue, Llama.cpp, and Zero-Cloud Extensions – Keep Your Code and Data 100% Private
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 core design uses a JSON-on-disk model, making data accessible, portable, and safe without a traditional database.
- The on-disk layout is the system’s API — any tool can read/write files directly, promoting interoperability and simplicity.
- Atomic file writes and tolerant merging prevent corruption and support forward compatibility.
- Syncing across devices is just copying files, with conflict management handled via manual resolution or external tools.
- This architecture excels in offline resilience, making it ideal for solo projects or environments with unreliable networks.
How Threlmark’s Disk-Based Data Model Keeps Everything Simple and Fast
Threlmark stores every piece of data as a JSON file on your disk. Imagine each task, project, or roadmap card as a tiny, self-contained file. When you open the app, it reads these files directly. No database, no API calls — just instant access.
This approach makes everything feel snappy. When you drag a card or mark it done, the change is written straight to the file. It’s like editing a document in your editor, not sending a request to a server and waiting for a response. Learn more about local-first architecture.
By relying on files rather than a database, Threlmark reduces complexity and potential points of failure. This design choice also means performance scales linearly with the number of files—small projects remain fast, and large projects can be optimized by selectively loading relevant files. However, it also introduces tradeoffs: as projects grow very large, file management and search may become less efficient unless supplemented with indexing or caching strategies.
For example, moving a task from ‘In Progress’ to ‘Done’ updates a single file in seconds. This simplicity means fewer bugs, faster performance, and easier backups or migrations. It also encourages a more transparent workflow, where every change can be tracked at the file level, making debugging and versioning more straightforward.
Why ‘Disk Is the Contract’ Means No Single Source of Record Is Needed
In Threlmark, the files on disk *are* the record. This shifts the usual thinking — instead of a central server or database, every tool, script, or collaborator reads and writes directly to these files. It’s a contract: if you see a file, you know its state is current.
This approach simplifies data consistency because it eliminates layers of synchronization or complex conflict resolution mechanisms typically associated with distributed systems. Each file becomes a trusted, authoritative source, which means that as long as the files are kept intact, the system remains consistent.
The implications are significant: you no longer need a separate database or API to maintain the current state. Instead, the state is distributed across the filesystem, which is inherently resilient—if your computer crashes, your data is still safe in these files. You can back them up, sync them via cloud storage, or open them in different applications without losing fidelity. The tradeoff is that managing concurrent edits or ensuring atomic updates across multiple files requires careful handling, which Threlmark addresses with specific safety mechanisms.
This model emphasizes transparency and control, empowering users to understand and manipulate their data at a granular level, which can foster better integration and customization.
The File Layout That Keeps Everything Clear and Interoperable
Threlmark organizes its files in a very deliberate way. At the root, you find a main manifest (`threlmark.json`) and a dependency graph (`links.json`). Each project lives in its folder with metadata, WIP limits, and lanes. Then, there’s an `items/` folder with one JSON file per task or card. For more on organizing project data, see file layout best practices.
Additional folders like `suggestions/`, `handoffs/`, and `reports/` support collaboration and automation. Shared items live under `shared/items/`, and old projects move to `archive/` — all readable and writable by any tool that understands the structure.
This structured organization promotes clarity by establishing a predictable hierarchy that’s easy to navigate and modify. It supports portability because each component—projects, tasks, links—is stored as a separate, self-describing JSON file, making it straightforward to migrate or replicate data across environments. Interoperability is enhanced because external tools or scripts can interact with individual files directly, enabling seamless integration without relying on proprietary formats or APIs. The clear separation of concerns reduces ambiguity, ensuring that users and tools can reliably interpret and manipulate the data regardless of context.
Making File-Based State Safe and Reliable
Working directly with files sounds risky — but Threlmark uses two proven techniques to keep data safe: atomic writes and tolerant merging. You can read about these techniques in local-first data safety.
Atomic writes mean saving changes in a temp file, then renaming it. This way, crashes or interruptions never corrupt data. For example, when you save a task, the app writes to `task.json.tmp`, then renames it to `task.json` — a simple trick that prevents partial saves.
The second method is read-merge-write. When updating a file, Threlmark reads the current version, merges in new info, and writes it back atomically. It also preserves unknown keys, so external tools or future versions can add fields without breaking old ones. These techniques ensure that even if a system crash occurs mid-write, the data remains consistent and recoverable, minimizing data loss risks. They also support collaborative workflows where multiple processes may access or modify files asynchronously, providing a safety net against corruption or conflicts.
While these methods greatly enhance reliability, they do not eliminate all potential issues—users must still handle conflict resolution carefully when multiple sources modify the same file simultaneously. Nonetheless, these strategies are essential for maintaining data integrity in a file-centric architecture, especially in offline or distributed scenarios.
How the Self-Healing Board Keeps Your Tasks Organized
Threlmark’s board is a clever mix of separation and reconciliation. Each lane’s order is stored in `board.json`, listing item IDs. But every time you view the board, it checks against the actual local data. items in `items/`. Missing or orphaned items get automatically cleaned up.
Imagine you delete a task directly in the folder. When you next open the board, that task disappears from the view — no manual clean-up needed. Conversely, if a new item appears in `items/`, it automatically shows up on the board.
This healing process keeps your view consistent, even if you manually tweak files or use external scripts. It’s a smart way to ensure data integrity without locks or complicated protocols. This approach allows the system to adapt dynamically to changes, reducing manual maintenance and preventing inconsistencies that could arise from external modifications.
By continually reconciling the stored order with the actual data, the board maintains a reliable, up-to-date view of your workflow, which is especially useful when multiple tools or scripts are involved in data management.
Sync and Collaboration Without a Server? Yes, It’s Possible
Threlmark’s local-first design means it works well offline, but what about multi-device sync? Since all data lives in files, syncing is simply copying those files between devices. Use Dropbox, Syncthing, or any file sync tool you like.
When a device comes back online, it pulls the latest files. Conflicts? They happen when two devices edit the same file simultaneously. Threlmark doesn’t automatically resolve conflicts — instead, it relies on clear user workflows or external merge tools.
For example, editing a task on your laptop and your phone will sync once files are updated. If both change the same task, you’ll need to merge manually or set rules. This approach emphasizes simplicity and user control, but it also means users must be aware of potential conflicts and handle them appropriately. The core benefit remains: no dedicated server or complex infrastructure is necessary, making it accessible and easy to set up for small teams or individual users.
Handling Conflicts and Ensuring Data Integrity
Conflicts are inevitable when multiple devices edit the same file. Threlmark doesn’t do conflict resolution automatically. Instead, it detects conflicts by timestamp or file hashes and prompts you to resolve them manually. This transparency allows users to see exactly what changed and choose the best course of action, whether merging, overwriting, or keeping multiple versions.
For example, if two devices change the same card differently, you’ll be presented with both versions. This process grants control to the user, preventing silent overwrites or data loss. It also encourages better workflows—users become aware of conflicts early and can resolve them before data becomes inconsistent. While manual conflict resolution might seem less seamless than automated methods, it provides greater safety and understanding, especially in complex or sensitive projects. The tradeoff is a more involved process, but one that ultimately preserves data integrity and user trust.
Backup, Recovery, and Security in a File-Based System
Backing up Threlmark is as simple as copying its data folder. No special tools needed. For recovery, just restore the folder from backup. The files are the entire state, making backups straightforward and reliable.
Security depends on your environment. Files stored locally are safe if your disk is encrypted. For shared or cloud setups, add encryption or access controls as needed. Because data is stored as plain files, you can leverage existing security practices—encrypt the folder, set proper permissions, or use disk encryption—to protect sensitive information. This simplicity means you’re not dependent on proprietary or complex backup solutions, but it also requires you to implement appropriate security measures based on your context.
Is This Approach Right for Small or Large Projects?
Threlmark’s disk-first design shines in small to medium projects, where speed, resilience, and portability matter most. For large-scale collaboration or huge data sets, it might need additional sync or conflict resolution layers.
For example, solo developers managing multiple micro-projects or teams working across a few devices benefit greatly from this approach. It offers speed, control, and offline capability without complex infrastructure. However, for very large projects, multi-user environments, or enterprise-scale deployment, the lack of built-in conflict resolution and the reliance on manual sync may become bottlenecks. In those cases, supplementing with a dedicated server, database, or conflict management system might be necessary. Nonetheless, for many practical scenarios, this architecture offers a compelling balance of simplicity and power.
Frequently Asked Questions
How does Threlmark handle conflicts when two devices edit the same task?
Threlmark detects conflicts via timestamps or file hashes. When conflicts occur, it presents both versions so you can resolve them manually. This approach keeps data safe and transparent, without automatic overwrites.
Can I use Threlmark without internet access?
Absolutely. Since all data resides on your disk, you can work offline at all times. Sync later by copying files via Dropbox or Syncthing. No internet needed for day-to-day use.
Is this architecture suitable for large teams or enterprise use?
It’s best suited for small to medium projects or solo work. Larger teams may need more sophisticated sync and conflict resolution tools, or a server-based backend for scalability. But for many workflows, this setup offers unmatched speed and simplicity.
How secure are my data files?
Data security depends on your environment. Files stored locally are safe if your disk is encrypted. For shared setups, add encryption or access controls. It’s straightforward to keep sensitive info protected in this model.
Conclusion
Threlmark’s disk-is-the-contract approach proves that simple, local-first design can be powerful. It’s fast, resilient, and puts you in control. When you need a project management system that works offline and plays well with other tools, this model might just be what you’re looking for.
Imagine your data as a set of well-organized files, always ready and never locked away in a cloud. That’s the beauty of trusting your disk as the source of truth — it’s freedom, clarity, and speed all wrapped into one.
