suaveplan/docs/old-network-planning/MODULAR_ARCHITECTURE.md

Modular Architecture for Network Library

Overview

This document outlines a modular architecture approach for the network library, designed to keep the core components lightweight while allowing for extensive functionality through plugins. This architecture enables users to include only the features they need, reducing bundle size and performance overhead in production applications.

Core Design Principles

1. Minimal Core: The core library should contain only essential functionality without which the network cannot operate
2. Plugin-Based Extensions: All non-essential features should be implemented as plugins
3. Lazy Loading: Support for loading modules only when needed
4. Dependency Isolation: Plugins should encapsulate their dependencies, not exposing them to the core
5. Clear Extension Points: Well-defined interfaces for extending functionality

Modular Structure

Core Package (@suaveplan/network-core)

The core package contains only the minimal components required for basic networking:

• NetworkNode: Basic node implementation with minimal features
• Transport Abstraction: Interface and minimal implementation for message passing
• Basic Routing: Essential message routing without advanced features
• Plugin System: Infrastructure to support plugins
• Type Definitions: Shared type definitions and interfaces

This core library should have minimal dependencies, ideally none beyond standard library functionality.

Plugin Packages

Each plugin package would be published separately and follow a consistent naming convention:

• @suaveplan/network-transport-webrtc: WebRTC transport implementation
• @suaveplan/network-transport-websocket: WebSocket transport implementation
• @suaveplan/network-state: State synchronization functionality
• @suaveplan/network-metrics: Performance monitoring and metrics
• @suaveplan/network-security: Security features
• @suaveplan/network-i18n: Internationalization support
• @suaveplan/network-simulation: Testing and simulation tools

Package Structure

network/
├── packages/
│   ├── core/              # Core package
│   │   ├── src/
│   │   ├── package.json   # Minimal or no dependencies
│   │   └── README.md
│   ├── transport-webrtc/  # WebRTC plugin
│   ├── transport-websocket/ # WebSocket plugin
│   ├── state/             # State synchronization plugin
│   ├── metrics/           # Metrics plugin
│   ├── security/          # Security plugin
│   ├── i18n/              # Internationalization plugin
│   └── simulation/        # Simulation plugin
├── bundle/                # Bundle with all plugins (for convenience)
├── examples/              # Example applications
└── docs/                  # Documentation

Integration with Existing Libraries

Each plugin can integrate with appropriate libraries while keeping them encapsulated:

1. Core Package:

   • Use @suaveplan/events for the event system
   • Keep other libraries as optional peer dependencies

2. Transport Plugins:

   • WebRTC/WebSocket specific implementations
   • Crypto functionality for secure transports

3. State Plugin:

   • Leverage @suaveplan/bitpacker for serialization
   • Keep this as an optional feature

4. Security Plugin:

   • Use @suaveplan/crypto and @suaveplan/keys
   • Implement session ownership and encryption

Loading Mechanisms

To support dynamic loading of plugins, implement:

1. Plugin Registry:

   // Core plugin system
   class PluginRegistry {
     register(plugin: IPlugin): void {
       // Registration logic
     }
   }
   
   // Application code
   import { NetworkCore } from '@suaveplan/network-core';
   import { StatePlugin } from '@suaveplan/network-state';
   
   const network = new NetworkCore();
   network.plugins.register(new StatePlugin()); 
   

2. Conditional Imports:

   // For environments that support dynamic imports
   async function loadSecurityIfNeeded() {
     if (config.securityEnabled) {
       const { SecurityPlugin } = await import('@suaveplan/network-security');
       network.plugins.register(new SecurityPlugin());
     }
   }
   

3. Feature Detection:

   class NetworkCore {
     hasFeature(featureId: string): boolean {
       return this.plugins.has(featureId);
     }
   
     // Method to safely use optional features
     withFeature<T>(featureId: string, callback: (feature: any) => T, fallback: T): T {
       if (this.hasFeature(featureId)) {
         return callback(this.plugins.get(featureId));
       }
       return fallback;
     }
   }
   

Plugin Categories

1. Core Enhancement Plugins

These plugins modify or enhance core functionality:

• Advanced Routing Plugin: Adds sophisticated routing strategies
• Priority Queue Plugin: Enhances message prioritization
• Connection Management Plugin: Improves connection handling

2. Feature Addition Plugins

These plugins add entirely new capabilities:

