Imagine working on your project without waiting for a server to respond. No cloud dependency. Just your disk, your files, and the freedom to work offline or online seamlessly.

That’s the core idea behind Threlmark’s architecture. It’s a bold shift from traditional client-server models, putting the disk front and center as the source of truth. This approach promises speed, resilience, and simplicity—if you’re willing to embrace some discipline around file structure and sync mechanics.

Key Takeaways

• Treat your disk as the single source of truth—your data lives in JSON files, making it transparent and portable.
• One file per item avoids race conditions and simplifies concurrency, even in multi-tool environments.
• Atomic writes ensure data durability and prevent corruption during crashes or interruptions.
• Forward-compatible JSON schemas allow seamless evolution without breaking older tools.
• Local-first architecture offers speed, resilience, and offline capability—ideal for distributed, dynamic workflows.

What does “disk is the contract” actually mean?

‘Disk is the contract’ means your data lives on your local disk, and that file system defines what’s true. Every change, every state, is a JSON file you can open, read, and modify directly.

Think of it like a shared notebook where every project, task, or idea lives in its own page. No middleman, no database—just a set of files that act as the single source of truth.

For example, Threlmark stores each card as a separate JSON file inside an ‘items’ folder. When you open your project, you’re reading and writing these files directly. It’s simple, transparent, and portable. You can learn more about local-first architectures.

Why choose local-first instead of traditional client-server?

Local-first software like Threlmark feels faster because it avoids round trips to a server. Your computer reads and writes directly to files, making interactions immediate and smooth.

Imagine editing a task list on your laptop and seeing instant updates without waiting for the cloud. That’s the power of local-first. Plus, you keep working during outages—your data remains accessible even if the internet drops.

For instance, Threlmark’s architecture lets you work offline on a plane, then sync changes later. It’s resilience in action, not just convenience.

How does Threlmark sync data across devices and handle conflicts?

Threlmark uses a layered approach for sync, built around files. Changes made on one device are tracked in individual JSON files, then merged or updated on others during sync.

When two devices edit the same card offline, conflicts are resolved through a merge strategy. The system preserves unknown keys, so no data is lost even if a newer version adds new fields.

For example, you might edit a task on your phone and your laptop offline. When you reconnect, Threlmark compares the JSON files, merges updates, and keeps everything consistent.

What does the JSON-on-disk data model look like?

The core of Threlmark is a set of neatly organized JSON files. Each project has a folder, with individual cards stored as separate files inside an ‘items’ directory.

For example, a card’s JSON might look like:

{"id": "123", "title": "Finish report", "status": "next", "createdAt": "2024-04-01T10:00:00Z", "updatedAt": "2024-04-02T15:00:00Z"}

This simple format makes it easy to inspect, diff, and migrate data, and any tool can read or write these files without special permissions.

How does Threlmark handle schema migrations and data evolution?

Schema changes are managed by updating the JSON format and ensuring older files remain readable. Threlmark’s design preserves unknown keys, so new fields can be added without breaking older tools. For more on this approach, see disk as the contract.

More importantly, this approach allows for flexible data evolution. When you introduce new fields or structures, older files still function because the system ignores unknown keys during parsing. This means you can incrementally upgrade your data and tools without disrupting existing projects.

For example, if you decide to add a ‘priority’ field to all cards, you can write a script that updates each JSON file without rewriting the entire dataset. This incremental migration reduces downtime and minimizes risk, enabling continuous improvement of your data model.

What are the benefits of a file-per-item approach?

Using one file per item avoids race conditions common with large JSON arrays. Each card can be updated independently, making concurrency safe and straightforward. This is a key benefit of file-per-item approach.

Imagine two different tools editing separate cards at once—no conflicts, no locks. Threlmark’s architecture also allows self-healing of the project board, which reconciles itself every time it’s read.

For example, updating a task doesn’t require reading and rewriting the entire roadmap; just the one card’s JSON file. This modular approach simplifies collaboration, reduces the chance of conflicts, and improves resilience against partial failures or corruption.

What tradeoffs come with a disk-based architecture?

While simplicity and portability are big wins, managing conflicts, migrations, and sync can get complex. You need discipline around file structure and conflict resolution strategies.

For example, if multiple users or tools modify files simultaneously without proper coordination, conflicts can escalate, leading to data inconsistency. Additionally, large projects with many files may slow down file operations or require more sophisticated indexing and synchronization tools.

Furthermore, this approach assumes users are comfortable with manual troubleshooting and understanding file-based workflows. It’s powerful but requires a disciplined mindset and good practices to avoid pitfalls that could compromise data integrity.

How to start implementing a local-first JSON system like Threlmark

1. Define a clear folder structure for your JSON files and metadata.
2. Use atomic write techniques: write to temp files, then rename, to prevent corruption.
3. Design your JSON schema to be forward-compatible, preserving unknown keys.
4. Implement a self-healing board that reconciles state on read.
5. Build or adopt a sync layer that compares files and merges changes.

For example, start with a simple folder of JSON cards, then add sync logic to handle offline edits and conflict resolution.

Frequently Asked Questions

What does “disk is the contract” actually mean?

It means your data is stored directly on your disk as JSON files, and these files define what’s true. No database, no cloud dependency—just files you can open, edit, and trust.

How does Threlmark sync data across devices?

Threlmark tracks changes in individual JSON files and compares them during sync. Conflicts are resolved through merging strategies that preserve unknown fields, ensuring consistency across devices.

Is JSON-on-disk a database?

Not exactly. It’s a simple, file-based persistence layer that acts like a lightweight database, but with the advantages of transparency, portability, and simplicity. It’s more like an event log in files than a traditional database.

How are schema migrations handled?

Schema updates are managed by scripts that modify existing JSON files or add new fields, all while preserving unknown keys for backward compatibility. This keeps your system flexible as it evolves.

What applications benefit most from this architecture?

Tools that need offline capability, fast local interactions, and portability—like task managers, note-taking apps, or collaborative design tools—are perfect fits for this approach.

Conclusion

Threlmark’s approach turns the familiar disk into a powerful contract—where your project data is always accessible, always under your control. It shifts the focus from server uptime to local discipline, simplicity, and portability.

Next time you think about data storage, imagine your files as the true record—clear, inspectable, and ready to move at a moment’s notice. That’s the real promise of the disk-first revolution.