Download the PHP package digitaldev-lx/laravel-process-map without Composer

Laravel Process Map

Static-analysis tool that maps the business processes inside any Laravel application — without ever executing it.

digitaldev-lx/laravel-process-map reads your application's source code and registered Laravel runtime metadata (routes, schedule, broadcast channels) and produces a machine- and human-readable map of the processes it can identify: who calls what, which models are mutated where, which jobs/events/listeners participate in each flow, and which parts of the codebase look fully automated versus manual.

The output is useful for:

• Developers onboarding a new project — get a feel for the architecture in minutes instead of days.
• Tech leads & consultants auditing a codebase — see automation gaps, bottlenecks and risks without instrumenting anything.
• Documentation — generate a versioned snapshot of the application's process map and commit it to the repo.
• AI agents (v0.3+) — expose the process map as an MCP resource so agents can reason about your domain.

Table of contents

• Status
• How it works
• Requirements
• Installation
• Quick start
• Artisan commands
• Output formats
  • JSON
  • Markdown
  • Mermaid
• Designed for LLM consumption
• MCP Support
• Configuration
• Available scanners
• Process detection
• Programmatic API
• Safety guarantees
• Limitations
• Roadmap
• Contributing
• License

Status

Stable (1.0.x). The public Artisan signatures, exporter formats and JSON schema (schema_version: "0.1") are committed to. Breaking JSON changes will bump the schema_version field and be documented in CHANGELOG.md.

How it works

Source files are parsed via nikic/php-parser into an AST. Class metadata (extends, implements, traits, public methods, calls to dispatch()/event()/Notification::send, etc.) is collected by a single visitor and decorated per scanner type.

Routes, scheduled tasks and broadcast channels come from Laravel's runtime APIs (Router::getRoutes(), Schedule::events(), routes/channels.php) — read-only access only.

A heuristic clustering step then groups classes into business processes by stripping verbs and technical suffixes from class names, and a set of detectors annotates each process with automation level, potential bottlenecks and risks.

Requirements

The package is tested against the matrix above on every push (see .github/workflows/tests.yml).

Installation

Install as a dev dependency — the package is a developer/consulting tool, not a runtime concern:

Run the install command to publish the configuration and create the output directory:

To install and scan in one go:

The service provider is auto-discovered via extra.laravel.providers, so no manual registration is required.

Quick start

This produces, in storage/app/process-map/:

• process-map.json — full structured data, schema-versioned.
• process-map.md — human-readable Markdown report.
• process-map.mmd — Mermaid flowchart of the discovered processes.

A typical terminal summary:

Artisan commands

process-map:scan accepts:

• --json, --markdown, --mermaid — generate the corresponding format.
• --all — generate every default format (JSON + Markdown + Mermaid).
• --output=path — override the output directory for this run.
• --no-routes — skip the route scanner.
• --no-process-detection — skip the heuristic clustering.

If no format flag is passed, the command falls back to config('process-map.exports.*').

Output formats

JSON

Canonical artefact, schema-versioned. Excerpt:

Markdown

The Markdown exporter produces a dense, single-pass document built so a human (or an LLM) can grasp the architecture in one read. Sections produced in process-map.md:

A real, fully-rendered example produced from a small fixture app (2 models, 1 controller, 1 action, 2 jobs, 1 event, 1 listener, 1 notification, 1 policy, 1 command, 3 routes):

That fixture renders to 85 lines (~2.6 KB). A typical ~150-class Laravel application produces ~600–800 lines (~20 KB) — well inside any modern context window.

Mermaid

Generates one overview flowchart plus one diagram per detected process:

Render with the Mermaid Live Editor, the GitHub-flavoured Markdown viewer, or VS Code's Mermaid Preview extension.

Designed for LLM consumption

The Markdown report is the canonical artefact for AI-assisted development. Drop process-map.md into Claude Code, ChatGPT, Cursor, Aider or any other LLM tool and you get an instantly navigable map of the application — without the LLM having to grep, open dozens of files, or guess how the pieces fit together.

Concrete advantages when fed to an LLM:

1. File path on every row. The Members and Unattached tables include the relative path of each class, so the LLM can open the right file directly instead of running a search.
2. One canonical place per class. Every class appears in exactly one spot — either inside the Process block it belongs to or inside Unattached Components. No duplicate listings, no wasted tokens.
3. Dense Notes column. Operational facts are inline: queue=reports · tries=5 · timeout=120s, channels: mail, database · queued, **sync** (no ShouldQueue). The LLM skips reading the source for the most common questions.
4. Explicit Flow trace. The route → controller → action → job/event → listener → notification sequence is spelled out as bullet points so the request lifecycle is comprehensible in one read.
5. Reference-aware clustering. Classes that don't match a naming convention are still attached to their process via static-call references (e.g. CreateLeadAction → dispatches SendLeadFollowUpJob pulls the job into the Lead Management block). Fewer orphans, cleaner reasoning.
6. Hedge wording on findings. Bottlenecks/risks/recommendations are prefixed with ⚠ Bottleneck:, 🛡 Risk:, 💡 Recommendation: — the LLM treats them as investigation hints, not as facts.
7. Schema-versioned header. Schema 0.1 lets you build reproducible prompts: pin the schema version in your tooling and your prompts keep working when you upgrade the package.
8. Token-efficient. ~85 lines / ~2.6 KB for a 12-class fixture; ~600–800 lines / ~20 KB for a typical ~150-class Laravel app. Plenty of room left for the LLM's own reasoning and tool calls.

Quick recipe — feed it to Claude Code

