Opening an unfamiliar repository often begins with the same questions: Where is the entry point? Which files depend on this module? Who understands this area? What could break if I change it?
braedonsaunders/codeflow turns a GitHub repository or local codebase into an interactive architecture map directly in the browser. Paste a repository URL—or select a local folder—and Codeflow analyzes files, functions, dependencies, patterns, security signals, ownership, churn, and change impact without requiring an account or application backend.
Its strongest idea is simple: architecture should be explorable. Instead of reading a folder tree and guessing at relationships, developers can click a node, follow its dependencies, measure its blast radius, and switch visual modes to expose layers or hot spots.
Codeflow is MIT-licensed, can run from a single index.html, and keeps processing client-side. That combination makes it unusually easy to try, inspect, self-host, and use on sensitive local projects.
What Codeflow Does
Codeflow is a client-side codebase visualization and static-analysis tool. It fetches repository data directly from GitHub—or reads local files—and builds a navigable dependency graph.
The current feature set includes:
- interactive file and dependency graphs with click, drag, pan, and zoom
- blast-radius analysis for individual files
- PR impact analysis from a pull-request URL
- ownership signals based on Git history
- activity heatmaps based on commit frequency
- detection of patterns, anti-patterns, dead code, cycles, and coupling
- checks for secrets, injection risks, dangerous
eval(), and production debug statements - an A–F health grade
- local folder, file-selection, and drag-and-drop analysis
- JSON, Markdown, text, SVG, PDF, and raw JSON exports
- Markdown and wiki-link graphs for documentation or Obsidian vaults
It also provides Codeflow Card, a GitHub Action that recalculates repository health, scale, fragility, and hidden costs after merges and publishes the result as a theme-aware SVG in the README.
From Files to an Architecture Map
Codeflow’s architecture is deliberately compact. The main application is a single browser page built with React 18, D3.js 7, and Babel loaded from pinned CDNs. There is no server-side analysis service and no package-install step for the app itself.
The parser extracts functions and dependency signals from supported source files. The visualization layer turns those relationships into nodes and edges. GitHub API data adds repository metadata, history, and contributor context.
Four visual modes help answer different questions:
- Folder: understand the repository’s physical organization.
- Layer: distinguish UI, service, utility, and other architectural roles.
- Churn: expose files that change frequently.
- Blast: show the potential impact of changing a selected file.
The result is not a replacement for reading code. It is a faster map for deciding where to read first.
Blast Radius and PR Impact
Dependency graphs become operationally useful when they support change decisions.
Select a file and Codeflow highlights the files that depend on it. This provides a quick blast-radius estimate: shared utilities and foundational services often reveal much wider impact than leaf-level UI modules.
PR impact analysis applies the same idea to proposed changes. Paste a pull-request URL to see the touched files and their architectural reach. Reviewers can use this to identify areas that deserve deeper tests, additional owners, or a more cautious rollout.
Blast radius should be interpreted as a prioritization signal. Dynamic imports, runtime wiring, reflection, generated code, and framework conventions can hide relationships from heuristic analysis.
Health, Patterns, and Security Signals
Codeflow summarizes codebase health using dead-code percentage, circular dependencies, coupling metrics, and security issues. It also recognizes common patterns such as Singleton, Factory, Observer/Event, and React custom hooks, while flagging possible God Objects and highly coupled modules.
The security scanner looks for hardcoded secrets and API keys, SQL injection patterns, dangerous eval() calls, and debug statements. The tool excludes tests, fixtures, documentation, and common tooling folders from some checks to reduce noise, while keeping executable CI and deployment surfaces in scope for secret detection.
These are screening signals, not formal security findings. A regex- or heuristic-based scanner can produce false positives and miss context-dependent vulnerabilities. Treat results as a review queue that needs human confirmation.
Privacy-First Local Analysis
Codeflow performs processing in the browser. For public repositories, the browser calls GitHub directly. For private repositories, a personal or GitHub App token can be supplied locally; the project states that tokens remain in browser memory and are cleared when the tab closes.
Local projects can be opened by folder selection or drag and drop, including custom exclusion patterns for caches, uploads, generated assets, or attachments. This path works offline and does not require code to be uploaded to GitHub.
That client-side model is compelling for quick inspection of internal or sensitive projects. Teams should still assess the page, loaded CDN dependencies, token permissions, and browser environment according to their security policy.
How to Try or Self-Host It
The quickest option is the project’s hosted application: paste a GitHub repository or pull-request URL and analyze it immediately.
Self-hosting is intentionally minimal:
git clone https://github.com/braedonsaunders/codeflow.git
cd codeflow
open index.html
There is no npm install or build pipeline for the application. Because dependencies are loaded from CDNs, fully offline use of a fresh self-hosted copy may require those browser assets to have been cached or hosted locally; local file analysis itself remains client-side.
Unauthenticated GitHub API access is limited to 60 requests per hour. A token raises the documented allowance to 5,000 requests per hour, which matters for larger repositories because Codeflow may request individual file contents.
Supported Languages and Realistic Accuracy
Codeflow lists support for a broad range: JavaScript, TypeScript, Python, Java, Go, Ruby, PHP, Vue, Svelte, Rust, C/C++, C#, Swift, Kotlin, Scala, Elixir, Erlang, Haskell, Lua, R, Julia, Dart, Shell, PowerShell, functional languages, and others.
Breadth comes with a tradeoff. The project explicitly describes dependency analysis as heuristic. Unique functions can be matched by name, while duplicates are scoped using files and explicit imports. Dynamic imports and renamed runtime references may still be missed.
Use Codeflow for fast orientation and hypothesis generation. For migration plans, security sign-off, or deletion decisions, confirm important relationships with language-native tooling, tests, runtime telemetry, and code owners.
A Practical Team Workflow
A useful workflow is:
- Generate the folder view to learn the repository shape.
- Switch to layers to identify architectural boundaries.
- Inspect churn to find active or unstable areas.
- Select the planned change and examine its blast radius.
- Review ownership before assigning reviewers.
- Export the report as JSON or Markdown for the change record.
- Validate important findings with tests and native analysis tools.
- Add Codeflow Card if continuous architecture drift visibility is valuable.
This makes Codeflow a conversation starter between maintainers, reviewers, and new contributors—not merely a one-time diagram generator.
Final Take
Codeflow lowers the cost of understanding an unfamiliar codebase. Its single-page, browser-first design combines architecture graphs, change impact, ownership, churn, health signals, security checks, reports, and README cards without asking teams to deploy another analysis backend.
Its value is highest when used honestly: as a fast, visual model of a repository rather than a perfect semantic representation. That model can still answer the questions developers face every day—where to start, what connects, who knows the area, and what deserves extra care before a change ships.
