From e76432d3caa99e4b8c2013ff22024eb832a50b62 Mon Sep 17 00:00:00 2001 From: Julien Calixte Date: Sat, 20 Jun 2026 02:20:05 +0200 Subject: [PATCH] docs: cross-link design docs with README Add a Design & docs section to the README linking CONTEXT, DESIGN, and the three ADRs, plus a backlink to the README from each of those documents. --- CONTEXT.md | 3 +++ DESIGN.md | 1 + README.md | 15 +++++++++++++++ docs/adr/0001-detected-feedback-loops.md | 2 ++ docs/adr/0002-vue-flow-substrate.md | 2 ++ docs/adr/0003-flow-as-node-materialised-clouds.md | 2 ++ 6 files changed, 25 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index 1e70a7a..cdd9716 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -5,6 +5,9 @@ models (stock-and-flow diagrams with feedback loops) in the spirit of Donella Meadows' *Thinking in Systems*. The diagram is the product now; numeric simulation is a planned later phase, so the language is chosen to be simulation-ready. +Part of [meadows](./README.md); see [DESIGN.md](./DESIGN.md) for how these terms +map to goals, functions, and components. + ## Language **System**: diff --git a/DESIGN.md b/DESIGN.md index 31a6e60..6faa692 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -7,6 +7,7 @@ model, and persistence for building stock-and-flow **Models**. It relies on [ADR-0001](./docs/adr/0001-detected-feedback-loops.md) (loops detected from a polarity-annotated graph, not stored). "Simulation-ready" is a constraint here, not a goal: nothing in the data model should need a rewrite when simulation lands. +See [README.md](./README.md) for the project overview and how to run it. Strength weights used in matrices: **9** strong, **3** medium, **1** weak, blank none. diff --git a/README.md b/README.md index 8fdfa3e..eaf995a 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,21 @@ Inspired by Donella Meadows' *Thinking in Systems*. Deployed at https://meadows.apoena.dev +## Design & docs + +- [CONTEXT.md](./CONTEXT.md) — the ubiquitous language: Stock, Flow, Converter, + Information Link, Polarity, and the Feedback Loops (Reinforcing / Balancing) the + wiring forms. +- [DESIGN.md](./DESIGN.md) — goal-driven design (QFD): goals → functions → + components, the House of Quality, the performance budget, and recorded tradeoffs. +- Architecture decisions (`docs/adr/`): + - [ADR-0001](./docs/adr/0001-detected-feedback-loops.md) — feedback loops are + detected from structure, not stored. + - [ADR-0002](./docs/adr/0002-vue-flow-substrate.md) — Vue Flow is the editor + substrate; the domain Model is the source of truth. + - [ADR-0003](./docs/adr/0003-flow-as-node-materialised-clouds.md) — a Flow is a + node; Source/Sink clouds are materialised nodes. + ## Stack Vite + Vue 3 + TypeScript, Tailwind v4, DaisyUI. Lint/format via [oxc](https://oxc.rs) diff --git a/docs/adr/0001-detected-feedback-loops.md b/docs/adr/0001-detected-feedback-loops.md index 3cee29e..87c6b07 100644 --- a/docs/adr/0001-detected-feedback-loops.md +++ b/docs/adr/0001-detected-feedback-loops.md @@ -1,5 +1,7 @@ # Feedback loops are detected from a polarity-annotated graph, not stored +_Part of [meadows](../../README.md) · see [DESIGN.md](../../DESIGN.md)._ + A **Feedback Loop** in a **Model** is a cycle in the wiring (Stock → Information Link(s)/Flow → same Stock). We chose to **derive** loops by detecting cycles and classifying each as **Reinforcing** (even number of `−` polarities) or diff --git a/docs/adr/0002-vue-flow-substrate.md b/docs/adr/0002-vue-flow-substrate.md index 7baa7a6..675279f 100644 --- a/docs/adr/0002-vue-flow-substrate.md +++ b/docs/adr/0002-vue-flow-substrate.md @@ -1,5 +1,7 @@ # Vue Flow is the editor substrate; the domain Model is the source of truth +_Part of [meadows](../../README.md) · see [DESIGN.md](../../DESIGN.md)._ + The editor is built on **Vue Flow** (`@vue-flow/core`) for pan/zoom, node dragging, handles, edge-drawing, and selection, with Stocks/Flows/Converters/ Clouds as custom Vue node components. We rejected hand-rolling an SVG editor (too diff --git a/docs/adr/0003-flow-as-node-materialised-clouds.md b/docs/adr/0003-flow-as-node-materialised-clouds.md index b5f1f8b..5c85e88 100644 --- a/docs/adr/0003-flow-as-node-materialised-clouds.md +++ b/docs/adr/0003-flow-as-node-materialised-clouds.md @@ -1,5 +1,7 @@ # A Flow is a node; Source/Sink clouds are materialised nodes +_Part of [meadows](../../README.md) · see [DESIGN.md](../../DESIGN.md)._ + In the domain `Model`, a **Flow** is a *node* carrying `source` and `target` references (each to a Stock or Cloud), not an edge. The pipe you see is *rendered* from those references. The **Source/Sink** boundary is a **materialised Cloud