TL;DR
Threlmark’s architecture treats disk files as the ultimate source of truth, making the system highly portable, restartable, and offline-first. This approach simplifies collaboration, enhances reliability, and empowers AI automation, all without a traditional database.
Imagine a project management app so simple that it runs entirely from plain text files on your disk. No servers, no cloud, just a folder full of JSON files that keep your work safe and portable. That’s the core idea behind Threlmark’s local-first architecture—where the disk isn’t just storage, it’s the contract.
This design isn’t just about saving files. It’s a radical shift that turns your computer’s file system into the single source of truth. You get faster performance, better offline support, and a system that’s inherently open and collaborative. Ready to see how it all works? Let’s peel back the layers of this elegant, file-based 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.
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.
Flash Drive for iPhone 256GB, 4 in 1 USB Type C Memory Stick, Photo Stick External Storage Thumb Drive for iPhone iPad Android Computer, Sky Blue
256GB 4 IN 1 PHOTO STICK – High quality aluminum frosted ZARMST usb c flash drive comes in…
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.
![Free Fling File Transfer Software for Windows [PC Download]](https://m.media-amazon.com/images/I/41Vq6ZqHfjL._SL500_.jpg)
Free Fling File Transfer Software for Windows [PC Download]
Intuitive interface of a conventional FTP client
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.
Music Studio 11 – Music software to edit, convert and mix audio files – Eight music programs in one for Windows 11, 10
8 solid reasons for the new Music Studio 11!
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
- Treating disk files as the system’s contract makes your app transparent, portable, and restartable.
- Atomic writes and tolerant merging prevent corruption and ensure data safety during concurrent updates.
- A file-per-item design simplifies collaboration and external tool integration, including AI automation.
- Self-healing data structures keep project views consistent without manual intervention.
- This architecture is ideal for offline work, multi-device sync, and flexible toolchains.
Why Making the Disk the Single Source of Truth Changes Everything
In Threlmark’s world, the disk isn’t just a backup or storage layer. It’s the entire contract, the blueprint for how the app functions. Think of it like a map that everyone agrees on—no matter what tool you’re using, the files are the law.
For example, each project gets its own folder with a project.json for metadata, and each task card lives as an individual file in the items/ directory. When you open your app, it just reads these files. When you make a change, it writes directly to the disk. No need to synchronize with a server or worry about conflicting data—because the files are always the truth.
This approach makes the system incredibly transparent. You can open any file, see exactly what it contains, and even edit it outside the app. It’s like having the source code for your project management system, right on your desktop.
How the File Layout Acts as a Protocol — Not Just Storage
Threlmark’s file structure isn’t just a random dump of data. It’s a carefully designed contract. The root contains a threlmark.json manifest, a links.json dependency graph, and each project has its own folder with JSON files for metadata, lanes, and cards. Learn more about this file structure.
For example, each task card lives in items/ as a separate file like abc123.json. External tools, like AI agents or other integrations, can read or modify these files directly. Find out how AI automation fits into this system. The entire system is open—any tool that can read and write JSON can participate.
This structure means that the entire state of your projects is just a folder full of JSON files. It’s portable—copy it to another machine, sync with Dropbox, or migrate to a new app—without losing fidelity.
Why Atomic Writes and Tolerant Merging Keep Data Safe
Using files as your database sounds risky—unless you do it right. Threlmark employs atomic writes: writing to a temporary file, then renaming it over the real file. This tiny trick guarantees that a crash during save never corrupts your data.
Plus, it uses a read-merge-write pattern. When updating a file, it reads the current state, merges in the changes, and writes back atomically. It even tolerates unknown fields, so older tools can read newer formats without breaking.
Imagine editing a task card while the app is open. The app reads the current file, merges your edits, and updates the disk without risking partial data. It’s like a well-trained editor who always leaves the page spotless, even if interrupted.
The Self-Healing Board: Keeping Your Workflow Consistent
Threlmark’s approach to managing tasks is simple but clever. Each project’s lane order lives in a board.json file, which is read and reconciled on each access. If a task gets deleted or moved outside the system, the board automatically heals itself.
For example, if a task is removed from items/ but still appears on board.json, the system notices the mismatch and corrects it on the fly. This keeps your workflow consistent, even when external edits happen.
This self-healing mechanism ensures your project view always reflects reality, preventing confusion and misplaced work. It’s like a map that automatically updates itself when roads change, without needing a GPS recalibration.
How External Tools and AI Agents Play Nice with Files
Threlmark’s design invites external tools to join the workflow. An AI agent, for example, can read task files, suggest updates, or even move cards to ‘Done’ without special permissions. It treats the files as its API.
In practice, this means you can have an AI assistant that looks at your items/, identifies priorities, and updates task statuses— all by reading and writing plain JSON files. No complicated API calls needed.
Imagine an AI that scans your project folder, flags overdue tasks, and automatically marks them as complete when they’re done—just by manipulating the files directly. That’s the power of treating the disk as the contract.
What Makes This Architecture Faster, Safer, and More Flexible?
Because all data lives on your disk, reading and writing is instant—no network lag, no server delays. Discover more about local-first architectures. If you’re offline, the system keeps humming, and syncs happen later.
It’s safer too. If your device crashes, your files are still intact—no database corruption or lost transactions. Plus, backing up is as simple as copying a folder.
And flexibility? Massive. You can swap tools, migrate data, or even edit files manually—because the data format is human-readable JSON, not a proprietary database.
Tradeoffs and Limitations You Should Know
This approach isn’t without tradeoffs. Managing conflicts in multi-device edits can get tricky—without CRDTs or operational transforms, conflicts rely on last-write-wins or manual resolution.
Performance can degrade if you have thousands of files—though with good structure, it’s manageable. And security? Files are readable, so encryption is essential if sensitive data is involved.
Think of it like a shared notebook: easy to use, but you need to be careful with concurrent edits and backups.
Real-World Examples: How Threlmark’s Approach Changes Your Workflow
Imagine you’re working on a team with three devices. You jot down ideas on your laptop, then switch to your tablet during a commute. Threlmark keeps all your tasks synchronized by simply reading and writing files in a shared folder.
Or picture a solo developer using AI. The AI reads the JSON files, suggests task improvements, and updates statuses— all without needing a special API. It’s like working with a smart, silent assistant that lives inside your disk.
These scenarios show how treating disk as the contract streamlines multi-device and AI collaboration, making your workflow more fluid and resilient.
Getting Started: How to Build Your Own File-Based Project Hub
- Set up a directory structure with folders for
items,shared, and project metadata. - Create a manifest file like
threlmark.jsonto define your projects and dependencies. - Design your task cards as individual JSON files inside
items/. - Implement atomic file writes for all updates.
- Use a self-healing algorithm to keep your board consistent on each read.
With these steps, you can turn your local machine into a resilient, portable project hub that works offline and plays nicely with other tools.
Frequently Asked Questions
What does ‘Disk Is the Contract’ mean in practice?
It means the app’s data and logic revolve around the files stored on your disk. The files are the source of truth, and all tools read from and write to them directly, making the system transparent and portable.
How is this different from a normal client-server app?
Instead of relying on a central server, all data lives on your device’s disk. Synchronization with other devices or cloud services happens later, making offline work seamless and reducing reliance on persistent internet connections.
Why use JSON on disk instead of a database?
JSON files are human-readable, easy to back up, and simple to manipulate with any tool. This transparency makes debugging, migration, and collaboration much easier than dealing with proprietary databases.
How does sync work when a device comes back online?
Changes are stored locally in JSON files. When connected, the system can reconcile differences—merging updates, resolving conflicts, and syncing across devices—using the file-based contract as the guide.
What happens when two devices edit the same data?
Without complex conflict-resolution algorithms like CRDTs, conflicts rely on last-write-wins or manual resolution. Careful design and user discipline are key to managing consistency in multi-device setups.
Conclusion
Threlmark shows that the simplest idea—making the disk the contract—can redefine what’s possible in project management tools. It’s a blueprint for systems that are faster, safer, and more open.
Next time you build or choose a tool, ask: does it treat the disk as the source of truth? If it does, you’re looking at a future-proof way to work that’s rooted in the simplest, most reliable technology: plain old files.
