From 971564ee6fcd4df4ca2987332391ed69b5147df3 Mon Sep 17 00:00:00 2001 From: lucaronin Date: Tue, 24 Mar 2026 16:45:33 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20add=20storage=20decision=20rule=20?= =?UTF-8?q?=E2=80=94=20vault=20vs=20app=20settings=20(follows=20vault=20vs?= =?UTF-8?q?=20installation-specific)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ARCHITECTURE.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6cdba254..ee48d19c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -14,6 +14,26 @@ Laputa is opinionated. Standard field names (`type:`, `status:`, `url:`, `Worksp This principle directly serves AI-readability: the more structure comes from shared conventions rather than per-user custom configurations, the easier it is for an AI agent to understand and navigate the vault correctly — without needing bespoke instructions for every setup. +### Where to store state: vault vs. app settings + +When deciding where to persist a piece of data, ask: **"Would the user want this to follow them across all their Laputa installations — other devices, future platforms (tablet, web)?"** + +| Follows the vault | Stays with the installation | +|-------------------|-----------------------------| +| Type icon, type color | Editor zoom level | +| Pinned properties per type | API keys (Anthropic, OpenAI) | +| Sidebar label overrides | GitHub token | +| Property display order | Window size / position | +| Any user-visible customization of how content is organized or displayed | Any machine-specific or credential-type setting | + +**Rule:** If the information is about *how the content is structured or presented* and the user would expect it to be consistent wherever they open their vault, store it in the vault (frontmatter of the relevant note, using the `_field` underscore convention for system properties). If it's about *this specific installation of the app*, store it in `~/.config/com.laputa.app/settings.json` or localStorage. + +Examples: +- ✅ Vault: `_pinned_properties` in a Type note (every device should show the same pinned properties) +- ✅ Vault: `_icon: shapes` in a Type note (icon is part of the type's identity) +- ✅ App settings: `anthropic_key` (credential, not vault data) +- ✅ App settings: `zoom: 1.3` (machine-specific preference) + ### No hardcoded exceptions No field names, folder paths, or vault-specific values should be hardcoded in the application source code. What can be a convention should be a convention. What needs to be configurable should live in a file. Relationship fields are detected dynamically by checking whether values contain `[[wikilinks]]` — no hardcoded field name lists.