CodeLens — Java Codebase Intelligence Platform

A high-performance, 100% offline, self-contained Java codebase intelligence and architectural exploration tool. Scan any Java source repository to extract Abstract Syntax Trees (AST), map dependency and call hierarchies, investigate repository-wide field mutation impacts, identify structural drift, audit Git author churn, and inspect source files with syntax highlighting — all served locally through an interactive cyber-dark web interface.

📖 Comprehensive Guides & Architecture Blueprints: Browse the Official GitHub Documentation Wiki for in-depth subsystem guides, ADRs, process specifications, and REST API references.

Official GitHub Documentation Wiki
Overview & Core Capabilities
Architecture & Tech Stack
- System Architecture
- Architectural Decisions (ADRs)
System Requirements & Zero-Admin Execution
Build & Quick Start
Shipping & Deployment Handbook
Configuration Management (codelens.conf)
Scanning Engine & Operational Guide
Workspace Views & Feature Guide
Critical Path Trace & Execution Analysis
Semantic Archetypes & Domain Templates
Impact Investigation & Deep Architectural Workflows
- Method Blast Radius Analysis
- Field-to-Method Mutation Propagation Chains
Data Storage, H2 Compaction & High-Scale Persistence
Comprehensive REST API Reference
Keyboard Shortcuts
Troubleshooting & FAQ

Overview & Core Capabilities

#	Capability	Description	Technical Engine
1	Source AST Indexing	Scans 100% of `.java` source files, extracting packages, types, methods, fields, modifiers, and line numbers into an embedded database.	JavaParser 3.25.8 + Embedded H2 Database
2	Dynamic Call Hierarchies	Computes upstream callers and downstream callees across methods with user-selectable BFS traversal depths (1 to 15 hops / Max).	In-memory JGraphT directed graph + reversed BFS iterator
3	CodeStory Transaction Narratives	Automatically discovers and synthesizes end-to-end execution flows from entry points down to persistent database mutation sinks into plain-English storylines.	Multi-hop sink tracer + Narrative synthesis engine
4	"Teach Me" Onboarding Tour	Guided 5-layer architectural tour (Domain Core, Ingestion & Store, Topology & Layouts, Semantic Storylines, Intelligence Reports) with source citations.	Multi-layer tour generator + Step traverser
5	Field Impact & Mutation Chains	Maps every method reading or writing a field, tracing multi-hop upstream triggers (`Field` $\leftarrow$ `Writers` $\leftarrow$ `Callers`) across the entire repository.	Custom relationship visitor + caller propagation engine
6	Structural Integrity Audit	14 active class-awareness rules auditing AST signature divergences, naming drift, interface contract gaps, and body hash clones.	14 AST rules + Levenshtein distance + SHA-256 hashing
7	Behavioral Hotspots Intelligence	Evaluates code risk and technical debt via composite metric $CC \times \log_2(1 + \text{churn}) \times \log_{10}(LOC)$. Overlays heat shaders on 2D Blooming Tree and 3D Software City.	JGit churn log + AST complexity scorer + Thermal shaders
8	Interactive DSM with Method Drilldown	Multi-tier Dependency Structure Matrix (`Modules` $\to$ `Packages` $\to$ `Classes` $\to$ `Methods`). Double-click headers to drill into method invocations with breadcrumbs, DAG acyclicity rating, and CSV/JSON exports.	Matrix permutation engine + Tarjan cycles + Adjacency exporter
9	Critical Path Execution Trace	Traces end-to-end execution sequences from controllers through domain services down to persistent entity mutations (`Get`, `Create`, `Modify`) and downstream audit sinks.	Multi-hop graph search + Risk scoring + Stepper Dock
10	Grounded AI Architecture Assistant	Context-grounded Q&A and code explanation engine supporting local Ollama models, OpenAI, and deterministic fallback templates.	Dual-provider AI bridge + Prompt grounding
11	Developer CLI Toolsuite	Headless CLI subcommands (`scan`, `story`, `trace`, `what-if`/`impact`, `ask`, `explain`, `teach-me`, `pr-story`) for terminals and CI/CD.	Built-in CLI runner + Direct H2/Lucene access
12	Semantic Archetypes Engine	Classifies methods and types into domain-specific roles (BaNCS ET/BT/TO/TC/Batch, Spring, DDD) with module token substitution (`{MODULE}`) and custom rules.	Regex & Prefix token substitution + LocalStorage persistence
13	Git Blame, Churn & PR Story	Computes commit counts, author blame, churn frequency, and automated Git pull request change narratives comparing base and head refs.	JGit 6.9 engine + Git PR storyline analyzer
14	Embedded Monaco Code Editor	Jump directly from graph nodes, member lists, or relationship links to precise source code lines with full Java syntax highlighting.	Monaco Editor 0.45 + REST file reader/writer
15	Reports Hub & Compliance Audits	14 comprehensive enterprise reports (Change Risk, Circular Dependencies, Dead Code, API Surface, Database Access Flow, Concurrency Audit, Module Coupling, etc.) with 60+ pre-rendered artifacts.	ReportService + REST export endpoints + Standalone HTML templates
16	Modular Two-JAR Distribution	Lightweight `codelens-app.jar` (~1.1 MB) referencing pre-extracted `codelens-deps.jar` (~22 MB) for ~4-second fast rebuilds and seamless enterprise distribution.	Maven Shade + Class-Path manifest isolation
17	125k Classes Scalability Engine	Multi-tier quotient graph rollups, Level-of-Detail (LOD) sub-pixel culling in Treemap/Sunburst/Chord/Graphify, and Sparse DSM matrix grids maintaining sub-100ms API response and 60 FPS UI rendering.	SQL-level aggregation queries + Viewport culling + Sparse DSM payload
18	Storage Compression & Compaction	LZF compressed H2 page storage with single-transaction chunk commits and MVStore tuning, eliminating leaks and reducing disk footprints by ~95%.	H2 MVStore Compression + HikariCP Transaction Safety
19	11-Engine Background Task Manager	Real-time monitoring and lifecycle controls over 11 background engines (AST Ingestion, Delta Watcher, Call Graph, Layout Engine, Module Coupling, Lucene Indexer, Git Churn, DB Sentinel, Stress Tester, Heap Watchdog, and Reports Precomputer).	Dedicated Process Hub + JMX Thresholds + REST lifecycle APIs
20	8-Stage Scan & Readiness Engine	Rigorous sequential scan execution (`PARSE`, `INDEX`, `GRAPH`, `LAYOUT`, `MODULES`, `INTEGRITY`, `CODESTORY`, `REPORTS`) guaranteeing 100% readiness across all views.	Sequential orchestrator + Dynamic SSE telemetry

Architecture & Tech Stack

System Architecture

codelens/
├── codelens-core/        Domain entities (CodeType, CodeMethod, CodeField, CodeRelationship, GitMeta, etc.)
├── codelens-parser/      JavaParser AST visitor, directory scanner, incremental delta detector
├── codelens-analysis/    In-memory call graph BFS, multi-hop field propagation, and 32-rule code reviewer
├── codelens-storage/     H2 database lifecycle, connection pooling (HikariCP), LZF compaction, Lucene indexer
├── codelens-git/         JGit repository locator, blame annotator, commit history extractor
├── codelens-api/         Javalin REST controller, file APIs, scan orchestration, shutdown handler
├── codelens-web/         Zero-build SPA (HTML5, Vanilla CSS design tokens, Canvas 2D Verlet physics, Three.js, Monaco)
├── codelens-app/         Fat-JAR bootstrap and entry point (Application.java)
└── sample-project/       Realistic 5-class algorithmic trading system for demonstration and tests

🧭 Compiled Archify Interactive Diagrams & Architecture Specs

CodeLens architecture, scanning pipelines, and lifecycles are formally modeled and compiled via Archify:

📐 System Architecture: Interactive HTML View | Spec
🔄 Ingestion Workflow: Interactive HTML View | Spec
⚡ Execution Sequence: Interactive HTML View | Spec
🌊 Data Flow Pipeline: Interactive HTML View | Spec
⏱️ Server & Ingestion Lifecycle: Interactive HTML View | Spec

See PROJECT_CONTEXT.md for full architectural blueprints, diagrams, and domain modeling.

Architectural Decisions (ADRs)

