Flow Analyzer

3-tier application flow visualizer with client-side static code analysis.

Upload source files from any project → the browser-based analysis engine extracts functions, classes, imports, routes, and data flow → explore the results as an interactive flowchart with three levels of detail.

Prerequisites

• Node.js 18+ (tested with v20.x)
• npm 8+
• Python 3.10+ with Flask (pip install -r requirements.txt)
• For systemd service: Linux with systemd

Quick Start

# Clone or copy to your Pi
cd flow-analyzer

# Run setup (installs deps, builds, creates systemd service)
chmod +x setup.sh
sudo bash setup.sh --port 8090

# Or run manually
npm install
npm run build
python3 server.py --port 8090

Then open http://<pi-ip>:8090 from any device on your LAN.

Architecture

flow-analyzer/
├── index.html          # Vite entry point
├── src/
│   ├── main.jsx        # React mount
│   └── App.jsx         # Full application (analysis engine + viewer)
├── server.py           # Flask static file server (production)
├── setup.sh            # Install, build, systemd setup
├── package.json        # Node dependencies (Vite + React)
├── vite.config.js      # Build config
└── dist/               # Built static files (generated)

How It Works

Static Analysis Engine (no API required)

The analysis runs entirely in the browser using regex-based extractors:

Language Family	Detects
Python	functions, classes, imports, decorators, Flask/Django routes, DB calls, I/O
JavaScript / TypeScript	functions, classes, imports/require, Express routes, DB calls, React components
PHP	functions, classes, use/require, Laravel/Slim routes, PDO/mysqli calls
Go	functions, structs, imports, HTTP handlers, database/sql calls
Ruby	methods, classes, require, Rails routes, ActiveRecord
Rust	functions, structs/enums/traits, use imports
Java / Kotlin	methods, classes, imports, Spring annotations, JPA

3-Tier Flowchart Generation

Tier 1 — System Overview: Files are classified by role (entry point, routes, models, middleware, auth, database, services, UI, config, utils) and grouped into high-level architectural nodes. Cross-role import analysis infers connections.

Tier 2 — Module Detail: Individual files within each role group, with shape assignment based on detected features (has DB calls → cylinder, has conditionals → diamond, has I/O → parallelogram).

Tier 3 — Component Detail: Functions, classes, and routes within each file. Shape assignment uses naming conventions:

• is_valid, check_auth → decision (diamond)
• get_user, fetch_data → data I/O (parallelogram)
• save_record, delete_item → database (cylinder)
• send_email, dispatch_event → subroutine (double rect)
• __init__, setup → terminal (rounded rect)

Optional AI Enhancement

The ✦ AI Enhance button (visible in the viewer) optionally sends the generated flowchart to the Claude API for improved labels, descriptions, and edge annotations. This is the only feature that makes a network call. The flowchart works completely without it.

Flowchart Shapes

Standard flowchart conventions:

Shape	Meaning
Rectangle	Process — computation, business logic
Diamond	Decision — conditionals, validation
Parallelogram	Data — input/output, API payloads
Cylinder	Database — persistent storage, caches
Rounded rect	Terminal — entry/exit points
Double-bordered	Subroutine — external calls, libraries
Wavy bottom	Document — logs, reports, generated files

Development

# Hot-reload dev server
npm run dev

# Build for production
npm run build

# Preview production build locally
npm run preview

Service Management

sudo systemctl start flow-analyzer
sudo systemctl stop flow-analyzer
sudo systemctl status flow-analyzer
journalctl -u flow-analyzer -f

Server Browse

When server.py is running, a Browse Server button appears in the drop zone. This lets you browse the server's filesystem and load a project directly — no drag-and-drop needed.

The server exposes three API endpoints:

Endpoint	Description
GET /api/project-root	Returns the configured root label (used by the frontend to detect server support)
GET /api/browse?path=	Lists directory entries under the root
POST /api/load-project	Recursively reads all source files in a directory (max 500 files, 500 KB each)

All paths are validated against the configured root — directory traversal is blocked.

Note: The service must run as the target user (not root) so Path.home() resolves correctly. setup.sh uses $SUDO_USER to set the correct User= in the service file.

Configuration

Setting	Default	How to change
Port	8090	setup.sh --port PORT or server.py --port
Browse root	invoking user's ~	setup.sh --root DIR or server.py --root DIR
Bind address	0.0.0.0	server.py --host 127.0.0.1
Debug mode	off	server.py --debug

Troubleshooting

Build fails with "dist/ not created"

• Ensure Node.js 18+ is installed: node --version
• Try deleting node_modules and running npm install fresh

Server shows "Build directory not found"

• Run npm run build first to generate dist/

Cannot access from other devices on LAN

• Check firewall: sudo ufw allow 8090/tcp
• Verify bind address (default is 0.0.0.0 for LAN access)

Service fails to start

• Check logs: journalctl -u flow-analyzer -f
• Ensure the service user has read access to the project directory

Documentation

• CLAUDE.md — AI agent guidance (build commands, architecture, common tasks)
• AGENTS.md — Detailed code style and conventions

License

MIT