Documenting internal processes

This guide explains how technical process documentation works in the DeepSkill docs repo and gives a step-by-step workflow for developers who add or extend a process.

Audience: Engineers working in platform, strapi-docker, or documentation.

Outcome: A published page under Processes → Detailed Process Documentation (and optionally links from hubs and user journeys).

---

How process documentation is structured

We use a three-layer model so behaviour stays tied to code while readers get readable docs.

Layer	Location	Purpose
Code comments	platform/, strapi-docker/	Single source of truth at the implementation; @process-id, @process-step, triggers, side effects
Process manifests	documentation/process-registry/<PROCESS-ID>.yml	Structured definition of the full flow (steps, repos, files, conditions)
Generated pages	documentation/docs/internal/processes/detailed/	Docusaurus pages with overview tables, Mermaid diagrams, and step breakdowns

Backend (strapi-docker): On merge to main / develop, CI can extract @process-id comments and update manifests automatically. See Backend-triggered process docs.

Frontend (platform): Use the same comment tags; manifests are updated manually or via planned platform merge tooling. Until then, authors maintain YAML in process-registry/ alongside platform comments.

Do not edit generated detailed/*.md by hand — change manifests (and code comments), then regenerate.

---

When to document a process

Create or extend process documentation when a workflow:

• Spans frontend and backend (or multiple services)
• Has implicit steps (lifecycle hooks, emails, background jobs) that are not obvious from the UI
• Involves team handoffs (e.g. Sales → Team Learning)
• Is referenced from user journeys or operational hubs (e.g. Program configuration & batches)
• Is hard to debug without a end-to-end step list

Skip process docs for trivial single-function helpers, one-off scripts, or pure UI layout with no cross-system effects.

---

Process ID and step numbering

Process ID

• Format: SCREAMING-KEBAB-CASE (e.g. PUBLISH-BATCH, PROGRAM-CONFIGURATION-HANDOVER)
• Same ID in every repository and in the YAML filename: PUBLISH-BATCH.yml
• Stable over time — do not rename lightly (breaks links and journey JSON)

Step numbers

Pattern	Meaning
1.0, 2.0	Major steps — often user action, repo boundary, or actor change
1.1, 1.2	Sub-steps under the previous major step

Increment the major number when:

• Crossing platform → strapi-docker
• Switching actor (user → system, Sales → Learning)
• Starting a clearly separate phase (request → validation → side effects)

Link steps with @triggers / @triggered-by (or manifest triggers / triggered-by) so the generator can build sequence diagrams.

---

Step-by-step: add a new process

1. Define scope and ID

• Agree on PROCESS-ID and a short human name.
• List repositories involved and owners (teams).
• Outline major steps (1.0, 2.0, …) before touching code.

2. Add process comments in source code

Tag every meaningful step in platform and/or strapi-docker.

Required tags:

Tag	Example
@process-id	PUBLISH-BATCH
@process-step	1.0
@repo	platform or strapi-docker
@description	What happens and why it matters

Use when applicable:

Tag	Use for
@explicit / @implicit	User-initiated vs automatic
@triggers / @triggered-by	Flow between steps (PUBLISH-BATCH:1.1)
@api-call	POST /batches/:id/publish
@lifecycle	Strapi hooks (beforeUpdate, …)
@side-effect	DB updates, emails, state changes
@condition	When a branch runs
@error-handling	Failure behaviour

Frontend — explicit user action:

/**
 * @process-id PROGRAM-CONFIGURATION-HANDOVER
 * @process-step 1.0
 * @repo platform
 * @description User confirms handover of the program configuration to Team Learning
 * @explicit
 * @triggers PROGRAM-CONFIGURATION-HANDOVER:1.1
 */
const handleHandover = async () => {
  // ...
};

Backend — implicit lifecycle hook:

/**
 * @process-id PROGRAM-CONFIGURATION-HANDOVER
 * @process-step 2.1
 * @repo strapi-docker
 * @lifecycle beforeUpdate
 * @triggered-by PROGRAM-CONFIGURATION-HANDOVER:2.0
 * @description Records configuration change history before persist
 * @implicit
 * @triggers PROGRAM-CONFIGURATION-HANDOVER:2.2
 */

Full tag reference: .cursor/rules/process-documentation.mdc in the documentation repo.

3. Create or update the YAML manifest

Path: documentation/process-registry/<PROCESS-ID>.yml

Naming: Filename must match process ID (e.g. PUBLISH-BATCH.yml).

Minimal structure:

process:
  id: PUBLISH-BATCH
  name: Publish batch
  description: |
    What this process does from the user's and system's perspective.
  owner:
    - team-platform
  repositories:
    - platform
    - strapi-docker

