Download the PHP package lumiio/cascadedocs without Composer

CascadeDocs

Automatically generate and maintain comprehensive documentation for your Laravel codebase using AI. CascadeDocs analyzes your code, organizes it into logical modules, and creates multi-tier documentation that stays in sync with your development.

Why CascadeDocs?

Modern codebases grow complex quickly. New team members struggle to understand the system architecture. Documentation becomes outdated the moment it's written. CascadeDocs solves these problems by:

• Understanding Your Code: AI analyzes your actual code structure, not just comments
• Multiple Perspectives: Three documentation tiers serve different needs:
  • Micro: Quick overview for code reviews and navigation
  • Standard: Balanced documentation for everyday development
  • Expansive: Deep dive for complex debugging and onboarding
• Living Documentation: Git integration ensures docs update only when code actually changes
• Contextual Understanding: Modules show how files work together, not just what individual files do

Perfect for AI-Powered Development

When using coding assistants like Claude Code, Cursor, or GitHub Copilot, context is everything. CascadeDocs provides:

• Module Index: Feed the modules/index.md to your AI to instantly convey your entire system architecture
• Targeted Context: Share specific module documentation to keep AI responses focused and accurate
• Consistent Code Generation: AI understands your patterns and conventions from the documented modules
• Better Recommendations: With full system context, AI agents make architectural decisions that fit your existing design

Instead of copying random files and hoping for the best, you can give your AI assistant exactly the context it needs to understand where new features should go and how they should be implemented.

Key Features

• 🤖 AI-Powered Analysis: Uses OpenAI or Claude to understand your code and generate meaningful documentation
• 📚 Three Documentation Tiers: Choose between micro (brief), standard (balanced), or expansive (detailed) documentation
• 🗂️ Automatic Module Organization: Intelligently groups related files into cohesive modules
• 🔄 Git-Based Updates: Only regenerates documentation for files that have actually changed
• 🏗️ Architecture Overview: Automatically generates high-level system architecture documentation
• ⚡ Queue Support: Process large codebases asynchronously without blocking your application
• 📊 Module Index: Provides a comprehensive overview of all modules for easy navigation

Quick Start

Installation

Setup

1. Publish the AI provider configuration:

2. Add your AI credentials to .env:

3. Publish CascadeDocs configuration:

Generate Documentation

Run these commands in order for a complete documentation setup:

Important: If you're using queue processing, wait for each command's jobs to complete before running the next command. Monitor your queue with php artisan queue:work or check your queue dashboard.

Your documentation is now available in docs/source_documents/.

Documentation Workflow

Initial Setup

When starting with a new codebase, run these commands in order, waiting for queue jobs to complete between each step:

Why wait between steps?

• Module docs need class docs to analyze file summaries
• Architecture docs need module summaries (generated by the module docs queue jobs)
• Running commands before queues complete will result in incomplete or empty documentation

Keeping Documentation Updated

As your code evolves:

The update command:

• Uses Git to detect which files have changed since the last documentation run
• Compares commit_sha in doc frontmatter against current file state
• Only regenerates documentation for files that actually changed
• Can automatically create new modules for new files that don't fit existing ones
• Saves time and API costs by avoiding redundant regeneration

Documentation Structure

Command Reference

Class Documentation

Module Documentation

Understanding the Module Workflow

CascadeDocs uses modules to group related files together. The module system has two distinct phases:

1. Module Assignment - Deciding which files belong to which modules
2. Documentation Generation - Creating documentation for those modules

Important: The update-all-modules command only updates documentation for existing modules with already-assigned files. It does NOT create new modules or assign unassigned files.

Complete Module Workflow

This command orchestrates the entire process:

1. Analyzes module structure (skipped if already done)
2. Assigns unassigned files to modules
3. Syncs module assignments
4. Updates all module documentation
5. Shows final module status

Manual Module Management

For more control over module creation:

Interactive Assignment

For maximum control:

Other Module Commands

Update Documentation

Utility Commands

Configuration

The config/cascadedocs.php file controls:

Module Granularity

The modules.granularity setting controls how the AI organizes files into modules:

• granular (default): Creates smaller, more focused modules. Each module represents a single, well-defined concern. Better for larger codebases where you want precise navigation.
• consolidated: Creates larger, broader modules. Groups related functionality together even if it serves different purposes. Better for smaller codebases or when you want fewer modules.

You can also set this via environment variable:

Tracking Files

CascadeDocs maintains several files to track state and enable efficient updates:

docs/module-assignment-log.json

Caches the AI's module organization analysis to maintain consistency across runs. This includes which files are assigned to which modules and any unassigned files.

docs/source_documents/modules/metadata/*.json

Individual module metadata including file assignments, summaries, and documentation status.

Documentation Files (YAML Frontmatter)

Each documentation file in docs/source_documents/full/ contains YAML frontmatter with:

• source_path: The original source file path
• commit_sha: The Git SHA when the documentation was generated
• doc_tier: The documentation tier level

This embedded metadata enables CascadeDocs to detect when files have changed since their documentation was last generated.

These files should be committed to your repository to maintain state across team members.

Programmatic Usage

Best Practices

1. Start with class documentation - This provides the foundation for module organization
2. Review module assignments - The AI makes intelligent suggestions, but you can manually adjust
3. Use queues for large codebases - Prevents timeouts and improves performance
4. Commit tracking files - Ensures consistent documentation across your team
5. Run updates regularly - Keep documentation in sync with code changes

Troubleshooting

"No modules found"

Run php artisan cascadedocs:generate-class-docs first to create the base documentation.

"No modules have undocumented files" but I have unassigned files

This is a common confusion. The update-all-modules command only updates documentation for files that are already assigned to modules. To handle unassigned files:

1. Run php artisan cascadedocs:module-status to see unassigned files
2. Run php artisan cascadedocs:assign-files-to-modules --auto-create to assign them to modules
3. THEN run php artisan cascadedocs:update-all-modules to generate their documentation

Remember: Module assignment and documentation generation are separate steps!

"AI response contains placeholder text"

The AI model is returning incomplete responses. Try using a different model (e.g., GPT-4 instead of GPT-3.5, or Claude instead of OpenAI).

Rate limit errors

• Ensure your queue worker is running: php artisan queue:work
• The package automatically retries with delays

Memory issues

• Use queue processing for large codebases
• Process documentation generation in smaller batches by documenting specific directories

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12
• Git (for change tracking features)
• Queue worker running (for async processing)

Testing

Contributing

Please see CONTRIBUTING for details.

Credits

• Shawn Veltman
• All Contributors

License

The MIT License (MIT). Please see License File for more information.