Analyze Flow

Analyze Flow is a Java/Spring Boot-first CLI, reusable library, local API, and Next.js dashboard for understanding backend code quality, endpoint workflows, repeated DB/API calls, cache opportunities, latency risk, dead code, and architecture smells.

The long-term design is cross-platform: Java/Spring Boot today, with Go, Python, and TypeScript analyzers added behind the same report contract later.

The screenshot above uses dummy orders-service data from the Next.js UI sample report.

What It Does
Use Cases
Architecture
Project Structure
Quickstart
CLI Usage
Next.js UI
Report Model
Detection Logic
Security Defaults
Extension Plan
Documentation

What It Does

Analyze Flow scans an existing backend project and generates a structured JSON report plus visual dashboards.

It currently detects:

Repeated database calls such as repository, JdbcTemplate, EntityManager, and Mongo template calls.
Repeated third-party/API calls such as RestTemplate, WebClient, Java HttpClient, OkHttp, and Feign-style calls.
Calls inside loops where batching, request-scope memoization, Redis, or Caffeine can reduce latency.
Pure function candidates that may benefit from memoization.
Similar method bodies using token normalization, n-gram Jaccard similarity, and LCS ratio.
Long if/switch logic that may be better expressed with Strategy or Factory patterns.
Direct client construction that should move behind an injected Proxy, Adapter, or Gateway.
Unused private methods, unused local variables, unused parameters, and unreachable statements.
Loop hotspots such as nested loops and large loop-heavy methods.
Folder/package structure smells such as controller-to-repository shortcuts and missing test source folders.
Spring controller endpoint workflows with happy-path, validation/error, bulk/loop, and dependency-latency scenarios.

Use Cases

Role	Use Case	Output
Developer	Run one command inside a service before refactoring.	JSON report, HTML dashboard, endpoint workflow view.
Tech Lead	Review repeated DB/API calls and cache opportunities across a module.	Latency savings, top findings, workflow risk cards.
Architect	Spot controller-service-repository boundary problems and pattern opportunities.	Architecture findings and recommendation cards.
Platform Team	Expose analyzer output to internal quality dashboards.	`/api/summary`, `/api/analytics`, `/api/workflows`, `/api/report`.
SaaS/Enterprise Team	Build a code-quality product around scan snapshots.	Stable report schema, local analyzer, Next.js UI starting point.

Architecture

Product View

flowchart LR
    Project["Existing Backend Project"] --> CLI["analyze-flow CLI"]
    CLI --> Config["Config Loader<br/>properties / yaml / json"]
    CLI --> Engine["Analysis Engine"]
    Engine --> Java["Java Analyzer<br/>JavaParser AST"]
    Engine -. later .-> Go["Go Analyzer"]
    Engine -. later .-> Python["Python Analyzer"]
    Engine -. later .-> TS["TypeScript Analyzer"]
    Java --> Detectors["Detectors<br/>redundancy / purity / patterns / waste / structure"]
    Java --> Workflow["Workflow Analyzer<br/>Spring endpoint scenarios"]
    Detectors --> Report["AnalysisReport JSON"]
    Workflow --> Report
    Report --> OfflineHtml["Generated HTML Dashboard"]
    Report --> LocalApi["Local API Server"]
    Report --> NextUi["Next.js Dashboard"]

Runtime View

sequenceDiagram
    participant User
    participant CLI as analyze-flow CLI
    participant Config as ConfigLoader
    participant Parser as JavaParser AST
    participant Detectors
    participant Report as ReportWriter
    participant UI as HTML / Next.js UI

    User->>CLI: analyze-flow ./project --install --fast
    CLI->>Config: Load defaults + project config
    CLI->>Parser: Parse Java source files
    Parser->>Detectors: Method profiles + call sites
    Detectors->>Detectors: Detect repeated IO, memoization, patterns, waste
    Detectors->>Report: Build AnalysisReport
    Report->>UI: Write JSON and dashboard
    UI-->>User: Cards, charts, workflows, recommendations

Endpoint Workflow View

flowchart TD
    Request["HTTP Request"] --> Controller["Spring Controller Method"]
    Controller --> Branch{"Validation / Branches"}
    Branch --> Service["Service / Orchestration"]
    Service --> Cache["Cache / Memoization Candidate"]
    Service --> DB["Repository / DB Call"]
    Service --> API["External API / Gateway"]
    DB --> Response["HTTP Response"]
    API --> Response
    Cache --> Response

Project Structure

