Skip to content

QUICKSTART.md

Latest commit

 

History

History
206 lines (159 loc) · 6.02 KB

QUICKSTART.md

File metadata and controls

206 lines (159 loc) · 6.02 KB
Raw

Quickstart

Run In 3 Steps

mvn package
./bin/analyze-flow /path/to/project
open analyze-flow-dashboard.html

One-command project installation plus first scan:

java -jar target/analyze-flow.jar /path/to/project --install --fast
open /path/to/project/.analyze-flow/reports/dashboard.html

The install step creates analyze-flow.yaml, .analyze-flow/README.md, and .analyze-flow/reports/ inside the target project. Existing files are skipped unless --force-install is used.

If you run from inside the project you want to analyze, the path is optional:

./bin/analyze-flow

The command auto-detects Java/Spring Boot projects from pom.xml, build.gradle, and .java files. It writes:

  • analyze-flow-report.json
  • analyze-flow-dashboard.html

For a very quick scan on larger projects:

./bin/analyze-flow --fast

Fast mode disables expensive similar-code comparison, caps very large files, and keeps the report/dashboard path optimized for quick feedback.

Run With Local API

mvn package
./bin/analyze-flow --serve --port 8765

Then open:

  • http://127.0.0.1:8765/dashboard
  • http://127.0.0.1:8765/api/summary
  • http://127.0.0.1:8765/api/analytics
  • http://127.0.0.1:8765/api/workflows
  • http://127.0.0.1:8765/api/findings
  • http://127.0.0.1:8765/api/mcp

For enterprise use, protect sensitive report endpoints:

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

/api/report and /api/findings use the token when enabled. Summary and analytics endpoints remain lightweight integration endpoints.

Run The Next.js UI

cd ui
npm install
npm run dev

Open http://127.0.0.1:3000. The UI can use sample data, upload a generated JSON report, or connect to the local analyzer API through its Next.js proxy route.

Project Config

Place one of these files in the target project:

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

Example:

sourceIncludes:
  - src/main/java
repeatedCallThreshold: 2
similarityThresholdPercent: 82
estimatedDbLatencyMs: 35
estimatedExternalLatencyMs: 120
enableUnusedCodeAnalysis: true
enableStructureAnalysis: true
enableSimilarityAnalysis: true
enableWorkflowAnalysis: true
fastMode: false
analysisParallelism: 4
maxSourceFileBytes: 1500000
maxSimilarityCandidates: 500
maxSimilarityComparisons: 50000
maxMethodTokensForSimilarity: 700
maxWorkflowScenarios: 80
cacheApiResponses: true
redactSecrets: true
exposeSourceSnippets: false
exposeAbsolutePaths: false
allowSourceIncludesOutsideProject: false
apiServerEnabled: false
apiServerPort: 8765
apiRequireToken: false
apiAuthToken: ""
apiAllowOrigin: ""
mcpServiceEnabled: false
mcpServerUrl: ""
mcpModel: "claude-opus-4.7"
mcpCardTitle: "AI Quality Assistant"
dbCallPatterns:
  - ".*Repository\\.(find|get|read|query|search|save|delete|count).*"
externalCallPatterns:
  - ".*RestTemplate\\.(getForObject|getForEntity|postForObject|exchange).*"
  - ".*WebClient.*\\.(get|post|put|delete|retrieve|exchangeToMono).*"

Embed As A Java Library

After publishing to your internal Maven repository:

<dependency>
  <groupId>io.github.analyzeflow</groupId>
  <artifactId>analyze-flow</artifactId>
  <version>0.1.0</version>
</dependency>

Use the API:

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

import java.nio.file.Path;

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

Or scan and write both reports:

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

CLI Options

./bin/analyze-flow [project-path] \
  --config analyze-flow.yaml \
  --output analyze-flow-report.json \
  --html-output analyze-flow-dashboard.html \
  --fast \
  --install \
  --serve \
  --port 8765 \
  --api-token change-me

Use --no-dashboard for JSON-only CI mode.

Security Controls

  • redactSecrets=true: redacts common access tokens, passwords, private keys, bearer credentials, and API keys from JSON/UI output.
  • exposeSourceSnippets=false: hides source snippets in finding cards by default.
  • exposeAbsolutePaths=false: stores only a project display name instead of full workstation paths.
  • allowSourceIncludesOutsideProject=false: prevents config from scanning outside the selected project root.
  • apiAllowOrigin: leave empty unless another local UI must call the API from a specific origin. Wildcard CORS is intentionally ignored.
  • apiRequireToken=true plus apiAuthToken: requires Authorization: Bearer <token> or X-Analyze-Flow-Token for sensitive report APIs.

Performance Tuning

  • analysisParallelism: number of parser workers.
  • maxSourceFileBytes: skip generated or huge files that slow scanning.
  • enableSimilarityAnalysis: turn off if you need the fastest possible scan.
  • enableWorkflowAnalysis: detects Spring controller endpoints and produces workflow scenarios.
  • maxSimilarityCandidates: caps methods considered for duplicate-code comparison.
  • maxSimilarityComparisons: hard stop for expensive pair comparisons.
  • maxWorkflowScenarios: caps endpoint scenario cards in very large services.
  • cacheApiResponses: keeps /api/* payloads in memory after analysis so dashboard/API reads are immediate.

Enable MCP/AI Assist Card

The tool does not call an AI model by default. It only surfaces configuration and exposes report data through the API so an enterprise MCP service can consume it.

analyzeFlow.mcpServiceEnabled=true
analyzeFlow.mcpServerUrl=http://127.0.0.1:9000/mcp
analyzeFlow.mcpModel=claude-opus-4.7
analyzeFlow.mcpCardTitle=AI Quality Assistant

When enabled, the dashboard card shows the configured model and MCP endpoint. The MCP service can read /api/report or /api/analytics and return deeper explanations in a future integration.