Laravel Process Map

Overview

O Laravel Process Map e uma ferramenta de analise estatica que mapeia os processos de negocio dentro de qualquer aplicacao Laravel. Le o codigo-fonte e os metadados de runtime registados (rotas, schedule, broadcast channels) e produz um mapa, legivel por humanos e por maquinas, dos processos que consegue identificar -- quem chama o que, que models sao mutados onde, que jobs/eventos/listeners participam em cada fluxo, e que zonas do codigo parecem totalmente automatizadas em comparacao com manuais.

Para quem e

• Developers a fazer onboarding num projecto novo -- ganham uma visao da arquitetura em minutos em vez de dias.
• Tech leads e consultores a auditar um codebase -- veem gaps de automatizacao, bottlenecks e riscos sem instrumentar nada.
• Documentacao -- gerar um snapshot versionado do mapa de processos e fazer commit ao repositorio.
• Agentes de IA (v1.1+) -- expor o mapa como recurso MCP para que os agentes consigam raciocinar sobre o dominio.

Instalacao

Instale como dependencia de desenvolvimento -- e uma ferramenta de developer/consulting, nao uma preocupacao de runtime.

composer require digitaldev-lx/laravel-process-map --dev

Corra o comando de install para publicar a configuracao e criar a directoria de output:

php artisan process-map:install
# ou para instalar e fazer scan no mesmo passo
php artisan process-map:install --scan

O service provider e auto-descoberto via extra.laravel.providers -- nao e necessario registo manual.

Requisitos

Comandos Artisan

Flags do process-map:scan

--json                 # gera JSON
--markdown             # gera Markdown
--mermaid              # gera Mermaid
--all                  # JSON + Markdown + Mermaid
--output=path          # override da directoria de output
--no-routes            # ignora o route scanner
--no-process-detection # ignora o clustering heuristico

Sem nenhuma flag de formato, o comando usa config('process-map.exports.*').

Desenhado para LLMs

O relatorio Markdown e o artefacto canonico para desenvolvimento assistido por IA. Faz-se drop do process-map.md em Claude Code, ChatGPT, Cursor, Aider ou qualquer outra ferramenta LLM, e fica imediatamente um mapa navegavel da aplicacao -- sem o LLM ter de fazer grep, abrir dezenas de ficheiros ou adivinhar como tudo se encaixa.

Vantagens concretas para um LLM

1. File path em cada linha. As tabelas Members e Unattached incluem o caminho relativo de cada classe -- o LLM abre o ficheiro certo directamente em vez de fazer search.
2. Um lugar canonico por classe. Cada classe aparece em exactamente um sitio -- ou dentro do bloco Process a que pertence ou em Unattached Components. Sem listagens duplicadas, sem tokens desperdicados.
3. Coluna Notes densa. Factos operacionais inline: queue=reports . tries=5 . timeout=120s, channels: mail, database . queued, sync (no ShouldQueue).
4. Trace de Flow explicito. A sequencia route -> controller -> action -> job/event -> listener -> notification e detalhada em bullet points.
5. Clustering reference-aware. Classes que nao seguem convencao de nomenclatura sao na mesma anexadas ao processo via referencias estaticas (e.g. CreateLeadAction -> dispatches SendLeadFollowUpJob puxa o job para o bloco Lead Management).
6. Hedge wording em findings. Bottlenecks/riscos/recomendacoes sao prefixados com Bottleneck:, Risk:, Recommendation: -- o LLM trata-os como pontos de partida para investigacao, nao como factos.
7. Header com schema versionado. Schema 0.1 permite construir prompts reproduzeis: pinne a versao no tooling e os prompts continuam a funcionar quando o pacote for actualizado.
8. Eficiente em tokens. ~85 linhas / 2.6 KB para 12 classes; ~600-800 linhas / 20 KB para 150. Folga para o raciocinio do LLM e tool calls.

Receita rapida -- Claude Code

php artisan process-map:scan --markdown
# depois, dentro do Claude Code:
#   /add-dir storage/app/process-map
# ou colar o ficheiro:
cat storage/app/process-map/process-map.md | pbcopy

Prompt de arranque sugerido

Configuracao

php artisan vendor:publish --tag=process-map-config

O ficheiro publicado vive em config/process-map.php e expoe os seguintes grupos:

return [
    'paths' => [
        'app' => app_path(),
        'routes' => base_path('routes'),
    ],

    'output_path' => storage_path('app/process-map'),

    'scan' => [
        'models' => true, 'controllers' => true, 'actions' => true,
        'jobs' => true, 'events' => true, 'listeners' => true,
        'notifications' => true, 'policies' => true, 'commands' => true,
        'routes' => true, 'schedule' => true, 'broadcasting' => true,
    ],

    'directories' => [
        'models' => ['app/Models'],
        'controllers' => ['app/Http/Controllers'],
        'actions' => ['app/Actions'],
        'jobs' => ['app/Jobs'],
        'events' => ['app/Events'],
        'listeners' => ['app/Listeners'],
        'notifications' => ['app/Notifications'],
        'policies' => ['app/Policies'],
        'commands' => ['app/Console/Commands'],
    ],

    'process_detection' => [
        'enabled' => true,
        'keywords' => ['create', 'update', 'delete', /* ... */],
        'business_suffixes' => ['Action', 'Job', 'Command', 'Service', 'Workflow', 'Process'],
    ],

    'exports' => [
        'json' => true, 'markdown' => true, 'mermaid' => true, 'html' => false,
    ],

    'privacy' => [
        'include_method_names' => true,
        'include_properties' => false,
        'include_docblocks' => false,
        'include_file_paths' => true,
        'redact_env_values' => true,
    ],
];

Layouts modulares (DDD, nwidart/laravel-modules)

Adicione roots adicionais em directories:

'directories' => [
    'actions' => ['app/Actions', 'modules/*/Actions'],
    'models' => ['app/Models', 'modules/*/Domain/Models'],
],

Deteccao de processos

O NamingConventionProcessDetector e propositadamente simples:

1. Percorre cada DiscoveredClass de um tipo participante.
2. Remove o sufixo de negocio (e.g. Action, Job).
3. Remove o verbo inicial (e.g. Create, Send).
4. Remove participios comuns (e.g. Created, Updated).
5. Cluster pelo que sobra. Clusters com pelo menos 2 classes tornam-se um processo.

Detectors que anotam cada processo

O output e sempre best-effort. As palavras Potential..., May indicate... sao intencionais e propagadas ao relatorio Markdown.

Garantias de seguranca

O pacote e estrictamente read-only. Nunca:

• Executa codigo de negocio, jobs, eventos ou notifications
• Faz queries a base de dados
• Faz HTTP calls
• Escreve fora da output_path configurada
• Expoe o conteudo do .env ou outros segredos

A analise e feita via parsing AST. Reflection e opt-in via process-map.safe_reflection.enabled e e usada apenas para metadata segura (interfaces, traits, parent class).

Um teste dedicado (tests/Unit/ReadOnlyInvariantTest.php) faz scan da propria src/ a procura de helpers proibidos (DB::, dispatch(, event(, Notification::send, Mail::send, Http::*) e falha o build se algum for introduzido.

Roadmap