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 approach uses local disk as the single source of truth, replacing traditional databases. This design improves offline capability, data portability, and system transparency. The development signals a shift towards file-based, resilient project management tools.
Threlmark’s latest architecture treats local disk storage as the definitive source of truth for project data, eliminating the need for traditional databases or cloud servers. This approach is detailed in the original analysis. This approach enhances offline usability, simplifies data synchronization, and improves data portability, making the system more transparent and resilient.
Threlmark’s system operates directly on plain files stored on the user’s disk, with each item, such as project cards, stored in individual files. This design avoids vendor lock-in and allows users to edit data with simple tools like text editors, while the system manages synchronization and consistency through atomic file operations and tolerant merging techniques.
The directory structure itself acts as a formal contract, dictating how data is organized and accessed. This transparency enables external tools to integrate seamlessly by reading and writing files directly, fostering interoperability without proprietary formats or APIs.
To ensure data safety, Threlmark employs atomic writes—writing to temporary files before renaming—and merge strategies that tolerate missing or unknown data, preventing corruption even during concurrent edits or unexpected failures. This architecture shifts complexity from centralized databases to careful file management and conflict resolution, aiming for a resilient, offline-capable system.
<!– DEPLOY: swap this Google Fonts for self-hosted base64 woff2 (German GDPR) –>
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.
├─ threlmark.json # manifest
├─ links.json # dependency graph
├─ projects//
│ ├─ project.json # meta + wipLimits
│ ├─ board.json # lane ordering
│ ├─ items/.json # ONE card per file ← source of truth
│ ├─ suggestions/ # the Inbox (drop-zone)
│ ├─ handoffs/ # recorded agent handoffs
│ ├─ reports/ # agent report drop-zone
│ └─ ROADMAP.md # human-readable mirror
├─ shared/items/ # cards many projects ref
└─ archive/ # archived, still readable
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.
→
fsync
→
rename() over target
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.
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.
→
29
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/report
Direct call. Applied immediately.
drop reports/.json
→ ingested on read
Robust even if the server’s down at finish time.
claude done: price-drop alerts shipped · typecheck + lint + build passed — card moved to Done
A small formula, and an honest hosting caveat
Because items are globally addressable (/), the Portfolio ranks everything together by a status-weighted score — finishing beats starting, blockers get a boost.
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.
Implications of Disk as the Single Data Source
This approach fundamentally changes how data persistence and collaboration are handled in project management tools. For a deeper understanding, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture. By making disk storage the contract, Threlmark offers increased data transparency, portability, and resilience against connection failures. It reduces vendor lock-in and simplifies recovery from errors, which is especially valuable for offline workflows. However, it also introduces new challenges around managing numerous small files and conflict resolution, requiring careful design and handling of concurrency issues.
Evolution of Local-First and File-Based Systems
Traditional project management tools rely heavily on centralized databases and cloud services, which can limit offline access and create vendor lock-in. This shift towards local-first systems is part of a broader movement toward file-based, decentralized data management. The concept of local-first architecture, emphasizing local storage as the primary data source, has gained traction over recent years, driven by the need for resilient, portable, and privacy-conscious tools. Threlmark’s implementation exemplifies this trend by treating each data item as a separate file, with directory structures serving as explicit data contracts, aligning with broader movements toward file-based, decentralized data management.
“Treating the disk as the contract simplifies synchronization and makes data more portable and transparent.”
— Thorsten Meyer, Threlmark developer
Unresolved Challenges and Risks of File-Based Architecture
While Threlmark’s approach offers clear benefits, it remains to be seen how well it scales with complex projects or large data sets. Managing numerous small files can introduce filesystem overhead and performance issues. Additionally, conflict resolution and manual intervention may become necessary in multi-user scenarios, and the system’s robustness against corruption or manual errors is still being evaluated.
Next Steps for Adoption and Development
Threlmark plans to refine its conflict resolution algorithms and expand tooling support for manual and automated data management. Future updates may include enhanced conflict detection, versioning, and integration with other tools, aiming to demonstrate the scalability and reliability of the local-first, file-based approach in broader use cases.
Key Questions
How does Threlmark ensure data consistency with file-based storage?
Threlmark uses atomic write operations—writing to temporary files before renaming—and tolerant merge strategies to prevent corruption and manage concurrent edits effectively.
Can external tools modify Threlmark data safely?
Yes, the explicit directory structure acts as a contract, allowing external tools to read and write files directly, provided they follow the agreed format and handle conflicts properly.
What are the main advantages of treating disk as the contract?
It enhances data portability, offline usability, transparency, and reduces vendor lock-in, making systems more resilient and easier to inspect or modify manually.
What are the potential downsides of this approach?
Managing many small files can lead to filesystem overhead, and conflict resolution in multi-user environments can be complex, requiring careful system design.
Source: ThorstenMeyerAI.com