📊 Full opportunity report: Disk Is the Contract: Inside Threlmark’s Local-First Architecture on ThorstenMeyerAI.com — validation score, market gap, and execution plan.
Get business pricing on office and shipping supplies
- Business-only prices and quantity discounts
- Tax-exempt purchasing
- Multiple users, one account, clear invoices
TL;DR
Threlmark’s system design centers on treating local disk storage as the definitive source of truth, avoiding traditional databases. This approach simplifies synchronization, improves offline usability, and enhances data portability. The article examines how this architecture shapes system reliability and developer workflows.
Threlmark has adopted a novel local-first architecture where the disk serves as the definitive source of truth, eliminating the need for traditional databases or cloud servers. This design choice enhances offline capabilities, simplifies synchronization, and promotes data portability, making the system more resilient and transparent.
Threlmark’s approach treats each piece of data as a separate file stored directly on the disk, rather than managing data within a centralized database. This setup allows users to edit files manually or with external tools, with the system ensuring consistency through atomic writes and tolerant merging techniques. The directory structure itself acts as a formal contract, providing clear organization and facilitating interoperability. This architecture simplifies recovery from failures, reduces lock-in, and enables seamless offline use. However, managing many small files introduces filesystem overhead and requires careful conflict resolution strategies to prevent data corruption during concurrent edits. The system’s self-healing mechanisms help reconstruct state from individual files, maintaining data integrity even when external interference occurs.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.
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/<file>.json
→ ingested on readRobust even if the server’s down at finish time.
A small formula, and an honest hosting caveat
Because items are globally addressable (<projectId>/<itemId>), 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.
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.
Impacts on Data Resilience and Developer Workflows
By making disk storage the core contract, Threlmark enhances system resilience, enabling offline operation and reducing dependency on centralized servers. This approach also simplifies data recovery and promotes interoperability with external tools, offering a more transparent and flexible workflow for users and developers. However, it shifts complexity toward managing file integrity and conflict resolution, which requires careful design. Overall, this architecture could influence future development of decentralized, offline-capable tools, emphasizing simplicity and data portability.external hard drive for data backup
As an affiliate, we earn on qualifying purchases.
As an affiliate, we earn on qualifying purchases.
Evolution of Local-First Data Architectures
Traditional project management tools rely on centralized databases or cloud services, which can introduce lock-in and limit offline capabilities. Recent trends in local-first design advocate for storing data directly on user devices, often using JSON files or similar formats. Threlmark’s approach builds on these principles, emphasizing a file-per-item model combined with atomic writes and directory-based data contracts. This design aligns with broader movements toward resilient, offline-first applications that prioritize user control and data portability. Prior implementations in tools like Logseq and Obsidian demonstrate the viability of local-first architectures, but Threlmark’s explicit focus on treating the disk as the contract offers a new perspective on system simplicity and transparency.“Treating the disk as the contract simplifies synchronization and makes data more portable and resilient, especially in offline scenarios.”
— Thorsten Meyer, Threlmark developer
As an affiliate, we earn on qualifying purchases.
Unresolved Challenges in Conflict Resolution
While Threlmark employs atomic writes and tolerant merging to safeguard data, the specifics of conflict resolution during simultaneous external edits remain under development. It is not yet clear how the system handles complex merge conflicts or manual manual interventions in the directory structure, especially in multi-tool environments.
As an affiliate, we earn on qualifying purchases.
Upcoming Improvements and Community Adoption
Developers plan to refine conflict resolution mechanisms, improve user-facing tools for manual merge handling, and expand interoperability with external applications. Community feedback and real-world testing will shape future updates, with potential for broader adoption of the disk-as-contract paradigm in offline-first systems.
As an affiliate, we earn on qualifying purchases.
Key Questions
How does Threlmark ensure data consistency with multiple tools editing files?
Threlmark uses atomic writes and tolerant merging techniques to prevent corruption and handle concurrent edits, but the detailed conflict resolution strategies are still being refined.
Can I manually edit data files without breaking the system?
Yes, the directory structure is transparent, and manual edits are supported, provided they follow the expected format and are done carefully to avoid conflicts.
What are the main benefits of treating disk as the data contract?
This approach enhances offline usability, simplifies data recovery, reduces vendor lock-in, and improves data portability across tools and platforms.
What challenges might arise from managing many small files?
Filesystem overhead and complexity in maintaining relationships between files can pose challenges, requiring careful directory and update management.
Is this architecture suitable for large-scale or enterprise applications?
While promising for personal and small-team tools, scalability and conflict resolution complexities need further evaluation before applying to large-scale systems.
Source: ThorstenMeyerAI.com
Columbus Day / Indigenous Peoples' Day Picks
long weekend sales
As an affiliate, we earn on qualifying purchases.
