TL;DR
Threlmark treats plain JSON files on disk as the authoritative source, avoiding databases entirely. This design makes data portable, inspectable, and restartable—perfect for offline work and easy sync. It’s a bold move towards simpler, more resilient software.
Imagine a project board that lives right on your disk—no cloud, no database, just plain files. That’s the core idea behind Threlmark’s architecture. It’s a radical shift from traditional apps that hide data behind servers and databases, making everything more transparent, portable, and resilient. Disk Is the Contract: Inside Threlmark’s Local-First Architecture
In this article, you’ll see how this approach isn’t just a cool trick. It fundamentally changes how you think about data, automation, and collaboration. We’ll explore why making disk the contract matters, how it works under the hood, and what it means for your workflow and future projects.
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.
Seagate Portable 2TB External Hard Drive HDD — USB 3.0 for PC, Mac, PlayStation, & Xbox -1-Year Rescue Service (STGX2000400)
Easily store and access 2TB to content on the go with the Seagate Portable Drive, a USB external…
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
Music software to edit, convert and mix audio files
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.
Real-World Android App Projects with Kotlin and Jetpack Compose: Build Production-Style Android Apps with Modern Architecture, API Integration, State Management, Local Data Storage, Practical Projects
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.
SMARTSHEET USER GUIDE FOR BEGINNERS AND ADVANCED USERS 2026: A Step-By-Step Manual To Project Management, Automation, Dashboards, And Team Collaboration heading
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 project data as plain JSON files on disk, making everything inspectable and portable.
- Use atomic `rename()` for every write to prevent data corruption and race conditions.
- Design your data with forward compatibility—preserve unknown fields during merges.
- File-per-item storage simplifies concurrency and makes your system restartable without fuss.
- Leverage existing sync tools like Dropbox or Syncthing for easy multi-device collaboration.
How ‘Disk Is the Contract’ Turns Simplicity Into Power
In Threlmark, the on-disk layout isn’t just storage—it’s the API. Every file, from the main manifest to individual cards, acts as the single source of truth. This means your tools, scripts, and even AI agents all read and write exactly the same files.
Picture working on a project where a single `items/` folder holds every task as a JSON file. No database lock, no server sync—just plain text files. You can open, edit, or diff them with any editor or script. It’s like having a living, breathing project document that’s always current and easy to back up.
Why Threlmark Chooses JSON Files Over Databases
JSON files are human-readable, easy to manipulate, and portable. Unlike databases, they don’t lock you into a vendor or specific platform. Threlmark’s design assumes that every change is a simple file edit, which makes version control, backups, and migrations straightforward.
For example, updating a card’s status is just editing a JSON file. You can diff it, revert it, or sync it across devices. This simplicity means fewer surprises and more control over your data.
How Multiple Devices and Agents Keep in Sync Without a Database
With the disk as the source of truth, syncing becomes a matter of copying files—no complex protocols needed. Threlmark’s architecture relies on simple file sync tools like Dropbox, Syncthing, or git. When conflicts arise, the system’s design encourages merging and human oversight.
Imagine working on a laptop and a tablet. You make a change on your laptop, sync, and see it on your tablet instantly. Agents can also operate by watching files and making changes—closing their own loops without needing a central server.
The Magic of Atomic File Writes and Tolerant Merging
Threlmark uses two simple but powerful patterns to keep data safe: atomic writes and tolerant merging. Atomic writes mean saving each file to a temp location, then renaming it—guaranteeing complete updates even if your computer crashes.
For example, updating a task involves reading its JSON, merging new info, and atomically replacing the file. This way, no partial updates or corruptions sneak in, keeping your data consistent.
The tolerant merge pattern ensures that unknown or new fields survive updates. If an external tool adds a new property to a card, older Threlmark versions won’t break—they’ll preserve those extra fields.
One File Per Item: How It Solves Concurrency and Keeps Things Clean
Instead of one big list of tasks, each task gets its own JSON file in the `items/` folder. This makes concurrent edits safe—no race conditions, no clobbering. Each change is atomic, so two tools can update different cards at the same time without conflict.
When you open your project, Threlmark reads all the files, and the board “self-heals” by reconciling the lane order with existing items. If a file disappears or a card is moved, the system adjusts automatically.
Making the System Restartable and Interoperable
Because everything is plain files, you can restart your app at any time without losing data. Just reload the files. Want to switch tools? Just point them at the same folder. Threlmark’s architecture plays nicely with any language that can read/write JSON.
This openness makes your project data portable and future-proof. Backups? Just copy the folder. Migrations? Move files around. No vendor lock-in, no proprietary database.
Practical Tips for Building Your Own Disk-First Apps
- Use atomic `rename()` for every write to prevent corruption.
- Design your data as small, independent JSON files—one per item.
- Merge updates carefully, preserving unknown fields for future compatibility.
- Keep your folder structure simple and predictable.
- Leverage existing sync tools like Dropbox or Syncthing to keep data in sync across devices.
Threlmark vs. Traditional Cloud Apps: Which Wins?
| Threlmark (Disk as the Contract) | Traditional Cloud Apps |
|---|---|
| Plain JSON files, no server | Database-backed, server-dependent |
| Portable, inspectable, merge-friendly | Opaque, locked-in, complex sync |
| Offline-first, restartable | Dependent on network, less resilient offline |
What Are the Tradeoffs? When Is Disk the Best Choice?
Disk-based, JSON-file systems excel in offline resilience, transparency, and portability. But they can struggle with large-scale collaboration or real-time updates. For huge teams or instant sync, traditional databases still shine.
Think of it like a small, nimble workshop versus a massive factory. Choose what fits your scale and needs.
Frequently Asked Questions
How does Threlmark handle conflicts when multiple devices edit files at the same time?
Threlmark relies on atomic file writes and merge patterns. When conflicts arise, manual merging or using sync tools with conflict resolution keeps things safe. The system encourages tools to handle conflicts gracefully without locking.Can I use Threlmark with my existing project folders or other tools?
Yes. Since everything is plain JSON files, you can integrate with any tool that reads or writes JSON. The folder structure is predictable, making it easy to incorporate into your workflow or migrate data.What happens if I lose my files? Is my data safe?
Your data lives on your disk—backups are just copying the folder. Because each artifact is a file, you can version control, sync, or restore easily. No hidden database or proprietary format to worry about.Is this approach suitable for large teams or real-time collaboration?
While excellent for offline, small to medium projects, large teams might find the lack of a central database limiting. For real-time collaboration at scale, traditional server-backed systems still have advantages.Conclusion
Threlmark’s disk-as-the-contract model isn’t just a technical choice; it’s a mindset shift. It shows that simple, plain files can power complex workflows—more transparent, more resilient, more portable.
Imagine a world where your project data is a folder full of JSON files you control, not locked behind a database. That’s the future of lightweight, local-first automation. Are you ready to ditch the lock-in and embrace the simplicity?