AST Parsing (JavaParser 3.25.8): Full Java 17 record, sealed class, and pattern-matching support without needing heavy bytecode compilation, maven builds, or runtime classpath dependencies.
Data Layer (H2 2.2.224 + Lucene 9.10.0): Zero-setup file-based persistence for SQL relations combined with Apache Lucene for sub-millisecond full-text entity search.
High-Speed Bulk Ingestion: Disables and drops secondary B-tree indexes during full scans to maintain $O(1)$ batch insertion speeds regardless of existing table size, rebuilding indexes and running ANALYZE upon scan completion.
Graph Visualisation (Custom HTML5 Canvas 2D): Fully offline force-directed physics engine using Verlet integration. Zero D3 or external JS bundle overhead.
3D Visualizations (Three.js r128): Self-contained WebGL shaders and post-processing bloom/vignette passes for 3D City and 3D Galaxy views.
HTTP Layer (Javalin 6.1.3 + Jetty 11): Lightweight microframework delivering ultra-fast REST endpoints and static asset serving with embedded WebSockets.

System Requirements & Zero-Admin Execution

Target Machine OS: macOS (Intel / Apple Silicon), Linux (Ubuntu, Debian, RHEL, CentOS, Arch), or Windows 10/11
Java Runtime Environment: JRE / JDK 17+ (java -version)
- macOS: brew install openjdk@17
- Ubuntu / Debian: sudo apt install openjdk-17-jre-headless
- RHEL / Fedora: sudo dnf install java-17-openjdk
- Windows: Download from Eclipse Temurin

Note

Zero Admin Rights Required (100% User-Space Execution)

CodeLens never requires Administrator / sudo / root permissions.
Unprivileged Port: Runs by default on port 7878 (any port $>1024$ can be bound without admin privileges).
Local Data Directory: Writes its embedded H2 database and Lucene index strictly to the local directory (./codelens-data or ~/.codelens-data) without touching system directories (C:\Program Files, /var, /etc).
Portable JRE (No installer needed): If you cannot install Java on a locked-down corporate Windows machine, simply extract a .zip build of Eclipse Temurin 17 JRE into any user folder (e.g. C:\Users\You\jre17) and run C:\Users\You\jre17\bin\java.exe -jar codelens.jar.

Build & Quick Start

1. Build the Modular Two-JAR Distribution

From the project root:

./mvnw clean package -DskipTests

This generates an optimized Two-JAR Modular Architecture:

codelens-app/target/codelens-app.jar (~1.1 MB): Contains all application logic, REST endpoints, analysis engines, and web resources. Daily feature updates compile in ~3-4 seconds.
codelens-app/target/codelens-deps.jar (~22 MB): Pre-packaged external dependencies (Javalin, Jetty, Jackson, Lucene, JGit, JavaParser, H2, HikariCP, JGraphT). Referenced automatically via Class-Path: codelens-deps.jar.

2. Launch the Application

java -jar codelens-app/target/codelens-app.jar

Once launched, open your web browser at: http://localhost:7878

Optional JVM Flags & Parameters

# Custom HTTP Port
java -Dcodelens.port=9090 -jar codelens-app/target/codelens-app.jar

# Custom Data & Index Directory
java -Dcodelens.data=/custom/path/codelens-data -jar codelens-app/target/codelens-app.jar

# Production Memory Allocation (for 30k+ file projects)
java -Xms1g -Xmx4g -XX:+UseG1GC -jar codelens-app/target/codelens-app.jar

3. Developer CLI Command Suite

CodeLens can run completely headless from your terminal or CI/CD pipelines without starting the web UI. All subcommands read directly from the embedded H2 database and Lucene index:

# 1. Full Ingestion & Indexing
java -jar codelens-app/target/codelens-app.jar scan ./path/to/java/src

# 2. Transaction Storyline Extraction
java -jar codelens-app/target/codelens-app.jar story [storyId]

# 3. Method Call Trace (Entry Point to Sinks)
java -jar codelens-app/target/codelens-app.jar trace "com.example.OrderController.submitOrder"

# 4. Blast Radius & Field Mutation Impact
java -jar codelens-app/target/codelens-app.jar impact "com.example.Account.balance"
java -jar codelens-app/target/codelens-app.jar what-if "com.example.PaymentService.charge"

# 5. Grounded AI Architecture Assistant
java -jar codelens-app/target/codelens-app.jar ask "Where are payments persisted in this codebase?"

# 6. Entity Purpose & Role Narrative Explanation
java -jar codelens-app/target/codelens-app.jar explain "com.example.OrderService"

# 7. Guided Onboarding Tour (Layers L1-L5)
java -jar codelens-app/target/codelens-app.jar teach-me

# 8. Git Pull Request Change Story Generator
java -jar codelens-app/target/codelens-app.jar pr-story main feature/billing-v2

Shipping & Deployment Handbook

CodeLens offers two distribution options:

Method 1: Lightweight Two-JAR Deployment (Recommended)

Build the JARs on your development machine:
```
./mvnw clean package -DskipTests
```
Copy the JAR pair: Copy both codelens-app.jar (1.1 MB) and codelens-deps.jar (22 MB) into your deployment directory:
```
scp codelens-app/target/codelens-app.jar codelens-app/target/codelens-deps.jar user@remote-machine:/opt/codelens/
```
Subsequent code updates only require transferring the tiny codelens-app.jar (1.1 MB)!

Run on target machine (requires Java 17+):

cd /opt/codelens && java -jar codelens-app.jar

Access http://localhost:7878 in any browser.

Method 2: Building from Source on the New Machine

If shipping the source repository (or cloning via Git):

Clone repository:

git clone <repo-url> codelens
cd codelens

Build using the embedded Maven Wrapper (no Maven installation required):

# On macOS / Linux
./mvnw clean package -DskipTests

# On Windows PowerShell
.\mvnw.cmd clean package -DskipTests

Run:

java -jar codelens-app/target/codelens-app.jar

Method 4: Docker Container Deployment

To run CodeLens inside an isolated container:

Build Docker Image:
```
docker build -t codelens:1.0.0 .
```

Run container mounting your local source folder and persistent data volume:

docker run -d \
  --name codelens \
  -p 7878:7878 \
  -v codelens_data:/app/data \
  -v /path/to/your/java/code:/sources:ro \
  codelens:1.0.0

Scan the mounted code in the web UI by entering /sources as the source path.

Method 5: Production Linux Systemd Service

To run CodeLens as a background system daemon on Linux servers:

Copy codelens-app.jar and codelens-deps.jar to /opt/codelens/.

Create /etc/systemd/system/codelens.service:

[Unit]
Description=CodeLens Java Intelligence Platform
After=network.target

[Service]
Type=simple
User=codelens
WorkingDirectory=/opt/codelens
ExecStart=/usr/bin/java -Xms1g -Xmx4g -XX:+UseG1GC -Dcodelens.port=7878 -Dcodelens.data=/var/lib/codelens -jar /opt/codelens/codelens-app.jar
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now codelens
sudo systemctl status codelens

Method 6: macOS LaunchAgent Daemon

To run CodeLens automatically at login in the background on macOS:

Place the JAR at ~/Applications/CodeLens/codelens.jar.

Create ~/Library/LaunchAgents/com.codelens.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.codelens.server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/java</string>
        <string>-Xms512m</string>
        <string>-Xmx2g</string>
        <string>-jar</string>
        <string>/Users/yourusername/Applications/CodeLens/codelens.jar</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/codelens.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/codelens-err.log</string>
</dict>
</plist>

Load the daemon:

launchctl load ~/Library/LaunchAgents/com.codelens.server.plist

JVM Tuning for Ultra-Large Repositories (50k–125k+ Classes)

For massive multi-module enterprise monorepos (e.g. 50,000 to 125,000 .java files):

java -Xms2g -Xmx6g \
     -XX:+UseG1GC \
     -XX:G1ReservePercent=15 \
     -XX:InitiatingHeapOccupancyPercent=45 \
     -Dcodelens.port=7878 \
     -jar codelens.jar

Configuration Management (`codelens.conf`)

CodeLens features a portable, human-readable configuration file format (codelens.conf) that encapsulates deployment settings, UI defaults, physics tuning, static analysis thresholds, POJO filtering, and custom domain archetypes.

When starting up, CodeLens automatically looks for configuration in:

-Dcodelens.config=/path/to/codelens.conf (System property override)
--config /path/to/codelens.conf (CLI argument)
./codelens.conf (Current working directory)
./codelens-data/codelens.conf (Data directory fallback)

