docs: add a Role in the framework section to every module README

Each module README now says where the module sits in the dependency
graph, why it is its own module, and lists use cases for application
developers.
This commit is contained in:
2026-10-11 00:58:17 +02:00
parent 87953f68bf
commit 602e0412f3
24 changed files with 240 additions and 0 deletions

View File

@@ -10,6 +10,16 @@ Schema-driven admin backend that compiles WinterCMS-style YAML list, form, filte
`cabana` is the SummerCMS counterpart of WinterCMS's backend: controllers with the List, Form and Relation behaviors, their `config_list.yaml`, `config_form.yaml`, `config_filter.yaml` and `config_relation.yaml` files, the model `columns.yaml` and `fields.yaml`, backend users, roles and permissions, settings models and backend navigation. Plugins declare admin controllers through the [pact](../pact/README.md) capability interfaces and embed their YAML; `cabana.Activate` compiles all of it once at boot, fails fast on any schema error, and returns the admin routes that [surf](../surf/README.md) mounts under the admin prefix (`backend.uri`, default `/backend`). The JSON API lives under `<prefix>/api/v1`, and every other path under the prefix serves the admin SPA from [boardwalk](../boardwalk/README.md).
## Role in the framework
The largest module and the admin backend of the framework. It sits on top of `backpack`, `lagoon`, `bouncer`, `party`, `pact`, `phrasebook`, `towel` and `bonfire`, and it mounts `boardwalk` to serve the admin SPA. `surf` wires its routes in. It mirrors the WinterCMS backend: YAML-driven lists, forms, filters and relations compiled once at boot.
Use cases:
- Give a model such as a blog post a full admin screen from fields.yaml and columns.yaml, with no Vue code.
- Add relation managers, filters, bulk actions and settings pages declaratively.
- Add custom form widgets and controller actions that run behind the admin's CSRF and permission checks.
## Features
- Boot-time schema compilation: `cabana.CompileList` and `cabana.CompileForm` read a controller's YAML from the plugin's embedded tree, check that `modelClass` matches the controller's model name, and cache a locale-neutral schema. Each request gets a translated copy (`cabana.ListSchema.Localize`, `cabana.FormSchema.Localize`, `cabana.RelationSchema.Localize`) through [phrasebook](../phrasebook/README.md), with CLDR plural forms for the SPA's messages.