TL;DR
Threlmark’s architecture makes disk storage the single source of truth, enabling open, portable, and restartable project data. This design simplifies concurrency, external tool integration, and AI-driven workflows without relying on a central server or database.
Imagine managing your entire project roadmap from a folder full of plain JSON files. No servers, no cloud, just your disk. That’s the core idea behind Threlmark’s local-first architecture. It’s a radical shift from traditional tools that rely on centralized databases or services.
Instead, Threlmark makes your disk the ultimate authority. This approach empowers you to control, backup, and extend your project data with ease — no vendor lock-in, no complicated syncing. Want to see how a simple file can power complex AI interactions and multi-project management? Let’s explore. You can learn more about this approach in this article.
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.
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.
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.![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]
Intuitive interface of a conventional FTP client
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.
Real-World Android App Projects with Kotlin and Jetpack Compose: Build Production-Style Android Apps with Modern Architecture, API Integration, State Management, Local Data Storage, Practical Projects
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.
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.
DNS Security: Defending the Domain Name System
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 (
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.
Key Takeaways
- Treat your disk as the ultimate source of truth—files are your API and contract.
- Design folder structures that are inspectable, portable, and interoperable—think of each artifact as a stand-alone file.
- Use atomic writes and read-merge-write cycles to keep data consistent and forward-compatible.
- Break down data into one file per item to avoid race conditions and simplify external tool integrations.
- Leverage the simplicity of plain JSON files to power AI workflows and multi-project hubs seamlessly.
How ‘Disk Is the Contract’ Simplifies Data Management
At its core, Threlmark treats your disk as the single source of truth. Every piece of data—whether it’s a project, a task, or an AI suggestion—is a JSON file. This makes your data transparent, portable, and easy to manipulate.
For example, instead of a giant database, each task is a file like items/abc123.json. Updating a task involves rewriting that file atomically. You can back it up, sync it, or even edit it manually, and the system always stays consistent.
This approach sidesteps many headaches of server-based systems, like lock contention or vendor lock-in. Your project data lives in a folder, ready for any tool to read or write, anytime.
What Makes Threlmark’s File Structure a Contract You Can Trust
Threlmark’s folder layout isn’t just a directory tree—it’s a contract. At the root, you find threlmark.json and links.json, defining project relationships and dependencies. Each project then has its own folder with files like project.json and board.json.
Most importantly, each task gets its own file in items/. This ensures that updating one task doesn’t clobber others. The system self-heals on read, reconciling the board.json with actual task files, preventing inconsistencies.
This structure guarantees inspectability, portability, interoperability, and restartability. You can open any file, see what’s happening, or move your entire project elsewhere without losing a single piece of data.
Atomic Writes and Tolerant Merging Keep Your Data Safe
Two key patterns make file-based data safe and reliable. First, atomic writes: when saving a file, Threlmark writes to a temp file, then renames it. This guarantees no half-written files even if your system crashes.
Second, it uses read-merge-write cycles with defaults and normalization. When updating, it reads the current file, merges in changes, preserves essential fields like id and createdAt, and writes atomically. Unknown fields are preserved, making the system forward-compatible.
For example, if an external tool adds a new comment field, Threlmark won’t drop it during save. This flexibility keeps your data safe and your tools compatible over time.
One File Per Item: How It Eases Concurrency and Extensibility
Instead of a giant list of tasks, each task lives in its own JSON file. This design eliminates race conditions common in systems where multiple tools edit a shared list. You can update or drop a single task without locking or coordination.
For example, a developer working on a new feature can edit items/xyz789.json while another updates items/abc123.json. Because each file is atomic and independent, conflicts are rare. The board.json self-heals by reconciling the actual tasks present.
This pattern makes project management more flexible. External tools or AI agents can add, move, or resolve tasks without clashing or corrupting data. Learn more about this architecture at Rotten Panda.
How Threlmark’s Architecture Powers AI and Multi-Project Workflows
Threlmark isn’t just about static data. Its disk-based design enables AI agents to participate naturally. Since the data lives as plain files, AI tools can read, interpret, and modify tasks directly.
Suppose an AI assistant suggests a new task. It can drop a JSON file into suggestions/. Human review or automation scripts then process these suggestions, updating task files atomically. The entire process is transparent and restartable. More on AI workflows with this approach can be found at Micronomicon.
This setup supports multi-project hubs, where different teams or tools collaborate seamlessly. Because all data is portable, you can move your entire setup to another machine or integrate with other tools like Threlmark on GitHub or [Threlmark’s website](https://threlmark.com).
Practical Tips for Building Your Own Local-First System
- Start with a clear folder layout—define your files and their purpose.
- Use atomic write functions whenever saving data.
- Implement read-merge-write cycles with defaults and normalization.
- Keep each item in its own file to avoid race conditions.
- Design your self-healing mechanisms to reconcile state on each read.
If you want to see the full setup, check out the open-source project on GitHub. It shows how to structure your project to stay flexible, safe, and easy to extend. For more background, visit Biodivert.
Conclusion
Threlmark’s architecture proves that simplicity can be powerful. By making the disk the contract, you gain control, transparency, and flexibility. It’s a reminder that sometimes, the clearest path forward is also the simplest.
Next time you design a system, ask yourself: can I make the disk my single source of truth? If yes, you’re already a step closer to a resilient, open, and AI-friendly project setup.
