📊 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 introduces a local-first architecture where project data is stored as JSON files on disk, making the system portable, inspectable, and serverless. This design challenges traditional database reliance and enables seamless integration with external tools and AI agents.
Threlmark has unveiled a new architectural approach that treats on-disk JSON files as the definitive contract for project data, eliminating the need for a centralized server or database. This design allows external tools, AI agents, and other applications to interact directly with project data stored locally, ensuring portability, inspectability, and restartability. The system’s core decision—making the disk the source of truth—challenges conventional database-centric project management tools and offers a new paradigm for local-first, open, and interoperable workflows.
Threlmark’s architecture is built around the principle that project data is stored entirely as JSON files on disk, specifically within a directory structure rooted at ~/.threlmark. See Disk Is the Contract: Inside Threlmark’s Local-First Architecture for a detailed explanation. The key files include a manifest (threlmark.json), a dependency graph (links.json), project metadata (project.json), lane configurations (board.json), and individual roadmap cards (items/
The system emphasizes data integrity and safety through atomic file writes, where updates are first written to temporary files and then renamed atomically. It also employs a read-merge-write pattern that preserves unknown fields, making the data contract forward-compatible. The design ensures that each project card is stored in its own file, allowing for collision-free concurrent updates and easy external modification. The board self-heals on read by reconciling the actual files with the lane ordering, ensuring consistency even when external changes occur.
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.
![Free Fling File Transfer Software for Windows [PC Download]](https://m.media-amazon.com/images/I/41Vq6ZqHfjL._SL500_.jpg)
Free Fling File Transfer Software for Windows [PC Download]
Intuitive interface of a conventional FTP client
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.
Project Planner: Management Notebooks Organizer & Work Log Book Tracker With Checklist Brainstorming for Entrepreneurs, Managers & Small Business Owners
TURN YOUR IDEAS INTO REALITY: Unleash your creativity with this unique planning notebook, consisting of 224 pages divided…
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.
Real-World Android App Projects with Kotlin and Jetpack Compose: Build Production-Style Android Apps with Modern Architecture, API Integration, State Management, Local Data Storage, Practical Projects
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.
Video Systems in an IT Environment: The Basics of Professional Networked Media and File-based Workflows
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 Disk as the Single Source of Truth
This approach fundamentally shifts how project data is managed, offering a portable and interoperable alternative to traditional databases. By making files inspectable, version-controlled, and easily backed up, Threlmark enables users to maintain control over their data without vendor lock-in. It also facilitates integration with external tools, AI agents, and automation workflows, potentially reducing complexity and increasing flexibility in project management.
For developers and teams prioritizing local-first workflows, this architecture provides a resilient, restartable system that remains consistent and safe even in the face of crashes or external edits. It empowers users to collaborate across tools and platforms without relying on centralized infrastructure, aligning with broader trends toward open, decentralized software systems.
Background and Evolution of Disk-Based Project Data
Traditional project management tools often rely on cloud servers and centralized databases, which can introduce vendor lock-in, reduce transparency, and complicate data portability. Threlmark’s previous iterations focused on local storage but lacked a formalized contract that ensured interoperability and safety. The recent shift to treating disk as the contract builds on prior work in file-based state management, emphasizing atomic operations and tolerant merging to prevent corruption and ensure data integrity. For an in-depth look, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture.
This development aligns with broader trends in local-first software, where users seek control over their data and tools aim to be more interoperable. Learn more in the article Disk Is the Contract: Inside Threlmark’s Local-First Architecture. The design also responds to challenges in multi-project roadmapping, providing a unified, portable format that can be easily extended or integrated with AI and automation tools.
“The core idea is simple: the on-disk layout is the API. This choice cascades into how concurrency is handled, how external tools participate, and how AI agents can automate progress without a server.”
— Thorsten Meyer
Unresolved Questions About Scalability and External Collaboration
It is not yet clear how well this architecture scales with very large projects or numerous concurrent external tools. While atomic file operations are robust for small to medium setups, performance implications for extensive datasets remain to be tested. Additionally, how this approach handles multi-user collaboration or conflict resolution in shared environments is still under exploration. The system’s effectiveness in diverse real-world workflows will become clearer with broader adoption and testing.
Next Steps for Adoption and Testing of Disk-Based Contracts
Threlmark plans to release detailed documentation and open-source the system, inviting community testing and feedback. Future updates may include enhanced support for multi-user environments, improved conflict resolution mechanisms, and integrations with popular external tools. Observers should watch for real-world case studies and performance benchmarks that will demonstrate the system’s robustness at scale.
Key Questions
How does Threlmark ensure data safety without a database?
It employs atomic file writes—writing to temporary files before renaming—and tolerant read-merge-write cycles that preserve unknown fields, preventing corruption and ensuring forward compatibility.
Can external tools modify project data directly?
Yes, since data is stored as JSON files in a shared directory, any tool that reads and writes files can participate without special permissions.
What are the limitations of this disk-based approach?
Potential challenges include scalability for very large projects and handling multi-user collaboration with conflict resolution, which are still under evaluation.
Will this system support multi-user workflows?
Support for multi-user environments is planned but not yet implemented; future versions may include conflict detection and resolution features.
Source: ThorstenMeyerAI.com