A useful starter prompt once the file is in context:

"Use process-map.md as the architectural map of this app. Don't grep unless I ask — pull file paths and references from the report. When you see ⚠/🛡/💡 markers, treat them as starting points for deeper review, not as confirmed bugs."

MCP Support

Laravel Process Map ships an optional read-only MCP layer on top of laravel/mcp. It exposes the same process map as MCP resources, tools and prompts so Claude Code (and any other MCP-compatible client) can query your application architecture interactively, without you having to load a large static report into the prompt.

The layer is off by default. Activating it does not relax any of the package's security guarantees: it remains strictly read-only — no shell, no SQL, no external HTTP, no .env exposure.

When to use which

Installation

The dependency ships with the package — there is nothing extra to install. You only have to opt in:

The status command prints the current toggles and the security policy flags so any deviation from the read-only defaults is visible at a glance.

Resources

Tools (every one read-only)

get_process_map_summary, list_processes, get_process_details, get_process_components, get_process_risks, get_process_recommendations, get_related_classes (depth-bounded), get_route_map, get_mermaid_diagram, refresh_process_map (re-runs the static scan; gated by process-map.mcp.tools.allow_refresh_scan), compare_process_maps (stub; gated by process-map.mcp.tools.allow_compare_scans, lands in v1.2).

Prompts

audit_process, refactor_process_safely, document_process, find_automation_opportunities, generate_technical_handover, prepare_mcp_tools_from_actions. Every prompt accepts the process slug (or name / entity) where applicable and a small set of tuning arguments.

Example — talking to Claude Code

Once the server is registered and the scan has been run, you can drop this into Claude Code:

"Use the Laravel Process Map MCP server to inspect the lead-management process before making any change. List the available processes first, then call get_process_details, get_process_components, get_process_risks and get_mermaid_diagram. Propose a safe refactoring plan via the refactor_process_safely prompt. Do not modify code until I approve."

Security envelope (always enforced)

• read-only by design — every tool carries #[IsReadOnly];
• no shell execution, no SQL, no external HTTP;
• .env is never read; sensitive metadata keys (password / secret / token / api_key / authorization / bearer / credential / connection / *_password / private_key) are redacted to [REDACTED];
• output size is capped per response (max_response_bytes), processes and classes have explicit ceilings, related-class graph walks have a hard depth limit (max_related_depth ≤ 5).

Configuration

Publish the configuration:

The published file lives at config/process-map.php and exposes the following groups:

For modular layouts (DDD, nwidart/laravel-modules), add additional roots under directories:

Available scanners

Each scanner can be turned off in config('process-map.scan.*').

Process detection

The NamingConventionProcessDetector is intentionally simple:

1. Walk every DiscoveredClass of a participating type.
2. Strip the business suffix (e.g. Action, Job).
3. Strip the leading verb (e.g. Create, Send).
4. Strip common participles (e.g. Created, Updated).
5. Cluster by what remains. Clusters with at least 2 classes become a process.

Then the detectors annotate:

• AutomationDetector — assigns none/low/medium/high based on which kinds of components a process ships (jobs and schedule weigh more than plain models).
• BottleneckDetector — surfaces hedge-worded hints like "Notifications in 'Lead Management' may run synchronously".
• RiskDetector — flags missing policies, jobs without $tries/$timeout, destructive command signatures.

The output is always best-effort. Hedge wording (Potential…, May indicate…) is intentional and propagated to the Markdown report.

Programmatic API

Resolve the singleton ProcessMap from the container:

The string returned by exportMarkdown() is identical to the file written by process-map:report and is safe to drop straight into an LLM prompt (see Designed for LLM consumption).

ProcessMapResult is a typed, readonly DTO:

Use cases:

• Diff two snapshots in CI to detect architectural drift.
• Pipe the JSON into Backstage / TechDocs / your internal wiki.
• Feed the JSON to an LLM as context for code-review prompts.

Safety guarantees

The package is strictly read-only. It never:

• executes business code, jobs, events or notifications;
• queries the database;
• makes HTTP calls;
• writes anywhere outside the configured output_path;
• exposes the contents of .env or other secrets.

Analysis is performed via AST parsing. Reflection is opt-in through process-map.safe_reflection.enabled and only used for safe metadata lookups (interfaces, traits, parent class).

A dedicated test (tests/Unit/ReadOnlyInvariantTest.php) scans the package's own src/ directory for forbidden helpers (DB::, dispatch(, event(, Notification::send, Mail::send, Http::*) and fails the build if any are introduced.

Limitations

• Heuristic detection: process clustering uses naming conventions. Apps that don't follow Laravel's standard structure may need custom suffixes/keywords in the config.
• AST scope: only top-level classes are inspected. Anonymous classes, interfaces and traits are skipped (intentional — they're not addressable as process participants).
• Lazy routes: routes registered conditionally at runtime (after RouteServiceProvider::boot) are detected; routes registered through middleware or rare runtime paths may not be.
• Schedule introspection: depends on Laravel's Schedule::events() API. Closure-based schedules expose only the cron expression and timezone.
• HTML exporter: stub in v0.1, scheduled for v0.2.

Roadmap

Contributing

Issues and pull requests are welcome at github.com/digitaldev-lx/laravel-process-map.

Before opening a PR, run the quality checks locally:

Bug reports should include:

• PHP version
• Laravel version
• Package version
• A minimal reproduction (sample app folder structure and the offending output)

See .github/ISSUE_TEMPLATE for the templates.

License

MIT — see LICENSE.md.

Built by DigitalDev.