Laravel Brain Laravel Package

Technical Evaluation

Architecture Fit

• Zero-config, non-intrusive: Leverages Laravel’s existing service provider auto-discovery, requiring no manual setup or route changes. Ideal for teams prioritizing developer experience without production impact.
• Complementary to existing tools: Integrates with Laravel’s native debugging (Telescope, Horizon) and Filament’s ecosystem, filling a gap in architectural visualization.
• Modular design: Analyzers (routes, middleware, Filament, etc.) operate independently, allowing selective adoption (e.g., disable Filament tracing if unused).
• Performance isolation: Runs scans as CLI commands, decoupling visualization from runtime. Graph data is static JSON, reducing runtime overhead.

Integration Feasibility

• Laravel-native: Built for Laravel 9–13, with PHP 8.0+ compatibility. No framework modifications required.
• Dev-only dependency: Installed via Composer --dev, ensuring no production bloat.
• Route integration: Serves via /_laravel-brain under Laravel’s routing system, avoiding port conflicts or external services.
• Filament synergy: Deep integration with Filament panels/resources, making it a natural fit for Filament-heavy apps.

Technical Risk

• Memory constraints: Large codebases may hit PHP memory limits (default 1GB). Mitigated by --memory-limit flag and auto-discover mode (which trades file/line metadata for lower memory usage).
• Auto-discover limitations: Programmatic route registration (e.g., via service providers) may not map to source files in auto-discover mode, impacting traceability.
• Scan accuracy: False positives/negatives possible in call-chain tracing (e.g., dynamic method calls via call_user_func). Requires manual validation for critical paths.
• React SPA dependency: Viewer relies on a bundled React app. Potential for CORS or asset-loading issues in non-standard Laravel setups (e.g., custom asset pipelines).

Key Questions

1. Target use cases:
   • Will this replace existing architecture docs, or supplement them?
   • Is Filament adoption high enough to justify its specialized tracing?
2. Scan frequency:
   • How often will scans run (CI/CD, local dev)? Auto-watch mode may impact performance on large projects.
3. Data sensitivity:
   • Does the graph expose sensitive routes/models (e.g., admin panels)? Consider excluding via config.
4. AI integration:
   • Will exported contexts be used for LLM-assisted refactoring? If so, validate token budgets for complex nodes.
5. Performance impact:
   • For CI/CD, will scan times become a bottleneck? Test with --memory-limit adjustments.

Integration Approach

Stack Fit

• Laravel 9–13: Native support with zero configuration. No version-specific risks.
• PHP 8.0+: Leverages modern features (attributes, typed properties) but avoids breaking changes.
• Filament: Deep integration with Filament 2/3, including panels, resources, and relation managers.
• Composer: Dev dependency model aligns with Laravel’s tooling ecosystem (e.g., Pest, Laravel Debugbar).
• React/Vite: Viewer uses a bundled SPA, but no custom build steps are required (assets auto-published).

Migration Path

1. Pilot phase:
   • Install in a dev environment: composer require --dev laramint/laravel-brain.
   • Run initial scan: php artisan brain:scan.
   • Validate graph accuracy for 2–3 critical routes/controllers.
2. Configuration tuning:
   • Adjust config/laravel-brain.php for:
     • Route discovery mode (auto_discover_routes).
     • Memory limits (--memory-limit).
     • Excluded namespaces (e.g., vendor routes).
   • Test Filament tracing if applicable.
3. CI/CD integration (optional):
   • Add scan to CI pipeline (e.g., GitHub Actions) with --memory-limit=2G.
   • Export AI contexts for documentation: php artisan brain:export-context --output=docs/architecture.md.
4. Production rollout:
   • Ensure /_laravel-brain is excluded from web server (e.g., Nginx location block) or protected by middleware (e.g., auth:sanctum).

Compatibility

• Laravel packages: May need to exclude vendor routes (default behavior). Use --auto-discover for programmatic routes.
• Custom routing: Routes registered via RouteServiceProvider or boot() methods are captured in auto-discover mode.
• Monorepos: Scan may include unrelated PHP files. Exclude directories via config/laravel-brain.php:

  'excluded_directories' => [
      'packages/*',
      'tests/*',
  ],
  

• Legacy code: Older PHP (pre-8.0) or non-Laravel classes may cause parsing errors. Filter via excluded_classes.

Sequencing

1. Pre-scan:
   • Review composer.json for dev dependencies that might conflict (e.g., other AST analyzers).
   • Allocate sufficient memory (start with --memory-limit=2G for large apps).
2. Scan execution:
   • Run in a clean environment (no active requests) to avoid race conditions.
   • For CI, use --watch sparingly (high CPU/memory usage).
3. Post-scan:
   • Validate graph for critical paths (e.g., checkout flow).
   • Generate AI contexts for documentation: php artisan brain:generate-rules.
4. Ongoing:
   • Re-scan after major refactors or package updates.
   • Monitor scan times/memory usage in CI.

Operational Impact

Maintenance

• Low operational overhead:
  • No runtime dependencies; scans are CLI-driven.
  • Graph data is static JSON (no database or external service).
• Configuration drift:
  • config/laravel-brain.php may need updates for:
    • New Laravel versions (check compatibility).
    • Added Filament panels/resources.
    • Excluded routes/namespaces.
• Dependency updates:
  • Monitor for breaking changes in Laravel or React (viewer).
  • Test after major Laravel releases (e.g., 12 → 13).

Support

• Troubleshooting:
  • Scan failures: Check memory limits, excluded directories, and PHP version.
  • Missing nodes: Verify auto-discover mode or AST parsing for routes.
  • Performance: Profile with --memory-limit adjustments or exclude large modules.
• Documentation gaps:
  • AI context exports require understanding of LLM token budgets.
  • Filament-specific nodes may need explanation for non-Filament teams.
• Community:
  • Active GitHub repo (841 stars) with responsive maintainer.
  • MIT license allows forks/modifications if needed.

Scaling

• Codebase size:
  • Small/medium: Scans complete in seconds (1–5GB memory).
  • Large: May require --memory-limit=4G or CI-based scanning.
  • Monoliths: Exclude unrelated directories to reduce scan scope.
• Team size:
  • Collaborative: Shared graph viewer aids onboarding (e.g., /_laravel-brain linked in docs).
  • Distributed: AI contexts enable async code reviews.
• CI/CD:
  • Scan as a pipeline step (e.g., after tests):

    - name: Generate architecture graph
      run: php artisan brain:scan --memory-limit=2G && php artisan brain:export-context --output=docs/architecture.md
    

Failure Modes

Ramp-Up

• Onboarding:
  • Developers: 15–30 mins to explore graph; focus on critical routes first.
  • PMs/Architects: 1–2 hours to validate accuracy against existing docs.
• Training:
  • Key features to highlight:
    • Route → controller → service flowcharts.
    • Fat-class detection (300+ lines).
    • AI context exports for LLM-assisted refactoring.
  • Hands-on exercise: Walk through a refactor using the graph + AI contexts.
• Adoption barriers:
  • Initial scan time: Communicate upfront (e.g., "First scan may take 5 mins").
  • Graph complexity: Start with a subset of routes (e.g., /users flow).
  • AI integration: Requires LLM access; position as optional enhancement.
• Success metrics:
  • Reduction in "