TL;DR
Threlmark’s architecture treats local disk storage as the core record, making it easy to work offline, sync seamlessly, and maintain full data ownership. This approach reduces backend complexity and boosts privacy, all while supporting multi-device workflows.
Imagine working on your project, unplugged from the internet, yet still fully in control. No cloud dependency, no server hiccups. That’s the power of Threlmark’s local-first design: the disk isn’t just storage; it’s the contract that keeps everything in sync.
In a world obsessed with cloud databases and centralized servers, Threlmark flips the script. It treats your device’s local storage as the definitive source of truth. This article takes you inside its design choices—why they matter, how they work, and what they mean for your data’s privacy, resilience, and flexibility.
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.
NEWQ 2TB External Hard Drive for iPhone, USB-C & Lightning Compatible Photo Storage Device, One-Click Backup Photos/Videos to Free Up Phone Space, Offline Transmission Support, No Computer Required
2TB Large Capacity One-Click Backup, Instantly Free Up Your Phone Storage: Running out of phone storage often forces…
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.
Smart Keypad Door Lock with Handle, Smart Door knobs with Lock, Auto Door Lock with Code and App, Keyless Entry Door Knob for Bedroom, Front Door, Smart Home, Apartment, Local Data Storage
3-in-1 Smart Access Upgrade for Every Space – Transform your entryway experience with the KLLOQUE door lock, designed…
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.
JSON file storage device
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 local disk storage as the single source of truth, not just a cache or backup.
- Use atomic file writes and file-based state to prevent corruption and race conditions.
- Design systems where the on-disk structure is the API—inspectable, portable, and interoperable.
- Offline-first design empowers users, enhances privacy, and simplifies data management.
- This architecture scales well for small to medium projects but needs careful handling for large datasets.
What Does ‘Disk Is the Contract’ Actually Mean?
‘Disk is the contract’ means your app’s core data lives on your device’s storage, and that’s where the truth resides. Unlike cloud systems that rely on a remote database as the single source, Threlmark treats local files as the authoritative source, with sync happening in the background.
Think of it like a notebook where every page is a file—no central server dictates what’s true. This makes your data portable, inspectable, and resilient. For example, if your laptop crashes, your project files stay intact, ready to be reopened on another device. Learn more about local-first architecture.
This approach simplifies data management. The files are the API—reading, writing, and updating happen directly on disk, with no middleman. It’s a straightforward, transparent contract between your system and the storage media.
Why Local-First Architecture Is More Relevant Than Ever
Local-first isn’t just a buzzword; it’s a practical necessity, especially in a world where connectivity isn’t guaranteed. According to recent data, roughly 40% of users experience intermittent internet, and many prefer offline workflows. Threlmark’s approach ensures your work isn’t crippled by a flaky connection.
Imagine editing a project during a flight or in a remote cabin—your data is accessible and editable, no matter what. When back online, the app syncs automatically, blending your local changes with other devices seamlessly.
This model also bolsters privacy. Your data is under your control, not locked in a cloud. And it reduces server load, making apps lighter, faster, and more reliable. That’s why local-first is the future, not just a fallback plan.
How Threlmark’s Architecture Works in Practice
Threlmark’s system is built around a simple but powerful idea: the on-disk layout *is* the API. At its core, each piece of data—like a task card—is stored as a separate JSON file inside an `items/` folder. No database, no complex sync protocol.
When you open your project, the app reads all these files directly. To update a task, it writes a new JSON file atomically. This guarantees consistency, even if your system crashes midway.
Here’s a quick peek at the structure:
| File | Purpose |
|---|---|
| threlmark.json | Project manifest and configuration |
| items/ | Individual task or card data |
| board.json | Lane ordering, self-healing on read |
| suggestions/ | External suggestions and inputs |
This layout makes everything inspectable, portable, and interoperable. Any tool or script can just read or write these files, making the entire system surprisingly flexible.
Benefits for You: Offline Work, Privacy, and Control
When your data lives on your disk, offline work becomes second nature. You can edit, review, or reorganize your tasks without an internet connection. Everything is just files, like a well-organized folder of notes.
Privacy gets a boost too. Your data isn’t floating in the cloud. Instead, it stays on your device, protected from external breaches unless you choose to sync or share.
And because every change is a simple file write, you gain full control. You can back up, migrate, or even manually tweak your data—no vendor lock-in, no proprietary formats.
How Developers Benefit from a File-Based, Local-First System
For developers, Threlmark’s architecture reduces the complexity of building sync and conflict resolution logic. Check out the project on GitHub. Instead of managing a complicated backend, you focus on your app’s core features.
Implementing features like undo, history, or real-time collaboration becomes easier because the data is just files. Conflict resolution is straightforward—atomic file writes prevent race conditions, and self-healing boards adapt automatically.
Plus, the system is fully open: you can extend, customize, or integrate with other tools by just reading and writing files. No vendor lock-in, no special SDKs. Check out the project on GitHub to see how simple yet powerful it is.
Tradeoffs and Limits You Should Know
This approach isn’t perfect. Handling very large datasets or high-frequency updates can strain a file-based system. Version conflicts still need care, especially in collaborative environments.
Syncing across devices relies on background tools—if those fail, data consistency might lag. And managing complex relationships or large-scale data might push the system to its limits.
However, for many use cases—solo projects, small teams, or offline-first apps—the benefits outweigh these tradeoffs. Threlmark’s design embraces simplicity without sacrificing power.
Your Questions About Local-First and Threlmark
- What does ‘local-first’ mean in plain English? It means your device’s storage holds the main copy of your data, with syncing as a background process, not the other way around.
- How does syncing work in Threlmark? Changes are tracked in files, and background tools sync them across devices, resolving conflicts automatically.
- Is this system suitable for large projects? It works well for small to medium projects, but very large datasets might need specialized solutions.
Conclusion
Making disk the contract turns your device into a resilient, private hub for your work. Discover more about local-first strategies. It’s a simple idea with big implications: full control, offline resilience, and easy collaboration—without the cloud dependency.
Next time you build or pick a tool, ask: does it treat my data as the primary record on my disk? If not, you might be missing out on the future of robust, user-empowered software.
