# How the Louvain Community Detection Algorithm Works in LLM Wiki: Graph-Based Knowledge Clustering

> Discover how the Louvain community detection algorithm clusters LLM Wiki pages by analyzing its link graph for interconnected knowledge.

- Repository: [nash_su/llm_wiki](https://github.com/nashsu/llm_wiki)
- Tags: deep-dive
- Published: 2026-09-13

---

**LLM Wiki applies the Louvain method to its internal link graph to automatically discover densely-connected communities of related pages and calculate cohesion scores that measure group interconnectedness.**

The Louvain community detection algorithm serves as the backbone of topic clustering in LLM Wiki, transforming the unstructured web of internal links into organized, navigable knowledge groups. By treating each wiki page as a node and each hyperlink as an edge, the system identifies natural content communities without manual tagging. This analysis examines the production implementation found in [`src/lib/wiki-graph-analysis.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph-analysis.ts) and the supporting type definitions in [`src/lib/wiki-graph.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph.ts).

## Graph Construction and Representation

The pipeline begins by constructing an undirected graph using the **Graphology** library. The `detectCommunities` function initializes a new graph instance and populates it with the wiki's structural data.

Nodes are added using `graph.addNode(node.id)` for every page in the knowledge base. For edges, the implementation calls `graph.addEdgeWithKey` to create weighted connections between linked pages while explicitly preventing duplicate edges. This deduplication ensures that multiple references between the same pair of pages do not skew community detection results.

The resulting structure represents the complete wiki topology as an undirected, weighted graph where edge weights reflect link strength between related content.

## Running the Louvain Algorithm

Once the graph is constructed, the system invokes the specialized `graphology-communities-louvain` package to perform the actual partition optimization. The function signature used is:

```typescript
const communityMap: Record<string, number> = louvain(graph, { resolution: 1 })

```

This returns a mapping from node ID to community ID, effectively assigning each wiki page to a specific cluster. The **`resolution`** parameter directly controls granularity: values less than 1 produce coarser communities (fewer, larger groups), while values greater than 1 yield finer-grained partitions (more, smaller groups). The default resolution of 1 provides a balanced clustering suitable for general topic organization.

## Community Analysis and Metrics Calculation

After obtaining the initial assignments, the implementation performs several analytical passes to compute meaningful community statistics.

### Node Grouping and Edge Counting

The code transforms the flat `communityMap` into a `Map<number, string[]>` structure that groups node IDs by their assigned community. It then iterates through the original edge list to tally **intra-community edges**—connections where both endpoints share the same community ID. This count is stored in `intraEdgesByCommunity` for subsequent calculations.

### Cohesion and Top Node Detection

For each discovered community, the system calculates four key metrics:

1.  **Node Count**: The total number of pages belonging to the community.
2.  **Possible Edges**: The theoretical maximum calculated as `nodeCount * (nodeCount - 1) / 2`, representing a fully-connected subgraph.
3.  **Cohesion Score**: The ratio of `intraEdges / possibleEdges`, where a value of 1.0 indicates a completely interconnected community (clique) and lower values indicate sparser connectivity.
4.  **Top Nodes**: The five pages with the highest `linkCount` (most outgoing connections) within the community, sorted in descending order to identify central hub pages.

### ID Remapping and Sorting

To ensure consistent UI presentation, communities are sorted by descending node count. The system then remaps community IDs to a consecutive range (`0` through `N-1`), eliminating gaps that may exist in the raw Louvain output. This normalization simplifies frontend consumption and ensures predictable ordering.

## Web Worker Integration for Performance

To maintain UI responsiveness during computation, LLM Wiki offloads the detection process to a dedicated Web Worker implemented in [`src/lib/wiki-graph-analysis.worker.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph-analysis.worker.ts). This architecture prevents graph analysis from blocking the main thread, allowing users to continue interacting with the wiki while the algorithm processes potentially thousands of nodes and edges in the background.

## Practical Implementation Example

The following TypeScript example demonstrates how to invoke the community detection pipeline using the actual LLM Wiki API:

```typescript
import { detectCommunities } from "./lib/wiki-graph-analysis"

// Define wiki pages with metadata
const nodes = [
  { id: "pageA", label: "Machine Learning Basics", linkCount: 12 },
  { id: "pageB", label: "Neural Networks", linkCount: 8 },
  { id: "pageC", label: "Deep Learning", linkCount: 15 },
  { id: "pageD", label: "Ancient History", linkCount: 3 },
]

// Define internal links between pages
const edges = [
  { source: "pageA", target: "pageB", weight: 1 },
  { source: "pageA", target: "pageC", weight: 1 },
  { source: "pageB", target: "pageC", weight: 1 },
  { source: "pageD", target: "pageA", weight: 0.5 }, // Weak cross-topic link
]

// Execute detection
const { assignments, communities } = detectCommunities(nodes, edges)

// View individual page assignments
for (const [nodeId, communityId] of assignments) {
  console.log(`${nodeId} → community ${communityId}`)
}

// Analyze community structure
communities.forEach(c => {
  console.log(`Community ${c.id}: ${c.nodeCount} pages, cohesion ${c.cohesion.toFixed(2)}`)
  console.log(`Central pages: ${c.topNodes.join(", ")}`)
})

```

This example illustrates how the algorithm separates the machine learning topics (pages A, B, C) from unrelated content (page D) based purely on connectivity patterns.

## Summary

- **Graph Representation**: LLM Wiki builds an undirected Graphology graph from page nodes and link edges in [`src/lib/wiki-graph-analysis.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph-analysis.ts).
- **Louvain Execution**: The `graphology-communities-louvain` package partitions the graph using a configurable resolution parameter to control community granularity.
- **Cohesion Metrics**: Communities are evaluated using the ratio of actual internal edges to possible edges, identifying tightly-knit knowledge clusters.
- **Performance Optimization**: Heavy computation runs inside [`src/lib/wiki-graph-analysis.worker.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph-analysis.worker.ts) to prevent UI blocking.
- **Hub Identification**: Each community surfaces its top five most-connected pages to highlight central reference materials.

## Frequently Asked Questions

### What is the Louvain algorithm used for in LLM Wiki?

The Louvain algorithm automatically organizes the wiki's knowledge base by detecting communities of densely interconnected pages. According to the `nashsu/llm_wiki` source code, this eliminates the need for manual categorization while ensuring that related topics are grouped together based on actual link patterns rather than superficial tags.

### How is community cohesion calculated?

Cohesion measures how tightly-knit a community is by dividing the count of actual intra-community edges by the number of possible edges in a complete graph of that size. In [`src/lib/wiki-graph-analysis.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph-analysis.ts), this is computed as `intraEdges / (nodeCount * (nodeCount - 1) / 2)`, producing a score between 0 and 1 where higher values indicate stronger internal connectivity.

### What does the resolution parameter control?

The resolution parameter passed to `graphology-communities-louvain` adjusts the granularity of detected communities. Values below 1 merge smaller communities into larger clusters, while values above 1 subdivide broad communities into more specific subgroups, allowing administrators to tune the knowledge organization scale.

### Where are the type definitions for community data structures?

The `CommunityInfo` interface and related type definitions reside in [`src/lib/wiki-graph.ts`](https://github.com/nashsu/llm_wiki/blob/main/src/lib/wiki-graph.ts). This file specifies the structure for community metadata including `id`, `nodeCount`, `cohesion`, and `topNodes`, ensuring type safety across the detection pipeline and its consumers.