📊 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’s new system uses on-disk JSON files as the sole data source, enabling portable, restartable, and interoperable project management without a database. Its architecture emphasizes local-first principles and atomic file operations.
Threlmark has unveiled a new approach to project management architecture that relies solely on local JSON files, eliminating the need for databases or cloud storage. This system, called ‘Disk Is the Contract,’ emphasizes local-first principles, ensuring data portability, restartability, and interoperability. The design choice allows external tools and AI agents to interact directly with project data without server dependencies, marking a significant shift from traditional cloud-based project tools.
The core of Threlmark’s architecture is that all project data resides in plain JSON files stored on disk, with the on-disk layout serving as the API. Key files include a manifest (threlmark.json), a dependency graph (links.json), and individual project folders containing metadata, lane configurations, and one file per roadmap card in the ‘items/’ directory. This structure enables any external tool to access, modify, or extend data simply by reading and writing files, avoiding vendor lock-in.
To ensure data integrity, Threlmark employs atomic file writes—writing to a temporary file and then renaming it atomically—preventing corruption during crashes. Updates use a read-merge-write pattern, preserving data consistency and forward compatibility by retaining unknown fields. The system’s design supports concurrency, with each card stored as a separate file, eliminating race conditions common in list-based structures. The self-healing board logic dynamically reconciles the actual set of files with lane configurations, ensuring consistency without locks.
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.
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.
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 Phoenix Project: A Novel about IT, DevOps, and Helping Your Business Win
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 utility
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.
file-based project management system
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 File-Based, Local-First System
This architecture challenges the prevailing cloud-centric model of project management tools, emphasizing data ownership, portability, and resilience. By making the data portable and interoperable, Threlmark enables users to integrate with other tools, back up easily, and avoid vendor lock-in. The approach also simplifies collaboration across diverse environments, including offline or restricted networks, and facilitates automation by external agents without server dependencies. It represents a shift toward more transparent, user-controlled project data management.
Background on Threlmark’s Design Philosophy and Prior Work
Threlmark’s design builds on the idea that project roadmaps often fragment across multiple tools and formats, complicating prioritization and automation. The company previously developed a localStorage-based kanban tool called ‘Roadmap Lab,’ which scored feature cards and managed local data. The new system generalizes this concept into a multi-project hub, emphasizing open, portable data and flow management. The decision to use files as the source of truth stems from a desire to avoid server dependencies, ensuring that all data remains accessible, modifiable, and safe from data loss.
Prior to this, most project tools relied on centralized databases or cloud services, which pose risks of lock-in, data breaches, and dependency on network connectivity. Threlmark’s approach aims to empower users with full control over their project data, aligning with broader local-first and open data movements.
“The core idea is that the on-disk layout is the API, making data portable, restartable, and interoperable without a server or database.”
— Thorsten Meyer, Threlmark developer
Unclear Aspects of Implementation and Adoption
It is not yet clear how well this architecture scales with very large projects or teams, or how it performs under high concurrency scenarios. The long-term stability of the file-based approach in collaborative environments remains to be tested, especially when multiple external tools modify data simultaneously. Additionally, the user experience and ease of integration with existing workflows are still under development, and broader adoption will depend on community feedback and tooling support.
Next Steps for Threlmark and Community Engagement
Threlmark plans to release an early version for public testing, inviting feedback on usability and performance. Future developments include expanding external tool integrations, enhancing automation capabilities, and documenting best practices for managing large-scale projects with this architecture. The team will also monitor real-world usage to address scalability concerns and refine the system’s robustness in collaborative settings.
Key Questions
How does Threlmark ensure data safety without a database?
Threlmark employs atomic file writes—writing to a temporary file and then renaming it atomically—to prevent corruption. It also uses a read-merge-write pattern that preserves data integrity during updates, even with concurrent external modifications.
Can external tools modify Threlmark data without permission?
Yes, since the data is stored as plain files in a shared directory, any tool that can read and write these files can participate, allowing flexible collaboration without centralized permissions.
What are the advantages of using disk as the contract?
It makes data portable, restartable, and interoperable. Users can back up, migrate, and integrate with other tools easily, avoiding vendor lock-in and enabling offline or distributed workflows.
What challenges might arise from this architecture?
Scalability with very large projects and handling high concurrency are still untested. Ensuring consistent external modifications and user-friendly workflows are ongoing concerns.
Is this approach suitable for enterprise or team environments?
While promising for individual use and small teams, the system’s scalability and collaboration features need further development before it can be confidently recommended for large-scale enterprise deployment.
Source: ThorstenMeyerAI.com