.
├── bin/
│   └── analyze-flow
├── docs/
│   ├── assets/
│   │   └── analyze-flow-ui-screenshot.svg
│   ├── DASHBOARD.md
│   ├── ENTERPRISE_ARCHITECTURE.md
│   ├── MAVEN_CENTRAL.md
│   ├── NEXT_UI.md
│   ├── QUICKSTART.md
│   └── SECURITY.md
├── examples/
│   ├── analyze-flow.yaml
│   └── application.properties
├── src/main/java/com/analyzeflow/
│   ├── api/
│   ├── cli/
│   ├── config/
│   ├── core/
│   ├── install/
│   ├── java/
│   ├── model/
│   ├── report/
│   └── security/
├── src/main/resources/
│   └── default-analyze-flow.yaml
├── src/test/java/com/analyzeflow/
├── ui/
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── package.json
│   └── README.md
└── pom.xml

Package Responsibilities

Package	Responsibility
`com.analyzeflow.api`	Public Java library API.
`com.analyzeflow.cli`	Terminal command, flags, local server startup.
`com.analyzeflow.config`	Defaults, config discovery, properties/yaml/json loading.
`com.analyzeflow.core`	Language-neutral analyzer interface and dispatch.
`com.analyzeflow.install`	One-command project bootstrap.
`com.analyzeflow.java`	JavaParser scanner, detectors, workflow analysis.
`com.analyzeflow.model`	Stable JSON report DTOs.
`com.analyzeflow.report`	JSON writer, generated HTML dashboard, local API server.
`com.analyzeflow.security`	Report sanitization and secret redaction.
`ui/`	Next.js dashboard for upload/live API report visualization.

Quickstart

Build the CLI:

mvn test
mvn package

The executable jar is produced at:

target/analyze-flow.jar

Analyze any Spring Boot project:

java -jar target/analyze-flow.jar /path/to/spring-boot-project --fast

Install project-local config and generate the first report in one command:

java -jar target/analyze-flow.jar /path/to/spring-boot-project --install --fast

This creates these files inside the target project:

analyze-flow.yaml
.analyze-flow/README.md
.analyze-flow/reports/report.json
.analyze-flow/reports/dashboard.html

CLI Usage

analyze-flow ./project-path \
  --config ./project-path/analyze-flow.yaml \
  --output ./analyze-flow-report.json \
  --html-output ./analyze-flow-dashboard.html

Common commands:

./bin/analyze-flow
./bin/analyze-flow ./project --fast
./bin/analyze-flow ./project --install --fast
./bin/analyze-flow ./project --no-dashboard --output report.json

Start the local dashboard/API server:

./bin/analyze-flow ./project --serve --port 8765

Protect sensitive report endpoints with a bearer token:

./bin/analyze-flow ./project --serve --api-token change-me
curl -H "Authorization: Bearer change-me" http://127.0.0.1:8765/api/report

Local API endpoints:

Endpoint	Purpose
`GET /dashboard`	Generated local HTML dashboard.
`GET /api/report`	Full report, token-protected when `apiRequireToken=true`.
`GET /api/summary`	Summary metrics for integration.
`GET /api/analytics`	Chart-ready analytics data.
`GET /api/workflows`	Endpoint workflow scenarios.
`GET /api/findings`	Findings list, token-protected when `apiRequireToken=true`.
`GET /api/mcp`	MCP/AI-assist configuration status.

Next.js UI

The richer interactive UI lives in ui/.

Run it:

cd ui
npm install
npm run dev

Open:

http://127.0.0.1:3000

The UI supports three modes:

Mode	How It Works
Sample	Opens with dummy `orders-service` report data.
Upload JSON	Upload any `analyze-flow-report.json` file.
Live Local API	Connects to a running `analyze-flow --serve` process through the Next.js proxy route.

Live local mode:

java -jar target/analyze-flow.jar /path/to/project --serve --api-token change-me

Then in the Next.js UI:

Local API: http://127.0.0.1:8765
Token: change-me

The proxy route is:

GET /api/analyze-flow/report?baseUrl=http://127.0.0.1:8765

It calls:

GET http://127.0.0.1:8765/api/report

Report Model

The report is intentionally stable so the generated HTML dashboard, Next.js UI, local API, CI jobs, and future SaaS backend can consume the same shape.

{
  "toolName": "analyze-flow",
  "version": "0.1.0",
  "generatedAt": "2026-07-04T00:00:00Z",
  "projectPath": "orders-service",
  "languagesDetected": ["java"],
  "summary": {
    "filesScanned": 128,
    "methodsScanned": 942,
    "findingsCount": 37,
    "estimatedCurrentLatencyMs": 1920,
    "estimatedOptimizedLatencyMs": 740,
    "estimatedSavingMs": 1180,
    "estimatedImprovementPercent": 61
  },
  "workflows": {
    "endpointCount": 2,
    "scenarioCount": 6,
    "scenarios": []
  },
  "findings": []
}

Detection Logic

Redundancy Detector

The redundancy detector works in four passes:

Parse source files into ASTs.
Build a MethodProfile for each Java method.
Group DB/API calls by semantic key.
Emit findings for repeated calls, loop calls, cross-method repeated access, and similar method bodies.

Latency estimate:

