Flowmap

Flowmap is a local static code-reading workbench for Go. Start from one function and explore a focused caller/callee neighborhood enriched with typed inputs, outputs, named data contracts, authored intent, source, test reachability, and evidence-based functional-core/imperative-shell classification.

Flowmap displays possible static calls. It does not claim that an edge executes at runtime or expose runtime values.

For installation and complete usage instructions, see USER_GUIDE.md or the Flowmap documentation site.

Run

go run ./cmd/flowmap serve /path/to/go/module

Open http://127.0.0.1:7878, search for a function, and choose upstream, downstream, or both directions. Use --tags tag1,tag2 for build tags and --addr 127.0.0.1:9000 to change the local address.

To keep Flowmap in the macOS Dock, open the running workbench in Safari and choose File > Add to Dock, or use Install Flowmap in Chrome. The installed web app uses the same host and port and does not start the Flowmap server; see the user guide for details.

Tests are indexed but hidden until the Tests toggle is enabled. Anonymous functions and non-local packages stay outside the visible graph. Dashed edges are interface/dynamic-dispatch candidates rather than definite static calls.

Navigate the graph

• A new focus starts with one hop. Use the + control on any node to expand only that function by one additional hop. The control becomes − after expansion; collapsing it removes any now-unreachable expanded subtree while preserving nodes still supplied by another path.
• Click a node to inspect it, then choose Focus graph here to make it the new root.
• Choose Extended for contracts and intent or Simplified for compact function-name nodes. Nodes are draggable in both views and their layouts are saved separately in browser storage.
• Graphs open at a readable 100% scale. Use the scrollbars, a trackpad, or Shift+wheel to move through an oversized graph. Use +, −, and Fit for zoom; Hand provides drag-to-scroll navigation with a viewport of extra room beyond every graph edge, so nodes can be moved clear of the detail panel. Disable it to resume node dragging.
• Reset layout clears saved positions for the current root, direction, test setting, and view.
• Rescan codebase rebuilds the analysis after source changes without restarting Flowmap. The current graph refreshes when its root still exists; otherwise Flowmap returns to function search. A failed rescan leaves the last successful graph available.
• When the module belongs to a Git repository, the header shows the branch captured by the current scan. Changes lists functions that differ from HEAD, including staged, unstaged, and non-ignored untracked work; changed-function details can switch their source viewer to a unified diff.

Classification

Authored Operations (Pure) and Side Effect (Edge) documentation wins. Otherwise Flowmap conservatively identifies visible effects such as package-state writes, object/index mutation, goroutines, channel sends, time/random access, and known I/O packages. A function is inferred pure only when it has no visible effects, no effect-unknown external calls, and every analyzed local callee is pure. Every result includes its provenance and evidence.

Optional intent summaries

AI generation is disabled by default. Opt in with a command that reads one JSON SummaryRequest from stdin and writes {"summary":"..."} to stdout:

go run ./cmd/flowmap serve /path/to/module --summarizer-command /path/to/your-adapter

Generation happens only when you press Generate fallback intent. Results are marked generated and cached by provider identity plus exact function source under the operating-system user cache; the analyzed repository is never modified.

HTTP API

• GET /api/search?q=<text>&tests=<bool>
• GET /api/graph?root=<id>&direction=<upstream|downstream|both>&depth=<0..8>&tests=<bool>
• GET /api/functions/<id>
• GET /api/git-status
• POST /api/functions/<id>/summary
• POST /api/rescan

Develop

Building Flowmap from source requires Go 1.25 or newer. Published binaries are built with Go 1.26 and support projects loaded by Go 1.24 through Go 1.26; see the user guide for the distinction between a module's go directive and its active toolchain.

go test ./...
go build ./cmd/flowmap

Build the three shareable release archives and their checksum manifest:

make release VERSION=0.1.0

Pushing a tag such as v0.2.0 runs .github/workflows/release.yml, builds and verifies every supported archive, and publishes them through GitHub Releases. .github/workflows/pages.yml publishes the canonical USER_GUIDE.md to GitHub Pages whenever the guide changes on main.

Maintainers can run the guarded release script from a clean, synchronized main branch. It builds the release locally before creating and pushing the annotated tag:

scripts/release.sh 0.2.0

Enable Settings → Pages → Build and deployment → GitHub Actions once for the repository before the first Pages deployment.