Backend-Triggered Process Documentation Workflow

This guide explains the recommended approach for automatically extracting and publishing process documentation from backend code comments on merge.

🏗️ Architecture Overview

┌─────────────────────────────────────────┐
│  Developer writes code with process     │
│  comments in strapi-docker repository   │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Code merged to main or develop branch  │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────────────┐
│  GitHub Actions Workflow Triggered                          │
│  (extract-and-publish-process-docs.yml)                    │
└──────────────┬────────────────────────────────────────────┘
               │
       ┌───────┴───────┬───────────────────┬──────────────┐
       ▼               ▼                   ▼              ▼
   [1.Extract]    [2.Convert]        [3.Generate]   [4.Publish]
   Comments      to Manifests         Documentation  to Docs Repo
   from Code         YAML              Markdown
       │               │                   │              │
       └───────────────┴───────────────────┴──────────────┘
                       │
                       ▼
        ┌──────────────────────────────────┐
        │ Documentation Repository Updated │
        │ with Latest Process Docs         │
        └──────────────────────────────────┘

🔄 Workflow Steps

Step 1: Extract Process Comments (Backend Repo)

Trigger: On push to main or develop if src/ files changed

Process:

Checkout strapi-docker repository
Run scripts/extract-process-comments.js
Scans all .js, .ts, .jsx, .tsx files in src/ and config/
Finds JSDoc blocks containing @process-id
Outputs process-comments.json

Output Example:

[
  {
    "processId": "PROGRAM-CONFIGURATION-HANDOVER",
    "processStep": "2.1",
    "repo": "strapi-docker",
    "description": "Automatically tracks configuration changes before save",
    "explicit": false,
    "lifecycle": "beforeUpdate",
    "file": "src/api/program-configuration/content-types/program-configuration/lifecycles.js",
    "line": 42,
    "function": "checkChangeHistoryGeneration"
  }
]

Step 2: Convert Comments to Manifests (Documentation Repo)

Process:

Checkout documentation repository
Run scripts/process-comments-to-manifests.js
Groups comments by processId
Creates YAML manifest files in process-registry/
One .yml file per process

Manifest Generated:

process:
  id: PROGRAM-CONFIGURATION-HANDOVER
  name: Program Configuration Handover
  description: Auto-generated process documentation extracted from strapi-docker code comments.
  owner:
    - team-platform
  repositories:
    - strapi-docker
  lastUpdated: 2024-01-23T10:15:30.000Z

steps:
  - id: '2.1'
    type: lifecycle-hook
    repo: strapi-docker
    description: Automatically tracks configuration changes before save
    explicit: false
    lifecycle: beforeUpdate
    file: src/api/program-configuration/content-types/program-configuration/lifecycles.js
    line: 42
    function: checkChangeHistoryGeneration

implicit-vs-explicit:
  explicit-actions: []
  implicit-actions:
    - '2.1: Automatically tracks configuration changes before save'

Step 3: Generate Documentation (Documentation Repo)

Process:

Run existing scripts/generate-process-docs.js
Reads YAML manifests from process-registry/
Generates Markdown pages with:
- Step-by-step breakdowns
- Mermaid sequence diagrams
- Code references
- Explicit vs implicit actions

Output: docs/internal/processes/detailed/program-configuration-handover.md

Step 4: Publish to Documentation Repository

Process:

Commit manifests and generated docs
Push to documentation repository
Docusaurus builds automatically
Updated documentation goes live

📁 File Structure

In strapi-docker Repository

strapi-docker/
├── .github/workflows/
│   └── extract-and-publish-process-docs.yml    ← Main workflow
├── scripts/
│   ├── extract-process-comments.js             ← Extraction script
│   └── process-comments-to-manifests.js        ← Conversion script
└── src/
    └── api/
        └── program-configuration/
            └── content-types/
                └── program-configuration/
                    └── lifecycles.js          ← Code with @process-id comments

In documentation Repository

documentation/
├── process-registry/
│   ├── PROGRAM-CONFIGURATION-HANDOVER.yml    ← Auto-generated manifest
│   ├── BATCH-CREATE-AND-LIFECYCLE.yml
│   └── ...
├── docs/internal/processes/detailed/
│   ├── program-configuration-handover.md     ← Auto-generated docs
│   ├── batch-create-and-lifecycle.md
│   └── ...
└── scripts/
    └── generate-process-docs.js               ← Existing generator

🔑 Key Features

1. Developer-Friendly

Developers document processes where they code
Familiar JSDoc syntax
No extra tools needed

2. Automatic on Merge

No manual steps required
Documentation always in sync with code
Triggered only when relevant files change

3. Cross-Repository Coordination

Workflow runs in backend repo
Pushes changes to documentation repo
Uses DOCUMENTATION_REPO_TOKEN for authentication

