Skip to main content

📚 LogiDAV Documentation System

This directory contains the documentation infrastructure for the LogiDAV ERP system, with a cronjob-first approach.

Overview​

This documentation system prioritizes cronjobs as the entry point for understanding critical workflows. Cronjobs are production-critical, run silently, and represent significant operational risk if undocumented.

Directory Structure​

docs/
├── README.md                      # This file
├── system-crontab.md             # ⭐ SOURCE OF TRUTH for all cronjobs
├── cronjobs/                     # Auto-generated cronjob documentation
│   ├── README.md                 # Cronjob documentation system guide
│   ├── menzzo-v2-sales.md
│   ├── menzzo-v2-products.md
│   └── ... (115 cronjob docs)
├── meta/
│   └── documentation-progress.md # Coverage tracking and TODO list
└── [other docs...]

Quick Start​

View Documentation Coverage​

cat docs/meta/documentation-progress.md

Current status:

  • 164 total cron entries
  • 115 unique commands
  • 95 documented (82% coverage)
  • 20 undocumented (18% needing investigation)
  • 46 critical risk commands (sales, payments, refunds, stock)

Generate/Update Documentation​

python3 tools/cronjob_doc_generator.py

This regenerates all cronjob documentation from system-crontab.md.

Validate Documentation​

# Regenerate the cronjob docs locally
python3 tools/cronjob_doc_generator.py

# Then verify the updated docs before pushing
git diff -- docs/

🎯 Documentation Philosophy​

1. Cron-First Approach​

Why cronjobs first?

  • 🔍 Silent Workflows: Run in background without visibility
  • ⚠️ Production Critical: Sales, payments, stock mutations happen here
  • 🚨 High Risk: Failures can have immediate business impact
  • 📊 Discoverable: System crontab is a concrete artifact
  • 🔗 Traceable: Maps to concrete Symfony Command classes

Cronjobs are the entry point to understanding:

  • What automated workflows exist
  • When they run and how often
  • What data they touch
  • What external systems they interact with

2. Code-First Documentation​

  • Documentation is generated from source (system-crontab.md)
  • Validation runs in the documented update flow before changes are pushed
  • Documentation should not get out of sync when the generator is rerun after cron changes
  • Manual enhancements are layered on top of generated structure

3. Obsolescence by Design​

All documentation includes:

last_verified: YYYY-MM-DD
regeneration:
  trigger: "Cron definition or command code changed"
  instruction: "Re-run documentation agent"

This makes staleness explicit rather than hidden.

4. Risk-First Prioritization​

Commands are classified by risk:

  • 🔴 CRITICAL (46): Sales, payments, refunds, stock mutations
  • 🟡 HIGH (40): Products, sync, orders, imports
  • 🟢 MEDIUM (8): Logs, stats, alerts, notifications
  • ⚪ UNKNOWN (21): Needs assessment

Critical commands must be documented first.

📋 System Components​

1. Source of Truth: system-crontab.md​

  • Contains the actual production crontab
  • Generated by: php bin/console logidav:cron:document
  • Last synced: 2025-12-05 14:33:07
  • Update whenever cron entries change

2. Generator: tools/cronjob_doc_generator.py​

Python script that:

  • Parses system-crontab.md
  • Extracts all active cron entries (ignoring comments)
  • Generates unique identifiers for each command
  • Attempts to locate Symfony Command class files
  • Determines risk levels based on command patterns
  • Generates structured Markdown documentation
  • Updates progress tracking

Run after any crontab changes.

3. Documentation: docs/cronjobs/​

Auto-generated Markdown files, one per unique command:

  • Structured frontmatter (YAML)
  • Schedule information
  • Command details
  • Risk assessment
  • Status tracking
  • Code linkage (when found)

Do not manually edit generated sections. Add manual enhancements below.

4. Progress Tracking: docs/meta/documentation-progress.md​

Central report showing:

  • Total cronjob count
  • Documentation coverage %
  • Critical risk commands
  • Commands without located classes
  • High-priority TODOs

Regenerated automatically with the documentation.

5. CI Enforcement​

Documentation checks in the team's review and Jenkins flow should ensure that:

  • ✅ Validates all cronjobs have documentation
  • ✅ Checks progress report exists and is parseable
  • ⚠️ Warns about undocumented commands
  • ⚠️ Warns about unknown risk levels
  • ⚠️ Identifies stale docs (>90 days old)
  • 📊 Reports coverage in review updates

