TL;DR
Threlmark’s system treats the local disk as the central contract, making data portable, safe, and accessible without a database. This design boosts offline usability, simplifies sync, and fosters open collaboration.
Imagine an app that works perfectly offline, with no server to connect to, no cloud to trust. It’s fast, resilient, and flexible. That’s the core idea behind Threlmark’s local-first architecture, where the disk isn’t just storage — it’s the contract that guides every interaction.
In this deep dive, you’ll see how a simple file layout—plain JSON files—becomes the backbone of a powerful, interoperable system. No lock-in, no complex databases. Just a clear, tangible structure that anyone can inspect, copy, or modify.
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.![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.
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.
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 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.
First Aid Only Z801 SmartCompliance Refill 52 x 84 Emergency Blanket, 1 Count
Reflects back 90% of the bodies heat
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 layout as the single source of truth, not a database or API.
- Use atomic file writes to ensure data safety and consistency during updates.
- Design your system so that the on-disk structure is inspectable, portable, and interoperable.
- Single-file per item prevents race conditions and simplifies concurrency.
- External tools and AI agents can participate seamlessly by reading/writing files directly.
What does ‘disk is the contract’ really mean?
‘Disk is the contract’ means that the on-disk layout defines the entire interface of the system. Every file, folder, and JSON document is a piece of the truth. If you want to understand or change the system, you just open these files. It’s as simple as that.
For example, each roadmap card lives in its own `items/` folder as a JSON file. External tools or scripts can read, modify, or add cards without needing a special API or database connection. This transparency makes the system inherently open and flexible. According to Disk Is the Contract: Inside Threlmark’s Local-First Architecture, this kind of architecture turns your storage into a universal, language-agnostic API.
How the file layout forms a rock-solid contract
Threlmark’s layout is a deliberate map of files and folders. At the top, a `threlmark.json` manifest and `links.json` dependency graph set the scene. Each project gets its own folder with `project.json`, `board.json`, and individual cards under `items/`. External suggestions go into `suggestions/`, and reports land in `reports/`. For more details, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture.
Here’s a quick comparison of this layout against traditional monolithic databases:
Why making file-based state safe is easier than you think
Using files might sound risky, but Threlmark’s patterns turn it into a safe, reliable foundation. Atomic writes use `rename()` to prevent partial updates. Read-merge-write cycles keep data consistent, even with concurrent edits. For example, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture when updating a card, the system writes to a temp file and then atomically replaces the original. This prevents corruption even if the app crashes mid-write.
These simple but disciplined patterns transform files into a resilient, lock-free database alternative.
One file per item — how it stops race conditions and keeps things simple
Instead of a giant `roadmap.json`, Threlmark uses one JSON file per item (`items/
Plus, the system automatically self-heals the lane order (`board.json`) on each read, ensuring consistency even if some cards are missing or moved. This approach simplifies concurrency and keeps the system easy to maintain.
How Threlmark’s local-first design enables AI and external tools
With the disk as the contract, external tools like AI agents can participate effortlessly. They just read and write files—no API required. For example, an AI can scan `suggestions/` for new ideas, process them, and drop updates directly into `items/`. When an AI moves a card to ‘Done,’ it simply updates the relevant JSON file. See Disk Is the Contract: Inside Threlmark’s Local-First Architecture for more on this pattern.
This openness means tools can work asynchronously, collaborate more freely, and even automate themselves. It’s a pattern that scales from solo projects to multi-user teams.
Practical tips for building your own disk-as-contract system
- Keep your file structure simple and predictable.
- Use atomic writes for all file updates.
- Merge updates carefully, preserving unknown fields.
- Design for self-healing by reconciling state on read.
- Make everything inspectable and portable — avoid hidden state.
For example, if you’re building a task manager, each task lives in its own JSON file, and your app reads all tasks on startup. Changes are written atomically, and external tools can add or modify tasks without breaking the system.
What are the big benefits of treating disk as the contract?
Using the disk as the single source of truth delivers four key benefits:
- Inspectability — you can open, read, and understand every file.
- Portability — move entire projects by copying files.
- Interoperability — any language or tool can join in by reading/writing files.
- Restartability — no in-memory state to lose, just reload files.
For example, backing up your project is as simple as copying the entire folder. Restoring or migrating is just copying files into a new environment.
Frequently Asked Questions
What does ‘disk is the contract’ really mean?
It means the on-disk layout of files and folders defines the entire interface of your system. Everything is stored as plain files, making it simple, inspectable, and portable.How do I keep file updates safe and consistent?
Use atomic writes with temporary files and `rename()`. When updating, write to a temp file first, then atomically replace the original, preventing corruption during crashes.Can external tools or AI really participate without APIs?
Yes. Since everything is just files, external tools can read, modify, or add files directly. This openness simplifies integration and automation.What are the main benefits of this approach?
Inspectability, portability, interoperability, and restartability. You can back up, copy, or migrate your system just by handling files.Is this approach suitable for all kinds of apps?
While ideal for offline, multi-device, or collaborative systems, it may not suit apps requiring real-time server-side processing or complex transaction management.Conclusion
Threlmark’s local-first architecture proves that simplicity can be powerful. When the disk is the contract, your app becomes more resilient, transparent, and flexible. It’s a reminder that sometimes, the most straightforward approach—using plain files—can create the most robust systems.
Next time you build or refactor, ask yourself: can I treat the disk as the ultimate authority? Chances are, you’ll find it’s a surpris. For more insights, visit aiespionage.net.ingly elegant solution that scales with your needs.
