Local dependency graph and factual context for AI-assisted software work.

Documentation · CLI · MCP · Docker · Configuration · Public API · Roadmap

Flow Engine analyzes a codebase on your machine and turns it into a graph an AI assistant can trust: files, symbols, dependencies, cycles, impact, risk, architecture rules, orphan code, bugs, snapshots, and compact context exports.

It is built for local use first. The CLI, MCP server, Docker image, read-only API, parsers, reports, and context exports work without network access, telemetry, accounts, or API keys.

You use Flow Engine from this repository, then point it at the project you want to understand. In the examples below, <project> means your application repository, such as C:\dev\my-app on Windows or /home/me/my-app on Linux.

Why Flow Engine

AI coding tools are strongest when they have precise codebase facts instead of a prompt full of guesses. Flow Engine gives them a deterministic map of the system before they suggest changes.

Use it to:

• Ask an AI assistant about a codebase with grounded context.
• Find cycles, hotspots, or orphaned code before a refactor.
• Estimate impact and risk for a class, method, route, or module.
• Keep local architecture rules enforceable in CI.
• Export reports for code review, planning, and maintenance.
• Expose a local MCP toolset to Claude, Codex, Cline, Continue, or any MCP-compatible client.

What It Includes

Area	Included
Engine	Local static analysis, graph construction, metrics, cycles, impact, risk, architecture checks, orphan detection
Languages	PHP, TypeScript, JavaScript, Python, Go, Dart, and Blade
Interfaces	CLI, MCP server, local read-only HTTP API, Docker
AI context	Minimal/full context exports, entrypoint-focused context, reports, Mermaid text output
Change tracking	Filesystem snapshots, compare, drift, cleanup, architecture gate
Privacy	No required remote service, no required API key, no required telemetry, no account system

Feature Benefits

• Local engine: build a deterministic dependency graph before changing code, so decisions are based on facts instead of guesses.
• CLI: run every analysis command from a terminal, script, or CI job.
• MCP server: let AI assistants inspect the codebase through local tools instead of relying on pasted context.
• Read-only API: expose local graph facts to scripts and local tools without write endpoints.
• Docker: run Flow Engine on Windows, Linux, macOS, and CI without installing PHP locally.
• Metrics: find hotspots, coupling pressure, and files that deserve attention before a refactor.
• Cycles: locate dependency loops that make changes harder and tests more fragile.
• Architecture checks: enforce local layer rules and catch unwanted dependencies early.
• Orphans: find code that may be unused, with audit evidence before deletion.
• Impact and risk: estimate what a change can affect before editing a class, method, route, or module.
• Flow tracing: follow upstream and downstream dependencies from one node to understand feature behavior.
• AI context exports: generate compact, factual Markdown for AI-assisted maintenance.
• Snapshots and gates: save local baselines, compare drift, and fail CI on new architecture issues.
• Diagrams and app maps: generate Mermaid diagrams and multi-service maps from local code facts.
• Configuration: tune scan paths, ignores, languages, architecture layers, and snapshot retention per project.

Start Here

Choose one setup:

• Windows, easiest path: install Git, PHP 8.2+, Composer, and use PowerShell.
• Linux/macOS: install Git, PHP 8.2+, Composer, and use your shell.
• Docker only: install Docker Desktop or Docker Engine, then build the image locally.

Flow Engine is not required to be installed inside the project you are analyzing. Clone it once, then run commands against any local repository.

Install From Source

Windows PowerShell:

git clone https://github.com/rborges/flow-engine.git
cd flow-engine
composer install
php .\bin\engine.php help

Linux/macOS:

git clone https://github.com/rborges/flow-engine.git
cd flow-engine
composer install
php bin/engine.php help

Composer package install will be documented here once the package is published.

Quick Start

Run these commands from the Flow Engine directory and replace <project> with the project you want to analyze.

Windows PowerShell:

