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.

Table Of Contents

• 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"]

Loading

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

Loading

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

Loading

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:

1. Parse source files into ASTs.
2. Build a MethodProfile for each Java method.
3. Group DB/API calls by semantic key.
4. 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:

1. Tokenize source into identifiers, literals, keywords, and operators.
2. Normalize literals to LIT.
3. Normalize identifiers to stable placeholders per block.
4. Compute token 3-gram Jaccard similarity.
5. 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:

1. analyze-flow.yaml
2. analyze-flow.yml
3. analyze-flow.json
4. analyze-flow.properties
5. src/main/resources/application.properties
6. src/main/resources/application.yaml
7. 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/javarepeatedCallThreshold: 2similarityThresholdPercent: 82enableUnusedCodeAnalysis: trueenableStructureAnalysis: trueenableSimilarityAnalysis: trueenableWorkflowAnalysis: truemaxWorkflowScenarios: 80redactSecrets: trueexposeSourceSnippets: falseexposeAbsolutePaths: 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:

importcom.analyzeflow.api.AnalyzeFlow;
importcom.analyzeflow.model.AnalysisReport;
importjava.nio.file.Path;
AnalysisReportreport = 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

• Quickstart
• Dashboard
• Next.js UI
• Enterprise Architecture
• Security
• Maven Central Publishing

Verification

Current verification commands:

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

Expected status:

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