steps:
  - id: "1.0"
    type: user-action          # user-action | frontend-action | api-request | backend-action | lifecycle-hook | email-notification
    repo: platform
    file: src/path/to/file.tsx
    line: 42
    description: User clicks Publish on the batch editor
    explicit: true
    triggers: PUBLISH-BATCH:2.0

  - id: "2.0"
    type: api-request
    repo: strapi-docker
    file: src/api/batch/controllers/batch.js
    line: 343
    description: Publishes the batch after pre-checks
    explicit: true
    endpoint: POST /batches/:id/publish
    side-effects:
      - Sets batch published state

implicit-vs-explicit:
  explicit-actions:
    - "1.0: User clicks Publish"
  implicit-actions:
    - "2.1: Pre-publish validation in program service"

Use an existing manifest as a template: process-registry/PROGRAM-CONFIGURATION-HANDOVER.yml.

For backend-only flows, CI may create or refresh the manifest from code comments; still review the YAML before merging.

4. Generate documentation

From the documentation repository root:

# One process
node scripts/generate-process-docs.js PUBLISH-BATCH

# All manifests
node scripts/generate-process-docs.js

This writes docs/internal/processes/detailed/<slug>.md and updates the Detailed Process Documentation items in sidebars.js for generated pages.

Preview locally:

npm run start

Open the new page under Processes.

5. Wire navigation and cross-links

If applicable	Action
Batch / configuration theme	Add a row to Program configuration & batches
User journey step	Add to processes in src/data/journeys/<journey>.json with link to /docs/internal/processes/detailed/<slug>
Frontend-only behaviour	Consider systems docs instead of a YAML process
Processes overview	Mention in Processes overview if top-level

Journey processes entry example:

{
  "id": "publish-batch",
  "title": "Publish batch",
  "type": "process",
  "link": "/docs/internal/processes/detailed/publish-batch",
  "description": "Backend publish flow and pre-checks"
}

6. Open a pull request

Documentation repo PR should include:

• process-registry/<PROCESS-ID>.yml (new or updated)
• Generated docs/internal/processes/detailed/*.md (if not applied by CI)
• Hub / journey / sidebar updates when relevant

Application repo PR(s) should include:

• @process-id comments on new or changed steps

Review checklist:

• Process ID is consistent in code, YAML, and links
• Explicit and implicit steps are documented
• File paths and line numbers in the manifest match the code (or will after merge)
• triggers / triggered-by form a coherent chain
• Regenerated docs were committed (or CI will commit them)
• No secrets or env-specific values in descriptions

---

Best practices

Do

• Document side effects — emails, DB fields, locks, notifications; these are what operations teams need most.
• Prefer one process per cohesive workflow — split only when flows are independently triggered and maintained.
• Update manifests when behaviour changes — treat YAML like code in review.
• Use first sentence of @description as the step title — the generator uses it for headings.
• Link related processes in YAML (related-processes) and in hub pages.

Avoid

• Different IDs for the same flow in platform vs strapi-docker.
• Skipping implicit steps — hooks and validations are usually where bugs hide.
• Editing generated Markdown — always regenerate from manifests.
• Documenting every function — reserve process IDs for multi-step, cross-system workflows.
• Vague descriptions — “updates batch” → “Sets publishedAt and disables draft edits via batch lock rules”.

Maintenance

1. Change code → update comments → update YAML → run generator.
2. During code review, ask: “Does this change need a manifest or step update?”
3. Periodically verify links from journeys and hubs still match slugs under detailed/.

---

Repository map

documentation/
├── process-registry/           # YAML manifests (source for generation)
│   └── PROCESS-ID.yml
├── scripts/
│   ├── generate-process-docs.js
│   ├── process-comments-to-manifests.js   # CI: JSON → YAML
│   └── extract-process-comments.js      # in strapi-docker CI
├── docs/internal/
│   ├── developer/              # this guide
│   └── processes/
│       ├── processes-overview.md
│       ├── program-configuration-and-batches.md   # thematic hub
│       └── detailed/           # generated — do not hand-edit
└── src/data/journeys/          # optional process links per step

---

Further reading

Resource	Content
Process registry README (documentation/process-registry/README.md)	Manifest conventions and generator usage
Backend-triggered process docs	CI pipeline from strapi-docker to manifests
Process documentation guide	Industry context and automation options
Processes overview	Reader-facing process catalogue
.cursor/rules/process-documentation.mdc	Authoritative tag and YAML reference for editors

---

Example end-to-end

Artifact	Location
Manifest	process-registry/PROGRAM-CONFIGURATION-HANDOVER.yml
Generated page	Program configuration handover
Thematic hub	Program configuration & batches
Journey link	Create/Edit Batch journey → confirmation / publish steps