TL;DR
Threlmark uses local disk storage as the single source of truth, making data portable, offline-capable, and safe. This design simplifies tools, enhances reliability, and unlocks new possibilities for multi-device workflows and AI integration.
Imagine a project management tool that works perfectly offline, data is always safe on your own disk, and external tools can join in without permission hurdles. That’s Threlmark in action. Its secret? The disk isn’t just storage—it’s the contract that keeps everything aligned and safe.
In a world obsessed with cloud databases, Threlmark flips the script. It makes local storage the primary source of truth, turning your filesystem into a flexible, resilient, and collaborative hub. Curious how this simple idea unlocks such power? Let’s explore the mechanics, the decision-making, and what it means for your tools and workflows. Learn more about local-first architecture.
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.
Seagate Portable 2TB External Hard Drive HDD — USB 3.0 for PC, Mac, PlayStation, & Xbox -1-Year Rescue Service (STGX2000400)
Easily store and access 2TB to content on the go with the Seagate Portable Drive, a USB external…
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.
SSK Portable SSD 1TB External Solid State Drives, up to 1050MB/s USB C SSD External Hard Drive USB 3.2 Gen2 for iPhone 15/16/17Pro, Windows, Mac, Android Phones and Tablets
Capacity Reminder: Display capacity of 1TB SSD often appears as around 931GB on Windows. MacOS typically shows full…
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.
Siveit CD/DVD Case Binder – 400 Capacity Disc Storage Holder, Black PU Binder
The Sivet CD/DVD case bag is made of durable, moisture-proof, and tear resistant silk fabric, which can be…
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 the disk as the single source of truth to simplify data safety, portability, and collaboration.
- Use atomic file writes and tolerant merge strategies to prevent corruption and conflicts.
- Design your system with one file per item to enable self-healing, concurrency, and seamless updates.
- Layer sync as a background, conflict-resistant layer rather than relying on the cloud as the authority.
- Prioritize local-first principles to build resilient, privacy-focused workflows that work offline and across devices.
Why Making the Disk the Single Source of Truth Changes Everything
Threlmark’s core idea is simple but revolutionary: the data on your disk is the one true record. Unlike cloud apps that rely on a server, this approach makes your local files the authoritative source. When you edit a card or move a task, you’re changing the real file, not a cache or a database.
For example, imagine working on a project with multiple devices. Changes made on your laptop immediately reflect on your tablet because both read and write the same files. No syncing conflicts, no server outages, just a consistent truth stored right there on your disk.
This approach also means the system is more flexible. You can back up, migrate, or even edit files manually. It’s like having the raw data in your hands, with every artifact inspectable, diffable, and portable. That’s a game-changer for resilience and collaboration.
How Threlmark Keeps Data Safe and Consistent Using Files
Using files safely is tricky—crashes, race conditions, and corruption threaten data integrity. Threlmark solves this with two key patterns: atomic writes and tolerant merge reads.
Atomic writes mean updating files through temporary files and renaming them only once complete. Think of it like changing a document: save to a temp file, then replace the original in one atomic step. This prevents corruption even if your computer crashes mid-save.
The second pattern—read-merge-write—lets multiple tools and agents update data without conflicts. When you read a file, you merge in new changes, preserve important metadata, and then write atomically. If another process changed the file meanwhile, your merge still respects those changes, keeping everything consistent.
For example, if your AI assistant suggests a new task, it writes directly to its JSON file. When you later review, it merges seamlessly with your existing data, avoiding clobbering or lost updates.
One File Per Card: Why This Simple Choice Prevents Chaos
Instead of a big JSON array, Threlmark uses one file per task or card. This tiny shift makes a huge difference. It eliminates race conditions and makes updating or deleting individual items straightforward. Read more about one-file-per-item design.
Imagine each task as a tiny, self-contained file. When you change one, you only rewrite that file. No need to read and rewrite a giant list—just swap out a single file atomically.
This design also enables the system to “heal” itself. When reading the board layout, it cross-references actual item files. Missing files are ignored, misplaced files are sorted, and your view stays consistent without manual cleanup.
For example, if you delete a card, its file vanishes. The next time the board reads the data, it automatically updates without clunky locks or complex merges.
How the Board Self-Heals and Keeps Your Workflow Smooth
The board isn’t just a static list; it’s a living, breathing view that adapts on each read. The lane order isn’t stored in a single list but is reconstructed from the actual items present. Discover how self-healing boards work.
For example, if an item is deleted or moved outside the system, the next read of the board will automatically ignore or reposition it. This makes the system resilient against manual edits or external file changes.
Think of it like a GPS that recalibrates itself after every turn. The data always reflects the current reality, not just a snapshot frozen in time.
This self-healing ensures your workflow stays consistent, even with external modifications or partial failures.
Sync as a Layer, Not the Core: How Threlmark Connects Devices
In Threlmark, sync isn’t the main storage—it’s a layer that keeps devices in harmony. The disk holds the truth; the cloud just shares copies. Learn about local-first device synchronization.
For example, when you finish a task on your desktop, the files update instantly. Your phone then syncs these changes in the background, merging any conflicts. It’s like a quiet, reliable assistant that keeps everything aligned without fuss.
This model allows offline work without losing data. Devices act independently, then reconcile when connected. It’s a flexible, resilient way to handle multi-device workflows, especially as more tools embrace local-first principles.
Tradeoffs and Challenges: What You Need to Know
While local-first is powerful, it’s not perfect. Managing conflicts, schema migrations, and multi-user collaboration requires careful design. CRDTs, commit graphs, and operation logs help, but they add complexity.
For example, if two devices edit the same card simultaneously, the system must choose how to merge. Threlmark’s approach favors deterministic merges, but it’s a balancing act between simplicity and robustness.
Another challenge: migrating data schemas or sharing data across users without a central server can be tricky. It often demands custom solutions or extra tooling.
Despite these hurdles, the benefits of resilience, privacy, and control often outweigh the tradeoffs, especially for solo projects and small teams.
Tools and Technologies That Power Threlmark’s Architecture
Threlmark relies on simple, reliable tech: JSON files, atomic `rename()` operations, and straightforward merging. No complex database or server needed.
In practice, it uses standard local storage options like IndexedDB or simple filesystem APIs, depending on the environment. The key is that these tools support atomic writes and easy merge strategies.
It also connects with external tools like IdeaClyst through shared files, making integration seamless. The architecture is open and flexible, encouraging collaboration across tools and languages.
For example, a script can generate new cards directly into the `items/` folder, and Threlmark will pick up those changes automatically.
Why This Matters for Developers and Users Alike
Local-first isn’t just a clever trick; it’s a paradigm shift. For developers, it means fewer dependencies, simpler state management, and more control over data. For users, it offers faster, more reliable workflows with privacy built-in.
Imagine editing your project on a plane—nothing breaks. Or backing up your entire system by copying a folder. That’s the power of treating disk as the contract.
As more tools adopt these principles, we’ll see a future where apps are more resilient, private, and portable—no lock-in, no cloud dependency, just robust local data.
Frequently Asked Questions
What does “disk is the contract” mean?
It means that your system’s primary data is stored directly on your disk, and this storage acts as the definitive source of truth. All tools and processes read from and write to these files, making the filesystem the core of your data management.
How is local-first different from offline-first or cloud-first?
Local-first places the disk as the main storage, ensuring data is always available locally. Offline-first emphasizes working without network, but still relies on a cloud for sync. Cloud-first apps depend on remote servers as the primary data source, often sacrificing offline reliability.
What happens when two devices edit the same data?
Threlmark uses merge strategies that reconcile changes deterministically, preventing conflicts from corrupting data. When conflicts happen, the system merges edits based on rules or CRDT-like algorithms, keeping everything consistent across devices.
How do sync conflicts get resolved?
The system employs conflict resolution techniques like operation logs or CRDTs to merge concurrent edits. This way, no data is lost, and the process remains transparent and predictable.
What technologies power local storage in Threlmark?
It typically uses IndexedDB or filesystem APIs depending on the environment, both supporting atomic writes and easy merging. These tools are simple, reliable, and well-suited for a local-first architecture.
Conclusion
Threlmark’s architecture proves that the simplest idea—making disk the contract—can lead to powerful, reliable tools. It’s a reminder that sometimes the best solutions are the ones closest to the user, not in a distant cloud.
For your projects, consider how making local storage the primary truth can cut complexity, boost resilience, and empower users. After all, the real power lies in the files we hold in our hands, not just in the cloud.
