Skip to main content

Cronjob Documentation System

This directory contains auto-generated documentation for all cronjobs defined in system-crontab.md.

Overview​

Cronjobs are production-critical workflows that run silently in the background. This documentation system ensures:

  • 🔍 Visibility: Every cronjob has structured documentation
  • 📊 Traceability: Links from cron schedules to Symfony Command classes
  • ⚠️ Risk Assessment: Identification of critical workflows (sales, payments, stock)
  • 🔄 Freshness: Automated checks for documentation completeness and staleness
  • 🚨 CI Enforcement: Automated validation that fails on missing or outdated docs

Statistics​

  • :material-file-document-multiple: Total Entries

    164 active cron entries parsed from system crontab

  • :material-code-braces: Unique Commands

    115 unique Symfony console commands identified

  • :material-link-variant: Code Linkage

    95/115 (82%) commands linked to source files

  • :material-alert-circle: High Risk

    46 critical + 40 high risk commands

Browse by Risk Level​

:material-alert-decagram: Critical Risk (46 commands)​

Commands involving sales, payments, refunds, or stock mutations:

:material-alert: High Risk (40 commands)​

Commands with significant business impact:

:material-information: Medium Risk (8 commands)​

Supporting commands: logs, statistics, alerts, notifications

:material-help-circle: Unknown Risk (21 commands)​

Commands needing risk assessment through code inspection

Browse Alphabetically​

  • A-C - Commands starting with A through C
  • D-M - Commands starting with D through M
  • N-Z - Commands starting with N through Z

Documentation Format​

Each cronjob documentation file follows this structure:

---
title: "command:name"
type: cronjob
source: system-crontab
status: active | undocumented
last_verified: YYYY-MM-DD
schedule:
  - "*/10 * * * *"
command:
  - "full:command --with-options"
risk_level: critical | high | medium | unknown
command_class: "src/Path/To/CommandClass.php"
---

# Command Name

## Overview
...

Risk Level Definitions​

LevelDescriptionBusiness ImpactExamples
🔴 CriticalSales, payments, refunds, stock mutationsImmediate financial/inventory impactmenzzo:v2:sales:payment
🟡 HighProducts, sync, orders, importsSignificant operational impactmenzzo:v2:products
🟢 MediumLogs, stats, alerts, notificationsSupporting functionsmenzzo:statistic
⚪ UnknownNeeds assessmentNot yet determinedVarious

Usage​

Regenerate Documentation​

python3 tools/cronjob_doc_generator.py

This will:

  1. Parse docs/system-crontab.md for all active cron entries
  2. Extract unique Symfony console commands
  3. Generate documentation files in docs/cronjobs/
  4. Attempt to locate corresponding Command class files
  5. Generate docs/meta/documentation-progress.md with coverage statistics

When to Regenerate​

Run the generator whenever:

  • ✅ Cron entries are added, removed, or modified in system-crontab.md
  • ✅ Command schedules change
  • ✅ New Command classes are created
  • ✅ Command classes are moved or renamed
  • ✅ You want to refresh coverage statistics

Update System Crontab​

# 1. Update crontab
crontab -e

# 2. Document changes
php bin/console logidav:cron:document

# 3. Regenerate docs
python3 tools/cronjob_doc_generator.py

# 4. Commit
git add docs/ && git commit -m "docs: update cronjobs"

CI Enforcement​

Documentation validation should happen whenever cronjob docs are updated:

  • ✅ All cronjobs have corresponding documentation files
  • ✅ docs/meta/documentation-progress.md exists and is parseable
  • ⚠️ Warns about commands without located class files
  • ⚠️ Warns about commands with unknown risk levels
  • ⚠️ Identifies potentially stale documentation (>90 days old)
  • 📊 Reports coverage statistics

Priority Tasks​

Based on the progress report:

🔴 Critical Priority​

  1. 46 commands mutating sales, payments, refunds, or stock - REQUIRES IMMEDIATE DOCUMENTATION
  2. 20 commands with no matching Command class or unable to locate

🟡 High Priority​

  1. 40 high-risk commands with significant business impact
  2. Add @doc.* annotations to all 95 located Command classes
  3. Document business intent and side effects for all commands

⚪ Unknown Risk​

  1. 21 commands need risk assessment through code inspection

Key Principles​

  1. Crontab is Source of Truth: system-crontab.md is the authoritative definition
  2. Never Silent: Cronjobs run in background but must be documented
  3. Operational Debt: Undocumented cronjobs are technical debt
  4. Regenerate, Don't Edit: Always regenerate base docs from source
  5. Code Linkage: Documentation must trace to actual Command classes
  6. Risk First: Prioritize documenting critical workflows

!!! info "Commands Not in This System" This system tracks cronjobs only. It does NOT document:

  • API endpoints
  • Web workflows
  • Manual console commands
  • Event listeners
  • Message queue consumers

These will be addressed in separate documentation initiatives.