php .\bin\engine.php analyze C:\dev\my-app
php .\bin\engine.php metrics C:\dev\my-app
php .\bin\engine.php cycles C:\dev\my-app
php .\bin\engine.php orphans C:\dev\my-app --audit
php .\bin\engine.php architecture C:\dev\my-app
php .\bin\engine.php context C:\dev\my-app --minimal

Linux/macOS:

php bin/engine.php analyze /home/me/my-app
php bin/engine.php metrics /home/me/my-app
php bin/engine.php cycles /home/me/my-app
php bin/engine.php orphans /home/me/my-app --audit
php bin/engine.php architecture /home/me/my-app
php bin/engine.php context /home/me/my-app --minimal

If you are already inside the project you want to analyze, use . as the project path:

Windows PowerShell:

php C:\dev\flow-engine\bin\engine.php context . --minimal

Linux/macOS:

php /home/me/flow-engine/bin/engine.php context . --minimal

The context --minimal command prints compact, factual context you can paste into an AI assistant. MCP is better for repeated use because the assistant can call Flow Engine tools directly.

Docker Quick Start

Build the local image from the Flow Engine repository:

docker build -t flow-engine .

Analyze a project on Windows PowerShell:

docker run --rm -v "C:\dev\my-app:/workspace:ro" flow-engine analyze /workspace
docker run --rm -v "C:\dev\my-app:/workspace:ro" flow-engine context /workspace --minimal

Analyze the current directory in PowerShell:

docker run --rm -v "${PWD}:/workspace:ro" flow-engine metrics /workspace

Analyze a project on Linux/macOS:

docker run --rm -v "/home/me/my-app:/workspace:ro" flow-engine analyze /workspace
docker run --rm -v "$PWD:/workspace:ro" flow-engine metrics /workspace

See docs/docker.md for Docker Compose and API examples.

Common Workflows

The same commands work on Windows with php .\bin\engine.php and a Windows path, or on Linux/macOS with php bin/engine.php and a Unix path.

Inspect the project graph:

php bin/engine.php nodes <project>
php bin/engine.php flow <project>
php bin/engine.php metrics <project>

Plan a change:

php bin/engine.php impact <project> "App\\Service\\OrderService::process"
php bin/engine.php change-risk <project> --node="App\\Service\\OrderService::process"
php bin/engine.php context <project> --entrypoint="App\\Service\\OrderService::process"

Track architecture drift:

php bin/engine.php snapshot <project> --save=before-change
php bin/engine.php architecture-gate <project> --baseline=before-change --fail-on=new

Generate local reports:

php bin/engine.php bugs <project>
php bin/engine.php diagram <project> --view=class

For multi-service maps, see System diagrams.

MCP Server

Flow Engine can run as a local MCP server so AI clients can inspect your codebase through tools instead of relying on pasted context.

The MCP server runs over stdio. Configure your MCP client to run the mcp command from this repository.

Windows PowerShell:

$env:FLOW_ENGINE_BIN = "$PWD\bin\engine.php"
php .\bin\engine.php mcp

Linux/macOS:

export FLOW_ENGINE_BIN="$PWD/bin/engine.php"
php bin/engine.php mcp

The committed .mcp.json uses FLOW_ENGINE_BIN, so it does not contain machine-specific paths. For most clients, the command is php, and the arguments are the full path to bin/engine.php followed by mcp.

See docs/mcp.md for setup, available tools, and an example system prompt.

Local Read-Only API

Start the API for a project, then query it from the same machine.

Windows PowerShell:

php .\bin\engine.php api C:\dev\my-app --host=127.0.0.1 --port=8080
Invoke-RestMethod http://127.0.0.1:8080/health
Invoke-RestMethod http://127.0.0.1:8080/api/v1/metrics

Linux/macOS:

php bin/engine.php api /home/me/my-app --host=127.0.0.1 --port=8080
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/api/v1/metrics
curl http://127.0.0.1:8080/api/v1/context

Public endpoints are GET-only:

• /health
• /api/v1/metrics
• /api/v1/cycles
• /api/v1/architecture
• /api/v1/orphans
• /api/v1/nodes
• /api/v1/edges
• /api/v1/flow
• /api/v1/snapshots
• /api/v1/context
• /api/v1/bugs
• /api/v1/appmap
• /api/v1/appmap-diff
• /api/v1/compliance-monitor
• /api/v1/deployment-map
• /api/v1/devops-map
• /api/v1/website-map
• /api/v1/diagram

POST requests return 405.

Configuration

Create a starter config in the project you want to analyze:

Windows PowerShell:

php .\bin\engine.php init C:\dev\my-app

Linux/macOS:

php bin/engine.php init /home/me/my-app

Then edit flow-engine.json to define:

• Paths to scan and paths to ignore.
• Architecture layers and allowed dependencies.
• Visibility and entrypoint rules.
• Snapshot retention.
• Optional external project roots for local audits.

Do not store secrets in flow-engine.json. Optional LLM providers are configured through environment variables only.

See docs/configuration.md.

Documentation Map

• Getting started: first run on Windows, Linux/macOS, or Docker.
• Overview: what Flow Engine does and where each interface fits.
• CLI commands: command reference with common examples.
• MCP server: connect Flow Engine to MCP-compatible AI clients.
• Docker: run analysis and the local API in containers.
• Configuration: flow-engine.json fields and examples.
• Analysis tools: metrics, cycles, architecture, orphans, impact, risk, and reports.
• Concepts: glossary for graph terms.

Optional LLM Providers

The core does not need an LLM. You can still analyze, export, serve MCP tools, and run the read-only API without any provider key.

Optional providers are opt-in:

export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...
export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=llama3.1

When these variables are not present, Flow Engine falls back to local context exports and deterministic reports.

Docker

Use this section when you want a little more than the quick Docker example above.

Analyze a mounted project:

Windows PowerShell:

docker build -t flow-engine .
docker run --rm -v "C:\dev\my-app:/workspace:ro" flow-engine analyze /workspace

Linux/macOS:

docker build -t flow-engine .
docker run --rm -v "$PWD:/workspace:ro" flow-engine analyze /workspace

Run the local API:

docker compose up --build
curl http://127.0.0.1:8080/health

See docs/docker.md.

Security And Privacy

• Local-first: analysis runs against local files.
• No required telemetry.
• No account or payment code.
• No required external runtime.
• API is local and read-only.
• LLM providers are optional and enabled only through environment variables.
• .claude/ settings are examples; local settings are ignored by Git.

To enable the example Claude Code hooks:

cp .claude/settings.example.json .claude/settings.json

Development

composer install
vendor/bin/phpunit --no-coverage
php bin/quality-gate.php --mode=main

Docker-only validation:

docker run --rm -v "$PWD":/src:ro -w /work composer:2 sh -lc \
  'cp -a /src/. . && composer validate --strict && composer install --no-interaction --no-progress && vendor/bin/phpunit --no-coverage'

Roadmap

Open source stays focused on the local engine, CLI, MCP, read-only API, Docker, parsers, graph, metrics, cycles, risk, impact, architecture checks, orphans, context exports, and local reports.

Future paid or closed work will be tracked separately and will not be required for the local open-source core.

See ROADMAP.md.

Contributing

Issues and pull requests are welcome. Good first contributions include parser coverage, documentation examples, bug fixtures, and focused tests for graph behavior.

Before opening a PR:

composer install
vendor/bin/phpunit --no-coverage
php bin/quality-gate.php --mode=main

Keep changes local-first, deterministic, and free of required remote services.

Author / Autor

Flow Engine is created and maintained by Rodrigo Borges, a software developer and architect from Brazil focused on codebase understanding, dependency graphs, refactoring, and AI-assisted software maintenance.

O Flow Engine foi criado e mantido por Rodrigo Borges, desenvolvedor e arquiteto de software no Brasil, com foco em entendimento de codebases, grafos de dependencia, refatoracao e manutencao de software assistida por IA.

More context: roborg.org · GitHub · LinkedIn

License

MIT. See LICENSE.