TL;DR
Threlmark uses plain JSON files on disk as the authoritative source, creating a local-first system that’s easy to inspect, sync, and extend. This design makes offline work seamless and simplifies AI integration, all without a central database.
Imagine a project management tool that doesn’t rely on a cloud database or complex server infrastructure. Instead, it treats your disk as the ultimate contract, where every file, every folder, defines the state of your work. That’s the core idea behind Threlmark.
You get a system that’s simple, transparent, and resilient. No lock-in, no hidden layers — just plain JSON files sitting on your disk, acting as both the data and the interface. It’s a radical shift from traditional databases, and it unlocks new freedom for developers and users alike.
In this article, I’ll walk you through how this architecture works, why it matters, and what makes it so powerful for modern workflows. Whether you’re building tools, managing projects, or just curious about the future of local-first software, you’ll find something here that challenges what you thought was possible.
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.
external 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.
local-first file synchronization tool
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.
SANDISK 32GB Ultra USB 3.0 Flash Drive – SDCZ48-032G-GAM46
Transfer speeds up to 10x faster than standard USB 2.0 drives (4MB/s); up to 130MB/s read speed; USB…
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 disk as the system’s single source of truth by storing all data as plain JSON files. This makes your system transparent, portable, and easy to recover.
- Use atomic file writes to prevent corruption and race conditions, ensuring data integrity even during crashes or concurrent updates.
- Design your architecture so that the on-disk layout is a clear contract — any tool or agent can participate by reading and writing files directly.
- Leverage the simplicity of plain files for debugging, backups, and offline resilience, reducing complexity and increasing reliability.
- This approach works best for small to medium projects, offline workflows, or when transparency and control matter most.
How the ‘disk is the contract’ reshapes your workflow
When you treat your disk as the system’s contract, you’re making a simple yet profound statement: the files on disk aren’t just storage. They are the single source of truth. Imagine editing a JSON file that describes your project’s state, and knowing that every tool, every process, reads and writes directly to that file.
Take Threlmark, for example. It stores each roadmap card in its own JSON file inside an `items/` folder. External tools or AI agents can read or modify these files directly, without needing a special API or database connection. This approach makes your workflow transparent and robust.
One real-world scenario: you’re working offline, editing project files on your laptop. When you go back online, syncing those files with your team becomes trivial — just copy or sync the folder. No complicated conflicts, no server to ask for permission. The disk is the contract, and that makes everything predictable and reliable.
Why JSON is the perfect language for your data contract
JSON isn’t just a data format here — it’s the language of your system’s contract. It’s human-readable, easy to edit, and universally supported. When your files are plain JSON, any tool in any language can participate.
For example, each roadmap item is a JSON object with fields like `id`, `status`, `title`, and `createdAt`. Because updates are just file writes, you can use simple command-line tools or scripts to modify them. And since no database schema restricts you, the contract can grow organically.
Imagine you want to add a new field, like `priority`. You just update the JSON structure in your files. Older tools that don’t recognize this field will ignore it, but newer ones can leverage it. That forward compatibility is a game-changer.
How file-based state handles concurrency and conflicts
Concurrency in a file-based system is a tricky beast. Threlmark tackles this with atomic file writes — writing to a temporary file, then renaming it. This simple step ensures that partial or corrupt updates never make it into your state.
Suppose two tools try to update the same JSON file at once. One writes, then the other. Thanks to atomic renames, these actions won’t clobber each other. Instead, each update either fully succeeds or not at all, avoiding race conditions.
For conflicts, Threlmark employs a read-merge-write pattern. It reads the current file, merges in the changes, preserves timestamps, and writes again. This approach keeps data consistent, even when multiple devices or agents work on the same files.
In a real-world scenario, a developer on a laptop and an AI agent on a server might update the same card. Thanks to atomic writes and tolerant merging, the system gracefully manages these overlaps.
Making your system resilient with simple file tricks
Resilience comes naturally when your system’s state lives in files. Because each update is atomic, your data won’t get corrupted even if your machine crashes mid-write.
Plus, you can back up, sync, or migrate your files with simple tools: `cp`, Dropbox, Syncthing, or git. No complex replication protocols needed. Just copy the folder, and your entire system’s state moves with it.
Another bonus: the system is restartable. When you restart your app, it just reads the current files. No need for a database connection or in-memory cache. Your data is always there, in plain sight, ready to be loaded or inspected.
For example, a developer can recover a lost card by inspecting the corresponding JSON file in their project folder, no special recovery tools required.
How the architecture supports AI and automation
Threlmark’s design makes AI and automation seamless. Because every piece of data is a file, an AI agent can read, modify, and even decide what to do next — all outside a traditional API.
Imagine an AI assistant that scans your `items/` folder, suggests updates, and moves cards to ‘Done’ without human intervention. It’s like a self-driving project manager, all working through plain files.
This setup allows for open, permissionless collaboration. External tools or AI agents can participate by simply reading and writing files — no special permissions or API keys needed. The result? A flexible, extensible workflow that adapts as your needs evolve.
Visit Threlmark to see how this plays out in real projects, with agents closing the loop on tasks and moving your work forward automatically.
Tradeoffs: When a file-based system might not be enough
Using files as your core data store isn’t perfect for every situation. Large-scale apps with thousands of users, real-time collaboration, or complex querying may hit performance limits.
For instance, trying to find a specific card across hundreds of JSON files can be slow. Or managing simultaneous edits from many devices may require additional conflict resolution strategies.
However, for small teams, solo projects, or tools focused on offline-first workflows, this approach excels. It’s simple, transparent, and resilient — exactly what you need for many use cases.
Debugging and developing with transparent files
One of the biggest advantages of treating files as the contract is how easy it is to debug. Just open your JSON files, `diff` changes, or read them directly.
Imagine troubleshooting a project. You don’t need complex logs or database dumps. You just inspect the JSON files in your editor, see exactly what’s stored, and track down inconsistencies.
This transparency accelerates development and reduces bugs. When you understand that the entire state lives in plain, accessible files, troubleshooting becomes simple and intuitive.
Use cases: Who benefits most from this approach?
Teams building offline-first tools, solo developers managing personal projects, or organizations requiring transparent workflows find this architecture ideal. It’s perfect for those who want control, simplicity, and resilience.
For example, a startup managing a product roadmap across multiple devices, or an indie dev working on a complex AI assistant, could leverage this system to keep everything consistent without cloud dependencies.
Even educational projects or prototypes gain from the transparency and ease of manipulation that JSON files provide.
Frequently Asked Questions
What does ‘disk is the contract’ actually mean?
It means that the files on disk directly define the system’s state. Instead of a database, your JSON files are the single source of truth, accessible and editable by any tool that can read/write files.
How is this different from a normal local-first app?
Most local-first apps cache data locally and sync with a server later. Threlmark treats the disk as the real authority, making the files themselves the system’s contract, which simplifies sync, conflict resolution, and debugging.
Why use JSON files instead of a database?
JSON files are human-readable, easy to manipulate, and support forward compatibility. They allow any tool or script to participate without complex APIs or schema migrations, fostering transparency and flexibility.
How does syncing work if the disk is the source of truth?
Syncing involves copying or exchanging the JSON files between devices. Because the files are the system’s contract, any change is immediately visible and can be merged or resolved manually or through automation.
What happens when multiple devices edit the same data?
Threlmark uses atomic file writes and a read-merge pattern to handle concurrent updates. Conflicts are resolved by merging changes, preserving unknown fields, and ensuring data consistency.
Conclusion
By making the disk the contract, you’re choosing a system that’s inherently transparent, resilient, and flexible. It’s a refreshing reminder that sometimes, the simplest tools — plain JSON files — can unlock the most powerful workflows. Embrace the power of local-first design, and watch your projects become more trustworthy and adaptable.
Next time you build or manage a system, ask yourself: could the disk be the contract? The answer might just change everything.