Re-run documentation checks when changing:

  • docs/system-crontab.md
  • docs/cronjobs/**
  • docs/meta/documentation-progress.md
  • tools/cronjob_doc_generator.py

🚀 Getting Started​

For Developers​

  1. Understand what cronjobs do:

    # See the full list
    cat docs/system-crontab.md

    # Check documentation for a specific command
    cat docs/cronjobs/menzzo-v2-sales.md

  2. Find the code:

    • Check the command_class field in the doc's frontmatter
    • Or search: find src/ -name "*Command.php" | xargs grep "setName('menzzo:v2:sales')"

  3. Understand the business impact:

    • Check the risk_level field
    • Review docs/meta/documentation-progress.md for critical commands
    • Read the "Intent & Purpose" section (may be incomplete)

For Operations​

  1. Monitor documentation coverage:

    cat docs/meta/documentation-progress.md

  2. Prioritize critical commands:

    • Focus on 46 critical risk commands first
    • These involve money and inventory

  3. Keep docs current:

    • After crontab changes: re-run generator
    • After command code changes: update last_verified date
    • Review stale docs quarterly

For Maintainers​

  1. Add new cronjobs:

    # 1. Update system crontab
    crontab -e

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

    # 3. Regenerate docs
    python3 tools/cronjob_doc_generator.py

    # 4. Commit everything
    git add docs/
    git commit -m "docs: add new cronjob for X"

  2. Remove cronjobs:

    # 1. Remove from crontab
    crontab -e

    # 2. Update system-crontab.md
    php bin/console logidav:cron:document

    # 3. Regenerate docs (old doc will remain but be marked stale)
    python3 tools/cronjob_doc_generator.py

    # 4. Optionally delete the old doc file
    rm docs/cronjobs/old-command.md

  3. Enhance documentation:

    # 1. Find the command class
    find src/ -name "*Command.php" | xargs grep "setName('command:name')"

    # 2. Add @doc.* annotations to the class:
    /**
     * @doc.intent: Clear business purpose in one sentence
     * @doc.side_effects: What data does this mutate?
     * @doc.risk: Why is this critical/high/medium risk?
     * @doc.dependencies: External systems it calls
     * @doc.recovery: What to do if it fails
     */

    # 3. Regenerate to pick up changes
    python3 tools/cronjob_doc_generator.py

    # 4. Manually enhance the generated doc if needed
    # (Add sections below the generated content)

📊 Current Status​

As of 2026-01-08:

Overall Coverage​

  • ✅ 82% of commands have located class files
  • ⚠️ 18% need manual investigation
  • 🔴 46 critical risk commands identified
  • 🟡 40 high risk commands identified

Top Priorities​

  1. Document critical risk commands (46 commands)

    • Focus on sales, payment, refund, stock workflows
    • Add @doc.* annotations to command classes
    • Complete business intent documentation

  2. Locate missing command classes (20 commands)

    • Some may be external scripts (not Symfony commands)
    • Update finder logic if patterns change
    • Mark as "external" if truly non-Symfony

  3. Assess unknown risk commands (21 commands)

    • Review command code
    • Determine actual business impact
    • Update risk level in documentation

  4. Add @doc. annotations* (all 115 commands)

    • Structured tags in command class docblocks
    • Makes intent machine-readable
    • Enables automated documentation enhancement

🔄 Maintenance Workflow​

Weekly​

  • Review CI warnings on PRs
  • Address high-priority TODOs
  • Keep coverage above 80%

Monthly​

  • Review documentation-progress.md
  • Update docs for frequently-changing commands
  • Verify critical commands are still accurate

Quarterly​

  • Check for stale docs (>90 days)
  • Reassess risk levels
  • Update documentation standards

On Crontab Changes​

  • Update system-crontab.md (via console command)
  • Regenerate all documentation
  • Review new/changed cronjobs
  • Commit all changes together

🎓 Best Practices​

DO​

✅ Run generator after crontab changes
✅ Commit system-crontab.md and generated docs together
✅ Add @doc.* annotations to command classes
✅ Prioritize critical risk commands
✅ Let CI catch documentation drift
✅ Update last_verified dates when reviewing

DON'T​

❌ Manually edit generated documentation sections
❌ Commit crontab changes without updating docs
❌ Ignore CI warnings
❌ Leave critical commands undocumented
❌ Skip risk assessment
❌ Update docs without regenerating

🔧 Troubleshooting​

Generator fails to find command classes​

Problem: Command class path not found

Solutions:

  1. Search manually: find src/ -name "*Command.php" | xargs grep "setName('command:name')"
  2. Check if command uses different naming pattern
  3. Update finder logic in tools/cronjob_doc_generator.py
  4. Mark as external if it's not a Symfony command

CI fails on PR​

Problem: Documentation validation errors

Solutions:

  1. Check the Jenkins logs for the specific error
  2. Regenerate the docs locally with python3 tools/cronjob_doc_generator.py
  3. Regenerate documentation if out of sync
  4. Commit missing or updated files

Documentation seems stale​

Problem: Content doesn't match current code

Solutions:

  1. Check last_verified date in doc frontmatter
  2. Review command class for changes
  3. Update system-crontab.md if schedule changed
  4. Regenerate documentation: python3 tools/cronjob_doc_generator.py
  5. Update last_verified to today

Can't determine risk level​

Problem: Command risk is marked "unknown"

Solutions:

  1. Read the command class code
  2. Identify what data it touches (sales? products? logs?)
  3. Assess business impact (money? inventory? just metrics?)
  4. Update risk level in generated doc
  5. Consider adding @doc.risk annotation to code

🚧 Future Enhancements​

Phase 2: Code Annotations (TODO)​

  • Define @doc.* annotation schema
  • Add annotations to all 115 command classes
  • Update generator to extract and use annotations
  • Auto-populate "Intent & Purpose" sections

Phase 3: API Workflows (TODO)​

  • Document REST API endpoints
  • Link endpoints to services and controllers
  • Identify data mutations in API layer
  • Apply similar validation in the team's delivery process

Phase 4: Event Listeners (TODO)​

  • Document Symfony event subscribers
  • Trace event flows through the system
  • Identify side effects of events
  • Document coupling between modules

Phase 5: Integration (TODO)​

  • Link cronjobs to APIs they call
  • Document data flow between components
  • Build dependency graphs
  • Identify circular dependencies

📞 Support​

For questions or issues with the documentation system:

  1. Check this README
  2. Review docs/cronjobs/README.md
  3. Look at docs/meta/documentation-progress.md
  4. Check Jenkins logs for validation errors
  5. Discuss with the team

📝 Related Files​

Remember: Undocumented cronjobs are operational debt. This system exists to make that debt visible and actionable.