📊 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 employs a unique local-first architecture where disk-stored JSON files serve as the system’s core. This approach eliminates the need for servers, enhances portability, and simplifies integration with external tools and AI agents.
Threlmark’s core architectural innovation is that it treats disk-based JSON files as the definitive contract for all project data, eliminating the need for a server or cloud database. This design enables external tools and AI agents to interact directly with project artifacts, ensuring portability and resilience.
Threlmark operates as a Next.js app that manages project data through a structured directory of JSON files stored locally, specifically in the ~/.threlmark directory by default. The system’s key decision is that the files themselves are the source of truth, not a remote database or server, which allows for straightforward inspection, backup, and migration.
The directory structure includes a manifest (threlmark.json), a dependency graph (links.json), and individual folders for each project, each containing files for metadata, lane configurations, and one JSON file per roadmap card. Shared cards and archived projects are also stored within this structure, ensuring everything remains accessible and portable. This approach supports interoperability across tools and prevents lock-in, as any application can read or write these files directly.
The system employs atomic file writes—writing to a temporary file before renaming—to prevent corruption during crashes. Updates are performed via read-merge-write cycles that preserve data consistency and forward compatibility, allowing newer tools to add fields without breaking existing ones. The self-healing read process ensures that the lane ordering always reflects the current set of cards, automatically reconciling discrepancies.
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]
- User-Friendly FTP Interface: Intuitive FTP client interface
- Reliable Site Management: Easy and dependable FTP site maintenance
- Automation & Sync: FTP automation and synchronization
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 Disk as the Single Source of Truth Matters
This architecture fundamentally shifts how project data is managed, emphasizing portability, transparency, and resilience. By avoiding centralized databases, Threlmark allows users to back up, migrate, and integrate their project data with minimal friction. It also enables external tools, including AI agents, to participate without permission barriers, fostering a more open and flexible ecosystem. This approach could influence future project management tools by demonstrating the viability of a purely file-based, local-first design that maintains data integrity and extensibility.
The Evolution of Local-First and File-Based Systems
Traditional project management tools rely heavily on cloud servers and databases, which can introduce lock-in, reduce transparency, and complicate backups. For more on this, see Disk Is the Contract: Inside Threlmark’s Local-First Architecture. Threlmark’s approach draws from earlier local-first philosophies and battle-tested file management practices, emphasizing that the source of truth can and should be stored on disk. This design aligns with broader trends toward decentralization and interoperability, offering a practical alternative to cloud-dependent systems.
“The core idea is that the files are the record, and everything else is just a view or a layer on top. This makes the system portable, restartable, and open to external tools.”
— Thorsten Meyer
Unanswered Questions About Threlmark’s Architecture
It remains unclear how well this architecture scales with very large projects or teams, or how it integrates with existing enterprise workflows. Additionally, the user experience implications of managing numerous JSON files and potential conflicts between external tools are still under exploration. Details about performance benchmarks and real-world adoption are also pending.
Next Steps for Threlmark’s Development and Adoption
Thorsten Meyer plans to gather user feedback and observe the system’s performance in diverse environments. Future updates may include enhanced tooling for managing large sets of files, improved conflict resolution, and integrations with popular IDEs or project management platforms. Broader community engagement could accelerate adoption and reveal new use cases.
Key Questions
How does Threlmark handle concurrent edits from multiple external tools?
Threlmark employs atomic file writes and a read-merge-write process that helps prevent conflicts. The self-healing lane reconciliation also ensures consistency, but detailed conflict resolution strategies are still being refined.
Can Threlmark work with existing cloud-based project management tools?
Currently, Threlmark is designed around local disk storage, but it can export or import data via JSON files, allowing integration with other systems. Direct cloud synchronization is not a core feature yet.
Is the disk-based approach suitable for large teams or enterprise use?
While promising for individual or small-team workflows, scalability and collaboration features for large teams are still under evaluation. The architecture’s reliance on file management may require additional tooling for enterprise environments.
What are the security implications of storing project data as JSON files?
Since data is stored locally, security depends on the user’s environment. No server-side vulnerabilities exist, but proper file permissions and backups are recommended.
Will Threlmark support real-time collaboration or version control?
Real-time collaboration is not yet implemented, but the file-based approach naturally supports version control systems like Git, enabling history tracking and branching.
Source: ThorstenMeyerAI.com
