uhhm/portal
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 89 Wiki Activity

A person stays in dialogue with their case

Browse Source 
Five things a building authority needed and portal could not say,
found by building one and replaying its cases through the engine.

The one that mattered: a submitter could only ever act on a record
nobody had touched. `access.rs` pinned a self_transition's from-state
to `open`, though the runtime had always passed the real state and
asked. So the applicant written to for a missing drawing could not
send it, and nobody could withdraw once anything had happened.
`self_transition` now takes `from: [state, ...]` and compiles one rule
per state; omitted it still means the initial state alone, which is
what every unsubscribe link already meant.

Then the four beside it. A record can belong to another record
(`type: record`, `of:`), with `where: { field, equals }` on a listing
as the other half, so an application's page lists the objections that
name it. A public view can be narrowed to the states worth showing,
so a register that is public by law is public about what was decided
and not about what was withdrawn. A state can grant a group, so an
approval that means membership needs no second step. And a state can
be moved by a clock (`after: { days, to }`, src/deadlines.rs) - held
to the same declared edge as a desk button, firing the same mail,
publishing the same event.

Also: the README is a README again, and everything that was crowding
it is in docs/ - architecture, content reference, state machines,
access, operations.

95 tests, up from 82.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Bendik Aagaard Lynghaug
2026-09-25 21:35:25 +02:00
co-authored by Claude Opus 5
parent 26c1762dfa
commit f18d1a5181
19 changed files with 1417 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content-reference.md
+232
View File
@@ -0,0 +1,232 @@
# Content reference
A content repo is the site. This is everything it may say.
```
site.yaml branding, language, mail
aggregates.yaml the state machine of every bucket
needs.yaml what the site is for (read by iris, never by portal)
questions/
index.yaml the front page, served at /
about.yaml served at /about
review/
_section.yaml applies to everything under /review
index.yaml served at /review
[record].yaml serves /review/<anything>
```
Nothing here is required except a `questions/` tree with something in
it. Portal's lint refuses content it cannot serve honestly, at boot,
on every hot reload, and in CI through `iris check`.
## site.yaml
```yaml
title: Vestmark kommune # the browser title and the header
wordmark: /site/logo.svg # an image instead of the title
wordmark_invert: true # flip it in dark mode
wordmark_height: 2.4 # rem
lang: no # the interface language: en or no
stylesheet: /site/theme.css # served same-origin from the repo
favicon: /site/icon.svg
hero: { kind: module, module: hero.js } # or { kind: plain }
mail:
from: Vestmark kommune <post@vestmark.example>
reply_to: post@vestmark.example
invite: { subject: "...", body: "..." } # rewords the built-in invite mail
```
`mail.from` is required as soon as any state declares a mail.
## A question
One YAML file is one page.
```yaml
id: /apply # defaults to the file's path
name: Apply to build
description: What we need from you.
qualifies: case_officers # a Kanidm group may open this page
requires_chain: /start # or: an answer they must already have given
followup: true # keep it out of the nav until earned
responsible: { name: Solveig, email: post@vestmark.example }
event: # this page announces an occasion
starts: 2026-10-14T18:00
duration: 2h
place: The town hall
place: # this page is about somewhere
lat: 59.8938
lon: 11.0332
zoom: 15
name: Tomter
alternatives: [ ... ]
```
`qualifies`, `requires_chain` and `responsible` are inherited from the
nearest `_section.yaml`. `event` makes a page an occasion with a time;
`place` makes it a place, drawing a still map under the question and
opening any `type: location` field on the page there rather than on
the whole world.
## An alternative
One choice. Never two actions behind one heading: if two things can be
done, they are two alternatives.
```yaml
alternatives:
- name: Send the drawings
description: We answer within twelve weeks.
action: /sent # the page to go to; /shape/{field} templates
record_as: applications # the bucket the answer lands in
disabled: false
consequence: [What happens next]
encouragements: [It takes two minutes]
images: [/site/drawing.png]
features: [ ... ]
```
Three things an alternative may do instead of, or beside, recording an
answer:
```yaml
self_transition: # the person moves their own record
bucket: applications
to: complete
from: [open, incomplete] # defaults to the initial state alone
label: Send them
invite: { group: case_officers } # onboard someone into Kanidm
```
`self_transition.from` is what keeps a person in dialogue with their
case: an applicant written to for a missing drawing answers from
`incomplete`, and may withdraw from wherever the case has got to.
Omitted, it is the initial state alone, which is what a one-shot
unsubscribe link means. Each state listed becomes its own access rule,
and the lint refuses a `from -> to` the state machine does not declare.
An `invite` needs a required `name` and `email` on the same
alternative, and the inviting group must be allowed to invite that
group by the policy.
## A feature
What an alternative offers, explained. A feature that is only layout
is a feature wasted: each one says something true about the choice.
```yaml
features:
- name: What you need
description: The case number from the letter.
icon: document
color: "#8ec2c0"
requirements: [ ... ] # form fields
resource: { ... } # live data
```
## A requirement (a form field)
```yaml
requirements:
- name: email # snake_case; this is the stored key
label: Your email
placeholder: you@example.no
type: email
optional: false
value: "{key}" # a preset; a dynamic page's segment fills it
```
`type` is one of:
| type | what it is |
|---|---|
| `text` | the default |
| `email`, `tel`, `date`, `number`, … | anything else is passed straight through as the HTML input type |
| `textarea` | several lines |
| `prosekit` | a rich-text editor |
| `select` | one choice, or `multiple: true` for any number |
| `file` | an upload, with `accept:` and `multiple:` |
| `location` | a pin on a map, stored as `{lat, lon, zoom}` |
| `record` | the record this one belongs to |
| `gesture`, `voice` | a drawn stroke or a recording, through a redoal relay |
| `hidden` | a carrier value, no label row |
| `module` | a widget the content repo ships |
A `select` takes either inline `options: [...]` or a `resource:` to
draw them from, with `id_field:` naming each item's stable id.
A field may load its value from a resource when a sibling changes:
```yaml
- name: contents
type: textarea
bind:
field: path # the sibling to watch
resource: { source: { kind: url, url: "https://git.example/raw/{path}" } }
```
### type: record
How one case belongs to another — an objection to the application it
objects to, an appeal to the decision it appeals.
```yaml
- name: case
type: record
of: applications # the bucket the other record is in
value: "{key}" # arrives on the link, on a dynamic page
```
Nobody types one of these: the stored value is the parent's record id,
which is a chain hash. It arrives the way it was given out, so the
field carries rather than asks, and renders hidden. A submission
naming a record that is not there is refused, so a reference in a
stored record is one that resolved at least once.
The other half is a listing that asks for the children:
```yaml
resource:
source: { kind: kv, bucket: objections }
requires_group: case_officers
where: { field: case, equals: "{key}" }
```
## A resource
Live data, declared by content and read by the server. What a resource
reads is never a client-supplied parameter.
```yaml
resource:
source: { kind: kv, bucket: applications }
key: abc123 # one record instead of the list
public: true # or requires_group: case_officers
states: [approved, refused] # only these; empty means all
where: { field: case, equals: "{key}" }
jq: ".[] | {name, url: .html_url}"
empty: Nothing decided yet.
transitions: # the desk's buttons
- { from: complete, to: on_hearing, label: Send it out }
```
`source.kind` is one of `kv`, `gitea_starred`, `gitea_org_repos`,
`gitea_releases`, `url`.
A spec with neither `public: true` nor `requires_group` is
unreachable: reads fail closed, and mutations always need a group
whatever `public` says.
`states` and `where` narrow a listing. They matter most for a register
that is public by law — public about what was decided, not about what
was withdrawn — while the desk working the same bucket is a different
spec and still sees all of it. A record that has no such field never
matches: "everything that did not say" is not something a page can ask
for by accident.
## needs.yaml
What the site is for, as a checkable spec: who wants what, which
bucket the answer must land in, which group carries it to a finished
state. The runtime never reads it. `iris check` proves the site meets
it, and `iris replay` runs cases through the real engine.