Skip to content

why-flat-json-files.md

Latest commit

 

History

History
34 lines (23 loc) · 1.53 KB

why-flat-json-files.md

File metadata and controls

34 lines (23 loc) · 1.53 KB
Raw
title Why Flat JSON Files
description The case for the filesystem as the datastore
audience architect

Wiki Home › Decisions

Why Flat JSON Files

The datastore is a folder of JSON files, not a database. For this project that is a feature, not a shortcut.

The forces

  • The product is sample data for learners — datasets are small, read-heavy, and valuable precisely because they're inspectable
  • Contributions arrive as pull requests — a JSON file is diffable, reviewable, and mergeable; database rows are none of those
  • Data must be resettable to a known baseline — a .json.backup twin and a file copy beat migrations and seed scripts (see Data Reset)
  • Operations should stay near zero — no database service, no connection management, no backups to run

The costs, and how they're paid

  • Concurrent writes could lose updates → serialized by a per-file promise queue in the JSON router
  • Every request hits the disk → acceptable at this scale, and it's exactly what makes resets take effect without a restart
  • No relations, no transactions → out of scope for the product; each collection stands alone

Revisit when

Datasets grow past what a per-request full-file read can serve, or collections need cross-references.

Related