• State Management Plugin: Adds state synchronization
• Voting Plugin: Adds consensus capabilities
• Metrics Plugin: Adds performance monitoring

3. Transport Plugins

These plugins add support for different transport mechanisms:

• WebRTC Transport Plugin
• WebSocket Transport Plugin
• HTTP Transport Plugin

4. Integration Plugins

These plugins integrate with other frameworks:

• React Integration Plugin
• Vue Integration Plugin
• Angular Integration Plugin

Implementation Strategy

1. Define Core Interfaces

Start by clearly defining stable interfaces for all extension points:

// Plugin interface
export interface IPlugin {
  id: string;
  version: string;
  initialize(core: NetworkCore): Promise<void>;
  shutdown(): Promise<void>;
}

// Transport plugin interface
export interface ITransportPlugin extends IPlugin {
  createTransport(config: TransportConfig): ITransport;
  getSupportedOptions(): TransportOptions[];
}

2. Implement Minimal Core

Implement only essential functionality in the core:

• Basic NetworkNode implementation
• Plugin registry and manager
• Simple event emitter (using existing library)
• Essential type definitions
• Memory transport for testing

3. Move Advanced Features to Plugins

Transform complex features into plugins:

• Advanced routing → Routing plugin
• State management → State plugin
• Voting and consensus → Voting plugin
• Security features → Security plugin

4. Provide Convenience Bundles

For users who need a full-featured solution, provide pre-bundled packages:

• Standard Bundle: Core + common plugins
• Full Bundle: All plugins
• Custom Bundles: Configurable builds

Dependency Management

Minimal Core Dependencies

The core should have minimal dependencies:

• @suaveplan/events (essential for event handling)
• TypeScript types and utilities

Optional Peer Dependencies

Plugins should list their dependencies as peer dependencies:

{
  "name": "@suaveplan/network-state",
  "peerDependencies": {
    "@suaveplan/network-core": "^1.0.0",
    "@suaveplan/bitpacker": "^1.0.0"
  },
  "peerDependenciesMeta": {
    "@suaveplan/bitpacker": {
      "optional": true
    }
  }
}

Bundle Size Optimization

Core Size Target

The core package should aim for:

• < 20KB minified
• < 5KB gzipped

Lazy Loading

Support for lazy loading plugins:

class NetworkCore {
  async loadPlugin(pluginId: string): Promise<void> {
    switch (pluginId) {
      case 'state':
        const { StatePlugin } = await import('@suaveplan/network-state');
        this.plugins.register(new StatePlugin());
        break;
      // Other plugins...
    }
  }
}

Modularization of Existing Plan

Phase-by-Phase Modularization

1. Phase 0-1: Implement modular core architecture

   • Define interfaces
   • Implement plugin system
   • Create minimal core

2. Phase 2-3: Implement transport and routing plugins

   • Move transport implementations to plugins
   • Create routing plugin

3. Phase 4-5: Implement metrics and tier plugins

   • Create metrics plugin
   • Create tier management plugin

4. Phase 6-7: Implement state and middleware plugins

   • Create state management plugin
   • Create middleware plugin

5. Phase 8-10: Implement monitoring and integration plugins

   • Create monitoring plugin
   • Create framework integration plugins

Benefits of this Approach

1. Smaller Bundle Size: Applications only include what they need
2. Flexibility: Easy to swap implementations or add custom plugins
3. Maintainability: Isolated code with clear boundaries
4. Testing: Easier to test smaller, focused modules
5. Versioning: Components can evolve independently
6. Adoption: Lower barrier to entry with minimal core

Migration Path

For users who start with the full bundle and want to optimize later:

1. Analysis Tools: Provide tools to analyze which plugins are actually used
2. Gradual Migration: Support incremental migration to cherry-picked plugins
3. Shim Layer: Provide compatibility layer during migration

Conclusion

By adopting this modular architecture, the network library can provide both simplicity for basic use cases and power for advanced applications. The core remains lightweight and focused, while plugins provide the extended functionality needed for more complex scenarios.

This approach allows for:

• Minimal bundle size for simple applications
• Full featured capabilities when needed
• Maximum flexibility for different use cases
• Better maintainability and testing
• Clear separation of concerns

For implementation details, see the appropriate sections in PLAN_ENHANCED.md, particularly Phase 6 which covers the plugin system implementation.