TL;DR
Threlmark is built on a simple idea: the disk is the contract. Its architecture makes data portable, safe, and instantly accessible by treating files as the source of truth. This approach simplifies syncing, conflict resolution, and working offline.
Imagine a project management tool that never loses your data, works flawlessly offline, and lets any app or tool step in without permission. That’s what Threlmark aims for with its unique approach. It doesn’t rely on a cloud database or a user login — just plain old files on your disk. Disk Is the Contract: Inside Threlmark’s Local-First Architecture
Why does this matter? Because in a world obsessed with cloud and centralized servers, Threlmark proves that your data can live on your machine, be fully portable, and still work seamlessly across multiple apps and devices. This deep dive uncovers how its simple, yet powerful, disk-as-the-contract approach reshapes what you think about data, collaboration, and automation.
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.
Music Studio 11 – Music software to edit, convert and mix audio files – Eight music programs in one for Windows 11, 10
8 solid reasons for the new Music Studio 11!
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.
Contemporary Project Management (MindTap Course List)
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.
Json Genie Premium: JSON Editor, Viewer & Formatter
Open, view, and edit JSON and JSONC files with a fast tree-based interface
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 idea is that the disk is the single source of truth, making data portable, safe, and easy to sync.
- Using one file per item and atomic writes prevents corruption and race conditions, even in concurrent editing scenarios.
- A strict folder and file structure acts as a formal contract, enabling seamless external integrations and AI participation.
- Offline work is effortless because all data lives locally, with simple sync options like Dropbox or git.
- Conflict resolution relies on read-merge-write with tolerant normalization, preventing data loss or corruption.
How Threlmark Turns Your Disk Into a Trustworthy Database
Threlmark treats your disk like a reliable database. Every piece of data — each task, each note, every project — lives as a separate JSON file in a dedicated folder. This isn’t just storage; it’s the core of the system’s logic. Disk Is the Contract: Inside Threlmark’s Local-First Architecture
By writing each file atomically, it avoids corruption even if your computer crashes mid-save. It’s like writing your notes on a whiteboard with a pen — either the note is there, or it isn’t. No half-finished scribbles.
For example, when you update a task, Threlmark writes a new JSON file in a temp location, then renames it. The renaming step is atomic; it guarantees your data’s integrity. This simple step makes the entire system robust, even when multiple tools edit files at once.
Why One File Per Item Wins Over a Big List
Many project tools keep all tasks in one giant list, like a spreadsheet. But that’s a collision waiting to happen. Threlmark breaks this habit by using one file per item. Each task or card has its own JSON file, like a tiny, self-contained notebook page.
This setup allows external tools to update individual tasks without messing up the whole list. It also makes conflict resolution easier — if two devices edit different files, they won’t overwrite each other.
For instance, if you work on your laptop and your phone, changes happen locally. When syncing, only the changed files move, not the entire list. It’s faster, safer, and more flexible.
How Threlmark’s Architecture Makes Offline Work Seamless
Threlmark is designed to work perfectly offline. Your files are always available locally, so you can see your roadmap, update tasks, or add new items without an internet connection. When you go back online, syncing is simple and conflict-minimized. Disk Is the Contract: Inside Threlmark’s Local-First Architecture
Imagine you’re traveling, working on a plane, or in a basement with no signal. Your data stays accessible and editable. When you reconnect, Threlmark compares the local files with what’s on other devices or in the cloud, then updates everything accordingly.
It’s like having a notebook that never needs Wi-Fi — just write, and it syncs later without hassle.
The Role of a Clear Folder Structure and a Strict Contract
Threlmark’s folder layout isn’t just about organization; it’s a contract. The root folder contains a manifest (`threlmark.json`) and a dependency graph (`links.json`). Each project has its own folder with metadata, lane order, and one file per task in `items/`.
This structure guarantees that any tool, from a simple editor to an AI agent, can reliably read and write data without breaking the system.
For example, an external script can add a new task by dropping a JSON file in `items/`. Threlmark recognizes it immediately, integrates it into the roadmap, and displays it. It’s a simple, predictable exchange.
Handling Conflicts and Merging in a Distributed, File-Based System
Conflicts happen when two devices change the same file at once. Threlmark handles this gracefully with *read-merge-write* and tolerant normalization.
When updating, it reads the current file, merges in the new data, and writes it atomically. If two apps edit different parts, both changes survive. If they conflict, the system preserves both versions for review.
For example, if you change a task’s status on your laptop and your phone at the same time, Threlmark keeps both updates. You can later reconcile them manually or with automation.
How External Tools and AI Agents Join the Party
Threlmark’s file system design invites any tool to participate. Drop a JSON file into `suggestions/` to suggest a new task, or update a card directly in `items/`. AI agents can read, modify, and move tasks without special permissions.
For example, an AI assistant scans `reports/`, finds a task marked as done, and automatically moves it to `done/`. It can also generate new ideas and drop them into `suggestions/` for review.
This open, permissionless approach fosters automation and collaboration without complex APIs or server setups.
Syncing, Backup, and Portability: Why It’s So Easy
Because everything is just files, syncing your data is as simple as copying folders or using Dropbox, Syncthing, or git. No special database or API needed. You back up by copying the folder — it’s that straightforward. Peppereyes: Emergency Power Solutions and Backup Systems
Imagine your project folder on a USB stick or in a cloud folder. When you switch devices, just sync the folder. All the data is instantly portable and fully accessible, no vendor lock-in.
This means you can easily migrate, share, or restore your project state — no vendor lock-in, no proprietary formats.
Making File Writes Safe and Reliable: Atomic and Tolerant Techniques
Threlmark uses two key patterns to keep file writes safe: atomic writes via rename and tolerant read-merge updates.
Writing atomically involves saving to a temp file then renaming it, so crashes leave only complete files. For example, when saving a task, it writes to `task123.json.tmp` then renames it to `task123.json`.
Updates read the current file, merge in new data, and write back atomically. It’s like editing a document on your computer — either the whole change saves, or not at all.
What Apps and Developers Need to Know to Build on Threlmark
If you’re a developer, Threlmark’s system is all about predictable, simple data formats. Read and write JSON files, follow the folder structure, and you can build integrations, automation, or new interfaces easily.
For example, a custom dashboard could watch `items/` for new files and display tasks in a different style. An AI agent can scan `reports/`, move cards, or suggest new ideas. The open format means you’re not locked out or limited.
Check out the open-source project on GitHub for detailed docs and examples.
Frequently Asked Questions
How does Threlmark handle conflicts when two devices edit the same task?
Threlmark uses read-merge-write with tolerant normalization. It keeps both changes if they’re different, allowing manual or automated reconciliation later. This avoids data loss and keeps everything consistent across devices.
Can I use Threlmark without an internet connection?
Absolutely. All your data is stored locally as files, so offline work is seamless. When you reconnect, it syncs changes automatically, making offline collaboration simple and reliable.
What’s the main advantage of using files instead of a cloud database?
Files are inherently portable, transparent, and lock-free. You can back them up, sync with any tool, or migrate data easily — no vendor lock-in or complex API needed.
How do I extend Threlmark or build custom integrations?
Just follow the folder and file structure, read and write JSON files, and you can create dashboards, automation, or AI integrations. The system is designed to be open and straightforward for developers.
Is there a risk of data corruption if my computer crashes while saving?
Not with atomic writes. Threlmark writes data to a temporary file first, then renames it atomically. This guarantees that only complete, uncorrupted files are ever used as the source of truth.
Conclusion
Threlmark proves that a simple, disciplined approach to data storage can unlock powerful benefits. By making the disk the contract, it creates a system that’s robust, flexible, and ready for automation.
For anyone building or working with project tools, thinking in files isn’t just old-school — it’s a smarter way to keep control and collaborate effortlessly. Your next project’s foundation might just be a folder full of JSON files.
