From 4787673841f05cd9ab8ecd958bc1f772b86ffc28 Mon Sep 17 00:00:00 2001 From: lucaronin Date: Sun, 8 Mar 2026 19:58:28 +0100 Subject: [PATCH] docs: add design principles and semantic field conventions - ARCHITECTURE.md: new Design Principles section covering filesystem as source of truth, convention over configuration, no hardcoded exceptions, AI-first knowledge graph, and three-representation model - ABSTRACTIONS.md: design philosophy intro + semantic field names table documenting all conventional frontmatter fields and their UI behavior Convention over configuration principle explicitly noted as serving AI-readability: shared conventions make vaults navigable by AI agents without bespoke per-vault instructions. --- docs/ABSTRACTIONS.md | 24 ++++++++++++++++++++++++ docs/ARCHITECTURE.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) diff --git a/docs/ABSTRACTIONS.md b/docs/ABSTRACTIONS.md index 9b91411b..b1e16801 100644 --- a/docs/ABSTRACTIONS.md +++ b/docs/ABSTRACTIONS.md @@ -2,6 +2,30 @@ Key abstractions and domain models in Laputa. +## Design Philosophy + +Laputa's abstractions follow the **convention over configuration** principle: standard field names and folder structures have well-defined meanings and trigger UI behavior automatically. This makes vaults legible both to humans and to AI agents — the more a vault follows conventions, the less custom configuration an AI needs to navigate it correctly. + +The full set of design principles is documented in [ARCHITECTURE.md](./ARCHITECTURE.md#design-principles). + +## Semantic Field Names (conventions) + +These frontmatter field names have special meaning in Laputa's UI: + +| Field | Meaning | UI behavior | +|---|---|---| +| `type:` | Entity type (Project, Person, Quarter…) | Type chip in note list + sidebar grouping | +| `status:` | Lifecycle stage (active, done, blocked…) | Colored chip in note list + editor header | +| `url:` | External link | Clickable link chip in editor header | +| `date:` | Single date | Formatted date badge | +| `start_date:` + `end_date:` | Duration/timespan | Date range badge | +| `goal:` + `result:` | Progress | Progress indicator in editor header | +| `Workspace:` | Vault context filter | Global workspace filter | +| `Belongs to:` | Parent relationship | Relationship chip in Properties panel | +| `Related to:` | Lateral relationship | Relationship chip in Properties panel | + +The list of default-shown relationships and semantic property rendering rules can be customized via `config/relations.md` and `config/semantic-properties.md` in the vault. + ## Document Model All data lives in markdown files with YAML frontmatter. There is no database — the filesystem is the source of truth. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4dacb765..4217074a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,6 +2,35 @@ Laputa is a personal knowledge and life management desktop app. It reads a vault of markdown files with YAML frontmatter and presents them in a four-panel UI inspired by Bear Notes. +## Design Principles + +### Filesystem as the single source of truth + +The vault is a folder of plain markdown files. The app never owns the data — it only reads and writes files. The cache, React state, and any in-memory representation are always derived from the filesystem and must be reconstructible by deleting them. When in doubt, the file on disk wins. + +### Convention over configuration + +Laputa is opinionated. Standard field names (`type:`, `status:`, `url:`, `Workspace:`, `Belongs to:`, `start_date:`, `end_date:`) have well-defined meanings and trigger specific UI behavior — without any setup. This is not convention *instead of* configuration: users can override defaults via config files in their vault (e.g. `config/relations.md`, `config/semantic-properties.md`). But the defaults work out of the box, and most users never need to touch them. + +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. + +### 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. Hardcoded lists (like `RELATIONSHIP_KEYS`) are a code smell — they create invisible walls that break when the user's vocabulary differs from the developer's assumptions. + +### AI-first knowledge graph + +Notes are not just documents — they are nodes in a structured graph of people, projects, events, responsibilities, and ideas. Every design decision should ask: "Does this make the knowledge graph easier for a human *and* an AI to navigate?" Conventions that are legible to both are better than conventions that are legible only to one. + +### Three representations, one authority + +Vault data exists in three forms simultaneously: +1. **Filesystem** — the `.md` files. This is the authority. +2. **Cache** — an index for fast startup. Always reconstructible from the filesystem. +3. **React state** — the in-memory view during a session. Always derived from the cache. + +These must never diverge permanently. If they do, the filesystem wins and the cache/state are rebuilt. + ## Tech Stack | Layer | Technology | Version |