TL;DR
Threlmark treats disk as the main contract, meaning all data lives in simple JSON files. This design makes the system offline-capable, portable, and easily integrable with external tools, while simplifying concurrency and sync.
Imagine managing multiple projects without a cloud, a server, or even a login. Sounds wild, right? But that’s exactly what Threlmark does. It’s a project hub built entirely around one idea: the disk is the contract. Your data lives in plain JSON files, and that’s the source of truth.
This approach flips the traditional model on its head, emphasizing the importance of local file systems in modern workflows. Instead of relying on a database or cloud service, it treats your local file system as the core. Why does that matter? Because it makes your system more resilient, portable, and open to external tools. Plus, it’s lightning-fast since everything happens on your local disk, not over the network.
In this deep dive, I’ll show you how Threlmark’s architecture works. We’ll explore why using files as the API is a game-changer, how it handles concurrency, and how it enables AI to do the building. Ready? Let’s get into the nuts and bolts of this innovative approach.
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.
offline JSON file editor
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.
The Phoenix Project: A Novel about IT, DevOps, and Helping Your Business Win
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.
disk-based data synchronization tools
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.
WORKPRO W051002 10 In. Flat File – Durable Steel File to Sharpen Tools and Deburr, Comfortable Anti-Slip Grip, Double Cut – Tool Sharpener for Professionals and DIY (Single Pack)
FLAT FILE – The WORKPRO W051002 Flat File has an ergonomic design, anti-slip, and comfortable grip so you…
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 your file system as the source of truth — your disk is the contract, not a server.
- Use one JSON file per item to prevent race conditions and make concurrent edits safe.
- Atomic file writes guarantee data integrity even during crashes or interruptions.
- Plain JSON files make your data portable, easy to sync, and open to external tools.
- Design your system to self-heal and reconcile differences automatically, reducing errors and manual fixes.
Why the disk is the real contract — not the server
In Threlmark, your disk isn’t just storage; it’s the contract. All project data, from cards to dependencies, lives in JSON files. Think of each file as a tiny, self-contained record that can be read, diffed, or changed without a middleman.
This means no server to sync with or rely on. When you open your project, you’re reading the files directly. When you change something, you write it back — atomically. It’s like editing a document on your desktop, not updating a database over the internet.
For example, each card lives in its own `items/
How Threlmark’s file structure keeps data safe and sync-ready
Threlmark’s folder structure isn’t just a dump of files. It’s a carefully designed contract. At the root, you find `threlmark.json` and `links.json` for project metadata and dependencies. Inside each project folder, there’s a `project.json`, a `board.json`, and then one file per item in `items/`.
Each item file is atomic — written using a safe pattern that renames a temp file over the original. This guarantees that even if your computer crashes mid-save, your data stays consistent.
Additionally, the board is a self-healing list. It scans the existing items each time it loads, fixing any missing or misaligned cards. This means your view always matches reality, even if external tools or agents move or delete files.
Making local files work with external tools and AI agents
One of Threlmark’s strengths is its openness. External tools can read or write files directly — no APIs or permissions needed. For example, an AI agent like IdeaClyst can suggest a new card by dropping a JSON file into `suggestions/`. The user or system can then review and approve it.
Similarly, the AI can mark tasks as done by editing the item files. Because everything is plain JSON, tools in any language can join the party. This openness fuels automation and collaboration without lock-in or complex integrations.
Think of it like a shared whiteboard where everyone just drops notes. The system’s design ensures everyone sees a consistent, up-to-date picture without locking you into a cloud service.
Why one file per item beats a giant list — and how it heals itself
Instead of having one big `roadmap.json`, Threlmark uses one JSON file per item. This might seem small, but it’s a game-changer. When you update a single card, you only rewrite that one file. No need to load and rewrite the entire list.
This design prevents race conditions and makes concurrent editing safe. Plus, the `board.json` that shows the order of cards is a self-healing list. It checks each time it loads: if an item is missing, it hides it; if a new item appears, it’s added automatically.
Imagine two devices working offline. One moves a card to ‘Done,’ the other just updates the card file. When they sync, everything stays aligned because each change is atomic and isolated.
How this design boosts portability, interoperability, and resilience
Because everything is plain JSON files, you can back up, sync, or migrate your data with simple commands: `cp`, `rsync`, or even Dropbox. No proprietary database lock-in here.
Any tool can join — just read or write the files. Want to build a custom dashboard or sync with another app? Just point it at the folder. This makes your project data portable, resilient to outages, and easy to extend.
For example, you can clone your entire setup to a new machine, and everything just works. The files form a universal language that any tool can speak.
Handling conflicts, sync, and offline work like a pro
Threlmark’s architecture is built for offline-first workflows. Changes happen locally, and sync is just a matter of copying files. When devices come online, they exchange files, resolving conflicts through simple merge rules.
If two devices edit the same card differently, the system preserves both versions and lets the user decide or automatically merge when possible. The key is that local edits are always atomic, so conflicts are minimized.
Imagine editing a task on your laptop and your phone while offline. When you reconnect, the system gracefully merges both updates, keeping your project consistent.
The real-world benefits — faster, safer, more flexible workflows
Think about the last time you waited for a server to respond. Now, picture editing your project instantly, even offline. That’s the power of Threlmark’s local-first approach. It feels snappy, reliable, and open.
Plus, you’re not locked into a platform. Move files, integrate tools, or experiment with automation — all without relying on a central server. It’s like having a portable, personal project hub that works anywhere.
This architecture is perfect for teams working in remote or unpredictable environments, where internet stability isn’t guaranteed. It’s also great for personal projects, hobbyists, or anyone who values control over their data.
Frequently Asked Questions
What does ‘local-first’ really mean in practice?
It means your app prioritizes local storage and offline working. Changes happen on your device immediately, and sync happens later, making the system fast, reliable, and usable offline.
Why is the disk called the ‘contract’ instead of the server?
The disk is the contract because it’s the single, authoritative source of all data. No server or cloud is needed for everyday work — your files are the truth.
How does sync work when I go back online?
When online, devices exchange files directly. Changes are merged based on atomic updates, preserving edits and resolving conflicts automatically, ensuring consistency across all devices.
What happens if two devices edit the same file differently?
The system preserves both versions and lets you decide or automatically merges them. Because each change is atomic, conflicts are manageable and less likely to cause data loss.
Is local-first only for offline use or also for collaboration?
It’s both. Local-first allows offline work and seamless sync. When connected, multiple devices or team members can collaborate by exchanging files, maintaining consistency even with intermittent connectivity.
Conclusion
Threlmark’s approach shows that simplicity can be powerful. When the disk is the contract, your system becomes more resilient, flexible, and open. It’s a reminder that sometimes, the best architecture is the one that treats the file system as the backbone of your workflow.
So next time you build or rethink a tool, ask yourself: how can I make the disk the single source of truth? The results might just surprise you.
