📊 Full opportunity report: Disk Is the Contract: Inside Threlmark’s Local-First Architecture on ThorstenMeyerAI.com — validation score, market gap, and execution plan.
TL;DR
Threlmark employs a unique local-first architecture where JSON files on disk serve as the system’s source of truth, enabling portability and external tool integration without a database. This approach allows for safe, atomic updates and self-healing project views, marking a significant shift in project management tools.
Threlmark has introduced a novel architecture where project data resides entirely in JSON files on disk, with no server or database involved, making the disk the definitive source of truth. This design choice enables seamless portability, external tool integration, and restartability, representing a significant shift in how project management systems can be built and operated.
The core architectural decision in Threlmark is that all data is stored as plain JSON files within a designated directory, defaulting to ~/.threlmark. The system treats these files as an immutable contract, with key files including a manifest (threlmark.json), a dependency graph (links.json), and individual project and item files stored under specific subfolders. Each project has its own folder with metadata, lane orderings, and individual cards, each represented by a separate JSON file in the items/ directory.
This file-based approach allows for multiple advantages: every artifact is inspectable and diffable, facilitating easy backups and migrations; it enables interoperability as any external tool can read and write these files; and it supports restartability since the process is stateless, relying solely on the files. Atomic writes are implemented by writing to temporary files and renaming, preventing corruption during crashes. Updates are performed via read-merge-write cycles that preserve data integrity and forward compatibility. The system’s design also includes self-healing features, where the in-memory view of lanes is reconciled with the actual files on disk each time it is read, ensuring consistency without locks or complex coordination.
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.
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.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.
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.
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.
Why Disk-Based Data Contracts Matter for Project Management
This approach fundamentally shifts how project data is managed, emphasizing portability, transparency, and resilience. You can learn more in Disk Is the Contract: Inside Threlmark’s Local-First Architecture. By avoiding reliance on centralized servers or databases, Threlmark enables users to maintain control over their data, easily migrate or backup projects, and integrate external tools without proprietary constraints. The design also simplifies collaboration, as external tools can participate directly by reading and modifying JSON files, fostering a more open ecosystem. Additionally, the atomic and tolerant update mechanisms reduce the risk of data corruption, making the system more robust against crashes or concurrent edits. Overall, this architecture could influence broader trends toward local-first, file-based project management solutions that prioritize user control and interoperability.
Python in Action: 60 Mini Projects to Automate Everything (Part 1): Practical CLI Tools, File Automation, and Data Cleaning with CSV, Excel, and JSON
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
Background and Evolution of Threlmark’s Architecture
Traditional project management tools often rely on centralized servers, databases, or cloud services, which can introduce lock-in, complicate backups, and hinder external integrations. Threlmark, developed by Thorsten Meyer, reimagines this paradigm by building a system that is entirely local-first. The idea emerged from the need for a portable, transparent, and resilient tool that can handle multi-project roadmaps without external dependencies.
The core concept of treating disk as the contract is inspired by battle-tested file operations, such as atomic writes and tolerant merge strategies, ensuring data integrity and forward compatibility. This is discussed in detail in Disk Is the Contract: Inside Threlmark’s Local-First Architecture. This approach contrasts with conventional systems that often embed data in proprietary formats or rely on server-side storage, making Threlmark a notable experiment in decentralizing project data management. Its development aligns with broader trends in open, interoperable software and the movement toward user-controlled data sovereignty.
“The on-disk layout is the API; it’s the contract that everything else depends on.”
— Thorsten Meyer
Unanswered Questions About Threlmark’s Scalability and Adoption
It is not yet clear how well this architecture performs with very large projects or numerous concurrent external tools. The approach’s scalability and real-world adoption in diverse workflows remain to be tested. Additionally, how existing project management practices will integrate or adapt to this file-based system is still uncertain, as is the extent of community support and tooling development around this model.
Next Steps for Threlmark’s Development and Ecosystem Growth
Threlmark plans to release further documentation and possibly open-source tools that facilitate integration with other systems. For an in-depth look at the system’s architecture, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture. User feedback and real-world testing will shape future enhancements, particularly around handling larger projects and more complex workflows. The developer also aims to foster an ecosystem of external tools that can participate in project updates through the shared file contract, potentially influencing broader adoption of local-first project management solutions.
Key Questions
How does Threlmark ensure data integrity without a database?
It uses atomic file writes by writing to temporary files and renaming them, preventing corruption during crashes. It also employs read-merge-write cycles that preserve data consistency and support forward compatibility.
Can external tools modify Threlmark data?
Yes, since all data is stored as plain JSON files, any external tool can read and modify them directly, enabling easy integration and collaboration.
What are the main advantages of this file-based approach?
It offers portability, inspectability, interoperability, restartability, and resilience against data corruption or loss, without reliance on proprietary servers or databases.
Is this approach suitable for large or complex projects?
It remains to be tested how well it scales with very large projects or high concurrency, and future updates will clarify its suitability for such use cases.
Source: ThorstenMeyerAI.com
