portal/docs/design/filesystem-routes.md

# Filesystem routes, sections, and where chains fit

Status: proposal (researched 2026-08-24, nothing implemented).

## What exists today, precisely

- A question's `id` doubles as its URL. Filenames are meaningless:
  `questions/` is loaded as a **flat** directory (both the Gitea
  loader and `question_lint --path`), every `*.yaml` becomes a
  `Question` keyed by its own declared `id`.
- Hierarchy exists only as strings: `action: /proposed` edges, plus a
  manual `followup: true` flag that hides post-submission pages from
  the nav. The graph is invisible in a repo listing — you open every
  file to learn the flow. (uhhm's actual graph: `/` fans out to three
  followups; `/develop` → `/develop-proposal` → `/proposed` is a
  two-step flow flattened into three top-level files.)
- Criteria are per-file: `qualifies: <kanidm-group>` on a question,
  `requires_group` on a resource. Gating a whole area means
  repeating the flag in every file of that area.
- Chains are query-string lineage: submitting hashes
  `(question, parents, responses, ts)` into `chain_hash`, the next
  page is `action + ?chain=<hash>`, and holding a chain is itself a
  capability (`self_transition` + email second factor). `chain.rs`
  reserves DAG shape (multiple parents) but nothing produces it yet.
- `Question.route` is a declared-but-never-read field — a fossil of
  this exact idea.

## The proposal, in three phases

### Phase 1 — the tree is the router

Directory structure becomes the URL structure, next-js style:

```
questions/
  index.yaml              → /
  applied.yaml            → /applied
  develop/
    index.yaml            → /develop
    proposal.yaml         → /develop/proposal
    proposed.yaml         → /develop/proposed
  review/
    index.yaml            → /review
```

- `id:` becomes optional and **derived from the path** (`index.yaml`
  names its directory). An explicit `id:` still wins so both content
  repos keep working unchanged; lint warns when it disagrees with the
  path, and the field can retire later along with `route`.
- `action:` accepts **relative references**: `action: proposed`
  resolves against the file's directory, `action: /subscribed` stays
  absolute. Resolution happens at load time, so validation and the
  runtime see absolute ids exactly as today. A flow directory becomes
  self-contained: rename `develop/` and every internal edge moves
  with it.
- **`followup:` is inferred**: `index.yaml` files are nav pages,
  non-index files are followups unless they say `nav: true`. This
  matches the real content exactly (uhhm's four `followup: true`
  files are precisely its non-index leaf pages) and deletes a flag
  people must remember.
- Loader: switch from the per-directory contents API to Gitea's git
  trees API (`/git/trees/{branch}?recursive=true`) — one request for
  the whole tree instead of one per directory, which the flat loader
  should be using anyway.

### Phase 2 — sections: criteria scoped by URL prefix

A `_section.yaml` in any directory applies to everything beneath it
(underscore = not a page, like next's private folders):

```
questions/review/_section.yaml:
  qualifies: portal_owners
  responsible: { name: Bendik, contact: … }
```

This is the URL/criteria interplay actually worth having: **a URL
prefix becomes a trust boundary**. "Everything under /review is
owner-only" is one line in one place, instead of a flag per file that
drifts. Per-question `qualifies` still overrides (tighter or looser —
lint should warn on looser). Sections are also the natural home for
shared `responsible` contacts and, later, per-section branding
accents.

### Phase 3 — dynamic segments, and chains stay out of the path

Two criteria axes exist: **who you are** (Kanidm group) and **what
you've done** (holding a chain). Phase 2 scopes the first by prefix;
phase 3 does the same for the second, plus gives records addresses:

- `[record].yaml` — a dynamic segment, one YAML file rendered per
  record: `questions/review/[record].yaml` serves `/review/<key>`,
  with the param available to the page's `ResourceSpec.key`. Today a
  single record is only reachable through a desk row or a
  `?chain=` link; this gives every record a real, gated URL —
  linkable from review desks, automations, and n8n notifications.
- `requires_chain: <question-ref>` (page- or section-level): the page
  only renders for a visitor whose chain tip answers the referenced
  question. Today's followup pages are soft-hidden (out of nav) but
  fully reachable; this makes "you must have come from X" an actual
  criterion, declared with a relative ref like actions are.

**Deliberately not proposed: encoding the chain in the path.** The
page tree is static structure; the chain is runtime lineage and a
bearer capability. Putting it in the path makes it look canonical and
shareable — exactly what a capability URL shouldn't invite — and a
DAG (the reserved multi-parent shape) doesn't linearize into a path
anyway. `?chain=` stays a query parameter: pages keep one canonical
URL, lineage rides along only when it's actually held.

## Migration

Phase 1 is fully backward compatible (explicit `id` wins, flat repos
are just trees of depth one). The content repos migrate by `git mv`:
uhhm's develop flow nests under `develop/`, its followups either stay
top-level (`/applied` keeps its URL) or move with their flows if URL
churn is acceptable; redoal's three files are already the tree. Lint
learns the same resolution rules in the same commit, so a bad
reference stays a caught push, never a 404.

## Order of value

Phase 1 is cheap and pays immediately (the repo listing becomes the
sitemap). Phase 2 is small and unlocks gated areas properly. Phase 3
is the real feature work — `[record]` pages change what desks and
automations can link to — and can wait until something concrete needs
it.