4. Detailed Tracking

Stores file paths and line numbers
Links to specific functions
Preserves original code context

5. Smart Detection

Only triggers on code changes in src/
Only processes files with @process-id comments
Skips if no changes detected

📝 Process Comment Format

Required Tags

/**
 * @process-id PROCESS-ID-IN-CAPS
 * @process-step 1.0
 * @repo strapi-docker
 * @description Clear description of what this step does
 */

Optional Tags

/**
 * @process-name Human Readable Process Name
 * @explicit                    // User-initiated action
 * @implicit                    // Automatic action
 * @triggered-by PROCESS:1.0   // Which step triggered this
 * @triggers PROCESS:1.1       // What this triggers
 * @condition When this executes
 * @side-effect Sets configuration.handoverDatetime
 * @lifecycle beforeUpdate      // Strapi hook name
 * @endpoint PUT /api/program-configuration/:id
 * @api-call PUT request to backend
 * @validation Check for required fields
 * @error-handling Log error to Sentry
 */

🔐 Setup Requirements

1. GitHub Token in Backend Repo

In strapi-docker repository settings:

Secrets and variables → Actions secrets → New repository secret
Name: DOCUMENTATION_REPO_TOKEN
Value: [Personal access token with repo access to documentation repo]

Required Permissions:

repo - Full repository access
workflow - Workflow permissions

2. Ensure js-yaml Package

In both repositories:

npm install js-yaml

🚀 Implementation Steps

1. Add Workflow to Backend Repo

Copy extract-and-publish-process-docs.yml to:

strapi-docker/.github/workflows/extract-and-publish-process-docs.yml

2. Add Extraction Scripts to Backend Repo

Copy scripts to strapi-docker:

strapi-docker/scripts/extract-process-comments.js
strapi-docker/scripts/process-comments-to-manifests.js

3. Create Test Process

Add a process comment to test code:

// strapi-docker/src/api/example/controllers/example.js

/**
 * @process-id TEST-PROCESS-EXAMPLE
 * @process-step 1.0
 * @repo strapi-docker
 * @description Example process to test documentation workflow
 * @explicit User clicks example button
 * @triggers TEST-PROCESS-EXAMPLE:2.0
 */
const exampleController = async (ctx) => {
  // Implementation
};

4. Commit and Push

cd strapi-docker
git add .github/workflows/extract-and-publish-process-docs.yml
git add scripts/extract-process-comments.js
git add scripts/process-comments-to-manifests.js
git commit -m "feat: add process documentation extraction workflow"
git push origin develop

5. Create PR to main/develop with Test Comment

This will trigger the workflow. Check:

Backend Repo - Workflow run status
Documentation Repo - New manifest file created
Documentation Site - New documentation page generated

🔍 Testing the Workflow

Local Testing

Step 1: Extract comments locally

cd strapi-docker
node scripts/extract-process-comments.js
cat process-comments.json

Step 2: Convert to manifests

node scripts/process-comments-to-manifests.js \
  --input process-comments.json \
  --output /path/to/documentation/process-registry \
  --source strapi-docker

Step 3: Generate documentation

cd documentation
node scripts/generate-process-docs.js

Step 4: View generated files

ls docs/internal/processes/detailed/
cat docs/internal/processes/detailed/test-process-example.md

GitHub Actions Testing

Watch the workflow run:
- Go to strapi-docker → Actions
- Select "Extract and Publish Process Documentation"
- Click the latest run
Check job summary:
- Shows extraction results
- Reports manifests generated
- Indicates if documentation repo was updated
Verify in documentation repo:
- Check for new manifest files in process-registry/
- Check for new documentation pages in docs/internal/processes/detailed/
- Verify generated Markdown looks correct

📊 Workflow Job Summary

The workflow provides detailed summaries:

📚 Process Documentation Extraction & Publication

Source Repository: DeepSkill/strapi-docker
Commit: abc123def456
Branch: develop

Extraction Results
- Process Comments Found: 3

Manifest Generation
- Manifests Updated: 3
- Status: ✅ Changes detected

Documentation Generation
- Documentation Pages Generated: 3
- Status: ✅ Committed and pushed to documentation repository

Documentation Repository: DeepSkill/documentation

⚙️ Workflow Configuration

Trigger Conditions

The workflow triggers when:

Code is pushed to main or develop branch
AND files in src/ directory were changed
This prevents unnecessary runs on non-code changes

Required Secrets

Secret	Where	Purpose
`DOCUMENTATION_REPO_TOKEN`	strapi-docker	Push to documentation repository
`GITHUB_TOKEN`	(auto)	Checkout and workflow operations

Concurrency

The workflow:

✅ Can run in parallel with other workflows
✅ Handles multiple processes gracefully
✅ Only commits if changes detected (prevents noise)

