Flows Versus Communities in the Code-Review-Graph Structure: Execution Paths vs Architectural Clusters

Flows represent execution call chains starting from entry points, while communities are densely connected code clusters discovered by the Leiden algorithm.

The tirth8205/code-review-graph repository models codebase structure in a SQLite graph database to power AI-assisted code reviews. Understanding flows versus communities in the code-review-graph structure enables developers to trace runtime impact and identify architectural boundaries during automated analysis.

What Are Flows?

Flows represent execution-oriented paths through the codebase. Each flow is a directed call chain that begins at an entry point—such as an HTTP handler, CLI command, or test function—and traces all reachable function and class calls.

According to the schema defined in docs/schema.md, the flows table stores these execution traces with the following critical attributes:

• id: Primary key for the flow
• name: Human-readable label identifying the flow
• entry_point_id: Reference to the node where execution begins
• depth, node_count, file_count: Metrics measuring flow complexity
• criticality: Weighted importance score for risk assessment
• path_json: Serialized ordered list of node IDs forming the complete call chain

In code-review-graph-vscode/src/backend/sqlite.py, the backend populates these rows during post-processing by tracing call graphs from detected entry points. Flows answer critical questions: which runtime paths does a code change affect, and what is the criticality of specific call chains?

Practical Applications of Flows

When a developer modifies a function, the graph enumerates all flows containing that function, ranks them by criticality, and identifies the minimal file set an AI reviewer must examine. This execution-oriented insight ensures comprehensive impact analysis for every change.

What Are Communities?

Communities represent architectural clusters of related code discovered through community detection algorithms. Unlike flows, communities group nodes based on connection density rather than execution order.

The communities table in docs/schema.md defines the schema for these architectural boundaries:

• id: Primary key for the community
• name: Auto-generated label (e.g., "Auth-Layer")
• level: Hierarchical depth for nested clustering
• parent_id: Link to higher-level communities enabling recursive splits
• cohesion: Intra-community edge density measuring internal coupling
• size: Total node count within the community
• dominant_language: Most common programming language in the cluster

The Leiden algorithm identifies these communities by finding densely connected subgraphs with sparse external connections. As implemented in the codebase, communities reveal architectural boundaries, knowledge islands, and hotspots regardless of specific runtime entry points.

Architectural Insights from Communities

Communities surface logical subsystems such as "ORM", "CLI", or "UI" layers. High cohesion scores indicate well-modularized code, while cross-community coupling may signal architectural technical debt. This structural view complements execution flows by showing how code organizes statically rather than how it runs dynamically.

Querying Flows and Communities via CLI and MCP

The repository exposes both concepts through command-line tools and Model Context Protocol (MCP) interfaces documented in docs/COMMANDS.md.

To examine execution flows:

# List top-10 flows sorted by criticality

code-review-graph list_flows_tool --limit 10

# Get detailed flow information

code-review-graph get_flow_tool --flow-id 42

To analyze architectural communities:

# List communities by size

code-review-graph list_communities_tool --order size_desc

# Retrieve specific community details

code-review-graph get_community_tool --community-id 7

The MCP tools (list_flows_tool, get_flow_tool, list_communities_tool, get_community_tool) return JSON structures that AI assistants consume to provide contextual code review feedback.

How Flows and Communities Interact

Flows and communities coexist hierarchically within the graph structure. A single flow belongs to one community (or a nested hierarchy of communities), while a community contains many flows.

This relationship enables multi-dimensional analysis: a critical flow might reside within a high-cohesion "Auth" community, or a scattered flow crossing multiple communities might indicate architectural erosion. The docs/architecture.md file details how these concepts integrate into the overall graph-based analysis pipeline.

Summary

• Flows trace execution paths from entry points through the complete call chain, stored with criticality scores and path metadata in the SQLite backend.
• Communities cluster densely connected code via the Leiden algorithm, revealing architectural boundaries and cohesion metrics independent of runtime behavior.
• Schema definitions in docs/schema.md establish the flows and communities tables with attributes like path_json, criticality, cohesion, and parent_id.
• CLI and MCP tools provide programmatic access to both concepts, enabling AI-assisted code review workflows that combine execution impact with structural analysis.

Frequently Asked Questions

How does the code-review-graph generate flows from source code?

The graph builder analyzes entry points such as HTTP handlers and test functions, then performs static analysis to trace all reachable function calls. These traces populate the flows table in code-review-graph-vscode/src/backend/sqlite.py with ordered node lists and calculated criticality scores.

What algorithm identifies communities in the graph?

The implementation uses the Leiden algorithm for community detection. This algorithm optimizes modularity to find clusters of densely connected nodes, assigning each community a cohesion score representing internal edge density relative to external connections.

Can a single flow span multiple communities?

Yes. While a flow originates within one community, its execution path may traverse multiple architectural clusters. This cross-community traversal often indicates coupling between subsystems and helps identify integration points that require careful review during changes.

How do criticality scores differ from community cohesion?

Criticality measures a flow's importance based on entry point significance and call chain characteristics, helping prioritize review efforts. Cohesion measures how tightly knit a community's internal connections are, indicating architectural modularity regardless of runtime execution frequency.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}