TL;DR
Threlmark’s local-first design treats disk storage as the primary record, allowing apps to work offline, sync seamlessly, and remain portable. This approach shifts trust from servers to durable local state, boosting speed and resilience.
Imagine an app that never delays because of network hiccups, never loses your data when offline, and syncs effortlessly when you’re back online. That’s the promise of a local-first architecture. And at its core lies a simple but powerful idea: the disk is the contract.
Instead of relying on a database or a cloud for the source of truth, Threlmark keeps everything on your disk—plain JSON files in a predictable layout. The way these files are organized and manipulated unlocks speed, resilience, and flexibility that traditional apps struggle to match.
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.
REXBETI 25Pcs Metal File Set, Premium Grade T12 Drop Forged Alloy Steel, Flat/Triangle/Half-round/Round Large File and 12pcs Needle Files with Carry Case, 6pcs Sandpaper, Brush, A Pair Working Gloves
all the 16 pieces file are made by T12 Drop Forged Alloy Steel, the long lasting teeth were…
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.
offline data synchronization software
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.
local-first app storage solutions
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 app’s data as a set of plain JSON files stored on disk, making it easy to inspect, move, and back up.
- Atomic file writes prevent corruption and race conditions, ensuring data safety during concurrent updates.
- One file per item avoids locking issues and enables seamless multi-process editing and syncing.
- The self-healing read cycle keeps the UI aligned with actual stored data, reducing manual cleanup.
- Syncing is just file copying—simple, reliable, and adaptable for multi-device workflows.
What ‘disk is the contract’ really means in simple terms
‘Disk is the contract’ means your app’s core data lives on your device’s storage, and that storage is the ultimate authority. Whatever state you see on-screen, or work on, is reflected directly in files sitting on your disk. No middleman, no remote database to check.
This makes your app self-contained. When you close it, your data stays exactly as you left it. When you reopen, it’s all there—fast and intact. Just like leaving a document on your desk and knowing it’s exactly the same when you pick it up again.
Why treating disk as the system of record makes apps faster and more resilient
Using disk as the main record reduces delays and dependency on network availability. When you save a card or update a task, it writes directly to a file—no waiting for server responses. This instant feedback makes the interface snappy, even offline.
It also means if your device loses power or crashes, your data remains safe on disk. No chance of corruption from server disconnects or partial updates. And because your files are plain text or JSON, you can back them up, move them, and share them with any tool that can read files.
How Threlmark’s file layout turns disk into a living, breathing data contract
Threlmark’s architecture organizes files in a clear, predictable way: a manifest, project folders, one file per item, and dedicated zones for suggestions and reports. This structure isn’t just tidy—it’s a formal contract. Any tool can read or write these files, knowing exactly what to expect.
For example, each item (a task or card) is stored as `items/1234.json`. The lane order is in `board.json`, and shared items sit in `shared/items/`. When a new suggestion arrives, it’s dropped into the `suggestions/` folder. All these files are easy to inspect, copy, or migrate.
How atomic file operations keep data safe and consistent
Imagine saving a file but only half of it makes it onto disk—that’s a common nightmare. Threlmark avoids that by writing to a temporary file first, then atomically renaming it over the original. This guarantees your data is either fully updated or untouched, even if your computer crashes mid-write.
For example, when updating a task, the app writes to `task.json.tmp`, then `rename()` replaces `task.json`. This tiny trick makes your data as reliable as a locked-in contract.
One file per item: how this design prevents race conditions and makes sync easy
Instead of updating a giant list, Threlmark keeps each card in its own file. This means multiple tools or processes can update different cards at the same time without clashing. No locks needed, no complex coordination.
When a change happens, only that one file updates. The system then reads all files to rebuild the current state, ensuring everything stays in sync and avoiding race conditions common in monolithic data structures.
How the read-heal-write cycle keeps the board consistent
The board’s lane order is stored separately, but every time it’s read, it checks against the actual items. Missing or orphaned cards are automatically cleaned up. This self-healing keeps your workflow accurate without manual cleanup.
Think of it like a to-do list that automatically ignores completed tasks or stray notes, always staying aligned with the actual items stored on disk.
Syncing: how changes flow smoothly across devices and tools
Threlmark’s architecture makes syncing straightforward. Since all data lives in files, syncing is just copying files between devices. When you connect your laptop and tablet, they share the `items/` folder, and updates merge naturally—no special sync engine needed.
For example, editing a task on your phone updates its JSON file, which then syncs to your desktop when connected, keeping everything fresh and consistent.
Handling conflicts and updates: merging changes without chaos
What happens if two devices change the same file? Threlmark uses a simple but effective approach: it preserves unknown fields, so older tools don’t break, and last-write-wins or timestamps help decide what stays. Conflicts are rare because each update is atomic.
In practice, if you change a task on your laptop and on your phone simultaneously, the system will keep the latest change, or you can set rules for conflict resolution—just like merging Git commits.
When local-first isn’t the best choice
While local-first is powerful, it’s not suited for every app. Highly real-time multiplayer games or financial trading platforms might need more immediate server validation. For most productivity and collaboration tools, though, it offers a clean, resilient model.
Think of it like choosing a car over a bike—great for most trips, but not for racing or mountain climbing.
Common misconceptions: it’s not just caching or offline mode
Many think local-first means simply caching data or making apps work offline. That’s only part of the story. Local-first apps treat local storage as the definitive source, enabling true resilience, portability, and collaboration—beyond just working offline.
It’s a paradigm shift, not just a feature.
Why this approach shifts trust from servers to local storage
Instead of relying on a server to always answer or validate, local-first makes your device the authority. The server becomes a sync partner, not the gatekeeper. This shifts trust to durable local files, which are always available, even in outages.
It’s like trusting your notebook more than the cloud—your work is safe, accessible, and under your control.
Frequently Asked Questions
What does ‘disk is the contract’ mean in practical terms?
It means your app’s core data is stored directly on your device’s disk in a predictable, structured way. The files serve as the single source of truth, making the app faster, more resilient, and portable without relying on a remote database.
Is local-first the same as offline-first?
Not exactly. Offline-first focuses on making apps usable without internet. Local-first goes further—making local storage the primary, authoritative data source, then syncing with other devices or servers as needed.
How do apps stay consistent across multiple devices?
Since all data lives in files, syncing is just copying those files between devices. When updates happen, they merge naturally, and conflict resolution ensures everyone stays in sync without chaos.
What happens when two devices edit the same data?
Threlmark handles this through last-write-wins or timestamp rules, preserving unknown fields to keep data safe. Conflicts are rare, but the system is designed to merge changes smoothly.
How does syncing work after reconnecting?
Syncing is just sharing files between devices. When a device reconnects, it pulls updates from others, and the system automatically reconciles differences, keeping everything consistent and up-to-date.
Conclusion
Threlmark’s local-first architecture proves that the disk can be the ultimate contract for your data. It’s a design that’s simple, resilient, and ready for the future of offline and collaborative apps.
Imagine a world where your data is always within arm’s reach, safe and portable—because the app’s core lives on your device, not in the cloud. That’s the power of making disk the contract.
