TL;DR
Threlmark’s system treats plain JSON files on disk as the single source of truth. This approach makes data portable, inspectable, and resilient—perfect for offline-first workflows and AI integration. It’s a radical departure from traditional database-driven apps.
Imagine a tool that keeps your project data safe, transparent, and ready for any AI to pick up and run with—no cloud required. That’s what makes Threlmark unique. Its secret? The entire system is built on a simple yet powerful idea: the disk is the contract.
You don’t need a server, a database, or even a user login. Just files, plain JSON files sitting on your local machine. This approach might sound old-fashioned, but it’s actually a game-changer for building resilient, flexible, and accessible tools. Today, we’re digging into how Threlmark’s architecture turns a simple filesystem into a robust, collaborative hub for your 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.
portable 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.
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.
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.
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.
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.
KALIM Needle File Set (10Pcs High Carbon Steel Files) and 1 Wire Cutter in A Carry Bag, File Tools for Soft Metal, Wood, Jewelry, Model, DIY, Hobby, etc.
【GREAT SMALL SIZE】 10 pcs 6'' high carbon needle files, 1pcs 5'' wire cutter, 1pcs 8'' carrying storage…
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 filesystem as the system’s API, making data transparent, inspectable, and portable.
- Use atomic file writes and tolerant merge strategies to ensure data safety and consistency.
- Design with one file per item to simplify concurrency and avoid race conditions.
- Leverage local-first principles for offline work, conflict resolution, and seamless sync.
- External tools and AI agents can participate directly by reading and writing JSON files—no API lock-in.
Why Making the Disk the Single Source of Truth Changes Everything
In Threlmark, the on-disk layout isn’t just storage—it’s the API itself. This means every file, every folder, is a piece of the system’s intelligence. When you open a folder, you see the latest state of a project, a roadmap, or a task. No need to query a database or deal with complex synchronization protocols.
This design makes the system incredibly transparent. You can open any JSON file, see exactly what’s stored, and understand how everything connects. It’s like having the source code and data all in one place, making debugging, backups, and migrations straightforward. It’s like having the source code and data all in one place, making debugging, backups, and migrations straightforward.
How Threlmark’s JSON Files Keep Your Data Portable and Safe
Threlmark stores each project, card, and dependency as a separate JSON file. This modular approach simplifies collaboration and version control. Want to back up your entire system? Just copy the folder. Need to move your setup to another machine? Copy the files and start working. It’s that simple.
Because files are plain text, you can diff changes, revert mistakes, and even hand-edit data if needed. For more on data management, see digital marketing and productivity tools. The architecture also supports version control—commit your JSON folder into Git, and you have a complete history of every change.
Here’s a quick comparison:
| Traditional Database | Threlmark Files |
|---|---|
| Opaque binary blobs or complex formats | Readable JSON files |
| Requires specialized tools for migration | Copy/move files directly |
| Harder to inspect or back up | Easy to diff, grep, and version |
Making Files Safe: Atomic Writes and Tolerant Merging
Writing to JSON files might sound risky, but Threlmark uses two clever tricks. First, every write goes to a temporary file, then renames itself atomically. This way, crashes or interruptions never leave your data half-written or corrupted.
Second, updates read the current file, merge changes intelligently, and preserve important metadata like IDs and timestamps. Unknown fields are kept untouched, so new features don’t break old tools.
This approach ensures consistency, even when multiple tools or agents edit your data at once. It’s like having a built-in safety net for your files.
One File per Card: How Threlmark Handles Concurrency Without Locks
Instead of a big monolithic JSON array, Threlmark assigns each task or card its own JSON file. This makes updates atomic and collision-free. When you change a card, only that file updates, no need to lock the entire list.
The project’s roadmap or board is reconstructed on each read. Threlmark compares the actual card files with the lane order, then heals any discrepancies. It’s like a self-healing puzzle that always shows the latest, most accurate picture.
For example, two team members editing separate cards won’t step on each other’s toes. They simply modify their own files, and the system reconciles the view on every read.
How External Tools and AI Agents Join the Disk-Based World
Since the data lives in plain files, any tool can read or write to it—no API lock-in. This openness enables seamless integration with external tools and AI agents, like IdeaClyst. External AI agents, like IdeaClyst, can drop suggestions into the `suggestions/` folder or move cards to ‘Done’ without special permission. They just treat the files like any other data.
This openness is a game-changer. It allows automation, collaboration, and extensions without complex integrations. Want your AI to finish a task? It just updates the relevant JSON files directly.
For example, an AI could scan your `handoffs/` folder, pick up a task, and mark it as complete—all by modifying a simple file.
Syncing, Conflicts, and Offline Resilience—The Power of Local-First
Threlmark’s architecture excels at offline work. Since everything is files on disk, you can unplug your device, work freely, then sync later. Conflicts are resolved through simple merge rules and file comparisons.
When multiple devices work offline, the files can be synchronized using Dropbox, Syncthing, or git. Conflicts? Threlmark’s reconciliation process compares files, keeps the latest updates, and preserves data integrity.
This approach reduces latency, improves resilience, and builds trust. You’re not waiting for a server to respond—you’re working directly on your data, always.
The Real-World Benefits of a Disk-Centric, Local-First System
Imagine working on a project without worrying about losing connectivity or locking conflicts. Your data stays human-readable, portable, and safe from server crashes. Migrations are just copying files. Backups? Copy the folder. Troubleshooting? Grep the JSON files.
Threlmark’s design makes collaboration across devices seamless. You can even manually edit files or roll back changes with ease. It’s resilient enough for serious production use, especially in environments where connectivity is spotty or security is paramount.
Frequently Asked Questions
What does “disk is the contract” actually mean?
It means that the on-disk file layout defines the system’s state and interface. All tools, users, and AI agents read and write the same JSON files, making the filesystem the single source of truth.How is this different from using a database?
Instead of an opaque database engine, data is stored in plain, human-readable JSON files. This makes the data more transparent, portable, and easier to back up or migrate.Why use JSON files instead of SQLite or another embedded database?
JSON files are simple, easy to inspect, and version control-friendly. They avoid lock-in and make it straightforward for external tools or AI agents to participate without complex APIs.How does syncing work if the app is offline-first?
Since all data is files on disk, you can sync via Dropbox, Syncthing, or git. Conflicts are resolved through file comparison and merge rules, ensuring safe collaboration across devices.Is this approach reliable for production use?
Yes, if you implement proper atomic writes and conflict resolution. Many projects use file-based systems for resilience, especially when offline access and portability are priorities.Conclusion
Thinking of your data as files on disk rather than in a database flips the usual approach. It offers simplicity, resilience, and flexibility—especially when AI automation or offline work matter. The key is seeing the disk not just as storage, but as the system’s contract, its single source of truth.
Next time you build or choose a tool, ask yourself: could the disk be the API? If yes, you might just be on to something revolutionary.
