Imagine a project management tool that’s so lightweight, it runs entirely on your local machine—no cloud, no complicated database. It’s fast, resilient, and endlessly flexible. That’s the promise of Threlmark’s approach, which centers on a simple yet radical idea: the disk is the contract.

By storing every piece of data as plain JSON files on your disk, Threlmark sidesteps the mess of traditional databases. This might sound old-school, but it’s a powerful move for building apps that are truly offline-first, easily portable, and highly transparent. Today, I’ll walk you through how this works, why it matters, and what it means for any app that wants to be resilient, collaborative, and straightforward.

Key Takeaways

• Treat your disk as the single source of truth by storing data in plain JSON files—no database needed.
• Design your app to read, write, and reconcile files atomically to prevent corruption and race conditions.
• Use a folder structure that mirrors your app’s components—each item as a separate file for simplicity and concurrency.
• Leverage the human-readable format for easy debugging, backups, and migrations. It’s transparency in its purest form.
• Plan for conflict resolution and schema evolution upfront—this keeps your system flexible as it grows.

Why Threlmark’s ‘disk is the contract’ changes everything

At the heart of Threlmark’s design is a simple truth: the files on your disk aren’t just storage—they’re the source of truth. Unlike traditional apps that rely on a server or database, Threlmark treats the filesystem as the API.

Imagine walking into a shared workspace with a single, well-organized folder. Inside, each project, task, or card is a separate JSON file. This setup makes the data transparent and easy to inspect. Want to see all your tasks? Just open the items/ folder and read the files. Want to modify something? Edit the JSON directly or with a script. It’s that straightforward.

This approach simplifies the architecture, reduces dependencies, and makes the data portable. You can back up, sync, or migrate everything with simple filesystem commands—no middleman required. And because the files are human-readable, debugging and collaboration become a breeze.

How the JSON-on-disk layout works in practice

Let’s get concrete. Threlmark’s root directory contains a few key files and folders, as discussed in this article:

• threlmark.json: the main manifest describing the system.
• links.json: the dependency graph between projects and items.
• items/: one JSON file per roadmap card, like items/abc123.json.
• board.json: the lane ordering for each project’s kanban board.
• suggestions/: a folder for external inputs, like new ideas or suggestions.
• handoffs/: recorded handoffs for AI agents or external tools.

This structure isn’t just tidy—it’s a contract, making every piece of data accessible, versionable, and portable. Want to update a card? Just overwrite its JSON file atomically. Need to see what’s next? Read the board.json, which is always reconciled with the actual items.

Because each item lives in its own file, multiple tools can work on the same data simultaneously without clobbering each other. This design sidesteps many concurrency headaches of traditional databases. Learn more about this architecture.

Why avoiding a database makes your app smarter

Choosing JSON files over a database might seem counterintuitive in a world obsessed with SQL and NoSQL. But it’s a deliberate move to simplify architecture and empower developers.

Without a database, you avoid vendor lock-in, complex migrations, and hidden layers. Instead, your data is plain text—easy to back up, move, and understand. Want to sync your data across devices? Just copy the folder. Want to inspect how your app makes decisions? Open the JSON files and see exactly what it stored.

This approach also reduces the attack surface. No server means fewer points of failure. Plus, it’s faster for local operations—reading a file beats querying a remote database over a slow connection every time. Read more about this.

For example, Threlmark’s architecture lets a developer modify a task directly in the file system, then see the change reflected immediately, even if the app isn’t running. That’s a game-changer for local-first workflows.

Sync and collaboration? Here’s how Threlmark keeps everyone on the same page

Syncing in a disk-based system might seem tricky—after all, files can get out of sync or overwritten. But Threlmark handles this elegantly by treating the filesystem as the single source of truth.

Changes are made locally by editing files. When syncing, the system compares file contents, detects differences, and applies conflict resolution rules. If two devices modify the same card offline, the last write wins, but the system can also be extended to smarter conflict handling.

External tools can participate by reading and writing JSON files directly, without special permissions or APIs. This openness means you can integrate with other apps, scripts, or AI agents easily.

For example, an AI agent might suggest a new task by dropping a JSON file into the suggestions folder. When the app scans this folder, it incorporates the new idea automatically. It’s a seamless, flexible collaboration model.

The tradeoffs: What you give up and what you gain

Using JSON files instead of a database isn’t magic. It comes with tradeoffs—some gains, some sacrifices.

**What you gain:**

• Ultimate transparency and inspectability
• Easy backups and migrations
• Reduced complexity and dependencies
• Offline resilience and speed

**What you give up:**

• Scalability beyond a single device (not suited for billions of records)
• Complex query capabilities (no SQL or indexes)
• Handling very large datasets efficiently

For smaller teams, solo projects, or edge devices, this tradeoff is often worth it. It’s about simplicity and control, not raw scale.

Real-world example: How Threlmark’s architecture handles schema evolution

Let’s say you want to add a new field to your task JSON—like a priority flag. In Threlmark, you simply update your code to handle the new field, and existing files remain readable because missing fields default to sane values.

For instance, older task files lack the priority key. When read, the system assigns a default. When saved, the new structure is written out, making migration smooth.

This forward compatibility means you can evolve your data model without breaking everything. It’s like adding a new gear to a bike—old files keep working, new files get the upgrade.

Many teams struggle with schema migrations in traditional databases. Here, it’s just about updating your code and letting the files adapt naturally.

Frequently Asked Questions

What does “disk is the contract” mean?

It means the filesystem and JSON files are the primary source of truth. The app reads and writes directly to these files, making the data transparent, portable, and easy to manage without a dedicated database.

How does syncing work in a local-first system like Threlmark?

Syncing compares file contents across devices, detects conflicts, and applies resolution rules. Because each item is a separate file, updates are atomic, and external tools can participate by reading and writing directly to the files.

Why use JSON files instead of a database?

JSON files are human-readable, easy to back up, and eliminate lock-in. They simplify architecture, reduce dependencies, and improve offline resilience—ideal for small teams, solo projects, or edge devices.

How does Threlmark handle schema changes?

Schema evolution is straightforward—just update your code to handle new fields with defaults. Old files remain compatible because missing data is filled with sane defaults, making migrations smooth.

Are there limits to this file-based approach?

Yes. It’s best suited for small to medium datasets. Handling billions of records or complex queries becomes impractical. It’s a tradeoff between simplicity and scale.

Conclusion

Threlmark’s approach proves that simplicity and control often beat complexity. By making the disk the contract, you gain total transparency, resilience, and portability. It’s a reminder that sometimes, the best architecture is the one that keeps everything right in front of you—literally on your disk.

Next time you think about building a new tool, ask yourself: do I need a database, or can I just use plain files? Your answer might just change everything.