Documentation v1.0

LaraNexus Official Documentation

LaraNexus is an open-source visual intelligence and architectural mindmapping toolkit designed specifically for Laravel architects, tech leads, and development teams.

💡 Architectural Vision: To make application flow transparent, eliminate tribal knowledge in growing engineering teams, and ensure that no route, middleware, or database dependency remains hidden in the dark.

The Problem Statement & Technical Solution

Modern Laravel applications easily grow to encompass hundreds of API endpoints, web routes, complex nested controllers, and distributed middleware pipelines. As development velocity increases, two critical problems emerge:

The Problem

Route files become disorganized monoliths. New developers spend weeks reading code to understand simple request journeys. Unprotected endpoints slip through code reviews because middleware groups are complex and easy to misconfigure.

The LaraNexus Solution

Zero-configuration dynamic visualization. LaraNexus executes during local development, inspecting Laravel's active RouteCollection, parsing Controller reflection data, and rendering an intuitive node graph in your browser.

Installation & System Requirements

System Prerequisites

PHP: `8.3` or `8.4`
Laravel Framework: `12.x` or `13.x`
Composer: `2.x`

Composer Installation

Install LaraNexus as a development-only dependency:

composer require diusazzad/laranexus --dev

🔒 Zero Production Footprint: LaraNexus registers only when in the local environment and should always be required with the --dev flag.

Publishing & Customizing Configuration

Publish the configuration file to customize the dashboard URI and applied middleware:

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

This creates config/laranexus.php:

<?php

return [
    /*
     * The URI path where LaraNexus will be accessible.
     * Default: 'laranexus' (e.g. http://your-app.test/laranexus)
     */
    'path' => env('LARANEXUS_PATH', 'laranexus'),

    /*
     * Middleware applied to LaraNexus routes.
     */
    'middleware' => [
        'web',
    ],
];

How the Discovery Engine Works

LaraNexus uses non-intrusive runtime reflection and static code parsing. It does not execute your controller methods or trigger side effects.

1. Route & Controller Subgraphs

The RouteMapCollector inspects the application routing table, ignores internal framework namespaces (Tinker, Ignition, Ray), and aggregates actions into controller subgraphs in Mermaid.js.

2. Security Middleware Badges

Each route node automatically parses its assigned middleware array. If middleware is present, it receives a prominent lock icon (🔐 auth, verified). Endpoints without middleware stand out as open routes.

3. Static Model & View Dependency Analysis

Using PHP's ReflectionClass, LaraNexus locates the controller file on disk and scans for imported Eloquent models (use App\Models\*) and rendered Blade views (view('...')).

4. 1-Click VS Code Integration

Clicking any controller subgraph in the mindmap opens the controller file directly in your VS Code workspace using the vscode://file/{path} protocol handler.

In-Depth Case Studies

Enterprise Productivity From 14 Days to 2 Hours

Cutting Developer Onboarding Time by 85%

Organization: FinTech Core Platform (450+ Endpoints)

The Problem: A financial services platform with 450+ routes and 12 years of legacy commits took junior and mid-level engineers an average of 2 full weeks just to map out request flows and identify which controllers owned critical business logic.

The Solution: By introducing LaraNexus into the local docker development environment, new engineers visualised the entire API topology in a single interactive canvas. Clicking on nodes opened controller methods directly in VS Code, removing documentation lag entirely.

Documented Results:

Onboarding cycle reduced from 14 days to under 2 hours
Zero documentation maintenance overhead (self-generating)
Eliminated tribal knowledge silos across engineering squads

Security & Compliance 17 Unprotected Endpoints Discovered

Preventing Production Data Leaks with Visual Auditing

Organization: HealthTech SaaS Provider (HIPAA / GDPR Compliance)

The Problem: During a quarterly security audit, developers were manually cross-checking `routes/web.php` and `routes/api.php` line by line. Hidden sub-routes inside resource controllers were accidentally deployed without the `auth:sanctum` or role-verification middleware.

The Solution: LaraNexus automatically parsed middleware chains into explicit visual badges (`🔐 auth`, `throttle`, `verified`). Unprotected endpoints stood out immediately in red and slate without security badges.

Documented Results:

Flagged 17 unprotected endpoints before ISO-27001 audit
Real-time security auditing during every PR review
Visual proof of compliance for security auditors in SVG format

Architecture Refactoring 60% Reduction in Controller Cyclomatic Complexity

Deconstructing God Controllers into Domain Services

Organization: E-Commerce Marketplace (High Throughput)

The Problem: The main `OrderController.php` spanned over 2,400 lines, rendering 14 blade views and querying 9 different Eloquent models. Developers were terrified to touch it due to unexpected side-effects across payment processing and inventory views.

The Solution: Using LaraNexus deep discovery reflection, the architecture team visually grouped all connected models and blade templates. They cleanly separated checkout, invoicing, and refunds into dedicated domain action classes.

Documented Results:

God controller cleanly decomposed into 4 discrete micro-actions
Zero regressions during refactoring thanks to visual boundary verification
Architectural blueprints exported as SVG directly into Git architecture docs

Open Source Contribution Guide

We actively encourage contributions to LaraNexus! Whether fixing typos, adding tests, or implementing new visualization drivers, your help is appreciated.

Coding Standards & Quality Tooling

Strict Types: All PHP files must begin with <?php declare(strict_types=1);.
Code Style: We use Laravel Pint to enforce PSR-12 code standards. Run ./vendor/bin/pint before submitting any code.
Automated Testing: Every feature or bug fix must include automated test coverage in tests/.

Step-by-Step Pull Request Guide

Fork & Clone: Fork diusazzad/LaraNexus to your GitHub account and clone locally.
Create Branch: Create a descriptive topic branch:
```
git switch -b feat/add-eloquent-relationships
```
Install & Setup: Run composer install and ensure tests pass.
Run Test Suite:
```
php artisan test
```
Format Code:
```
./vendor/bin/pint
```
Push & Open Pull Request: Push your branch to GitHub and open a PR. Fill out the structured PR template completely.

🛡️ Security Vulnerabilities: Please do not disclose vulnerabilities publicly via the issue tracker. Email [email protected] directly.