📊 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 uses a local-first architecture where JSON files on disk are the primary data source, enabling open, portable, and restartable project management without a database. This approach impacts how tools interact and how concurrency is handled.
Threlmark has adopted a unique local-first architecture where the filesystem, specifically plain JSON files stored on disk, serve as the definitive record for project data, eschewing traditional databases or cloud storage.
This design choice means that all project artifacts, including task cards, dependencies, and progress reports, are stored as individual JSON files within a designated directory, primarily ~/.threlmark. The core principle is that the filesystem itself becomes the API, ensuring data is portable, inspectable, and restartable.
Threlmark’s system is built on two key patterns: atomic file writes and read-merge-write updates. Atomic writes involve writing to temporary files and renaming them, preventing corruption during crashes. The read-merge-write approach allows safe, forward-compatible updates, where unknown keys are preserved and defaults are applied, ensuring compatibility with future tools.
Each project contains specific files such as project.json, board.json, and individual item files under items/. External tools can interact with these files directly, enabling seamless integration without a central server or database. This approach simplifies collaboration, backups, and migration, as everything is stored in plain, version-controllable files.
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.
JSON file management software
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.local-first project management tools
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.
atomic file write 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.
version control for JSON files
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.
Implications of a Disk-Contract Architecture
This approach fundamentally shifts how project data is managed and shared, emphasizing portability, transparency, and resilience. Developers and teams can easily back up, migrate, or modify project files without vendor lock-in. It also enables external tools and AI agents to participate directly by reading and writing these files, fostering a more open ecosystem. For a detailed look, see Disk Is the Contract.
By removing the dependency on centralized databases, Threlmark’s design reduces complexity, enhances data safety during crashes, and supports continuous workflows across multiple tools and environments. The approach aligns with a broader trend toward local-first, open data architectures in software development.
Evolution of Local-First Project Management
Traditional project management tools rely heavily on cloud-based servers and databases, which can introduce lock-in, complicate backups, and hinder interoperability. Threlmark’s design builds on prior efforts to decentralize data, but its key innovation is making the filesystem itself the source of truth.
Earlier tools often struggled with concurrency and data integrity; Threlmark addresses these with atomic file operations and self-healing read logic. Its architecture is similar to other local-first systems but distinct in its explicit contract: the disk layout is the API.
This development follows broader movements in software toward open, portable data formats and away from monolithic cloud solutions, reflecting a push for more resilient and interoperable tools.
“The core idea is simple: the on-disk layout is the API. This choice cascades into how concurrency, external tools, and AI agents interact with the data.”
— Thorsten Meyer, creator of Threlmark
Remaining Questions About Threlmark’s Disk-First Approach
While the architecture is clearly defined, it is not yet confirmed how well this approach scales with very large projects or high concurrency environments. The practical limits of file-based storage in complex workflows remain to be tested in real-world scenarios.
Additionally, the ease of integrating existing tools and ensuring consistent data synchronization across multiple environments is still being explored. How external tools handle conflicts or partial updates is also an open question.
Next Steps for Threlmark’s Development and Adoption
Thorsten Meyer plans to release further documentation and community examples demonstrating how external tools and AI agents can leverage the file-based system effectively. User feedback and real-world testing will guide future refinements, especially regarding scalability and multi-user workflows.
Additionally, efforts are underway to develop integrations with popular development environments and version control systems to streamline collaboration and backup processes, solidifying the disk as the definitive contract for project data.
Key Questions
How does Threlmark handle concurrent updates to project files?
Threlmark uses atomic file writes and self-healing read logic, which helps prevent conflicts and corruption during concurrent modifications. Each file is written atomically, and the system reconciles the project state on each read.
Can external tools modify project data without using Threlmark’s interface?
Yes, because the data is stored as plain JSON files in a known directory, external tools can read and write these files directly, enabling flexible integrations and automation.
What are the benefits of a disk-based contract over a cloud database?
It offers greater portability, transparency, and resilience. Data can be easily backed up, migrated, and inspected, without vendor lock-in or reliance on external servers.
Is this approach suitable for large or collaborative projects?
The approach is promising for small to medium projects and environments where control over the data is paramount. Its scalability and concurrency handling in large, multi-user projects are still being evaluated.
Source: ThorstenMeyerAI.com
