TL;DR
Threlmark uses plain JSON files on disk as the real system of record, avoiding databases. This approach makes data portable, transparent, and resilient, especially for offline and multi-tool workflows. It’s a powerful example of local-first design in action.
Imagine a system where your project’s entire state lives in a handful of simple JSON files on your disk. No cloud, no server, just plain files. That’s the core idea behind Threlmark’s local-first architecture. It’s a bold move that flips the typical client-server model on its head.
Instead of relying on a central database or cloud service, Threlmark’s design makes the filesystem the contract. This means your data is transparent, portable, and inherently resilient. Want to back it up? Just copy a folder. Need to merge changes from two devices? Diff the files. This approach isn’t just about simplicity; it’s about control, flexibility, and future-proofing.
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.
SANDISK 512GB Ultra USB 3.0 Flash Drive – SDCZ48-512G-G46, Black
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.
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.
JSON file backup storage
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.
SUUNTO Nautic S Dive Watch Computer w/Bright AMOLED Display, GPS, Offline Maps and Weather Tools, Wireless Tank Pressure, Up to 60H on a Single Charge
Bright AMOLED Display for Superior Readability-Enjoy crystal-clear visibility underwater with a bright AMOLED screen, designed for easy reading…
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
- Using the filesystem as the system’s source of truth makes data transparent, portable, and merge-friendly.
- Atomic file writes prevent corruption and ensure data safety even during crashes or power outages.
- One file per item reduces conflicts and simplifies concurrent editing across tools and devices.
- External tools and AI agents can seamlessly participate by reading and writing files directly.
- Careful planning around conflict resolution, schema evolution, and scaling is crucial for large projects.
What Does ‘Disk Is the Contract’ Actually Mean?
When Threlmark says “disk is the contract,” it means the system’s entire state is stored directly in files—specifically JSON files—on your disk. These files aren’t just storage; they define how the app understands and manipulates data.
For example, each project card becomes a separate JSON file in the items/ folder. The file’s contents are the source of truth. If you change it, the app reads the new state directly from that file, no middleman needed.
This approach heavily contrasts with traditional apps that rely on a database — a black box that manages data behind the scenes. Here, your filesystem is the database, and every change is a file update.
Why does this matter? Because it shifts the paradigm from opaque, complex data management to a transparent, file-based system. This transparency allows developers and users to see exactly what’s stored, make manual edits if needed, and understand data flow without specialized tools. It also enables seamless merging and conflict resolution, which are crucial for offline and multi-device workflows.
Why Choosing Files Over a Database Changes Everything
Using files instead of a database simplifies the entire data lifecycle. There’s no need for complex schemas, migrations, or server setup. Just edit a JSON file, and the system reads the latest version.
Take a typical project card: it’s a single JSON file, like items/1234.json. To update it, you overwrite that file atomically. No transaction logs, no locking, just a simple rename() operation that guarantees consistency.
This simplicity impacts how teams collaborate. When everyone works with files, they can use familiar tools—diff, merge, version control—to manage changes. This transparency reduces errors, speeds up troubleshooting, and makes the system more resilient. However, it also introduces tradeoffs: managing conflicts manually or through merge strategies becomes necessary as the system scales, and ensuring atomicity across many files can become complex if not carefully engineered. Still, for many workflows, this tradeoff favors flexibility and control over the overhead of a traditional database.
In essence, this approach transforms data management from a black-box process into a transparent, controllable one. It empowers users to understand and manipulate their data directly, which can be a game-changer for collaboration and offline work.
How Threlmark Ensures Data Safety with Files
File safety might sound tricky, but Threlmark uses two key tricks: atomic writes and tolerant merge. Atomic writes mean every file update happens in a temp file, then moves into place. This prevents corruption if your machine crashes mid-save.
For example, when you move a card from “In Progress” to “Done,” the app writes a new JSON file atomically, so you never end up with a half-written file. This makes your data reliable, even on flaky disks or power outages.
The second trick, tolerant merge, reads the current file, applies updates, and writes back. It preserves unknown fields and merges changes smoothly. This allows multiple tools or agents to update files without conflicts or data loss.
These techniques are crucial because they maintain data integrity without the overhead of locking or complex transaction management typical in databases. They enable a resilient system that can recover gracefully from crashes or interruptions, which is vital for offline-first workflows where network or power reliability can vary.
One File Per Item: How It Solves Concurrency and Sync Issues
Instead of a giant JSON array for all cards, Threlmark uses one file per item. This design drastically reduces conflicts. Two tools editing different files won’t overwrite each other.
Imagine two team members working on separate cards. One updates items/123.json while the other works on items/456.json. They can save independently, and the system ensures each change is atomic and safe.
This separation also simplifies synchronization. When syncing, only changed files need to be transferred, reducing bandwidth and conflict potential. Learn more about the local-first architecture. The system can also easily handle concurrent edits by merging changes at the file level, rather than dealing with complex diffs on a large dataset. This approach encourages modularity and isolates changes, making the overall system more robust.
The self-healing board.json tracks lane order but reconciles every time it’s read, making sure the visual workflow stays consistent despite concurrent edits. This design emphasizes resilience and clarity, allowing multiple tools to operate without stepping on each other’s toes.
How External Tools and AI Agents Play Nice with Files
Threlmark’s design is open and portable — external tools can jump in without permissions or APIs. Just read and write files.
For instance, an AI agent like IdeaClyst can suggest new cards by placing JSON files into suggestions/. Human or AI can then review and move them into items/.
When the AI moves a card to ‘Done,’ it updates the file atomically and records a report back in reports/. No API calls needed, just file manipulation.
This openness allows seamless integration with a wide range of tools, from simple scripts to complex AI agents. Because the data is just files, any system that can read/write JSON can participate, making the architecture inherently flexible and future-proof. This promotes collaboration across diverse tools and workflows, reducing dependency on proprietary APIs or vendor lock-in.
What Are the Real Benefits of a Disk-First System?
There are clear wins with Threlmark’s approach. First, full transparency: every artifact is a file you can open, diff, and back up. Second, portability: move your project by copying a folder or syncing via Dropbox.
Third, offline resilience: you can work disconnected, and changes sync later. Fourth, interoperability: any tool, any language, can read and write the files.
For example, a developer can use `diff` or `git` to see exactly what changed in a card, or migrate their data to another system with ease.
Beyond these practical benefits, this transparency fosters better understanding and control over your data. It enables debugging, auditing, and manual intervention when necessary. The ability to work offline without special dependencies or server setups means teams can operate in remote or disconnected environments with confidence, making this approach especially appealing for distributed or fieldwork scenarios.
The Challenges and Trade-offs of a File-Based Approach
This approach isn’t without hurdles. Managing concurrency across devices becomes complex. Conflicts have to be merged carefully, and schema evolution needs versioning strategies.
Backup and recovery depend on copying files, which is simple but requires discipline. And scaling large datasets can slow down if every operation involves many small file reads.
For example, syncing a terabyte of JSON files across multiple devices can become cumbersome without proper tooling. Additionally, as the dataset grows, performance bottlenecks may arise because the system relies on file I/O rather than optimized database queries. This necessitates careful planning for data organization and possibly layered caching or indexing strategies to maintain responsiveness.
How Does Threlmark Compare to Traditional Databases?
| Feature | File-Based (Threlmark) |
|---|---|
| Data Storage | Plain JSON files |
| Atomicity | File rename + temp files |
| Portability | Copy folder, sync tools |
| Interoperability | Any language can read/write files |
| Conflict Resolution | Merge patches, tolerant updates |
What Should You Watch for Before Going Disk-First?
If you’re considering this pattern, focus on conflict management, schema evolution, and backup strategies. It works great for small to medium projects but can become tricky at scale.
Ensure your tooling supports atomic file operations, and plan for conflict resolution workflows. Think about how to migrate data if you need to switch to a different format later.
For example, start with a small project and test sync and merge before scaling up.
Frequently Asked Questions
What does ‘disk is the contract’ actually mean?
It means the system’s entire state is stored in plain files—usually JSON—on disk. These files define the data structure and are the single source of truth, making the data transparent and easy to manage.
How is this different from using a database?
Instead of a centralized database, each piece of data is a file. This simplifies backups, migrations, and integrations, but requires careful handling of concurrency and conflicts. It’s a more transparent, flexible approach.
Why choose JSON files over Postgres or SQLite?
JSON files are human-readable, easy to diff, and portable. Moving data is just copying files. Plus, no need to manage a database server, which reduces complexity and dependencies.
How does sync work across devices?
Changes are stored as individual files, which can be synced via conventional tools like Dropbox or Syncthing. When devices sync, the files merge naturally, and the system reconciles any conflicts.
What happens when two people edit the same data at once?
Since each item is a separate file, conflicts are minimized. If conflicts occur, tolerant merge strategies combine changes smoothly, preserving unknown fields and avoiding data loss.
Conclusion
Threlmark’s disk-first architecture isn’t just clever — it’s a radical shift that gives you control, transparency, and resilience. By making files the contract, you turn your project into a living, portable artifact you can back up, migrate, and extend with ease.
Think of it as turning your project into a garden: simple to tend, easy to share, and always visible. If you want a system that works offline, plays nice with tools, and keeps your data transparent, this might be your blueprint.
