Merge pull request #8 from RandomCodeSpace/docs/update-claude-readme-accuracy

docs: update CLAUDE.md and README.md with verified codebase facts

Author: aksOps

CLAUDE.md

@@ -21,7 +21,7 @@
 - JavaParser 3.28.0 (Java AST analysis)
 - ANTLR 4.13.2 (TypeScript/JavaScript, Python, Go, C#, Rust, C++ grammars)
 - Picocli 4.7.7 (CLI framework, integrated with Spring Boot)
-- Thymeleaf + HTMX (web UI)
+- React 18 + TypeScript + Vite 6 + Tailwind CSS (web UI)
 - H2 (incremental analysis cache)
 
 ## Architecture
@@ -96,10 +96,10 @@ io.github.randomcodespace.iq
   |-- grammar/                     # ANTLR parser factory + generated parsers
   |-- graph/                       # GraphStore (Neo4j facade), GraphRepository (SDN, writes only)
   |-- health/                      # GraphHealthIndicator (Spring Actuator)
-  |-- mcp/                         # McpTools (30 @McpTool methods, read-only)
+  |-- mcp/                         # McpTools (31 @McpTool methods, read-only)
   |-- model/                       # CodeNode, CodeEdge, NodeKind (32), EdgeKind (27)
   |-- query/                       # QueryService, StatsService (categorized), TopologyService
-  |-- web/                         # ExplorerController (Thymeleaf web UI)
+  |-- web/                         # Static resource serving (React SPA)
 ```
 
 ## Critical Rules
@@ -144,6 +144,7 @@ io.github.randomcodespace.iq
 | `bundle [path]` | Package graph + source into distributable ZIP |
 | `cache [action]` | Manage analysis cache |
 | `plugins [action]` | List and inspect detectors |
+| `topology [path]` | Show service topology map |
 | `version` | Show version info |
 
 ### Standard Pipeline
@@ -161,25 +162,46 @@ code-iq serve /path/to/repo          # needs enrich if using index
 
 ## Server Endpoints (all read-only)
 
-### REST API (`/api`)
+### REST API (`/api`) -- 34 endpoints
+
+**GraphController** (`/api`):
 - `GET /api/stats` -- Rich categorized statistics (graph, languages, frameworks, infra, connections, auth, architecture)
 - `GET /api/stats/detailed?category=` -- Single category stats
 - `GET /api/kinds` -- Node kinds with counts
 - `GET /api/kinds/{kind}` -- Paginated nodes by kind
-- `GET /api/nodes`, `GET /api/edges` -- Paginated queries
+- `GET /api/nodes` -- Paginated node queries
 - `GET /api/nodes/{id}/detail` -- Full node detail with edges
 - `GET /api/nodes/{id}/neighbors` -- Neighbor traversal
+- `GET /api/edges` -- Paginated edge queries
 - `GET /api/ego/{center}` -- Ego subgraph
-- `GET /api/query/cycles`, `/shortest-path`, `/consumers/{id}`, `/producers/{id}`, `/callers/{id}`, `/dependencies/{id}`, `/dependents/{id}`
+- `GET /api/query/cycles` -- Cycle detection
+- `GET /api/query/shortest-path` -- Shortest path between nodes
+- `GET /api/query/consumers/{id}`, `/producers/{id}`, `/callers/{id}`, `/dependencies/{id}`, `/dependents/{id}`
 - `GET /api/query/dead-code` -- Dead code detection (semantic edge filtering, excludes entry points)
-- `GET /api/triage/component?file=`, `/impact/{id}` -- Agentic triage
+- `GET /api/triage/component?file=` -- Agentic triage by file
+- `GET /api/triage/impact/{id}` -- Impact trace
 - `GET /api/search?q=` -- Free-text search
 - `GET /api/file?path=` -- Source files (path traversal protected)
-- `GET /api/flow/{view}` -- Flow diagrams
-- `GET /api/topology` -- Service topology map
 
-### MCP Tools (30, via `@McpTool` annotation)
-`get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `find_dead_code`, `generate_flow`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`, `get_topology`, `service_detail`, `service_dependencies`, `service_dependents`, `blast_radius`, `find_path`, `find_bottlenecks`, `find_circular_deps`, `find_dead_services`
+**TopologyController** (`/api/topology`):
+- `GET /api/topology` -- Service topology map
+- `GET /api/topology/services/{name}` -- Service detail
+- `GET /api/topology/services/{name}/deps` -- Service dependencies
+- `GET /api/topology/services/{name}/dependents` -- Service dependents
+- `GET /api/topology/blast-radius/{nodeId}` -- Blast radius analysis
+- `GET /api/topology/path` -- Find path between services
+- `GET /api/topology/bottlenecks` -- Find bottleneck services
+- `GET /api/topology/circular` -- Circular dependency detection
+- `GET /api/topology/dead` -- Dead service detection
+
+**FlowController** (`/api/flow`):
+- `GET /api/flow` -- List available flow views
+- `GET /api/flow/{view}` -- Flow diagram for specific view
+- `GET /api/flow/{view}/{nodeId}/children` -- Node children in flow
+- `GET /api/flow/{view}/{nodeId}/parent` -- Node parent in flow
+
+### MCP Tools (31, via `@McpTool` annotation)
+`get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `find_dead_code`, `generate_flow`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`, `get_topology`, `service_detail`, `service_dependencies`, `service_dependents`, `blast_radius`, `find_path`, `find_bottlenecks`, `find_circular_deps`, `find_dead_services`, `find_node`
 
 ## Adding a New Detector
 
@@ -218,7 +240,7 @@ code-iq serve /path/to/repo          # needs enrich if using index
 ## Testing
 
 ```bash
-# Run all tests (~1385 tests)
+# Run all tests (~1440 tests)
 mvn test
 
 # Run a specific test class
@@ -287,7 +309,7 @@ mvn dependency-check:check
 | `config/JacksonConfig.java` | Jackson config (FAIL_ON_UNKNOWN_PROPERTIES disabled for MCP compat) |
 | `cache/AnalysisCache.java` | H2 incremental cache |
 | `api/GraphController.java` | REST API endpoints (read-only) |
-| `mcp/McpTools.java` | 30 MCP tool definitions (`@McpTool`, read-only) |
+| `mcp/McpTools.java` | 31 MCP tool definitions (`@McpTool`, read-only) |
 | `query/QueryService.java` | Graph query operations with Spring caching |
 | `query/StatsService.java` | Rich categorized statistics (7 categories) |
 | `query/TopologyService.java` | Service topology queries |
@@ -321,6 +343,7 @@ mvn dependency-check:check
 - `codeiq.max-radius` -- max ego graph radius (default: 10)
 - `codeiq.max-depth` -- max impact trace depth (default: 10)
 - `codeiq.batch-size` -- files per H2 flush batch (default: 500)
+- `codeiq.neo4j.enabled` -- Neo4j conditional toggle (default: `true`, overridden to `false` in `indexing` profile)
 - `spring.ai.mcp.server.protocol` -- MCP protocol (STREAMABLE)
 
 ### Project-level overrides (`.osscodeiq.yml`)

README.md

@@ -18,7 +18,7 @@
 
 ---
 
-**OSSCodeIQ** scans codebases to build a deterministic knowledge graph of code relationships -- classes, methods, endpoints, entities, dependencies, infrastructure resources, auth patterns, service topology, and more. 97 detectors across 35+ languages, Neo4j Embedded graph database, Spring AI MCP server (31 tools), REST API (32+ endpoints), React web UI, and zero AI dependency.
+**OSSCodeIQ** scans codebases to build a deterministic knowledge graph of code relationships -- classes, methods, endpoints, entities, dependencies, infrastructure resources, auth patterns, service topology, and more. 97 detectors across 35+ languages, Neo4j Embedded graph database, Spring AI MCP server (31 tools), REST API (34 endpoints), React web UI, and zero AI dependency.
 
 ## Quick Start
 
@@ -50,18 +50,18 @@ java -jar target/code-iq-*-cli.jar serve /path/to/repo
 - **Neo4j Embedded** graph database -- full Cypher query support, no external server needed
 - **H2 analysis cache** -- batched streaming for memory-efficient indexing on CI runners
 - **Spring AI MCP server** -- 31 tools via streamable HTTP for AI-powered triage
-- **REST API** -- 32+ endpoints for programmatic access
-- **React UI** -- Dashboard, Topology (Cytoscape.js), Explorer, Flow, MCP Console (Monaco Editor), API Docs
+- **REST API** -- 34 endpoints for programmatic access
+- **React UI** -- Dashboard, Topology (Cytoscape.js), Explorer, Flow, MCP Console, API Docs (Swagger)
 - **Service Topology** -- AppDynamics-style service map with blast radius, circular deps, bottleneck detection
-- **CLI with 14 commands** -- analyze, index, enrich, serve, stats, graph, query, find, flow, bundle, cache, plugins, topology, version
+- **CLI with 15 commands** -- analyze, index, enrich, serve, stats, graph, query, find, cypher, flow, topology, bundle, cache, plugins, version
 - **Virtual threads** (Java 25) -- adaptive parallelism across all available cores
 - **Config-driven pipeline** -- `.osscodeiq.yml` to control languages, detectors, parsers, excludes
 - **Multi-repo support** -- `--graph` + `--service-name` for shared graph across repositories
 - **Flow diagrams** -- interactive Cytoscape.js architecture diagrams (Overview, CI, Deploy, Runtime, Auth views)
 - **Bundle & distribute** -- package graph DB + source + interactive HTML into a ZIP
 - **100% deterministic** -- same input, same output, every time
 - **Incremental analysis** -- H2-backed file hash cache, only re-analyzes changed files
-- **1,227 tests** passing
+- **1,440 tests** passing
 
 ## Three-Command Architecture
 
@@ -129,6 +129,7 @@ Spring Security, Django Auth, FastAPI Auth, NestJS Guards, Passport/JWT, K8s RBA
 | `graph [path]` | Export graph in various formats (JSON, YAML, Mermaid, DOT) |
 | `query [path]` | Query graph relationships (consumers, producers, callers, etc.) |
 | `find [what] [path]` | Preset queries (endpoints, guards, entities, topics, etc.) |
+| `cypher [query]` | Execute raw Cypher queries against Neo4j |
 | `topology [path]` | Service topology queries (blast radius, circular deps, bottlenecks) |
 | `flow [path]` | Generate architecture flow diagrams |
 | `bundle [path]` | Package graph + source into distributable ZIP |
@@ -195,7 +196,7 @@ code-iq serve /path/to/repo
     |         |        |
     v         v        v
  REST API   MCP     React UI
- (32+ ep)  (31 tools) (6 pages)
+ (34 ep)   (31 tools) (6 pages)
 ```
 
 ## Server
@@ -212,12 +213,12 @@ Modern React 18 + TypeScript + Tailwind CSS interface:
 - **Topology** -- Cytoscape.js service dependency map with drill-down
 - **Explorer** -- browse by node kind, click to drill into details with edges
 - **Flow** -- interactive architecture diagrams (Overview, CI, Deploy, Runtime, Auth)
-- **Console** -- Monaco Editor for MCP tool invocation
+- **Console** -- MCP Inspector for tool invocation with category filters and JSON response viewer
 - **API Docs** -- embedded Swagger/OpenAPI documentation
 - Dark/light/system theme toggle
 
 ### REST API (`/api`)
-32+ endpoints for programmatic access:
+34 endpoints for programmatic access:
 - `/api/stats`, `/api/stats/detailed?category=` -- graph and categorized statistics
 - `/api/kinds`, `/api/kinds/{kind}` -- node kinds with counts, paginated nodes
 - `/api/nodes`, `/api/edges` -- paginated queries with `?kind=&limit=&offset=`
@@ -228,17 +229,18 @@ Modern React 18 + TypeScript + Tailwind CSS interface:
 - `/api/triage/component?file=`, `/api/triage/impact/{id}` -- agentic triage
 - `/api/search?q=` -- free-text graph search
 - `/api/file?path=` -- source files (path traversal protected)
-- `/api/flow/{view}` -- flow diagrams
-- `POST /api/analyze` -- trigger analysis
+- `/api/flow`, `/api/flow/{view}`, `/api/flow/{view}/{nodeId}/children`, `/api/flow/{view}/{nodeId}/parent` -- flow diagrams
+- `/api/topology/services/{name}/deps`, `/api/topology/services/{name}/dependents` -- service dependencies
+- `/api/topology/path` -- find path between services
 
 ### MCP Server (`/mcp`)
 31 tools via Spring AI streamable HTTP for AI-powered code triage:
 
 **Core (21 tools):**
-`get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `generate_flow`, `analyze_codebase`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`
+`get_stats`, `get_detailed_stats`, `query_nodes`, `query_edges`, `get_node_neighbors`, `get_ego_graph`, `find_cycles`, `find_shortest_path`, `find_consumers`, `find_producers`, `find_callers`, `find_dependencies`, `find_dependents`, `find_dead_code`, `generate_flow`, `run_cypher`, `find_component_by_file`, `trace_impact`, `find_related_endpoints`, `search_graph`, `read_file`
 
 **Topology (10 tools):**
-`get_topology`, `get_service_detail`, `get_service_dependencies`, `get_service_dependents`, `get_blast_radius`, `find_service_path`, `find_bottlenecks`, `find_circular_dependencies`, `find_dead_services`, `find_topology_node`
+`get_topology`, `service_detail`, `service_dependencies`, `service_dependents`, `blast_radius`, `find_path`, `find_bottlenecks`, `find_circular_deps`, `find_dead_services`, `find_node`
 
 ## Service Topology
 
@@ -340,7 +342,7 @@ cd code-iq
 # Build
 mvn clean package
 
-# Run tests (1,227 tests)
+# Run tests (1,440 tests)
 mvn test
 
 # Analyze this repo
@@ -369,7 +371,7 @@ java -jar target/code-iq-*-cli.jar serve .
 | Graph DB | Neo4j Embedded 2026.02.3 (Community Edition) |
 | Analysis Cache | H2 (pure Java, virtual thread safe) |
 | Cache | Spring Cache (simple in-memory, @Cacheable on query methods) |
-| MCP | Spring AI 1.1.4 (streamable HTTP) |
+| MCP | Spring AI 2.0.0-M3 (streamable HTTP) |
 | Java AST | JavaParser 3.28.0 |
 | Multi-lang AST | ANTLR 4.13.2 (10 grammars) |
 | CLI | Picocli 4.7.7 |