PHPackages lumiio/cascadedocs - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. lumiio/cascadedocs ActiveLibrary[Utility & Helpers](/categories/utility) lumiio/cascadedocs ================== AI-powered documentation generation for Laravel applications v0.4.4(5mo ago)03261[4 PRs](https://github.com/dataffinityhealth/CascadeDocs/pulls)MITPHPPHP ^8.2CI passing Since Jul 7Pushed 1mo agoCompare [ Source](https://github.com/dataffinityhealth/CascadeDocs)[ Packagist](https://packagist.org/packages/lumiio/cascadedocs)[ Docs](https://github.com/lumiio/cascadedocs)[ GitHub Sponsors](https://github.com/Lumiio)[ RSS](/packages/lumiio-cascadedocs/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (18)Versions (27)Used By (0) CascadeDocs =========== [](#cascadedocs) [![Latest Version on Packagist](https://camo.githubusercontent.com/df40ec0ad617425a12f146c04276ebab136507268b6db98c94d56b8c3f0192e0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c756d69696f2f63617363616465646f63732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lumiio/cascadedocs)[![GitHub Tests Action Status](https://camo.githubusercontent.com/b77a6eabc4cbbb5b38e89878fc56829307f1e547b4f6c990e0f59db55a3fc011/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6c756d69696f2f63617363616465646f63732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/lumiio/cascadedocs/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/f53459d3092265cfa7b77375241a3e2294ddd58cf24410137a8806fe180dba21/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6c756d69696f2f63617363616465646f63732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/lumiio/cascadedocs/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/b45461966ea78ebd01f9aa8d99c6c59a34208d7841cf2aae6026cabede12fa22/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c756d69696f2f63617363616465646f63732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/lumiio/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? ---------------- [](#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 [](#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 ------------ [](#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 ----------- [](#quick-start) ### Installation [](#installation) ``` composer require lumiio/cascadedocs ``` ### Setup [](#setup) 1. **Publish the AI provider configuration:** ``` php artisan vendor:publish --provider="Shawnveltman\LaravelOpenai\LaravelOpenaiServiceProvider" ``` 2. **Add your AI credentials to `.env`:** ``` # For OpenAI OPENAI_API_KEY=your-openai-api-key OPENAI_ORGANIZATION=your-org-id # Optional # For Claude/Anthropic ANTHROPIC_API_KEY=your-anthropic-api-key ``` 3. **Publish CascadeDocs configuration:** ``` php artisan vendor:publish --tag="cascadedocs-config" ``` ### Generate Documentation [](#generate-documentation) Run these commands in order for a complete documentation setup: ``` # 1. Generate documentation for all your classes php artisan cascadedocs:generate-class-docs # 2. Organize files into logical modules and create module documentation php artisan cascadedocs:generate-module-docs # 3. Generate high-level architecture documentation php artisan cascadedocs:generate-architecture-docs ``` **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 ---------------------- [](#documentation-workflow) ### Initial Setup [](#initial-setup) When starting with a new codebase, run these commands **in order**, waiting for queue jobs to complete between each step: ``` # Step 1: Generate class documentation (queued) php artisan cascadedocs:generate-class-docs # ⏳ Wait for queue to complete: php artisan queue:work # Step 2: Generate module documentation (queued) php artisan cascadedocs:generate-module-docs # ⏳ Wait for queue to complete: php artisan queue:work # Step 3: Generate architecture documentation php artisan cascadedocs:generate-architecture-docs ``` **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 [](#keeping-documentation-updated) As your code evolves: ``` # Update documentation for changed files only php artisan cascadedocs:update-changed # ⏳ Wait for queue to complete if you need to run architecture docs # Update and auto-commit the changes php artisan cascadedocs:update-changed --auto-commit ``` 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 ----------------------- [](#documentation-structure) ``` docs/source_documents/ ├── short/ # Micro-tier: Brief one-line summaries ├── medium/ # Standard-tier: Balanced documentation ├── full/ # Expansive-tier: Detailed documentation with examples ├── modules/ # Module-level documentation │ ├── content/ # Module overview documents │ ├── metadata/ # Module configuration and tracking │ └── index.md # Searchable index of all modules └── architecture/ # System-level architecture documentation ├── architecture-summary.md # 1-2 page overview └── system-architecture.md # Comprehensive architecture doc ``` Command Reference ----------------- [](#command-reference) ### Class Documentation [](#class-documentation) ``` # Generate all tiers (default) php artisan cascadedocs:generate-class-docs # Generate specific tier only php artisan cascadedocs:generate-class-docs --tier=standard # Force regeneration of existing docs php artisan cascadedocs:generate-class-docs --force # Use a specific AI model php artisan cascadedocs:generate-class-docs --model=gpt-5.1 ``` ### Module Documentation [](#module-documentation) #### Understanding the Module Workflow [](#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 [](#complete-module-workflow) ``` # Recommended: Run the complete workflow php artisan cascadedocs:generate-module-docs ``` 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 [](#manual-module-management) For more control over module creation: ``` # 1. Check current module status and unassigned files php artisan cascadedocs:module-status # 2. Get AI suggestions for unassigned files (preview only) php artisan cascadedocs:assign-files-to-modules --dry-run # 3. Review and apply suggestions php artisan cascadedocs:assign-files-to-modules # You'll be shown the suggestions and asked: # - "Yes": Apply all changes (assigns files AND creates new modules) # - "No": Cancel without changes # - "Feedback": Provide feedback for better suggestions # 4. Generate documentation for the modules php artisan cascadedocs:update-all-modules # Optional: Skip confirmation prompts php artisan cascadedocs:assign-files-to-modules --force ``` #### Interactive Assignment [](#interactive-assignment) For maximum control: ``` # Review each suggestion individually php artisan cascadedocs:assign-files-to-modules --interactive # Process only a few files at a time php artisan cascadedocs:assign-files-to-modules --limit=5 ``` #### Other Module Commands [](#other-module-commands) ``` # View detailed module analysis php artisan cascadedocs:analyze-modules --suggest # Create a module manually php artisan cascadedocs:create-module # Force fresh analysis (ignores cache) php artisan cascadedocs:generate-module-docs --fresh # Generate module index php artisan cascadedocs:generate-module-index ``` ### Update Documentation [](#update-documentation) ``` # Update based on git changes php artisan cascadedocs:update-changed # Update from specific commit php artisan cascadedocs:update-changed --from-sha=abc123 # Update and commit changes php artisan cascadedocs:update-changed --auto-commit ``` ### Utility Commands [](#utility-commands) ``` # View module status php artisan cascadedocs:module-status # Create a new module manually php artisan cascadedocs:create-module "Payment Processing" # Force fresh module analysis (ignores cache) php artisan cascadedocs:generate-module-docs --fresh ``` Configuration ------------- [](#configuration) The `config/cascadedocs.php` file controls: ``` return [ 'paths' => [ 'source' => ['app/', 'resources/js/'], // Directories to document 'output' => 'docs/source_documents/', // Documentation location ], 'file_types' => ['php', 'js', 'vue', 'jsx', 'ts', 'tsx'], 'ai' => [ 'default_model' => 'gpt-5.1', // or 'claude-3-5-sonnet', etc. 'temperature' => 1, // Use 1 for thinking/reasoning models 'thinking_effort' => 'high', // For models that support extended thinking ], 'modules' => [ 'granularity' => 'granular', // 'granular' (more focused) or 'consolidated' (broader) 'min_files_per_module' => 2, // Minimum files required to form a module ], 'queue' => [ 'connection' => 'default', 'queue' => 'documentation', ], ]; ``` ### Module Granularity [](#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: ``` CASCADEDOCS_MODULE_GRANULARITY=granular ``` Tracking Files -------------- [](#tracking-files) CascadeDocs maintains several files to track state and enable efficient updates: ### `docs/module-assignment-log.json` [](#docsmodule-assignment-logjson) 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` [](#docssource_documentsmodulesmetadatajson) Individual module metadata including file assignments, summaries, and documentation status. ### Documentation Files (YAML Frontmatter) [](#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 ------------------ [](#programmatic-usage) ``` use Lumiio\CascadeDocs\Facades\CascadeDocs; // Get documentation for a specific file $docs = CascadeDocs::getDocumentation('app/Models/User.php', 'standard'); // Get all modules $modules = CascadeDocs::getModules(); // Get module documentation $moduleDocs = CascadeDocs::getModuleDocumentation('user-management'); // Get file's module assignment $module = CascadeDocs::getFileModule('app/Services/UserService.php'); ``` Best Practices -------------- [](#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 --------------- [](#troubleshooting) ### "No modules found" [](#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 [](#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" [](#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 [](#rate-limit-errors) - Ensure your queue worker is running: `php artisan queue:work` - The package automatically retries with delays ### Memory issues [](#memory-issues) - Use queue processing for large codebases - Process documentation generation in smaller batches by documenting specific directories Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 10, 11, or 12 - Git (for change tracking features) - Queue worker running (for async processing) Testing ------- [](#testing) ``` composer test ``` Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Credits ------- [](#credits) - [Shawn Veltman](https://github.com/shawnveltman) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 41 — FairBetter than 89% of packages Maintenance81 Actively maintained with recent releases Popularity16 Limited adoption so far Community11 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 89.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~7 days Recently: every ~35 days Total 22 Last Release 174d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/6dd8d72a34070f86fc3cd5180b2cacbf81d41d69b1016b91da26b5ef409b577c?d=identicon)[shawnveltman](/maintainers/shawnveltman) --- Top Contributors [![shawnveltman](https://avatars.githubusercontent.com/u/8326484?v=4)](https://github.com/shawnveltman "shawnveltman (52 commits)")[![dataffinityhealth](https://avatars.githubusercontent.com/u/48269242?v=4)](https://github.com/dataffinityhealth "dataffinityhealth (2 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)") --- Tags laravelLumiiocascadedocs ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/lumiio-cascadedocs/health.svg) ``` [![Health](https://phpackages.com/badges/lumiio-cascadedocs/health.svg)](https://phpackages.com/packages/lumiio-cascadedocs) ``` ### Alternatives [barryvdh/laravel-ide-helper Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion. 14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9682.1M97](/packages/roots-acorn)[laragear/preload Effortlessly make a Preload script for your Laravel application. 119363.5k](/packages/laragear-preload)[spatie/laravel-livewire-wizard Build wizards using Livewire 4061.0M4](/packages/spatie-laravel-livewire-wizard)[flarum/core Delightfully simple forum software. 211.3M1.9k](/packages/flarum-core)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)