Communities

Communities are functional groupings of code that work together. Unlike directories or modules, communities are detected algorithmically based on actual code relationships.

What is a Community?

A community is a cluster of code symbols (functions, classes, methods) that:

• Frequently call each other
• Share common purposes
• Have higher internal cohesion than external connections

Think of communities as the natural boundaries in your codebase - the groups of code that "belong together" based on how they're actually used.

How Communities Are Detected

noodlbox uses modularity optimization algorithms to identify communities:

1. Build the call graph - Map all function calls in your codebase
2. Calculate modularity - Find groupings that maximize internal connections
3. Detect boundaries - Identify where one community ends and another begins
4. Label communities - Generate meaningful names based on symbols

Community Properties

Cohesion Score

A measure from 0 to 1 of how tightly connected the community is:

• High cohesion (0.8+): Well-defined, focused responsibility
• Medium cohesion (0.5 to 0.8): Reasonable grouping, some external dependencies
• Low cohesion (below 0.5): May indicate code that should be split

Entry Points

Functions that are called from outside the community. These are the community's "API" - how other code interacts with it.

Key Symbols

The most central symbols in the community, based on how many other symbols depend on them.

Example Community

{
  "label": "Authentication",
  "cohesion": 0.92,
  "symbol_count": 85,
  "entry_points": [
    { "name": "login", "calls": 156 },
    { "name": "logout", "calls": 89 },
    { "name": "validateToken", "calls": 234 }
  ],
  "key_symbols": [
    { "name": "authenticateUser", "centrality": 0.95 },
    { "name": "createSession", "centrality": 0.87 }
  ]
}

Communities vs. Files

Working with Communities

Exploring Communities

Use the Codebase Map to see all communities:

GET map://{repository}

Deep Diving

Get details about a specific community:

GET map://{repository}/community/{id}

Querying with Cypher

Find symbols in a community:

MATCH (s:CodeSymbol)-[:MEMBER_OF]->(c:Community)
WHERE c.label = "Authentication"
RETURN s.name, s.symbol_type

Find cross-community calls:

MATCH (s1:CodeSymbol)-[:MEMBER_OF]->(c1:Community),
      (s2:CodeSymbol)-[:MEMBER_OF]->(c2:Community),
      (s1)-[:CALLS]->(s2)
WHERE c1 <> c2
RETURN c1.label, c2.label, s1.name, s2.name

Use Cases

Understanding Codebase Structure

Communities reveal the actual architecture of your code, beyond what's documented or intended.

Impact Analysis

Changes to a community's key symbols affect the entire community. Changes to entry points may affect external code.

Refactoring Planning

Low cohesion communities may need to be split. Frequently cross-communicating communities may need to be merged.

Onboarding

New developers can understand the codebase by exploring communities instead of navigating file trees.

Learn More

• Codebase Map - See all communities
• Community Detail - Explore a specific community
• Processes - Execution flows within and across communities