View source on GitHub →

Module Splitting Analysis - Executive Summary

Issue: Analyze large modules for potential splitting
Status: ✅ Analysis Complete
Date: 2026-01-23
Priority: LOW (Tech Debt)

TL;DR

Analyzed 9 large Rust modules (>2000 lines each) in the ICN codebase. Recommended splitting icn-ledger/src/ledger.rs (5,447 lines) into 5 focused submodules. Full analysis and implementation guide provided.

Quick Links

Key Findings

🔴 High Priority

icn-ledger/src/ledger.rs (5,447 lines)

  • ✅ Natural boundaries identified: 5 subdomains
  • ✅ Low-medium risk with incremental approach
  • ✅ Backward compatibility via re-exports
  • Recommendation: Split into 5 submodules

🟡 Medium Priority

icn-gossip/src/gossip.rs (3,672 lines)

  • Split by protocol phase (push/pull/anti-entropy)

icn-governance/src/protocol_store.rs (3,452 lines)

  • Extract state management layer

icn-ledger/src/treasury.rs (3,048 lines)

  • Split by operation type (budgets/approvals/audit)

icn-net/src/actor.rs (2,506 lines)

  • Split by message type handlers

🟢 Low Priority / Defer

icn-obs/src/metrics_legacy.rs (4,920 lines)

  • Legacy code, mark deprecated
  • Recommendation: Create migration guide to new metrics

icn-ccl/src/disputes.rs (2,654 lines)

  • Well-structured, near threshold
  • Recommendation: Defer

icn-governance/src/proposal.rs (2,310 lines)

  • Stable, acceptable size
  • Recommendation: Defer

icn-net/src/protocol.rs (2,309 lines)

  • Stable definitions
  • Recommendation: Defer

Recommended Action Plan

Option A: Full Implementation

  1. Split ledger.rs
  2. Split gossip.rs
  3. Split protocol_store.rs
  4. Split treasury.rs
  5. Split net/actor.rs
  6. Final validation

Option B: Incremental (Start with ledger.rs)

  1. Review analysis documents
  2. Get team approval
  3. Implement ledger.rs split in 5 phases
  4. Evaluate results
  5. Plan next modules

Option C: Documentation Only (Current)

  • Keep analysis as reference
  • Implement when time permits
  • Use as template for future refactoring

Benefits of Splitting

Code Quality

  • ✅ Smaller, more focused modules
  • ✅ Clearer separation of concerns
  • ✅ Easier code navigation
  • ✅ Improved code review experience

Performance

  • ✅ Parallel compilation of submodules
  • ✅ Faster incremental builds
  • ✅ Better IDE performance

Maintainability

  • ✅ Easier to understand and modify
  • ✅ Reduced cognitive load
  • ✅ Better testing isolation
  • ✅ Clearer documentation structure

Implementation Safety

Risk Mitigation

  • ✅ Incremental extraction (one module at a time)
  • ✅ Backward compatibility via re-exports
  • ✅ Comprehensive test coverage
  • ✅ Easy rollback (git revert)

Success Criteria

  • ✅ All tests pass
  • ✅ No API breakage
  • ✅ No performance regression
  • ✅ Documentation intact
  • ✅ Clippy/fmt clean

Example: ledger.rs Split

Before

icn-ledger/src/
├── ledger.rs (5,447 lines) ❌ Too large
├── treasury.rs (3,048 lines)
└── ... (other modules)

After

icn-ledger/src/
├── ledger.rs (~2,700 lines) ✅ Manageable
├── ledger_impl/
│   ├── mod.rs
│   ├── queries.rs (~600 lines)
│   ├── balances.rs (~400 lines)
│   ├── fork_ops.rs (~500 lines)
│   ├── freeze_ops.rs (~300 lines)
│   └── witness_ops.rs (~400 lines)
├── treasury.rs (3,048 lines)
└── ... (other modules)

Note: Submodule directory named ledger_impl/ to avoid Rust naming conflict with ledger.rs.

API Compatibility

// Old code still works:
let entry = ledger.get_entry(&hash)?;
let balance = ledger.get_balance(&did, "USD");

// Implementation delegated to submodules internally

Comparison with Prior Work

This follows the pattern established in:

  • Supervisor modularization (Phase 4): Split supervisor.rs into multiple modules
  • Identity bundle refactor: Modularized identity components

Both were successful and improved code maintainability.

Decision Points

For ledger.rs

  • ✅ Clear natural boundaries identified
  • ✅ Low-medium risk
  • ✅ High value (largest module in codebase)
  • 🤔 Decision needed: Proceed with implementation?

For other modules

  • ✅ Analysis complete
  • ✅ Recommendations documented
  • 🤔 Decision needed: Prioritize after ledger.rs?

Team Feedback Needed

  1. Approval: Should we proceed with ledger.rs split?
  2. Timeline: When is best time (least disruptive)?
  3. Approach: Full implementation or incremental PRs?
  4. Scope: Just ledger.rs or other modules too?
  5. Resources: Who should lead the implementation?

Metrics

Current State

  • 9 modules >2000 lines
  • Largest: 5,447 lines (ledger.rs)
  • Total: ~28,000 lines in large modules

After ledger.rs Split

  • 8 modules >2000 lines
  • Largest: 4,920 lines (metrics_legacy.rs)
  • ledger.rs: ~2,700 lines (↓50%)

After All Recommended Splits

  • 4 modules >2000 lines (defer these)
  • All active modules <3000 lines
  • Better code organization across workspace

Next Steps

Immediate (This PR)

  • Complete analysis
  • Document findings
  • Create implementation guide
  • Team review

Short Term (If Approved)

  • Split ledger.rs Phase 1: Query operations (#778)
  • Split ledger.rs Phase 2: Balance operations (#779)
  • Split ledger.rs Phase 3: Fork operations (#780)
  • Split ledger.rs Phase 4: Freeze operations (#781)
  • Split ledger.rs Phase 5: Witness operations (#782)

Medium Term

  • Split gossip.rs (#783)
  • Split protocol_store.rs (#784)
  • Split treasury.rs (#785)
  • Split net/actor.rs (#786)

Long Term

  • Apply learnings to other modules
  • Establish module size guidelines
  • Add CI check for module size

Conclusion

The analysis is complete and comprehensive. The ledger.rs split is recommended as a high-value, low-risk improvement. The implementation guide provides step-by-step instructions for safe execution.

Recommendation: Proceed with ledger.rs split when team bandwidth allows, using the incremental approach outlined in the implementation guide.

Documents Created:

Status: Ready for team review and decision

← Back to Docs