🐛 Troubleshooting

Workflow doesn't trigger

Problem: Workflow not running on push

Solutions:

Check branch is main or develop
Verify src/ files were actually changed
Check workflow file is in .github/workflows/
Verify workflow is enabled in repository settings

Token issues

Problem: "Permission denied" when pushing to documentation repo

Solutions:

Generate new personal access token
Verify token has repo scope
Update DOCUMENTATION_REPO_TOKEN secret
Test with: git ls-remote https://token@github.com/DeepSkill/documentation.git

No manifests generated

Problem: Process comments not extracted

Solutions:

Verify comment format uses @process-id tag
Ensure comments are JSDoc blocks (/** ... */)
Check file is in src/ or config/ directory
Run extraction script locally to debug: node scripts/extract-process-comments.js

Documentation generation fails

Problem: Generated Markdown is empty or invalid

Solutions:

Check manifest YAML is valid: node -e "require('js-yaml').load(require('fs').readFileSync('file.yml'))"
Verify manifest has required fields
Review generate-process-docs.js for errors
Check existing manifest files for format reference

🎓 Best Practices

Do's ✅

✅ Add @process-id for all multi-step processes
✅ Document implicit actions (automatic behaviors)
✅ Link steps with @triggers and @triggered-by
✅ Include clear descriptions
✅ Review workflow summaries after merge

Don'ts ❌

❌ Document every function (only cross-system processes)
❌ Use different process IDs for same workflow
❌ Forget @repo strapi-docker tag
❌ Skip implicit actions in documentation
❌ Assume process is documented without checking

Backend API Documentation Export:

strapi-docker/.github/workflows/export-api-docs.yml
Exports OpenAPI specs
Triggers on similar schedule

Documentation Deployment:

documentation/.github/workflows/deploy.yml
Builds and deploys Docusaurus site
Triggered on documentation repo changes

❓ Questions?

Contact the platform team for questions about process documentation automation.

🏗️ Architecture Overview​

🔄 Workflow Steps​

Step 1: Extract Process Comments (Backend Repo)​

Step 2: Convert Comments to Manifests (Documentation Repo)​

Step 3: Generate Documentation (Documentation Repo)​

Step 4: Publish to Documentation Repository​

📁 File Structure​

In strapi-docker Repository​

In documentation Repository​

🔑 Key Features​

1. Developer-Friendly​

2. Automatic on Merge​

3. Cross-Repository Coordination​

4. Detailed Tracking​

5. Smart Detection​

📝 Process Comment Format​

Required Tags​

Optional Tags​

🔐 Setup Requirements​

1. GitHub Token in Backend Repo​

2. Ensure js-yaml Package​

🚀 Implementation Steps​

1. Add Workflow to Backend Repo​

2. Add Extraction Scripts to Backend Repo​

3. Create Test Process​

4. Commit and Push​

5. Create PR to main/develop with Test Comment​

🔍 Testing the Workflow​

Local Testing​

GitHub Actions Testing​

📊 Workflow Job Summary​

⚙️ Workflow Configuration​

Trigger Conditions​

Required Secrets​

Concurrency​

🐛 Troubleshooting​

Workflow doesn't trigger​

Token issues​

No manifests generated​

Documentation generation fails​

📚 Related Documentation​

🎓 Best Practices​

Do's ✅​

Don'ts ❌​

🔗 Related Workflows​

❓ Questions?​

🏗️ Architecture Overview

🔄 Workflow Steps

Step 1: Extract Process Comments (Backend Repo)

Step 2: Convert Comments to Manifests (Documentation Repo)

Step 3: Generate Documentation (Documentation Repo)

Step 4: Publish to Documentation Repository

📁 File Structure

In strapi-docker Repository

In documentation Repository

🔑 Key Features

1. Developer-Friendly

2. Automatic on Merge

3. Cross-Repository Coordination

4. Detailed Tracking

5. Smart Detection

📝 Process Comment Format

Required Tags

Optional Tags

🔐 Setup Requirements

1. GitHub Token in Backend Repo

2. Ensure js-yaml Package

🚀 Implementation Steps

1. Add Workflow to Backend Repo

2. Add Extraction Scripts to Backend Repo

3. Create Test Process

4. Commit and Push

5. Create PR to main/develop with Test Comment

🔍 Testing the Workflow

Local Testing

GitHub Actions Testing

📊 Workflow Job Summary

⚙️ Workflow Configuration

Trigger Conditions

Required Secrets

Concurrency

🐛 Troubleshooting

Workflow doesn't trigger

Token issues

No manifests generated

Documentation generation fails

📚 Related Documentation

🎓 Best Practices

Do's ✅

Don'ts ❌

🔗 Related Workflows

❓ Questions?