README

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

composer require lumiio/cascadedocs

Setup

Publish the AI provider configuration:

php artisan vendor:publish --provider="Shawnveltman\LaravelOpenai\LaravelOpenaiServiceProvider"

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

Publish CascadeDocs configuration:

php artisan vendor:publish --tag="cascadedocs-config"

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

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

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

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

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

Understanding the Module Workflow

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

Module Assignment - Deciding which files belong to which modules
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

# Recommended: Run the complete workflow
php artisan cascadedocs:generate-module-docs

This command orchestrates the entire process:

Analyzes module structure (skipped if already done)
Assigns unassigned files to modules
Syncs module assignments
Updates all module documentation
Shows final module status

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

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

# 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 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

# 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

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

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

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

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

Start with class documentation - This provides the foundation for module organization
Review module assignments - The AI makes intelligent suggestions, but you can manually adjust
Use queues for large codebases - Prevents timeouts and improves performance
Commit tracking files - Ensures consistent documentation across your team
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:

Run php artisan cascadedocs:module-status to see unassigned files
Run php artisan cascadedocs:assign-files-to-modules --auto-create to assign them to modules
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

composer test

lumiio/cascadedocs

包简介

关键字：

README 文档