@architecture-model/editable-metadata 0.3.0 → 0.4.0

package/Metadata.astro

@@ -1,7 +1,6 @@
 ---
-import { existsSync, readFileSync } from 'node:fs'
-import config from 'virtual:editable-metadata/config'
 import Editor from './Editor.jsx'
+import { fieldOf, people } from './fields.js'
 import { model } from './model.js'
 
 interface Props {
@@ -11,18 +10,17 @@ interface Props {
 
 type Option = string | { value: string; label?: string }
 
-const types = ['text', 'number', 'date', 'url', 'boolean', 'select', 'multiselect']
+const types = ['text', 'number', 'date', 'url', 'boolean', 'select', 'multiselect', 'people']
 
 const { of, name } = Astro.props
-const fields = existsSync(config.fieldsFile) ? JSON.parse(readFileSync(config.fieldsFile, 'utf8')) : {}
-const field: { type: string; options?: Option[] } = fields[name] ?? { type: 'text' }
+const field: { type: string; options?: Option[] } = fieldOf(name)
 if (!types.includes(field.type)) {
   throw new Error(`Unknown type "${field.type}" for metadata "${name}". Known types: ${types.join(', ')}`)
 }
 
 const valuesOf = (fqn: string) => [model.element(fqn).getMetadata(name) ?? []].flat()
 const values = valuesOf(of)
-const listed = (field.options ?? []).map((option) =>
+const listed = ((field.type === 'people' ? people() : field.options) ?? []).map((option: Option) =>
   typeof option === 'string' ? { value: option, label: option } : { value: option.value, label: option.label ?? option.value },
 )
 const labels = new Map(listed.map((option) => [option.value, option.label]))
@@ -39,7 +37,14 @@ const text =
 
 {
   import.meta.env.DEV ? (
-    <Editor client:load fqn={of} name={name} type={field.type} values={values} options={options} />
+    <Editor
+      client:load
+      fqn={of}
+      name={name}
+      type={field.type === 'people' ? 'multiselect' : field.type}
+      values={values}
+      options={options}
+    />
   ) : field.type === 'url' && text ? (
     <a href={text}>{text}</a>
   ) : (

package/People.astro

@@ -0,0 +1,33 @@
+---
+import { peopleFields } from './fields.js'
+import Metadata from './Metadata.astro'
+import { model } from './model.js'
+import { referencedBy } from './references.js'
+
+interface Props {
+  of: string
+}
+
+const { of } = Astro.props
+const users = referencedBy(model.element(of))
+---
+
+<table>
+  <tbody>
+    {
+      Object.entries(peopleFields).map(([key, label]) => (
+        <tr>
+          <th>{label}</th>
+          <td>
+            <Metadata of={of} name={key} />
+          </td>
+        </tr>
+      ))
+    }
+    <tr><th>Referenced by</th><td>{users.join(', ')}</td></tr>
+    <tr>
+      <th>Last confirmed</th>
+      <td><Metadata of={of} name="peopleConfirmed" /></td>
+    </tr>
+  </tbody>
+</table>

package/PeopleTable.astro

@@ -0,0 +1,37 @@
+---
+import { peopleFields } from './fields.js'
+import Metadata from './Metadata.astro'
+import { model } from './model.js'
+import { referencedBy } from './references.js'
+
+const systems = [...model.elements()].filter((element) => !element.parent && element.shape !== 'person')
+---
+
+<table>
+  <thead>
+    <tr>
+      <th>System</th>
+      {Object.values(peopleFields).map((label) => <th>{label}</th>)}
+      <th>Referenced by</th>
+      <th>Last confirmed</th>
+    </tr>
+  </thead>
+  <tbody>
+    {
+      systems.map((system) => (
+        <tr>
+          <td>{system.title}</td>
+          {Object.keys(peopleFields).map((key) => (
+            <td>
+              <Metadata of={system.id} name={key} />
+            </td>
+          ))}
+          <td>{referencedBy(system).join(', ')}</td>
+          <td>
+            <Metadata of={system.id} name="peopleConfirmed" />
+          </td>
+        </tr>
+      ))
+    }
+  </tbody>
+</table>

package/README.md

@@ -53,7 +53,7 @@ The editors are React components built on [Radix](https://www.radix-ui.com/) and
 
 ## Field types
 
-Without configuration every key is text. To give keys other types, create `model/metadata.json`:
+Without configuration every key is text, except the [people keys](#people). To give keys other types, create `model/metadata.json`:
 
 ```json
 {
@@ -70,6 +70,7 @@ Without configuration every key is text. To give keys other types, create `model
 | `boolean` | switch | `'true'` or `'false'`, shown as Yes or No |
 | `select` | searchable list of the options | string |
 | `multiselect` | searchable list of the options, several can be checked | list of strings |
+| `people` | searchable list of the people in `model/people.json`, several can be checked | list of handles |
 
 The options of `select` and `multiselect` are the ones listed plus every value already in use in the model. A `url` is a link in the built site.
 
@@ -96,6 +97,52 @@ Payments calls us back: <Derived of="payments" value={callsBack} />
 
 A function returns a string, a number, a list, or a boolean, shown as Yes or No. A derived value is never editable.
 
+## People
+
+"Owner" rarely tells you whom to ask. Each system, internal or external, can say whom to go to for which job:
+
+| Key | Who | Ask them when |
+| --- | --- | --- |
+| `integratedBy` | integrated it originally | you need to know why it works the way it does |
+| `experts` | know best how it works and how its integration is changed | there is an incident, an API or contract change, an upgrade, or a change to review |
+| `contributors` | have worked on it | you need reviewers or extra hands, or the experts are away |
+| `administrators` | manage it: for an external service, the vendor account, keys, billing and support; for our own, its accounts and access | credentials need rotating, someone needs access, or a support ticket or plan change is due |
+| `peopleConfirmed` | | the date someone last checked these; older than about six months, check again |
+
+The four people keys are `people` fields without any configuration. Each stores handles from one shared list, `model/people.json`, so a person is added once and every field picks from it:
+
+```json
+[
+  { "value": "igor", "label": "Igor Morozov" },
+  { "value": "dana", "label": "Dana Kim" }
+]
+```
+
+```
+stripe = external 'Stripe' {
+  metadata {
+    integratedBy 'igor'
+    experts 'dana'
+    contributors ['igor', 'dana']
+    administrators 'dana'
+    peopleConfirmed '2026-10-17'
+  }
+}
+```
+
+`People` shows them for one system, with the systems and containers that reference it, worked out from the model's relationships. `PeopleTable` shows the same for every system:
+
+```mdx
+import People from '@architecture-model/editable-metadata/People.astro'
+import PeopleTable from '@architecture-model/editable-metadata/PeopleTable.astro'
+
+<People of="stripe" />
+
+<PeopleTable />
+```
+
+In the dev server the people fields are click-to-edit, picking from the list. A new person is added to `model/people.json` first. Someone who has left keeps their entry, with `"left": "2026-05-01"`, so their handle still shows as their name and you can [find the systems whose people have left](https://arch.morozov.is/recipes/people-who-left/). [Model who knows and manages each system](https://arch.morozov.is/people/) says which questions the people fields let the model answer, and why.
+
 ## Properties
 
 `Property` shows and edits an element's own `title`, `summary`, `description`, `technology` or `links`:
@@ -120,10 +167,11 @@ A title can't be emptied. Links replace the element's own links, and a row witho
 editableMetadata({
   model: 'model', // folder with the .c4 files
   fields: 'model/metadata.json', // field types
+  people: 'model/people.json', // the people the people fields pick from
 })
 ```
 
-Both paths are relative to the Astro project root.
+The paths are relative to the Astro project root.
 
 ## How it saves
 

package/editor.js

@@ -49,14 +49,14 @@ export async function setProperty(dir, { fqn, property, value }) {
   await update(dir, fqn, { [property]: token }, asMarkdown(token, text))
 }
 
-export const editor = ({ modelDir, fieldsFile }) => ({
+export const editor = ({ modelDir, fieldsFile, peopleFile }) => ({
   name: 'editable-metadata-editor',
   apply: 'serve',
   configureServer(server) {
     // Pages load the model once per module evaluation, so a changed model has to evict what was evaluated.
-    server.watcher.add([modelDir, fieldsFile])
+    server.watcher.add([modelDir, fieldsFile, peopleFile])
     server.watcher.on('change', (file) => {
-      if (!file.endsWith('.c4') && file !== fieldsFile) return
+      if (!file.endsWith('.c4') && file !== fieldsFile && file !== peopleFile) return
       for (const environment of Object.values(server.environments)) environment.moduleGraph.invalidateAll()
       server.ws.send({ type: 'full-reload' })
     })

package/fields.js

@@ -0,0 +1,20 @@
+import { existsSync, readFileSync } from 'node:fs'
+import config from 'virtual:editable-metadata/config'
+
+export const peopleFields = {
+  integratedBy: 'Integrated by',
+  experts: 'Experts',
+  contributors: 'Contributors',
+  administrators: 'Administrators',
+}
+
+const defaults = {
+  ...Object.fromEntries(Object.keys(peopleFields).map((key) => [key, { type: 'people' }])),
+  peopleConfirmed: { type: 'date' },
+}
+
+const read = (file, fallback) => (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : fallback)
+
+export const fieldOf = (name) => read(config.fieldsFile, {})[name] ?? defaults[name] ?? { type: 'text' }
+
+export const people = () => read(config.peopleFile, [])

package/index.js

@@ -19,13 +19,17 @@ const withoutEditor = {
   },
 }
 
-export default function editableMetadata({ model = 'model', fields = 'model/metadata.json' } = {}) {
+export default function editableMetadata({
+  model = 'model',
+  fields = 'model/metadata.json',
+  people = 'model/people.json',
+} = {}) {
   return {
     name,
     hooks: {
       'astro:config:setup': ({ config, command, updateConfig }) => {
         const root = fileURLToPath(config.root)
-        const paths = { modelDir: resolve(root, model), fieldsFile: resolve(root, fields) }
+        const paths = { modelDir: resolve(root, model), fieldsFile: resolve(root, fields), peopleFile: resolve(root, people) }
         const hasReact = config.integrations.some((integration) => integration.name === '@astrojs/react')
         updateConfig({
           integrations: hasReact ? [] : [react()],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@architecture-model/editable-metadata",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Show LikeC4 element metadata and properties in Astro pages and edit them in place in the dev server",
   "keywords": [
     "astro-integration",
@@ -21,15 +21,21 @@
     ".": "./index.js",
     "./Metadata.astro": "./Metadata.astro",
     "./Property.astro": "./Property.astro",
-    "./Derived.astro": "./Derived.astro"
+    "./Derived.astro": "./Derived.astro",
+    "./People.astro": "./People.astro",
+    "./PeopleTable.astro": "./PeopleTable.astro"
   },
   "files": [
     "index.js",
     "editor.js",
     "model.js",
+    "fields.js",
+    "references.js",
     "Metadata.astro",
     "Property.astro",
     "Derived.astro",
+    "People.astro",
+    "PeopleTable.astro",
     "Editor.jsx",
     "NoEditor.jsx",
     "editor.css"

package/references.js

@@ -0,0 +1,9 @@
+const systemOf = (element) => (element.parent ? systemOf(element.parent) : element)
+
+export function referencedBy(element) {
+  const sources = [...element.incoming('all')]
+    .map((relationship) => relationship.source)
+    .filter((source) => source.id !== element.id && !source.isDescendantOf(element) && source.shape !== 'person')
+  const titles = sources.map((source) => (source.parent ? `${source.title} (${systemOf(source).title})` : source.title))
+  return [...new Set(titles)]
+}