TL;DR
Threlmark’s system treats local disk files as the single source of truth, enabling offline reliability, portability, and interoperability. Its design simplifies data management without sacrificing power or privacy.
Imagine managing your entire project workflow—priorities, notes, AI suggestions—without logging into an app or relying on a cloud server. That’s what Threlmark’s local-first approach delivers. It’s a simple idea: your disk is the contract, the single source of truth, and everything else follows from that.
In a world obsessed with cloud storage and centralized databases, Threlmark flips the script. Its architecture is built around one core principle: everything lives on your disk as files. No cloud, no user accounts, just a straightforward file structure that your tools can read, write, and trust. This isn’t just about saving space; it’s about creating a system that’s reliable, portable, and open—built for real-world work, especially when offline or multi-device sync matters most.
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.
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.
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.
Local AI with VS Code: Mastering Private, Offline LLM Development: Run Open-Source Models Securely with Ollama, Continue, Llama.cpp, and Zero-Cloud Extensions – Keep Your Code and Data 100% Private
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 Genie Premium: JSON Editor, Viewer & Formatter
Open, view, and edit JSON and JSONC files with a fast tree-based interface
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 as the primary source of truth: store each task or note as a separate JSON file.
- Use atomic writes to ensure data safety, even during crashes or concurrent edits.
- Design your file structure as a contract that external tools and AI agents can rely on for interoperability.
- Break large data sets into small, manageable files that self-heal and stay consistent.
- Open data formats like JSON make your system portable, inspectable, and future-proof.
How the Disk Becomes the Single Source of Truth
Threlmark treats your disk as the ultimate record keeper. The main folder, typically at threlmark.com, contains a manifest, project data, and individual cards—each in its own JSON file. This setup means the entire system is just a bunch of plain text files. Want to see what’s urgent? Open the relevant file. Need to back it up? Copy the folder. Want to integrate with another tool? Just read and write files.
By relying on a simple, transparent file structure, Threlmark emphasizes that the core of your data isn’t hidden behind complex schemas or proprietary formats. Instead, it’s accessible and modifiable by anyone with basic tools. This transparency fosters trust and flexibility, allowing users to understand exactly how their data is stored and manipulated. It also means that the system’s reliability hinges on the integrity of these files rather than on external databases, which can be points of failure or lock-in. The design choice underscores a fundamental tradeoff: simplicity and openness versus the potential need for more sophisticated conflict resolution in complex scenarios. However, for many workflows, this tradeoff favors robustness and control.
For example, each card—think of it as a task or note—is stored as a separate JSON file in the items/ directory. When you update a card, Threlmark uses atomic writes (more on that later) to replace the file. This guarantees no partial updates or corruption. The folder structure acts as a contract: all tools agree on where data lives and how to interpret it. This approach ensures that, regardless of external changes or disruptions, the core data remains consistent and accessible, emphasizing that the disk layout itself is a reliable API.
Why Local-First Means No Server Is the Rule, Not a Limitation
When Threlmark says “disk is the contract,” it means there’s no central server holding your data. Instead, every tool, script, or AI agent reads and writes directly to the files. This approach makes the system naturally offline-first. You can add tasks, move cards, or tweak priorities without an internet connection.
Take a busy developer who’s on a plane. They update their roadmap, add new ideas, and shift priorities. When they land, the app syncs changes seamlessly—because the data was local all along. The system doesn’t rely on cloud availability or server uptime; the device is the primary data hub. This model empowers users with control over their data, reducing reliance on external services that might be unreliable or slow. However, it also introduces challenges: without a central authority, conflicts can arise when multiple devices or tools modify the same files concurrently. Addressing these conflicts requires careful design—like atomic operations and self-healing mechanisms—to ensure data consistency. The tradeoff favors resilience and independence but demands thoughtful handling of synchronization complexities.
The Power of a Plain JSON File System — No Lock-In, No Complexity
Threlmark’s design uses plain JSON files—no databases, no special formats. Each item gets its own file, so external tools can easily read or modify data without complex integrations. It’s like having a shared Google Doc—except it’s just a text file sitting on your computer.
This approach also means you can back up your data with a simple cp command or sync it with Dropbox. No vendor lock-in, no proprietary format. Want to switch tools? Just point the new app at your folder. The data remains yours, portable and readable by anything that understands JSON. This method fosters a future-proof architecture: as new tools emerge, they can easily adopt the same format without needing special adapters or conversions, ensuring longevity and interoperability of your data ecosystem.
Atomic Writes and Conflict-Free Data Management
Writing files safely is crucial. Threlmark uses atomic writes—write to a temp file, then rename it—so partial updates can’t corrupt data. Learn more about atomic operations and data safety. Imagine editing a task and saving it. The system first saves the change to a temporary file, then swaps it in place. If your laptop crashes mid-save, you’re still safe with either the old or new file.
This technique is vital because it prevents data corruption during unexpected failures, ensuring that each write operation either completes fully or not at all. It also simplifies conflict resolution: when multiple tools attempt to modify the same file, the atomic operation guarantees that only one version is ultimately saved, avoiding inconsistent states. This approach shifts the complexity from managing locks to designing for idempotency and resilience. It means you can safely automate updates or run multiple processes concurrently without risking data loss or corruption, which is essential for maintaining trust in a decentralized, file-based system.
File Per Item and the Self-Healing Board
Instead of one giant roadmap file, Threlmark stores each card as an individual JSON file. The project’s board is a list of IDs stored separately in board.json. When the system reads the board, it cross-checks with actual files in items/. Missing files are automatically cleaned up, so the board always reflects current data.
This design ensures robustness by decoupling individual item data from the overarching project view. If a file is accidentally deleted or corrupted, the system can detect the inconsistency during the next read cycle and automatically remove references to missing items. This self-healing property reduces manual maintenance and prevents stale or broken data from propagating through the system. It’s akin to a jigsaw puzzle that dynamically re-aligns itself, maintaining the integrity of the entire picture without external intervention. Such resilience is crucial in environments where data may be modified outside the main application or where multiple tools interact with the same dataset.
Open, Portable, and Interoperable Data — Why That Matters
Threlmark’s files are plain JSON, making the data easy to inspect, edit, and share. You can open a card in any text editor, diff changes with git diff, or sync the entire folder with Dropbox. This openness reduces lock-in and invites integrations.
Beyond convenience, this openness has profound implications: it democratizes data access, allowing anyone to understand, modify, or migrate data without proprietary tools. This fosters innovation, collaboration, and long-term sustainability. If a new AI tool or workflow emerges, it can simply read or write these JSON files without needing special APIs or vendor support. The tradeoff is that while open formats promote flexibility, they require disciplined management to prevent schema drift or inconsistency. But overall, this approach ensures that your data remains accessible and adaptable as your needs evolve, making your system future-proof and resilient to vendor lock-in.
How Threlmark Supports External Tools and AI Agents
Threlmark’s file-based architecture isn’t just for humans. It’s designed for AI agents, scripts, and external tools to participate seamlessly. They can read the current state, add suggestions, or mark work as done by simply modifying files in the right folders.
For example, an AI agent could scan Threlmark’s GitHub repo, identify a high-priority task, and move it to the “done” folder. All of this happens without special APIs or permissions—just file operations. This openness enables automation at the system level, reducing friction for integration and allowing a diverse ecosystem of tools to operate on the same data without complex interfaces. It empowers users to extend their workflows in ways that traditional database-driven systems often cannot support, making the architecture more adaptable and resilient.
Practical Tips for Building Your Own Local-First System
- Use atomic write patterns to keep data safe.
- Break your data into small, independent files.
- Maintain separate files for state, config, and metadata.
- Design your file structure as a contract—tools should agree on location and format.
- Implement self-healing logic to reconcile inconsistencies on read.
Frequently Asked Questions
How does Threlmark handle conflicts when multiple tools edit the same task?
Threlmark uses atomic, lock-free file writes, which naturally prevent corruption. For conflicts, it relies on versioning and merge strategies—like merging JSON patches—so no data gets lost. This makes multi-tool editing safe and predictable.
Can I sync Threlmark data across devices without a server?
Yes, because all data lives in plain files, you can sync folders via Dropbox, Syncthing, or other file sync tools. When you open Threlmark on another device, it reads the same files, making multi-device workflows seamless.
Is local-first architecture suitable for collaborative teams?
It can be, especially with conflict resolution and merge strategies in place. But it’s best for teams that value control and offline access. For real-time collaboration, you might combine local-first with peer-to-peer sync or conflict-aware systems.
What are the main challenges with a file-based system like Threlmark?
The key issues are managing sync conflicts and schema evolution. However, with careful design—atomic writes, self-healing logic, and clear contracts—you can build a resilient system that scales well without a database.
Conclusion
Threlmark’s architecture proves that the simplest idea—disk as the contract—can be revolutionary. It’s a reminder that reliable, flexible systems don’t need complicated databases or cloud lock-ins. Your data, on your disk, is more powerful than you think.
Next time you build or rethink a tool, ask yourself: can I make the disk the single source of truth? The results might just surprise you—more control, more resilience, and more freedom.
