📊 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 system design makes the local disk the primary source of truth, avoiding traditional databases. This approach improves offline capabilities, simplifies data sync, and enhances portability, all while maintaining system transparency.
Threlmark’s new approach treats local disk storage as the definitive source of truth for data, eliminating the need for traditional databases or cloud servers. This design is detailed in the original analysis. This design choice aims to simplify synchronization, improve offline usability, and make data portable across tools, marking a significant shift in how project management and data systems are conceptualized.
Threlmark’s architecture centers on storing each data item as a separate file on the local disk, with atomic write operations to prevent corruption and race conditions. The directory structure itself acts as a formal contract, defining how data is organized and accessed, enabling external tools to read and write files directly without proprietary formats or permissions.
The system employs safety mechanisms such as atomic file writes—writing to a temporary file before renaming it—and tolerant merging, which allows it to handle missing or unknown data gracefully. This approach ensures data integrity even during concurrent edits or external modifications.
By using one file per item, Threlmark reduces conflicts and simplifies recovery, as the system can reconstruct the overall state from individual files if needed. The directory layout explicitly defines the data contract, fostering transparency and interoperability, though it requires careful management to prevent filesystem overhead and maintain consistency.
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.
SANDISK 2TB Extreme Portable SSD (Old Model) – Up to 1050MB/s, USB-C, USB 3.2 Gen 2, IP65 Water and Dust Resistance, Updated Firmware – External Solid State Drive – SDSSDE61-2T00-G25
- High-Speed NVMe Performance: Up to 1050MB/s read, 1000MB/s write
- Durable and Water-Resistant: IP65 water and dust resistance, 3-meter drop protection
- Portable and Secure: Includes carabiner loop for easy attachment
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 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 Treating Disk as the Single Source of Truth Matters
This approach fundamentally changes data management by removing reliance on centralized databases, making systems more resilient, portable, and offline-capable. It reduces vendor lock-in and allows users to manipulate data directly with simple tools like text editors, which can be especially valuable in collaborative or disconnected environments. However, it shifts complexity toward ensuring file safety, conflict resolution, and maintaining clear directory structures, which can be challenging but ultimately results in more transparent and flexible systems.
Background and Development of Local-First Data Architectures
Traditional data systems rely heavily on centralized databases or cloud services, which can introduce lock-in, reduce transparency, and limit offline functionality. You can learn more about local-first architectures in this overview. Recent trends in local-first architecture advocate storing data directly on local disks, emphasizing resilience, portability, and user control. Threlmark’s approach builds on these principles, emphasizing a file-based model where each data entity is a separate file, with safety and consistency mechanisms integrated into the design.
This development aligns with broader movements toward decentralized data management, aiming to empower users and improve system robustness by treating the disk as the ultimate authority for data integrity and access. For a deeper dive, see this internal resource.
“Treating the disk as the contract for data simplifies synchronization and enhances offline usability, making the system more resilient and transparent.”
— Thorsten Meyer, Threlmark Developer
Unresolved Challenges and Future Considerations
It is not yet clear how Threlmark’s system will handle complex merge conflicts or large-scale data sets in practice. The effectiveness of the directory structure as a strict contract depends on user adherence and external tool compliance, which could introduce inconsistencies. Additionally, managing many small files might impact filesystem performance, especially on less capable devices. The scalability and robustness of self-healing mechanisms in diverse environments remain to be tested extensively.
Next Steps for Threlmark’s Local-First System Development
Threlmark plans to further refine its conflict resolution strategies and optimize performance for large projects. Future updates may include enhanced tooling for managing directory structures, improved conflict detection, and broader integration with external tools. User feedback and real-world testing will likely shape ongoing improvements, with the goal of making the system more scalable and user-friendly.
Key Questions
How does Threlmark prevent data corruption during simultaneous edits?
Threlmark employs atomic write operations—writing data to a temporary file before renaming it over the original—to prevent corruption during concurrent edits or crashes.
Can I manually edit data files in Threlmark?
Yes, the directory structure and individual files are transparent and accessible, allowing manual editing if needed, but users should understand the data contract to avoid inconsistencies.
What are the tradeoffs of using one file per item?
While this reduces conflicts and simplifies recovery, it can introduce filesystem overhead and complexity in maintaining relationships between files, especially in large projects.
Will this approach work with external tools or integrations?
Yes, the explicit directory structure acts as a data contract, enabling external tools to read and write files directly, provided they adhere to the established format.
Source: ThorstenMeyerAI.com
