Disk Is the Contract: Inside Threlmark’s Local-First Architecture

📊 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 disk the ultimate data contract, using one file per item and atomic writes to improve resilience and interoperability. This approach challenges traditional database reliance and enhances offline capabilities.

Threlmark’s latest architecture treats the local disk as the definitive source of truth for data, eliminating reliance on traditional databases. This design simplifies synchronization, improves offline usability, and enhances data portability, making the system more resilient and transparent.

Threlmark’s approach centers on storing each data item in a separate file, with atomic write operations ensuring data integrity even during crashes or interruptions. The directory structure acts as a formal contract, providing clarity and interoperability for external tools and extensions. This system also employs self-healing mechanisms to reconstruct state from individual files, reducing conflicts and simplifying recovery. By avoiding a centralized database, Threlmark aims to create a faster, more flexible, and more transparent project management environment suitable for offline use and multi-tool workflows. However, this approach shifts complexity to managing file concurrency, merge conflicts, and directory structures, which requires careful design and handling.
Disk is the contract: inside Threlmark’s architecture — ThorstenMeyerAI.com
ThorstenMeyerAI.com
Threlmark · Technical Deep-Dive
Threlmark · architecture

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.

Next.js · TypeScript · JSON-on-disk · MIT · part 2 of the Threlmark series
01The core decision

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/ ├─ 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.

02Making files safe
SANDISK 1TB 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-1T00-G25

SANDISK 1TB 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-1T00-G25

Get NVMe solid state performance with up to 1050MB/s read and 1000MB/s write speeds in a portable, high-capacity…

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.

Pattern 1

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.

write .tmp-pid-rand fsync rename() over target
Pattern 2 · one file per item

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 payoff: an external tool never touches 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.
03Derived, never stored
Express Rip Free CD Ripper Software - Extract Audio in Perfect Digital Quality [PC Download]

Express Rip Free CD Ripper Software – Extract Audio in Perfect Digital Quality [PC Download]

Perfect quality CD digital audio extraction (ripping)

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.

priority = max(0, round(impact·3 + evidence·2 + fit·2effort·1.5))
a 5 / 5 / 5 / 4 card 29
work-item age
now − lane-entry time. Past threshold (dev 7d, ranked 21d, idea 60d) → stale.
cycle time
first DevelopmentDone. Derived from append-only transitions[].
throughput
items reaching Done per ISO week, 8-week window.
WIP
count per lane; over the cap shows 3 / 2 in red.
04The closed agent loop · press play
Amazon

JSON file editor for project management

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.

Ranked
Add price-drop alertsscore 31 · ready
Development
Handed off 🤖
Done
▶ preferred — REST
POST /api/projects/:id/
items/:itemId/report

Direct call. Applied immediately.

▶ fallback — filesystem
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
05Portfolio score & deployment
Local AI with VS Code: Mastering Private, Offline LLM Development: Run Open-Source Models Securely with Ollama, Continue, Llama.cpp, and Zero-Cloud Extensions – Keep Your Code and Data 100% Private

Local AI with VS Code: Mastering Private, Offline LLM Development: Run Open-Source Models Securely with Ollama, Continue, Llama.cpp, and Zero-Cloud Extensions – Keep Your Code and Data 100% Private

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 (/), 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.

score = priority · statusWeight (+ 0.1 · blockedCount · priority)
1.3
development
1.0
ranked
0.85
idea
0.15
done
Path 1

Static read-only demo

Seeded data, writes to localStorage. Try-before-you-clone.

Path 2

Personal Node instance

Password-gated, persistent backed-up THRELMARK_DATA_DIR.

Path 3

Multi-tenant SaaS

Add accounts + per-tenant isolation. A separate build.

The elegant part: the store interface 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.
ThorstenMeyerAI.com
Threlmark · open source (MIT) · github.com/MeyerThorsten/threlmark · part 2 of a series · file layout, formula, weights & agent-loop channels are Threlmark’s actual mechanics.

Impact of a Disk-Centric Data Model on Productivity

Making the disk the primary contract transforms how data is stored, accessed, and shared, offering increased resilience, portability, and transparency. It removes vendor lock-in, enabling users to edit files directly and integrate with external tools easily. This approach can lead to faster workflows and more reliable offline capabilities, especially important in environments with limited or unreliable internet connectivity. However, it also introduces challenges in managing concurrent edits and ensuring consistency across files, which Threlmark addresses with safety mechanisms like atomic writes and tolerant merging.

Evolution of Data Storage in Project Management Tools

Traditional project management systems rely on centralized databases, often cloud-hosted, which can create lock-in and complicate offline access. Recent developments in local-first architectures, inspired by principles from the broader software movement, emphasize storing data directly on local disks in plain files. Threlmark’s approach exemplifies this shift, prioritizing simplicity, resilience, and interoperability. This design aligns with trends toward decentralization and user control, and responds to needs for faster, more reliable offline workflows. Prior efforts in local-first systems have demonstrated the feasibility of treating disk as the source of truth, but Threlmark’s explicit directory structure and file-based approach aim for a practical, scalable implementation.

“Treat your disk as the ultimate source of truth—no need for a database or server.”

— Thorsten Meyer

Unresolved Challenges in File-Based Data Management

It is not yet clear how well Threlmark’s approach scales with very large data sets or complex concurrency scenarios. Managing many small files could introduce filesystem overhead, and manual intervention may be needed to resolve conflicts or manual edits. The robustness of self-healing mechanisms under extreme conditions remains to be fully tested, and integration with external tools might face consistency issues if not carefully managed.

Upcoming Developments and Testing Phases

Threlmark plans to expand testing of its file-based architecture in real-world scenarios, focusing on scalability, conflict resolution, and integration with external tools. Future updates may include enhanced conflict management, user-guided merge tools, and broader adoption of the directory structure as a formal data contract. Community feedback and case studies will shape ongoing improvements, aiming to demonstrate the approach’s viability at scale.

Key Questions

How does Threlmark ensure data consistency with multiple tools editing files?

Threlmark employs atomic writes and tolerant merging strategies to prevent corruption and handle concurrent edits, ensuring data remains consistent across tools.

Can I manually edit files without risking data loss?

Yes, the system is designed to allow manual edits, but users should follow the directory and file structure conventions to avoid conflicts or corruption.

What are the main advantages of a disk-based data contract?

It offers increased resilience, offline usability, transparency, and avoids vendor lock-in by making data accessible and portable through simple files.

What challenges does this architecture face?

Managing many small files, resolving conflicts during concurrent edits, and ensuring consistency across external integrations remain key challenges to address.

Is this approach suitable for all types of project management tools?

While ideal for tools prioritizing offline access, transparency, and extensibility, complex real-time collaboration scenarios may require additional conflict resolution mechanisms.

Source: ThorstenMeyerAI.com

You May Also Like

RSVP-and-payment co-host tool for supper club hosts

A new tool designed for private supper club hosts to streamline RSVP, dietary notes, and payments is entering initial testing, aiming to reduce no-shows and simplify event management.

Scholarship application organizer for school counselors

A new scholarship application organizer for high school counselors is being tested to streamline tracking student scholarship requirements, deadlines, and references.

IdeaClyst: The Engine That Decides What’s Worth Building

IdeaClyst is launched as an idea engine that transforms rough concepts into validated, targeted product initiatives by analyzing roadmaps and market opportunities.

The Deploy Button Became the Bottleneck — and Cloudflare Just Bought the Build Step

Cloudflare’s acquisition of VoidZero aims to streamline build-to-deploy workflows, addressing the shift in software development speeds driven by AI coding tools.