Core-Periphery Metric

Core-Periphery Metric

Overview

Core-Periphery analysis identifies the structural organization of your system by dividing components into two groups:

• Core: Highly connected, central components that form the system’s backbone
• Periphery: Less connected components that depend on or are used by the core

This metric helps understand architectural health by quantifying the structural organization and coupling patterns.

What It Measures

Primary Metrics

• core_periphery.score: Overall core-periphery structure quality (higher is better)

  • Formula: (core_density - periphery_density) × core_percentage
  • Positive values indicate a well-defined core with sparse periphery
  • Negative values suggest poor structural organization

• core_periphery.core_size: Number of nodes classified as core

• core_periphery.periphery_size: Number of nodes classified as periphery

• core_periphery.core_percentage: Percentage of nodes in the core (0.0 to 1.0)

Density Metrics

• core_periphery.core_density: Internal connectivity within core (0.0 to 1.0)

  • Formula: core_internal_edges / possible_core_edges
  • Higher values indicate tightly connected core components

• core_periphery.periphery_density: Internal connectivity within periphery (0.0 to 1.0)

  • Formula: periphery_internal_edges / possible_periphery_edges
  • Lower values are typically better (periphery should be sparse)

Coupling Metrics

• core_periphery.coupling: Fraction of edges connecting core and periphery (0.0 to 1.0)
  • Formula: (core_to_periphery + periphery_to_core) / total_edges
  • Moderate values (0.2-0.4) are healthy
  • Very high values (>0.6) suggest tight coupling

Edge Counts

• core_periphery.core_internal_edges: Edges within core
• core_periphery.periphery_internal_edges: Edges within periphery
• core_periphery.core_to_periphery_edges: Edges from core to periphery
• core_periphery.periphery_to_core_edges: Edges from periphery to core

Optional config (HTML report size)

When generating HTML reports, the core-periphery graph can be large for big codebases. You can limit the embedded graph (the metric still runs on the full graph):

• graph_max_nodes (number). Include only the top N nodes by reachability in the graph (e.g. 500).
• graph_edge_sample_rate (number, 0–1). Include only this fraction of edges between those nodes (e.g. 0.2 for 20%).

See Configuration for an example.

Why It Matters

Well-structured core-periphery systems:

• Have a clear architectural center (core) with stable interfaces
• Enable independent development of peripheral features
• Reduce cognitive load (developers understand the core structure)
• Facilitate refactoring (changes to periphery don’t affect core)
• Support microservice extraction (periphery components are candidates)

Poor core-periphery structure indicates:

• Lack of architectural clarity
• High coupling throughout the system
• Difficulty identifying stable vs. volatile components
• Increased maintenance costs
• Higher risk of breaking changes

Interpretation

Core Score

Score Range	Architecture Quality	Characteristics
> 0.10	Excellent	Clear core with dense internal connections, sparse periphery
0.05 - 0.10	Good	Well-defined structure with some organization
0.00 - 0.05	Warning	Weak core-periphery distinction
< 0.00	Poor	No clear structure, high coupling everywhere

Core Percentage

Percentage	Interpretation
10-20%	Ideal: Small, focused core
20-30%	Good: Reasonable core size
30-50%	Warning: Core may be too large
> 50%	Poor: Most components are “core” (lack of structure)

Core Density

Density	Interpretation
> 0.3	Tightly connected core (good for stability)
0.1 - 0.3	Moderate core connectivity
< 0.1	Loose core (may indicate missing abstractions)

Examples

Well-architected system:

core_periphery.score: 0.12
core_periphery.core_size: 15
core_periphery.periphery_size: 85
core_periphery.core_percentage: 0.15
core_periphery.core_density: 0.35
core_periphery.periphery_density: 0.05
core_periphery.coupling: 0.25

Small, dense core (15%) with sparse periphery. Clear architectural boundaries.

Poorly structured system:

core_periphery.score: -0.02
core_periphery.core_size: 60
core_periphery.periphery_size: 40
core_periphery.core_percentage: 0.60
core_periphery.core_density: 0.15
core_periphery.periphery_density: 0.20
core_periphery.coupling: 0.55

Large, loose core (60%) with high coupling. No clear structure.

Policy Recommendations

For New Projects

policy:
  invariants:
    - metric: core_periphery.score
      op: ">="
      value: 0.05 # Maintain clear structure
    - metric: core_periphery.core_percentage
      op: "<="
      value: 0.25 # Keep core small
    - metric: core_periphery.coupling
      op: "<="
      value: 0.40 # Limit core-periphery coupling

For Legacy Refactoring

policy:
  invariants:
    - metric: core_periphery.score
      op: ">="
      value: 0.00 # Prevent further degradation
    - metric: core_periphery.core_percentage
      op: "<="
      value: 0.40 # Gradual improvement target

With Regression Prevention

policy:
  baseline:
    mode: git
    ref: origin/main
  no_regression: true # Core score must not decrease

How to Improve Core-Periphery Structure

1. Identify Core Components

Core components should be:

• Stable: Rarely change
• Central: Many components depend on them
• Well-tested: High test coverage
• Well-documented: Clear APIs

Examples: authentication, data models, core utilities.

2. Extract to Periphery

Move volatile components to periphery:

• Feature-specific code
• UI components
• External integrations
• Experimental code

3. Reduce Core Size

If core is too large (>30%):

• Extract stable abstractions
• Create intermediate layers
• Use dependency inversion
• Apply facade pattern

4. Improve Core Density

If core density is low (<0.1):

• Identify missing abstractions
• Consolidate related functionality
• Create shared interfaces
• Reduce redundant dependencies

5. Manage Coupling

If coupling is high (>0.5):

• Limit direct dependencies between core and periphery
• Use event-driven communication
• Apply mediator pattern
• Create clear boundaries

Academic Background

Core-Periphery analysis originates from network science and has been applied to software architecture:

“The core-periphery structure is a fundamental organizational pattern in complex networks” - Borgatti & Everett (2000)

In software architecture research, it’s been used to:

• Identify architectural patterns
• Measure structural quality
• Predict maintenance costs
• Guide refactoring efforts

Technical Details

• Algorithm: Uses reachability analysis to identify core nodes
  • Core nodes have above-average in+out reachability
  • Threshold: nodes with reachability score >= average
• Complexity: O(n²) for reachability + O(n + m) for edge classification
• Requires: Reachability index and import graph
• Cache: Results are cached; recomputed only when graph changes

Related Metrics

• Propagation Cost: High PC often correlates with weak core-periphery structure
• SCC: Cycles in core are particularly problematic
• Centrality (future): Betweenness centrality can identify core candidates
• Modularity (future): Community detection can complement core-periphery analysis