Configuration Schema

# ── Server & Storage ──
server.port=7878
storage.dataDir=./codelens-data
scan.defaultPath=./src/main/java
scan.excludePatterns=build, target, dist, .git, .gradle, node_modules

# ── UI & Appearance ──
ui.theme=dark                               # dark | light
ui.packageMode=auto                         # auto | flatten | nested
ui.defaultTab=graph                         # graph | knowledge | review | git | source | codebase
ui.tabOrder=["graph","knowledge","review","git","source"]

# ── Graph Physics & Visuals ──
graph.nodeBaseRadius=18                     # Base node radius in px
graph.repulsion=420                         # Verlet repulsion force
graph.springLen=120                         # Link distance
graph.damping=0.85                          # Velocity damping
graph.showParticles=true                    # Animated call-flow particles
graph.showMinimap=true                      # Bottom-right radar minimap
graph.showLabels=true                       # Entity text labels
graph.showGrid=true                         # Cyber-grid canvas backdrop
graph.showHulls=true                        # Package / Community convex hulls
graph.defaultDepth=3                        # Initial traversal hop depth (1–15 / Max)
graph.autoFit=true                          # Auto-center and fit on load

# ── Macro 3D & 2D Studio ──
macro.defaultLevel=city3d                   # city3d | galaxy3d | treemap | sunburst | dsm | chord
macro.defaultGranularity=arch               # arch | methods
macro.brightness=1.0                        # Scene illumination
macro.showArcs=true                         # Three.js 3D bezier call arcs

# ── Code Review Thresholds ──
review.cyclomaticComplexityThreshold=15     # Flag methods with CC > 15
review.cognitiveComplexityThreshold=15      # Flag methods with cognitive complexity > 15
review.methodLinesThreshold=50              # Flag methods longer than 50 lines
review.classLinesThreshold=500              # Flag classes longer than 500 lines
review.parameterCountThreshold=6            # Flag methods with > 6 parameters

# ── POJO Classification ──
pojo.includeStandardAccessors=true          # Filter get*, set*, is*, has*
pojo.customPatterns=get*, set*, is*, has*, with*, toString, hashCode, equals

# ── Custom Archetype Rules (JSON array) ──
archetypes.rulesJson=[{"id":"rule-bancs-bt","target":"METHOD","pattern":"{MODULE}BT",...}]

Tip

Export & Import via Web UI: You can also view, modify, and download codelens.conf or import external configurations directly through the Settings Modal (⚙ Settings in the top header).

Scanning Engine & Operational Guide

1. Full Scans vs Incremental Delta Scans

CodeLens supports two intelligent scanning modes tailored for initial onboarding vs active development:

A. Full Rescan (`POST /api/scan`)

Use Case: First-time repository indexing, major branch switches, or clean rebuilds.
Granular 8-Stage Sequential Pipeline:
1. PARSE (2–70%): High-speed parallel AST parsing, type hierarchy extraction, method/field discovery, and batch chunk insertion.
2. INDEX (70–76%): Apache Lucene full-text symbol search commit and secondary relational B-tree index rebuild.
3. GRAPH (76–82%): In-memory JGraphT call graph vertex indexing and bidirectional call edge resolution, followed by field mutation propagation indexing.
4. LAYOUT (82–86%): Sequential precomputation and caching of all 6 sunflower spiral and 3D architectural layouts (ensures zero rendering freeze when opening graph views).
5. MODULES (86–90%): Package architecture, afferent/efferent couplings, and Robert C. Martin's instability ratings ($I = C_e / (C_a + C_e)$).
6. INTEGRITY (90–93%): Class-aware structural inconsistency detection & integrity audit (14 active rules, AST signature drift, naming divergences).
7. CODESTORY (93–96%): Business transaction storylines discovery from controllers to persistent DB sinks, 5-layer guided onboarding tour synthesis, and critical path targets.
8. REPORTS (96–99%): Sequential precomputation of all 14 enterprise architecture, debt, quality, and risk snapshots.
- COMPLETE (100%): 100% readiness across all views, tabs, and interactive engines.

B. Incremental Delta Scan (`POST /api/scan/incremental`)

Use Case: Day-to-day development after editing, pulling Git changes, or creating new classes.
Sequential Pipeline:
1. Compares disk file modification timestamps and sizes against indexed metadata via GET /api/scan/changes.
2. Identifies exact sets of New, Modified, and Deleted files.
3. Purges database records only for changed/deleted files via deleteBySourceFiles(...).
4. Parses delta files and merges them using idempotent MERGE INTO ... KEY(id).
5. Runs the exact same sequential 8-stage pipeline (Index, Topology, Layouts, Modules, Integrity, CodeStory, Reports) to guarantee 100% readiness across all features.

# Trigger an incremental delta rescan via cURL
curl -X POST http://localhost:7878/api/scan/incremental \
     -H 'Content-Type: application/json' \
     -d '{
       "sourcePath": "/path/to/project",
       "excludePatterns": ["target", "build", ".mvn", ".git"]
     }'

2. Background Execution & Non-Blocking Scan Modal

CodeLens features a fully non-blocking scan workflow designed so analysts never have to wait idly on a modal screen:

Dismiss at Any Point: Minimize the central scan modal at any time using the top-right ✕ button, the "Run in Background" button, clicking the backdrop, or pressing Escape.
Live Background Progress:
- Top-Bar Status Badge & Header Progress Bar: Displays live progress percentage (e.g. 94%), animated spinner, and linear gradient fill.
- Bottom-Left Footer Status Indicator: Displays the active phase with color-coded status pills (footer-scan-pill-integrity, footer-scan-pill-codestory, etc.) and real-time step details.
Instant Reopen & Post-Scan Navigation:
- Click either the top-bar badge, the header progress bar, or the bottom-left footer status text to bring back the detailed scan dialog at any point.
- Upon completion, the modal provides two dedicated exploration buttons:
  - 📖 Explore CodeStory: Navigates directly to the interactive Storylines tab.
  - ▶ Explore Graph: Navigates directly to the 2D Graphify Canvas.

3. Progressive Feature Enablement

As each pipeline step completes, corresponding navigation tabs and analytical modules unlock dynamically without waiting for the entire deep analysis run to finish:

Stage 1 (PARSE complete): Source Code and Git Analytics unlock immediately so code can be inspected and blame examined.
Stage 2 (INDEX complete): Knowledge Base Catalog, On-Demand Code Review, and Global Full-Text Search unlock.
Stage 3 (GRAPH complete): Call Hierarchy BFS unlocks.
Stage 4 (LAYOUT complete): Interactive 2D Graph and 3D Macro Studio (City & Galaxy) unlock with precomputed sunflower coordinates for immediate 60 FPS rendering.
Stage 5 (MODULES complete): Macro Architecture Studio and Module Coupling Matrices unlock.
Stage 6 (INTEGRITY complete): Structural Integrity & Inconsistency Audits unlock.
Stage 7 (CODESTORY complete): CodeStory Narratives, Storyline Player, and Guided Onboarding Tour unlock.
Stage 8 (REPORTS complete): All 14 Intelligence Reports unlock.
Feedback on Locked Features: Clicking any pending tab displays an informational banner stating the exact analysis stage needed for activation.

4. Live Scan Cancellation

If a scan was started with an incorrect path or exclude pattern, you can cancel it immediately without corrupting data or leaking database connections:

Click the Cancel Scan button on the scan modal or floating progress bar.
Or issue POST /api/scan/cancel.
The scanner thread safely halts at the current chunk boundary, cleans up active transactions, and restores the UI to idle state.

5. Folder & File Exclusions

Configure directory names or globs to ignore non-essential files. Set these via the UI ⚙ Settings modal or API:

Default Exclusions:
target, build, .mvn, .git, .gradle, node_modules, bin, out, **/test/**, *Test.java, */generated-sources/*

6. Graceful Server Shutdown & Interrupted Scan Recovery

Graceful Shutdown: Click Shutdown Server in the ⚙ Settings modal or POST to /api/shutdown. CodeLens cleanly flushes Lucene index writers, commits database transactions, closes HikariCP pools, and exits the process.
Interrupted Scan Recovery: If the server process was terminated abruptly (e.g. system reboot or power outage) while a scan was active, CodeLens automatically detects the interrupted state on restart, marks the scan status as INTERRUPTED, and provides a one-click Resume Rescan button on the landing page.

7. Automatic Package Hierarchy Handling

CodeLens automatically discovers common namespace roots (e.g. com.company.project.) across all scanned packages and cleans them into human-readable module clusters (e.g. trading.risk → Trading › Risk) without requiring manual prefix configuration. Choose your preferred label style anytime in ⚙ Settings:

Auto-Detect & Clean (Recommended): Groups under smart module roots.
Abbreviated (c.e.trading): Compact IDE-style package notation.
Full Qualified Name (FQN): Complete raw Java package strings.

8. Scope Management & Boundary Control (Excluding & Restoring Classes/Packages)

CodeLens provides fine-grained, interactive boundary management so engineers can eliminate external mocks, generated DTOs, or legacy boilerplate from their architectural intelligence:

Quick Hover Exclude: Hover over any class, interface, enum, record, or package in the Left Explorer tree to reveal the red × exclusion trigger.
Right-Click Context Menu: Right-click any entity or package to trigger a dedicated context menu with actions: Exclude Class / Package from Scope, Inspect Entity, and Copy FQN.
Cascading Purge: When an entity or package is excluded, CodeLens atomically:
1. Persists the exclusion rule into the embedded H2 EXCLUDED_SCOPE table.
2. Recursively cascades deletions across types, methods, fields, and relationships.
3. Purges corresponding documents from the Apache Lucene search index.
4. Prunes graph vertices/edges from in-memory Call Graphs, DSM matrices, and Reports.
Dedicated Scope Manager Dialog: Click the 🎯 Scope (N) button in the Left Explorer header to inspect all active exclusions.
Instant Restoration: Restore individual classes or packages with one click (or "Restore All"), automatically re-indexing them into the active graph and database without needing a full rescan.

Workspace Views & Feature Guide

1. Header Bar & Project Telemetry

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ⬡ CodeLens  [ /path/to/source/dir         ] [ Browse… ] [ Scan ▼ ] [ 3D Studio ] [ Reports Hub ] [ ⚙ ] [ ❓ ]│
│             [ 124 types ] [ 890 methods ] [ 430 fields ] [ 2,140 rels ]                                     │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Source Path Input: Accepts absolute filesystem paths to Java source trees.
Browse… Button: Native directory chooser with automatic Git repository discovery.
Scan / Rescan Dropdown: One-click triggers for Full Scan and Incremental Delta Scan.
3D Studio Button (M): Opens the dedicated Macro 3D Codebase Studio featuring 3D Software City and 3D Star Galaxy.
Reports Hub Button (R): Opens the comprehensive compliance & quality reports hub with 11 downloadable reports.
⚙ Settings Modal: Configure Dark/Light themes, exclusion patterns, package display modes, physics parameters, archetype rules, and graceful server shutdown.
❓ User Guide Button (?): Opens the interactive 5-tab in-app Feature & User Guide.
Realtime Entity Counters: Instant counts for Types, Methods, Fields, and Relationships.

2. Left Explorer & Lucene Search Engine

┌─────────────────────────────────────────────────────────┐
│ ⌕ Search classes, methods, fields… (⌘K)                 │
│ [ All ] [ Class ] [ Iface ] [ Enum ] [ Record ]         │
│ Explorer                        [ 🎯 Scope (2) ] [ Collapse ]│
│ ▾ com.example.trading                                [×]│
│   🔷 Portfolio                                       [×]│
│   🔷 TradeProcessor                                  [×]│
│   🔷 RiskEngine                                      [×]│
└─────────────────────────────────────────────────────────┘

Lucene Search (⌘K / Ctrl+K): Sub-millisecond indexed search across all classes, interfaces, enums, records, methods, fields, and signatures.
Kind Filter Chips: Filter the explorer tree to display only Classes, Interfaces, Enums, or Records.
Scope Manager Button (🎯 Scope (N)): View and restore excluded classes and packages.
Hover & Context Menu Exclusion: Click × or right-click any item to prune out-of-scope boundaries.
Collapsible Package Tree: Full package hierarchy with instant member navigation.

3. Interactive Center Workspace Views

CodeLens organizes primary codebase intelligence into 5 dedicated workspace screens, accompanied by top-level 3D Studio and Reports Hub:

1. Graph Canvas (Graphify Knowledge Graph & Verlet Physics)

Verlet Physics Simulation: Real-time multi-body force simulation calculating Coulomb repulsion, Hooke spring tension, package clustering, and anti-collision.
Convex Hull Clustering (◈ Clusters): Visualizes architectural modules as colored translucent hulls.
Behavioral Hotspots Heat Mode (♨ Heat / H): Overlays thermal shaders on nodes based on composite risk $CC \times \log_2(1 + \text{churn}) \times \log_{10}(LOC)$.
BFS Depth Controls (1–15 hops / Max): Explore transitive callers and callee dependencies.
Camera Controls: Auto-fit (F), Zoom In/Out (+/-), Reset Zoom (0), and Freeze Physics (Space).

2. Knowledge Base Catalog & Complexity Analysis

Complete tabular catalog of all scanned types, member variables, and methods.
Computes Cyclomatic Complexity (CC) scores for every method with color health badges:
- 🟢 Low Complexity (1–4): Clean, straightforward execution path.
- 🟡 Moderate Complexity (5–10): Branching logic requiring thorough unit tests.
- 🔴 High Complexity (11+): Heavy nesting; prime candidate for refactoring.
Filtering by visibility (Public, Protected, Package-private, Private) and archetype roles.

3. Code Review & 32-Rule Static Auditor

32 deep AST static analysis rules across 6 critical quality categories:

Correctness: Null pointer hazards, unclosed streams, switch fallthroughs, array reference leaks.
Concurrency: Non-atomic shared state mutation, unsynchronized collections in multithreaded classes.
Exception Safety: Swallowed exceptions, catching Throwable, throwing raw runtime exceptions.
Code Smells: God classes, long parameter lists ($>5$), high cyclomatic complexity ($>15$).
API Contracts: Missing interface contracts, broken equals/hashCode symmetry.
Architectural Blast Radius: Core utility methods with extreme upstream caller fan-in.

4. Git Analytics & Churn Heatmap

Top Authors Leaderboard: Contribution metrics, entities touched, and recent commit dates.
Hot Churn Entities: Ranked bar chart of highest-churn classes and methods.
Blame Annotations: Detailed author breakdown and last modified timestamps per entity.

5. Integrated Monaco Source Code Editor

Embedded Microsoft Monaco editor (VS Code engine).
Jump directly to exact line numbers from graph nodes, member lists, or code review findings.
Full syntax highlighting, breadcrumb navigation, and in-place editing back to disk.

4. 3D Codebase Studio & 2D Architectural Macro Views

Accessible anytime via the 3D Studio header button (M) or Visualizations menu:

🏙️ 3D Software City: Interactive Three.js WebGL urban layout mapping packages to city blocks, classes to skyscrapers, LOC to building height, and complexity or churn to roof colors. Includes Bloom post-processing, camera fly-throughs, and Thermal Heat Mode.
🌌 3D Galaxy: Orbital gravitational star system rendering classes as stars orbiting central module suns.
📊 Interactive Dependency Structure Matrix (DSM):
- Multi-tier dependency grid (Modules $\to$ Packages $\to$ Classes $\to$ Methods).
- Method-Level Drilldown: Double-click any class header to inspect precise method call invocations, complete with breadcrumb navigation.
- DAG Acyclicity Rating: Calculates strict acyclic ordering and highlights cyclic dependencies in red.
- Adjacency Exports: Download DSM data as CSV or structured JSON.
🗺️ Treemap & Sunburst: Hierarchical area partitioners with sub-pixel Level-of-Detail (LOD) culling.
⭕ Chord Diagram: Radial flows visualizing cross-package coupling.

5. Reports Hub & Compliance Audits (`R`)

Click the Reports Hub button in the header (R) to access 11 enterprise architectural and quality reports:

Change Risk Analysis: Combines blast radius and historical churn into a compound refactoring risk score.
Circular Dependencies: Identifies recursive call loops and package dependency cycles using Tarjan's strongly connected components algorithm.
Dead Code & Unused Methods: Detects unreferenced private methods and orphan classes with 0 incoming callers.
API Surface & Exposure: Inventories public API contracts, exposed interfaces, and external boundaries.
Behavioral Hotspots: Quantifies technical debt via $CC \times \log_2(1 + \text{churn}) \times \log_{10}(LOC)$.
God Classes & Bloat: Identifies monolithic classes exceeding LOC, field, and method thresholds.
Coupling & Cohesion: Analyzes Afferent ($C_a$) and Efferent ($C_e$) coupling and Martin instability metrics.
Security & Vulnerability Audit: Surfaces OWASP-relevant patterns (unvalidated input flows, raw SQL concatenation).
Inheritance Depth: Analyzes deep inheritance hierarchies and class coupling.
Exception Flow: Identifies unhandled, swallowed, or broad catch (Throwable) blocks.
Comprehensive Executive Summary: High-level code health score, aggregate metrics, and prioritized remediation actions.

All reports offer 1-click export to CSV, Standalone Interactive HTML, and Markdown.

4. Right Inspector Panel & Multi-Hop Propagation

Metadata Card: Displays modifiers, inheritance, implemented interfaces, lines, and Git history.
Action Triggers:
- ⬆ Callers: Visualizes upstream callers in the Graph view.
- ⬇ Callees: Visualizes downstream dependencies in the Graph view.
- ⚡ Impact (Direct): Shows immediate readers, writers, and propagators for a field.
- 🔗 Propagation Chain: Traces repository-wide upstream triggers of field mutations.

5. Analyst Notes Engine

Free-text markdown notes attached to any class, interface, method, or field.
Persisted locally in the H2 database and included in exported reports.

6. Export Reports Hub (14 Reports & 60+ Export Artifacts)

CodeLens automatically precomputes a comprehensive suite of 14 deep architectural, risk, persistence, coupling, and concurrency reports, generating 60+ pre-rendered artifacts in CSV, standalone HTML, Markdown, and JSON stored in ./codelens-data/graph-cache/reports/:

#	Report Key	Report Title	Focus & Primary Indicators
1	`architecture`	Architecture & Coupling Report	Robert C. Martin's Package Coupling ($C_a$, $C_e$, Instability $I$, Distance from Main Sequence $D$)
2	`change-risk`	Change Risk & Blast Radius Matrix	Behavioral Hotspots ($CC \times Churn \times LOC$) and highest downstream blast radius classes
3	`dead-code`	Dead Code & Reachability Analysis	Private & package-private methods with 0 incoming call edges and orphan subsystems
4	`circular-dependencies`	Circular Dependencies & Tangling	Tarjan strongly connected components / cycles at package and class level
5	`archetype-governance`	Enterprise Archetype Governance	Architectural layer compliance (Controllers $\to$ Services $\to$ DAOs) and naming consistency
6	`technical-debt`	Technical Debt & SQALE Remediation ROI	SQALE remediation hours, debt ratio, and prioritized refactoring opportunities
7	`executive-summary`	Executive Architectural Scorecard	Unified architectural health grade (A–F) across 5 core dimensional indices
8	`review`	Code Quality & Security Audit	Consolidated list of all 32 AST static rule findings with precise file and line numbers
9	`metrics`	Codebase Inventory & Metrics Census	Comprehensive breakdown of packages, classes, methods, fields, and LOC distributions
10	`api-catalog`	API Surface & REST Endpoint Catalog	REST routes, HTTP verbs (GET, POST, PUT, DELETE), controllers, auth checks, and blast radius
11	`database-access`	Database & Data Access Flow	Persistence integrity score, DAO access points, CRUD distribution, and target tables touched
12	`concurrency-audit`	Concurrency & Thread Safety Audit	Thread safety score/grade, synchronized locks, volatile fields, and mutable shared collections
13	`module-coupling`	Inter-Module Dependency & Stability	Cross-module caller-callee couplings, stability indices, and dependency violation warnings
14	`html-snapshot`	Standalone Offline HTML Snapshot	Bundled single-file offline interactive HTML snapshot for offline review and air-gapped sharing

Sequential Precomputation & Audit Logging

Reports precomputation runs in a strict sequential runner (1 through 13) with per-report error isolation, individual execution duration tracking, and formatted ASCII logging banners in the server console:

╔════════════════════════════════════════════════════════════════════════════════════╗
║ CODELENS BACKGROUND PROCESS REPORT_BUILD_STARTED                                   ║
║ Process:   [10/13] API Surface & REST Endpoint Catalog                             ║
║ Target:    api-catalog                                                             ║
║ Details:   Computing analysis model and rendering artifacts                        ║
║ Timestamp: 2026-10-01 22:19:04.066                           Memory: 185MB / 512MB ║
╚════════════════════════════════════════════════════════════════════════════════════╝
...
[REPORT 10/13] COMPLETED API Surface & REST Endpoint Catalog in 17 ms

7. Background Tasks & Process Manager (11 Engines)

Accessible via the top-bar Tasks button or GET /api/processes, the Background Tasks & Process Manager provides real-time telemetry and lifecycle management across all 11 asynchronous engines:

┌────────────────────────────────────────────────────────────────────────┐
│               CODELENS BACKGROUND TASK PROCESS HUB                     │
├─────────────────────┬───────────────────┬──────────────┬───────────────┤
│ Process ID          │ Subsystem Name    │ Role         │ Control       │
├─────────────────────┼───────────────────┼──────────────┼───────────────┤
│ scanner             │ Source Scanner    │ Parallel AST │ [Restart]     │
│ delta-scanner       │ Delta Scanner     │ File Watcher │ [Scan Delta]  │
│ call-graph          │ Call Graph Engine │ JGraphT Topo │ [Rebuild]     │
│ layout-engine       │ Layout Engine     │ Sunflower 2D │ [Precompute]  │
│ module-analyzer     │ Module Touchpoint │ Cross-Module │ [Recompute]   │
│ lucene-indexer      │ Lucene Indexer    │ Text Search  │ [Re-index]    │
│ git-analyzer        │ Git Churn Engine  │ JGit Logs    │ [Analyze]     │
│ db-watchdog         │ DB Pool Sentinel  │ Leak Guard   │ [Check Health]│
│ stress-test         │ Stress Tester     │ Benchmarks   │ [Run Test]    │
│ heap-watchdog       │ Memory Sentinel   │ OOM Sentinel │ [Force GC]    │
│ reports-generator   │ Reports Generator │ 13 Reports   │ [Regenerate]  │
└─────────────────────┴───────────────────┴──────────────┴───────────────┘

Live Telemetry: Real-time status (ACTIVE, IDLE, COMPLETE), active stage, progress percentage, and throughput metrics (e.g. Heap: 142 MB / 512 MB (28%), 320 files/sec).
Lifecycle Endpoints: Individual processes can be restarted via POST /api/processes/:id/restart or cooperatively canceled via POST /api/processes/:id/kill.
Memory Sentinel & Circuit Breaker: JMX threshold monitoring and background watchdog that evicts caches at 85% heap usage and trips a circuit breaker at 92% to prevent OutOfMemoryError.

Critical Path Trace & Execution Analysis

In large enterprise codebases, critical domain entities (such as Accounts, Loans, Deposits, and Trades) are manipulated through intricate, multi-layered service workflows. Critical Path Analysis automates the end-to-end discovery and interactive visualization of these vital execution sequences.

flowchart LR
    Entry["⚡ Entry Point\ne.g. AMBTAccountOpen"] --> Service["Domain Service\ne.g. AccountService"]
    Service --> Task["Own / Common Task\ne.g. AMTOVerifyStatus\nAMTCVerifyKYC"]
    Task --> Entity["💾 Persistent Target\ne.g. Account.Modify()"]
    Entity --> Sink["🛡️ Downstream Sink\ne.g. AuditTrailService.log()"]

Persistent Entity Identification & Filter Immunity

CodeLens scans all indexed classes to identify persistent domain entities using:

The Persistent Contract Triplet: Classes containing Get(), Create(), and Modify() methods.
Persistent Conventions: Classes matching configured prefix patterns (e.g. PC_*) or enterprise entity annotations (@Entity, @Table).
Strict DTO Separation: Message Objects (MO_INP_*, MO_OUT_*, MO_*) are strictly categorized as transfer payloads and excluded from being falsely identified as persistent database entities.
Architectural Lifecycle Exemption: Persistence methods Get(...), Create(), and Modify(...) are explicitly shielded from POJO accessor classification, guaranteeing that hydrated entity reads are never misidentified as trivial getters.
Critical Path Filter Immunity: When a Critical Path is active, every node along the execution chain (ENTRY_POINT, PERSISTENT_TARGET, DOWNSTREAM_SINK, INTERMEDIARY) is granted absolute immunity against POJO suppression, package legend toggling, archetype filtering, and canvas orphan pruning.

Interactive Stepper Dock & Step Traversal

When a critical path is loaded, CodeLens presents a non-intrusive floating Stepper Dock docked along the bottom of the canvas:

Chronological Flow Cards: Each hop along the execution path is rendered as a distinct card with its execution sequence step number, archetype badge, method name, and cyclomatic complexity (CC).
Synchronized Visual Focus: Clicking any step card (or navigating via the ‹ Prev / › Next buttons) smoothly centers and zooms the 2D canvas on that method, highlights incident edges, and pulses execution flow particles with vertical headroom above the bottom dock.
Bidirectional Canvas Interaction: Clicking on any node in the graph automatically highlights and centers its corresponding step card in the stepper dock without destroying the active path topology.
Collapsible Layout: Click the Collapse button to minimize the dock into a slim 34px status bar, granting a 100% unobstructed view of the graph canvas while retaining step navigation controls.
Graph State Restoration: Closing the dock or pressing Escape instantly restores the user's prior canvas state and call graph mode.

Candidate Path Modes

CodeLens computes multiple candidate execution paths for every persistent class, switchable with zero latency:

Mode	Path Focus	Description
Primary	Highest Impact	Top-ranked overall transactional path combining caller depth, complexity, and downstream audit.
Mutation	Write & State Change	Focuses strictly on execution sequences leading to entity creation or modification (`Create`, `Modify`, `{MODULE}BT`).
Read	Query & Hydration	Read-only inquiry path retrieving entity state (`Get`, `{MODULE}ET`, `{MODULE}DG`).
Longest	Deepest Propagation	The longest call chain from an external boundary entry point down to persistence.
Max CC	Peak Business Complexity	Traverses methods accumulating the highest cumulative Cyclomatic Complexity ($\Sigma$ CC).

Complexity & Risk Metrics

The Stepper Dock header displays real-time telemetry:

Hops: Number of intermediate method calls along the sequence.
$\Sigma$ CC: Cumulative cyclomatic complexity across all methods in the path.
Risk Score: Weighted impact score factoring complexity, mutation types, and audit sinks.
Bottlenecks: Automatic flagging of methods with excessive branching ($CC > 8$).

CodeStory — Guided Onboarding & Narrative Flow Engine

CodeLens elevates traditional graph visualization into an interactive storytelling platform. Rather than navigating an overwhelming hairball of hundreds of thousands of disconnected AST nodes, engineers can explore the codebase as sequential, human-readable transaction storylines.

flowchart LR
    subgraph L1["Layer 1: Entry Point"]
        Ctrl["REST Controller / Endpoint\ne.g. OrderController.placeOrder()"]
    end
    subgraph L2["Layer 2: Domain Workflows"]
        Svc["Domain Services & Policies\ne.g. PricingEngine.calculate()"]
    end
    subgraph L3["Layer 3: Mutation Sinks"]
        Repo["Database Mutation Target\ne.g. OrderRepository.save()"]
    end
    subgraph L4["Layer 4: Audit & Events"]
        Audit["Downstream Sinks & Events\ne.g. AuditLog.record(), EventBus"]
    end

    Ctrl --> Svc
    Svc --> Repo
    Repo --> Audit

1. Interactive Transaction Storylines

Automated Workflow Synthesis: Scans entry points (@RestController, @PostMapping, @GetMapping, message consumers) and traces all reachable execution paths down to persistent entities and downstream mutation sinks.
Natural Language Explanations: Translates multi-hop call hierarchies into plain-English narrative summaries explaining the business intent, roles, and potential failure points of the transaction.
Storyline Player & Stepper Dock:
- Interactive sequence cards showing method names, archetype badges, source line citations, and execution sequence numbers.
- One-click step navigation (‹ Previous / › Next) that centers and pulses the canvas with particle flow tracers.
- Step details show exact input parameters, return types, field mutations, and downstream blast radius.

2. "Teach Me This Codebase" — 5-Layer Guided Onboarding Tour

Designed to take new developers from zero to architectural mastery in minutes, the Teach Me tour organizes repository exploration into 5 progressive layers:

Layer 1: Domain Core & Entities: Core persistent entities, aggregates, and data models defining the business domain.
Layer 2: Ingestion & Storage Architecture: Database access objects, repository interfaces, and data persistence contracts.
Layer 3: Topology & Call Graphs: High-traffic service orchestrators, task executors, and inter-module communication channels.
Layer 4: Semantic Storylines: Primary user journeys and critical transactions from external API boundaries to database commits.
Layer 5: Intelligence & Risk Hotspots: Behavioral hotspots, circular dependency hubs, and prioritized technical debt areas.

Each stop on the tour includes a comprehensive explanation, file/line links to the source code in Monaco, and direct visualization in the Graph.

3. Git Pull Request Change Story Generator

Compare any branch or pull request against a base reference (main or release):

Summarizes the structural impact of changes instead of just line-by-line diffs.
Identifies newly added entry points, modified persistent entity contracts, and widened blast radiuses.
Generates a ready-to-paste Markdown PR architectural summary for code reviews.

4. Grounded AI Architecture Assistant

CodeLens includes a context-grounded AI conversational assistant accessible via the web drawer or CLI (codelens-app.jar ask "<question>"):

Local Ollama Integration: Fully air-gapped support for local LLMs (DeepSeek-Coder, Llama 3, Qwen 2.5 Coder) running via Ollama (http://localhost:11434).
OpenAI Compatible: Connects to OpenAI or any OpenAI-compatible API endpoint with custom API keys and model selections.
Deterministic Template Fallback: When no LLM is configured or available, CodeLens automatically falls back to an internal deterministic template engine that answers architectural questions using pure static AST facts and graph queries.

Structural Integrity Engine (14 Active Class Rules)

Phase 6 of the scan pipeline executes a rigorous Structural Integrity Audit evaluating 14 foundational architectural contracts and class-awareness rules:

#	Integrity Rule	Contract & Verification Focus	Severity
1	DTO Encapsulation	Request/Response Message Objects (`MO_*`) must never directly access persistence sinks or DAOs	🔴 High
2	Repository Isolation	Repositories and DAOs must only be invoked from domain service layers, never directly from controllers	🔴 High
3	Controller Boundary	API Controllers must not contain raw SQL, business mutation logic, or multiple persistence mutations	🟡 Moderate
4	Service Layer Integrity	Domain services must implement consistent transaction boundaries and logging sinks	🟡 Moderate
5	Entity Contract Symmetry	Persistent entities must declare symmetric `equals()` and `hashCode()` implementations	🟡 Moderate
6	Immutable Value Objects	Classes designated as Value Objects must have final fields and zero public mutation methods	🟢 Low
7	Interface Segregation	Interfaces exceeding 15 method declarations are flagged for separation	🟡 Moderate
8	Dead Storage Methods	DAO methods with zero incoming call edges across the repository	🟢 Low
9	Signature Divergence	Classes with similar naming but divergent method signatures (Levenshtein distance $\le 2$)	🟡 Moderate
10	AST Body Clones	Duplicate AST method body hashes across non-inherited class implementations	🟡 Moderate
11	Exception Swallowing	Catch blocks that catch `Exception` or `Throwable` and neither log nor re-throw	🔴 High
12	Circular Module Coupling	Tightly coupled packages violating acyclic dependency graph principles	🔴 High
13	Unsynchronized Mutations	Multithreaded components mutating shared non-thread-safe collection instances	🔴 High
14	Naming Convention Drift	Classes violating configured domain prefixes or semantic archetype conventions	🟢 Low

Semantic Archetypes & Domain Templates

CodeLens features a Semantic Archetype Engine that classifies methods and types into meaningful domain roles rather than generic programming language constructs.

Dynamic Module Substitution (`{MODULE}`)

In large enterprise codebases (such as TCS BaNCS), naming conventions embed module identifiers into method and class names. CodeLens supports dynamic {MODULE} and {MOD} tokens in archetype rules:

An archetype rule defined with pattern {MODULE}BT dynamically matches AMBTAccountOpen in package com.tcs.bancs.AM, LNBTDisbursement in com.tcs.bancs.LN, and TRBTExecuteOrder in com.tcs.bancs.TR.
Module regex token boundary matching (^[A-Z]{2,4}{SUFFIX} and \.[A-Z]{2,4}{SUFFIX}) eliminates collisions on English words (e.g. MONITORING or BATCH).
In modern enterprise refactorings, transactions and tasks (ET, BT, TO, TC) are implemented as domain methods inside orchestrator services rather than standalone boilerplate classes.

TCS BaNCS Enterprise Banking Template

CodeLens includes a built-in, out-of-the-box preset for TCS BaNCS Core Banking Architecture:

1. Method Archetypes

Archetype Rule	Pattern	Badge	Category	Color	Description
Business Transaction	`{MODULE}BT`	`MUTATE`	`MUTATION`	`#f59e0b` (Amber)	Mutating transaction methods creating or modifying domain state
Elementary Transaction	`{MODULE}ET`	`FETCH`	`READ_ONLY`	`#10b981` (Emerald)	Read-only inquiry methods for high-throughput lookups
Own Task	`{MODULE}TO`	`TASK-OWN`	`WORKFLOW`	`#0ea5e9` (Sky Blue)	Internal module workflow validation and calculation steps
Common Task	`{MODULE}TC`	`TASK-COMMON`	`SHARED_TASK`	`#a855f7` (Purple)	Shared cross-module workflow steps (KYC, audit, GL posting)
Batch Stream	`{MODULE}PS`	`STREAM`	`BATCH`	`#8b5cf6` (Violet)	Batch processing streams and scheduled job runners
Batch Pre-Processor	`{MODULE}PB`	`PRE-BATCH`	`PRE_PROCESS`	`#3b82f6` (Blue)	Pre-batch data extraction and validation jobs
Batch Post-Processor	`{MODULE}PA`	`POST-BATCH`	`POST_PROCESS`	`#ec4899` (Pink)	Post-batch reconciliation and report generation

2. Class Archetypes

Archetype Rule	Pattern	Badge	Category	Color	Description
Message Object	`MO_`, `MO_INP_`, `MO_OUT_*`	`MSG-OBJECT`	`MESSAGE_DTO`	`#14b8a6` (Teal)	Request/response DTOs and state transfer payloads
Persistent Class	Domain entities with `Get`, `Create`, `Modify`	`PERSISTENT`	`PERSISTENCE`	`#6366f1` (Indigo)	Core domain database entities (e.g. `Account`, `Loan`, `OrderEntity`)
Data Grabber	`{MODULE}DG`	`GRABBER`	`DATA_ACCESS`	`#06b6d4` (Cyan)	Read-only data access objects fetching entity records

Spring Boot MVC & Domain-Driven Design (DDD)

CodeLens also provides ready-to-use presets for standard Java enterprise applications:

Spring Boot MVC: Classifies @RestController, @Service, @Repository, and @Configuration beans with distinct visual badges and layer separation.
Domain-Driven Design (DDD): Identifies Entities, Value Objects, Aggregates, Domain Services, Repositories, and Domain Events.

Custom POJO & Accessor Detection Rules

To prevent boilerplates from cluttering call graphs and complexity calculations, CodeLens includes intelligent POJO detection:

Standard JavaBean Heuristics: Automatically classifies zero-argument getters and single-argument setters (getId(), setBalance(v), isActive(), hasPermissions()) while preserving parameterized business methods.
Standard Object Filtering: Filters equals, hashCode, toString, clone, compareTo, and canEqual methods.
Domain Lifecycle Protection: Core persistence methods (Get, Create, Modify) and Critical Path execution roles (ENTRY_POINT, PERSISTENT_TARGET, DOWNSTREAM_SINK, INTERMEDIARY) are protected against accidental POJO suppression.
Multi-Studio Enforcement: The POJO classifier engine (isPojo / isPojoAccessor) operates consistently across the 2D Graph, 3D Studio (City & Galaxy), Sunburst, Treemap, Chord, and Dependency Structure Matrix (DSM).
On-the-Fly Toggle: Toggleable instantly via the bottom canvas toolbar button Hide POJOs.

Impact Investigation & Deep Architectural Workflows

Method Blast Radius Analysis

Locate target method (e.g. PaymentGateway.processTransaction).
Click ⬆ Callers in the Right Inspector.
Set Scan Depth Slider to 3 or 5.
The canvas renders all public API controllers, background schedulers, and services that depend directly or transitively on this method.

Field-to-Method Mutation Propagation Chains

Select any mutable field (e.g. Account.accountBalance).
Click 🔗 Propagation Chain.
CodeLens traverses: $$\text{Field} \longleftarrow \text{Direct Writer Methods} \longleftarrow \text{Upstream Calling Triggers}$$
Color-coded roles:
- 🟡 Field (Target state variable)
- 🔴 Direct Writer (Methods mutating the variable)
- 🔵 Calling Trigger (Upstream entry points invoking the writers)
- 🟢 Direct Reader (Methods accessing the variable)

Data Storage, H2 Compaction & High-Scale Persistence

All database files and search indices are stored locally in ./codelens-data/:

codelens-data/
├── codelens_db.mv.db       # Compressed Embedded H2 Database (LZF compression, auto-compact)
├── codelens_db.trace.db    # H2 transaction trace log
└── lucene-index/           # Apache Lucene index directory shards

High-Scale Performance Architecture (30k–50k+ Java Files)

High-Throughput Bulk Ingestion: Drops secondary B-tree indexes and disables undo logging during full scans to achieve constant $O(1)$ batch insertion speeds regardless of existing table size.
LZF Page Compression & Compaction: H2 runs with COMPRESS=TRUE and AUTO_COMPACT_FILL_RATE=50. Post-scan and shutdown triggers execute SHUTDOWN COMPACT to eliminate MVStore dead page fragments, keeping 30k-file repositories under 1–2 GB on disk (instead of 40GB+ uncompacted).
Leak-Free Connection Management: All database connections operate under strict try-with-resources blocks with explicit setAutoCommit(false) chunk commits, preventing connection pool exhaustion and HikariCP leak warnings.
Graceful Shutdown & Interrupted Scan Recovery: Process termination or API shutdown requests cleanly flush Lucene index writers and H2 connection pools. Interrupted scans are safely flagged upon startup and can be resumed with a single click.

Tip

Resetting the Database: To completely reset your indexed data, simply delete the ./codelens-data/ folder and initiate a fresh scan from the web interface.

Comprehensive REST API Reference

All endpoints return JSON and are accessible locally at http://localhost:7878/api.

Scan & Lifecycle Controls

POST /api/scan — Start a background full scan ({"sourcePath": "/path/to/src", "excludePatterns": ["target", "build"]})
POST /api/scan/incremental — Start an incremental delta scan ({"sourcePath": "/path/to/src", "excludePatterns": [...]})
POST /api/scan/cancel — Cooperatively cancel an active scan in progress
GET /api/scan/status — Poll current scan progress, phases, entity counts, and status
GET /api/scan/changes — Inspect detected filesystem changes (new, modified, deleted files)
GET /api/scan/browse — Open native OS directory chooser dialog
POST /api/shutdown — Gracefully stop the CodeLens server process and flush storage
GET /api/stats — Summary entity counts (types, methods, fields, relationships, inconsistencies)

Packages & Types

GET /api/packages — Flat list of indexed packages
GET /api/packages/{fqn}/types — Types declared in a specific package
GET /api/types — List all types (supports ?q= query and pagination)
GET /api/types/{fqn} — Detail for a type including member fields, methods, and Git telemetry

Methods, Call Graphs & Architectural Views

GET /api/methods/{fqn} — Method details, parameters, lines, and cyclomatic complexity
GET /api/methods/{fqn}/graph?depth=3 — Call hierarchy graph view (nodes + edges) up to depth hops
GET /api/methods/{fqn}/callers?depth=4 — Upstream caller hierarchy
GET /api/methods/{fqn}/callees?depth=4 — Downstream callee hierarchy
GET /api/graph/architecture?scope=module|package|class — Quotient architecture graph view aggregated at module, package, or class level
GET /api/graph/dsm?scope=module|package|class — Sparse Dependency Structure Matrix payload with fast cell lookup array
GET /api/graph/treemap?scope=module|package|class — Hierarchical treemap payload aggregated by lines of code and complexity

Reports & Export Hub

GET /api/reports/status — Current precomputation progress, percentage, phase, and cached keys
POST /api/reports/regenerate — Trigger background sequential precomputation of all 14 reports
GET /api/reports/{reportKey}?format=markdown|html|json|csv — Retrieve report in requested format
- Supported keys: architecture, change-risk, dead-code, circular-dependencies, archetype-governance, technical-debt, executive-summary, review, metrics, api-catalog, database-access, concurrency-audit, module-coupling, html-snapshot
GET /api/reports/download?type={key}&format=markdown|html|csv — Direct file download endpoint

CodeStory, Narrative Flows & Guided Tour

GET /api/storylines — List all discovered transaction storylines with entry points, persistent targets, and step counts
GET /api/storyline?id={id} — Detailed storyline execution trace with narrative synthesis, step metadata, and blast radius
GET /api/storyline/what-if?method={fqn} — Hypothetical blast radius simulation and mutation impact for a method
GET /api/storyline/teach-me — 5-layer guided architectural onboarding tour stops
GET /api/storyline/system-tour — Complete system walkthrough data with Monaco source line citations
GET /api/git/pr-story?base={baseRef}&head={headRef} — Structural change storyline comparing Git branches or commits

Grounded AI Architecture Assistant

GET /api/ai/ask?q={query} or POST /api/ai/ask — Context-grounded architectural question answering (Ollama/OpenAI/Deterministic fallback)
GET /api/ai/explain?target={fqn} or POST /api/ai/explain — Plain-English narrative explanation of class or method responsibilities
GET /api/ai/config — Retrieve active AI provider configuration
POST /api/ai/config — Save AI configuration (provider ollama|openai, model, endpoint URL, API key)

Modules & Macro Architecture

GET /api/modules/dependencies — Full inter-module dependency matrix
GET /api/modules/insights — High-level module stability and architectural violation insights
GET /api/modules/{name}/dependencies — Focused dependencies for a single module

Background Process Manager & JVM Sentinel

GET /api/processes — Live status, stage, progress %, and throughput for all 11 background engines
POST /api/processes/{id}/restart — Restart/re-queue engine (scanner, call-graph, layout-engine, module-analyzer, lucene-indexer, git-analyzer, reports-generator, etc.)
POST /api/processes/{id}/kill — Cooperatively terminate/cancel active task
GET /api/jvm/metrics — Live heap usage, pool occupancy, GC stats, and circuit breaker state
POST /api/jvm/gc — Trigger JVM garbage collection
POST /api/jvm/trim-memory — Force cache eviction, DB compaction, and memory trimming
GET /api/jvm/auto-recovery — Current auto-recovery watchdog metrics and status
POST /api/jvm/auto-recovery/trigger — Manually trigger auto-recovery sequence
POST /api/jvm/auto-recovery/reset-circuit-breaker — Reset memory circuit breaker to CLOSED
POST /api/jvm/auto-recovery/simulate — Test auto-recovery sentinel by injecting synthetic memory pressure
GET /api/jvm/threads — Dump live JVM thread stacks, monitors, and lock contention
GET /api/jvm/deadlocks — Detect active thread deadlocks

Fields & Impact Analysis

GET /api/fields/{fqn} — Field metadata and initializer expression
GET /api/fields/{fqn}/impact?depth=1 — Field impact and multi-hop propagation chain (readers, writers, propagators, graph)

Analysis, Critical Path & Search

GET /api/analysis/persistent-classes — Discover and rank all persistent domain entities across the repository by risk score, hops, and complexity
GET /api/analysis/critical-path?class={classFqn}&mode=primary|mutation|read|longest|max_complexity — Multi-hop end-to-end critical execution path report with candidate paths, precomputed coordinates, and metrics
GET /api/analysis/blast-radius?method={methodFqn} — Calculate downstream blast radius fan-out for a method
GET /api/inconsistencies — List of all flagged structural inconsistencies and AST clones across 14 class rules
GET /api/search?q={query}&limit=30 — Apache Lucene full-text entity search

Scope Management & Boundary Exclusion

POST /api/scope/exclude — Exclude class or package from the analysis
GET /api/scope/excluded — List all currently excluded scopes
POST /api/scope/restore — Restore previously excluded entity
POST /api/scope/clear — Clear all exclusion rules and restore full codebase scope

Configuration Management

GET /api/config — Retrieve active runtime configuration JSON
POST /api/config — Update configuration settings
POST /api/config/reset — Reset all configuration settings back to defaults
GET /api/config/export — Download the active codelens.conf file

Source Files & Git Metadata

GET /api/files/read?path={filePath} — Read source file contents from disk
POST /api/files/write — Save updated file content ({"path": "...", "content": "..."})
GET /api/git/summary — Top authors leaderboard and hot churn entities
GET /api/git/meta/{fqn} — Git commit history and blame stats for an entity

Analyst Notes & Documentation

GET /api/notes/{entityFqn} — Retrieve analyst notes for an entity
POST /api/notes — Create or update an analyst note ({"entityFqn": "...", "content": "..."})
DELETE /api/notes/{id} — Delete an analyst note
GET /api/readme — Retrieve this full comprehensive markdown guide from the server

Keyboard Shortcuts

Shortcut	Action	Scope
`⌘K` / `Ctrl+K`	Focus global Lucene entity search	Global
`Esc`	Clear search query / Close active modal dialog / Deselect node	Global
`1`	Switch to Graph Canvas view	Global
`2`	Switch to Knowledge Base Catalog view	Global
`3`	Switch to Code Review & Logic Auditor view	Global
`4`	Switch to Git Analytics & Churn view	Global
`5`	Switch to Source Code (Monaco Editor) view	Global
`M`	Open Macro 3D Codebase Studio (City & Galaxy)	Global
`R`	Open Reports Hub (13 Architecture & Quality Reports)	Global
`P`	Open Background Tasks & Process Hub	Global
`?`	Open Feature & User Guide (with About CodeLens)	Global
`\` / `\|`	Toggle Critical Path Stepper Dock	Global
`[`	Toggle Left Explorer panel visibility	Global
`]`	Toggle Right Inspector panel visibility	Global
`H`	Toggle Behavioral Hotspots / Git Churn Heat Mode	Graph & 3D City
`Space`	Toggle Force Physics simulation (Freeze / Unfreeze)	Graph Tab
`F`	Fit entire graph to screen (Auto-Zoom & Center)	Graph Tab
`+` / `-`	Zoom in / Zoom out on canvas	Graph Tab
`0`	Reset zoom to 100%	Graph Tab

Troubleshooting & FAQ

1. The database file grew too large on previous scans

Solution: Run a fresh scan in CodeLens 1.0.6+. The newly implemented LZF page compression and automated post-scan compaction (SHUTDOWN COMPACT) will shrink the .mv.db file from 40GB+ down to 1–2 GB.

2. Java Heap Out of Memory during 100k+ Class Scans

Solution: Increase max heap allocation:

java -Xms2g -Xmx6g -XX:+UseG1GC -jar codelens.jar

3. Port 7878 is already in use

Solution: Pass -Dcodelens.port=PORT on startup:
```
java -Dcodelens.port=8080 -jar codelens.jar
```

4. How do I completely wipe all indexed data?

Solution: Shut down the server, delete the ./codelens-data directory, and restart.

CodeLens — Offline Java Architectural Intelligence
Zero telemetry · Zero cloud dependencies · 100% Local

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.codex		.codex
.github/workflows		.github/workflows
.impeccable/live		.impeccable/live
.mvn/wrapper		.mvn/wrapper
codelens-analysis		codelens-analysis
codelens-api		codelens-api
codelens-app		codelens-app
codelens-core		codelens-core
codelens-git		codelens-git
codelens-macos		codelens-macos
codelens-mobile		codelens-mobile
codelens-parser		codelens-parser
codelens-storage		codelens-storage
codelens-web		codelens-web
docs		docs
e2e-tests		e2e-tests
plans		plans
sample-project		sample-project
scripts		scripts
wiki		wiki
.gitignore		.gitignore
DESIGN.md		DESIGN.md
PRODUCT.md		PRODUCT.md
PROJECT_CONTEXT.md		PROJECT_CONTEXT.md
README.md		README.md
build.sh		build.sh
codelens.conf		codelens.conf
mvnw		mvnw
pom.xml		pom.xml
skills-lock.json		skills-lock.json

Latest commit

History

Folders and files

Repository files navigation