current = observed_operations * configured_backend_latency
optimized = first_backend_call + duplicate_operations * configured_cache_latency
saving = current - optimized

Similarity Analysis

Two code blocks are compared like this:

Tokenize source into identifiers, literals, keywords, and operators.
Normalize literals to LIT.
Normalize identifiers to stable placeholders per block.
Compute token 3-gram Jaccard similarity.
Compute longest common subsequence ratio.

Final score:

score = 0.60 * jaccard_3gram + 0.40 * lcs_ratio

Workflow Analyzer

The workflow analyzer detects Spring controller mappings such as @GetMapping, @PostMapping, and @RequestMapping, then creates endpoint scenario cards:

Scenario	Meaning
`HAPPY_PATH`	Normal request and response flow.
`VALIDATION_OR_ERROR_PATH`	Branch-heavy path with validation or exception outcomes.
`BULK_OR_LOOP_PATH`	Loop-heavy path where runtime may grow with input size.
`DEPENDENCY_LATENCY_PATH`	DB/API dependency path with latency risk.

Configuration

Analyze Flow auto-discovers config in this order:

analyze-flow.yaml
analyze-flow.yml
analyze-flow.json
analyze-flow.properties
src/main/resources/application.properties
src/main/resources/application.yaml
src/main/resources/application.yml

Example Spring properties:

analyzeFlow.sourceIncludes=src/main/java
analyzeFlow.repeatedCallThreshold=2
analyzeFlow.dbCallPatterns=.*Repository\\.(find|get|query|save|delete|count).*
analyzeFlow.externalCallPatterns=.*RestTemplate\\.(getForObject|postForObject|exchange).*
analyzeFlow.enableWorkflowAnalysis=true
analyzeFlow.redactSecrets=true
analyzeFlow.exposeSourceSnippets=false
analyzeFlow.exposeAbsolutePaths=false

Example YAML:

sourceIncludes:
  - src/main/java
repeatedCallThreshold: 2
similarityThresholdPercent: 82
enableUnusedCodeAnalysis: true
enableStructureAnalysis: true
enableSimilarityAnalysis: true
enableWorkflowAnalysis: true
maxWorkflowScenarios: 80
redactSecrets: true
exposeSourceSnippets: false
exposeAbsolutePaths: false

Security Defaults

Analyze Flow handles source-derived data carefully:

Secrets are redacted from reports by default.
Source snippets are hidden by default.
Absolute project/config paths are hidden by default.
Source include paths outside the target project root are skipped by default.
The local API binds to 127.0.0.1.
Wildcard CORS is not emitted.
Sensitive report endpoints can require a bearer token.
The generated dashboard and local server use no-store, no-sniff, no-referrer, frame-deny, and CSP protections.

Reusable Library API

Use the library from Java after publishing to an internal or public Maven repository:

import com.analyzeflow.api.AnalyzeFlow;
import com.analyzeflow.model.AnalysisReport;

import java.nio.file.Path;

AnalysisReport report = AnalyzeFlow.scan(Path.of("."));

Write both JSON and HTML:

AnalyzeFlow.builder()
    .projectRoot(Path.of("."))
    .jsonOutput(Path.of("analyze-flow-report.json"))
    .htmlOutput(Path.of("analyze-flow-dashboard.html"))
    .build()
    .analyze();

Extension Plan

The CLI and report model should stay stable while new language analyzers are added.

Language	Suggested Parser	Target Output
Go	`go/parser` or tree-sitter	Function profiles, call sites, endpoint handlers.
Python	`libcst` or Python `ast`	Function profiles, Flask/FastAPI/Django routes.
TypeScript	`ts-morph` or TypeScript compiler API	Nest/Express routes, call sites, service flows.

Each analyzer should emit the same internal concepts:

source files
method/function profiles
call sites
loop and branch metadata
endpoint/workflow metadata
findings and recommendations

Documentation

Verification

Current verification commands:

mvn test
cd ui && npm run build
cd ui && npm audit

Expected status:

Java tests: passing
Next.js production build: passing
UI dependency audit: 0 vulnerabilities

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Analyze Flow

Table Of Contents

What It Does

Use Cases

Architecture

Product View

Runtime View

Endpoint Workflow View

Project Structure

Package Responsibilities

Quickstart

CLI Usage

Next.js UI

Report Model

Detection Logic

Redundancy Detector

Similarity Analysis

Workflow Analyzer

Configuration

Security Defaults

Reusable Library API

Extension Plan

Documentation

Verification

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Analyze Flow

Table Of Contents

What It Does

Use Cases

Architecture

Product View

Runtime View

Endpoint Workflow View

Project Structure

Package Responsibilities

Quickstart

CLI Usage

Next.js UI

Report Model

Detection Logic

Redundancy Detector

Similarity Analysis

Workflow Analyzer

Configuration

Security Defaults

Reusable Library API

Extension Plan

Documentation

Verification