domma-cms 1.6.59 → 1.7.0

package/docs/recruitment-recipe.md

@@ -0,0 +1,501 @@
+# Recipe - Building a Job Board with Stock Primitives
+
+Domma CMS doesn't ship a recruitment plugin, but every primitive you need for a working job board is in the base
+distribution. This recipe builds an end-to-end candidate/employer flow from scratch using only:
+
+- **Collections** with structured filtering
+- **Forms** that capture applications
+- **Actions** that link applications to jobs
+- **Pages** with role-based visibility and per-user scoping
+
+The same pattern works for any relational app: bookings, classified ads, marketplace listings, bug trackers, RSVPs.
+
+---
+
+## Architecture overview
+
+```
+content/collections/jobs/                ← postings authored by employers
+content/collections/applications/        ← per-candidate applications linking back to jobs
+content/pages/jobs/index.md              ← public job listing with filters
+content/pages/dashboard.md               ← signed-in dashboard with "My applications"
+content/forms/apply.json                 ← form embedded on each job page
+Actions:
+  - "submit-application" creates an application linked to the job + candidate
+  - "withdraw-application" deletes an application owned by the candidate
+Roles (added to content/collections/roles/):
+  - candidate (level 5)
+  - employer  (level 4)
+```
+
+---
+
+## 1. Add the roles
+
+In the admin panel **System > Roles** (or by editing `content/collections/roles/data.json`):
+
+```json
+{
+  "name": "candidate",
+  "label": "Candidate",
+  "level": 5,
+  "permissions": ["notifications"],
+  "badgeClass": "badge-info"
+}
+{
+  "name": "employer",
+  "label": "Employer",
+  "level": 4,
+  "permissions": ["notifications"],
+  "badgeClass": "badge-secondary"
+}
+```
+
+Roles are dynamic - once saved, every visibility check and `where_role=` filter recognises them immediately.
+
+The base roles are `super-admin` (0), `admin` (1) and `user` (2), so levels 4 and 5 sit below `user`: a plain
+`user` counts as "more senior" than a candidate. Use the exact form (`visibility: "=candidate"`) where a page or
+menu item must be for candidates only.
+
+---
+
+## 2. Create the `jobs` collection
+
+Schema fields (admin → Collections → New):
+
+| Field      | Type       | Notes                              |
+|------------|------------|------------------------------------|
+| `title`    | text       | Job title                          |
+| `company`  | text       | Hiring organisation                |
+| `location` | text       | City or "Remote"                   |
+| `type`     | select     | `full-time`, `contract`, `part-time` |
+| `salary`   | number     | Annual GBP                         |
+| `tags`     | multiselect| `remote`, `hybrid`, `on-site`, etc. |
+| `summary`  | textarea   | Short pitch                        |
+| `body`     | rich-text  | Full description                   |
+| `postedAt` | date       | Defaults to `createdAt`            |
+
+**Permissions:**
+
+- `api.read` = enabled, access = `public` - anyone can list jobs
+- `api.create`, `update`, `delete` = enabled, access = `employer` - employers post their own roles
+- Add a **row-level access** rule (`content/collections/jobs/schema.json → rowAccess`):
+  ```json
+  "rowAccess": {
+    "update": { "ownerField": "createdBy", "fallbackRoles": ["admin", "super-admin"] },
+    "delete": { "ownerField": "createdBy", "fallbackRoles": ["admin", "super-admin"] }
+  }
+  ```
+  Employers can only edit/delete jobs they created; admins can manage all.
+
+---
+
+## 3. Create the `applications` collection
+
+Fields:
+
+| Field         | Type        | Notes                                                                    |
+|---------------|-------------|--------------------------------------------------------------------------|
+| `jobId`       | **reference** | `reference: { collection: "jobs", displayField: "title", linkTemplate: "/jobs/{{id}}" }` |
+| `candidateId` | text        | Set automatically to `meta.createdBy`                                    |
+| `coverLetter` | textarea    | What the candidate wrote                                                 |
+| `resume`      | **file**    | `file: { accept: "application/pdf", maxSize: 5242880 }` - PDF up to 5 MB |
+| `status`      | select      | `submitted`, `reviewing`, `interview`, `offered`, `rejected`, `withdrawn`|
+| `submittedAt` | date        | Defaults to `createdAt`                                                  |
+
+The `jobId` is a **reference** to the `jobs` collection. This single change
+means:
+
+- The apply form auto-renders a populated dropdown of job titles (no manual
+  options or denormalised `jobTitle` field needed)
+- The candidate's "My applications" view shows the job title - not the id -
+  because resolution happens automatically when listing
+- Each row links to `/jobs/<id>` for the original posting (via `linkTemplate`)
+- Validation prevents stale apps pointing at deleted jobs (you'll get
+  `"Job" → no entry "<id>" in "jobs"` on create)
+
+**Permissions:**
+
+- `api.read` = **disabled** (we'll use `scope="mine"` instead - see step 7)
+- `api.create` = **disabled** (created via Action, not directly)
+- No row-level rules needed - the scope=mine endpoint already restricts to `createdBy = user.id`
+
+---
+
+## 4. Build the public job listings page
+
+Create `content/pages/jobs/index.md`:
+
+```markdown
+---
+title: Jobs
+visibility: public
+---
+
+## Find your next role
+
+[collection slug="jobs"
+  display="cards" columns="3"
+  searchable
+  filterable="location,type,salary,tags"
+  sortable
+  page-size="9"
+  title-field="title"
+  fields="company,location,salary,type,tags"
+  sort="postedAt" order="desc"
+  cta="apply-flow"
+  cta-label="View & Apply"
+  cta-icon="briefcase"
+  empty="No matching roles right now - try widening your filters." /]
+```
+
+That single shortcode renders:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  [🔍 Search…]                       [Sort: Most recent ↓]  │
+├──────────────┬─────────────────────────────────────────────┤
+│ Filters      │ ┌────────┐ ┌────────┐ ┌────────┐            │
+│ ──────────   │ │ Job #1 │ │ Job #2 │ │ Job #3 │            │
+│ Location     │ └────────┘ └────────┘ └────────┘            │
+│ [London ▾]   │ ┌────────┐ ┌────────┐ ┌────────┐            │
+│ Type         │ │ Job #4 │ │ Job #5 │ │ Job #6 │            │
+│ ☐ Full-time  │ └────────┘ └────────┘ └────────┘            │
+│ ☐ Contract   │ ┌────────┐ ┌────────┐ ┌────────┐            │
+│ Salary       │ │ Job #7 │ │ Job #8 │ │ Job #9 │            │
+│ [50k]──●───  │ └────────┘ └────────┘ └────────┘            │
+│ Tags         ├─────────────────────────────────────────────┤
+│ ☐ remote     │     ‹ Prev    Page 1 of 4    Next ›        │
+│ ☐ hybrid     │                                             │
+└──────────────┴─────────────────────────────────────────────┘
+```
+
+- The filter rail is **derived from the schema**: `location` (text) becomes a dropdown of distinct values, `type`
+  (select) becomes a single-pick dropdown, `salary` (number) becomes a min/max range, `tags` (multiselect) becomes
+  a checkbox group. No JS authoring required.
+- Every change updates the URL: visiting `/jobs?cb_jobs-N_filter[location]=London&cb_jobs-N_filter[salary_gte]=50000`
+  deep-links to that exact filtered view - shareable, bookmarkable, back-button-friendly.
+- All client-side by default (mode=client) - instant response.
+
+**For a pre-narrowed landing page** like `/jobs/well-paid`, bake in a constraint that users can refine but not
+escape:
+
+```markdown
+---
+title: Well-paid Roles
+---
+
+[collection slug="jobs"
+  display="cards"
+  searchable filterable="location,type" sortable
+  where_salary_gte="50000"
+  where_type_in="full-time,contract" /]
+```
+
+The `where_*` attributes are locked in - the filter rail lets visitors narrow further (e.g. only London full-time)
+but can never widen back to part-time or sub-£50k roles. Server-rendered initial view + interactive refinement,
+in one shortcode.
+
+**Mongo-backed at scale.** Once `jobs` outgrows the in-memory cap (default 1000 entries), add `mode="server"`:
+
+```markdown
+[collection slug="jobs" searchable filterable="location,type,salary,tags"
+  sortable mode="server" page-size="12" /]
+```
+
+Every filter change becomes a `GET /api/collections/jobs/public?filter[…]&page=…` round-trip; MongoAdapter
+translates the filter to a native `$gte`/`$in`/regex query and hits a B-tree index. Same UX, no payload bloat.
+
+---
+
+## 5. Build the apply form
+
+Create `content/forms/apply.json` (or via the admin Forms editor):
+
+```json
+{
+  "slug": "apply",
+  "title": "Apply for this role",
+  "fields": [
+    {
+      "name": "jobId", "type": "reference", "required": true, "label": "Position",
+      "reference": { "collection": "jobs", "displayField": "title" }
+    },
+    { "name": "coverLetter", "type": "textarea", "required": true, "label": "Cover letter" },
+    {
+      "name": "resume", "type": "file", "required": true, "label": "Resume (PDF)",
+      "file": { "accept": "application/pdf", "maxSize": 5242880 }
+    }
+  ],
+  "settings": {
+    "successMessage": "Application submitted!",
+    "successRedirect": "/dashboard",
+    "actionSlug": "submit-application",
+    "rateLimitPerMinute": 3,
+    "honeypot": true
+  },
+  "actions": {
+    "collection": { "enabled": false }
+  }
+}
+```
+
+Embed it on a generic apply page:
+
+```markdown
+[form slug="apply" /]
+```
+
+That's the whole form. The reference field auto-renders as a populated
+dropdown of all open jobs - server-side at render time, no extra round-trips,
+no JS-side fetching. No hidden ids, no denormalised job titles, no manual
+glue. **The form file declares the relationship and the platform handles the
+rest.**
+
+---
+
+## 6. Wire the apply action
+
+The form's `settings.actionSlug` references `submit-application`. Create this action (admin → Actions → New):
+
+```json
+{
+  "slug": "submit-application",
+  "title": "Submit Application",
+  "collection": "form-submissions",
+  "access": { "roles": ["candidate", "admin", "super-admin"] },
+  "steps": [
+    {
+      "type": "createInCollection",
+      "config": {
+        "targetCollection": "applications",
+        "createdBy": "{{user.id}}",
+        "data": {
+          "jobId":        "{{entry.data.jobId}}",
+          "candidateId":  "{{user.id}}",
+          "coverLetter":  "{{entry.data.coverLetter}}",
+          "status":       "submitted",
+          "submittedAt":  "{{now}}"
+        }
+      }
+    },
+    {
+      "type": "email",
+      "config": {
+        "to":       "{{user.email}}",
+        "subject":  "We received your application for {{entry.data.jobTitle}}",
+        "template": "Hi {{user.name}},\n\nThanks for applying - we'll be in touch.\n"
+      }
+    }
+  ]
+}
+```
+
+**Key trick:** the public form submission endpoint (`POST /api/forms/submit/:slug`) does an *optional* JWT verification.
+Signed-in candidates get their identity captured automatically; `{{user.id}}` and `{{user.email}}` resolve correctly
+inside the action's templates. Anonymous applicants would get blank values - for the recruitment use case, gate the
+job-detail page with `visibility: candidate` to force sign-in.
+
+The `createInCollection` step is new (introduced alongside this recipe). Unlike `moveToCollection`, it does **not**
+delete the source entry - so the original `form-submissions` record remains as an audit trail and the new
+`applications` entry is what the dashboard reads.
+
+---
+
+## 7. Candidate dashboard with "My applications"
+
+Create `content/pages/dashboard.md`:
+
+```markdown
+---
+title: My Dashboard
+visibility: [candidate, employer]
+---
+
+## My Applications
+
+[collection slug="applications"
+  scope="mine"
+  display="cards"
+  title-field="jobId"
+  fields="jobId,status,submittedAt"
+  sort="submittedAt"
+  order="desc"
+  cta="withdraw-application"
+  cta-label="Withdraw"
+  cta-icon="x-circle"
+  cta-style="danger"
+  cta-confirm="Withdraw this application?"
+  empty="You haven't applied for any roles yet." /]
+```
+
+`title-field="jobId"` doesn't show the raw id - because `jobId` is a
+**reference**, the platform resolves it to the job's title automatically. The
+card title reads "Senior Engineer", clickable to `/jobs/<id>` thanks to the
+`linkTemplate` on the schema. No denormalisation needed, no broken links when
+a job is updated.
+
+`visibility: [candidate, employer]` - both roles see the page; super-admin and admin inherit access automatically.
+`scope="mine"` makes the block render client-side via `POST /api/collections/render-scope`, which auto-applies
+`createdBy = <current user id>`. The page itself stays cached per role; only the per-user data is fetched per visit.
+
+---
+
+## 8. Wire state-machine transitions
+
+Define **one action per legal state transition** and let the platform render
+the right buttons for the right row's current state. Add `transition` to each:
+
+```json
+{
+  "slug": "withdraw-application",
+  "title": "Withdraw",
+  "collection": "applications",
+  "transition": { "field": "status", "from": ["submitted", "reviewing"], "to": "withdrawn" },
+  "access": { "roles": ["candidate"], "rowLevel": { "mode": "owner" } },
+  "steps": [
+    { "type": "updateField", "config": { "field": "status", "value": "withdrawn" } }
+  ]
+}
+```
+
+```json
+{
+  "slug": "start-review",
+  "title": "Move to reviewing",
+  "collection": "applications",
+  "transition": { "field": "status", "from": ["submitted"], "to": "reviewing" },
+  "access": { "roles": ["admin", "hr"] },
+  "steps": [
+    { "type": "updateField", "config": { "field": "status", "value": "reviewing" } },
+    { "type": "email", "config": {
+      "to": "{{user.email}}",
+      "subject": "{{entry.data.jobId}} - moved to review",
+      "template": "Application for {{entry.data.jobId}} is now in review."
+    }}
+  ]
+}
+```
+
+```json
+{
+  "slug": "schedule-interview",
+  "title": "Invite to interview",
+  "collection": "applications",
+  "transition": { "field": "status", "from": ["reviewing"], "to": "interview" },
+  "access": { "roles": ["admin", "hr"] },
+  "steps": [{ "type": "updateField", "config": { "field": "status", "value": "interview" }}]
+}
+```
+
+The candidate's dashboard from step 7 just needs `paginate` and `transitions`
+added. Transition buttons are drawn by the interactive Collection Browser, and
+`paginate` (or `searchable`, `sortable`, `filterable`) is what turns it on - a
+`scope="mine"` block then hydrates as the Browser over the candidate's own rows:
+
+```markdown
+[collection slug="applications" scope="mine" display="cards"
+  title-field="jobId"
+  fields="jobId,status,submittedAt,resume"
+  paginate
+  transitions
+  empty="You haven't applied for any roles yet." /]
+```
+
+Now each application card automatically shows the right buttons:
+
+- `submitted` → "Withdraw"
+- `reviewing` → "Withdraw"
+- `interview` → (none - candidate can't withdraw from an active interview process)
+- `offered` / `rejected` → (none - terminal)
+
+The `resume` field renders as a clickable link to the candidate's uploaded
+PDF; the recruiter's parallel dashboard (an interactive `display="table"`
+block with no `scope`) sees the same files and can run their own transitions
+(`start-review`, `schedule-interview`, etc.) thanks to the role-based
+filter in `listTransitionsForEntry`.
+
+`access.roles: ["admin", "hr"]` means either role is enough (and anyone more
+senior): an `hr` user runs `start-review` although `admin` ranks above them.
+
+Everything the candidate's block does stays inside their own rows on the
+server: the button list and every run carry `scope: "mine"`, and a row they did
+not create is refused with 403 - as is a direct call to `withdraw-application`
+on someone else's row, through its `rowLevel` owner rule.
+
+Try to skip ahead - copy an admin URL and POST it as a candidate, or POST
+`withdraw` against an already-rejected row - and you get a clean HTTP 409
+`Cannot apply "Withdraw" - current status is "rejected", allowed: submitted, reviewing`.
+**The state machine is enforced server-side; the UI just renders what's legal.**
+
+---
+
+## 9. Employer view (bonus)
+
+Add an employer dashboard at `content/pages/employer.md`:
+
+```markdown
+---
+title: Employer Dashboard
+visibility: employer
+---
+
+## My Jobs
+
+[collection slug="jobs"
+  scope="mine"
+  display="table"
+  fields="title,location,type,salary,postedAt"
+  sort="postedAt"
+  order="desc"
+  cta="archive-job"
+  cta-label="Archive"
+  cta-confirm="Archive this listing?" /]
+
+## Applications to my jobs
+
+[collection slug="applications"
+  display="table"
+  fields="jobTitle,candidateId,status,submittedAt"
+  where_jobId_in="{{ employerJobIds }}"
+  sort="submittedAt"
+  order="desc" /]
+```
+
+The second block needs cross-collection filtering (applications matching the employer's job ids). This currently
+needs a saved view - define one at `content/views/employer-applications.json` that does the join, then use
+`[view slug="employer-applications" /]`. Full cross-collection joins in `[collection]` is a future enhancement.
+
+---
+
+## Mental model - why this works
+
+| Need                        | Primitive used                                                   |
+|-----------------------------|------------------------------------------------------------------|
+| Per-role landing pages      | `visibility` (string, or array for sibling roles)                |
+| Public job listings         | `[collection]` + `api.read: public`                              |
+| Filtered listings           | `where_<field>_<op>` shortcode attributes                        |
+| Faceted browsing UI         | `[collection searchable filterable=... sortable]` (Browser)      |
+| Apply button                | `[form]` + `settings.actionSlug`                                 |
+| Apply = create link record  | Action step `createInCollection`                                 |
+| Job ↔ Application link      | `type: "reference"` field with `displayField` + `linkTemplate`   |
+| Resume upload               | `type: "file"` field with mime/size validation                   |
+| "My applications" view      | `[collection scope="mine"]` + hydration endpoint                 |
+| Lifecycle transitions       | `transition: { field, from }` on actions + `transitions` on shortcode |
+| Row-level security          | `access.rowLevel` (`mode: "owner"`) on actions                   |
+| Audit trail                 | Form submissions persist in their original collection            |
+
+No plugin code. Everything is configuration plus Markdown. The same five building blocks (collections, forms,
+actions, shortcodes, roles) compose into bookings, RSVPs, marketplaces, classifieds, internal task trackers, or
+anything else where a public page needs to read structured data, accept input, and create relational records on
+behalf of an identified user.
+
+---
+
+## Reference
+
+- `docs/markdown-shortcodes.md` - full `[collection]` and `[form]` syntax
+- `docs/api-reference.md` - filter query params, render-scope endpoint
+- `docs/configuration.md` - page frontmatter (`visibility`, `status`, ...)
+- `server/services/actions.js` - full list of action step types and template variables
+- `server/services/filterEngine.js` - full operator semantics for `where_*` attributes