Piccolo.Core 0.1.1

Piccolo.NET — A Namekian Architecture for Modular Monoliths

Piccolo is a .NET library that simplifies and empowers the creation of modular monoliths. Inspired by the Namekians from Dragon Ball and their ability to fuse and regenerate, Piccolo enables a host application to integrate and manage modules dynamically and resiliently.

• Fusion of Modules: Extend functionality of the host by fusing external modules (plugins) into the core.
• Regeneration (Concept): Improve resilience by isolating and restarting faulty modules without taking down the whole app.
• Isolation via AssemblyLoadContext: Each module can be loaded in its own collectible AssemblyLoadContext to reduce coupling and enable unloading.

This repository contains:

• Piccolo.Core — the core abstractions and module loader.
• Example/ — a minimal example host and a HelloModule demonstrating how to load a module.

Why modular monoliths?

A modular monolith deploys as a single application while being organized as cohesive modules (e.g., Users, Orders, Inventory). Piccolo acts as the fusion manager for these modules, letting teams develop modules independently and plug them into the application without tight coupling.

Key Concepts

Fusion — Extending Functionality

Piccolo can “fuse” external modules with the host application. Each module represents a feature area. The host discovers, loads, and initializes these modules at startup.

How fusion works in Piccolo:

1. Module discovery: At startup, the host uses Piccolo to find compatible modules ("Namekians"). You can:
   • Load modules already present in the default AssemblyLoadContext, or
   • Specify explicit assembly file paths to load, each in its own AssemblyLoadContext for isolation.
2. Integration and communication: Modules are instantiated via dependency injection (ActivatorUtilities). Contracts are defined via IModule and, optionally, application-specific interfaces or the IEventBus for decoupled communication.
3. Extending capabilities: Once initialized, the module contributes features to the host (e.g., a Payments module enabling transaction processing) with minimal changes to the host code.

Regeneration — Fault Tolerance and High Availability (Vision)

Inspired by Piccolo’s regeneration, the library aims to support isolating and restarting faulty modules without affecting the rest of the app.

• Fault detection: Monitor module health (future work; the Example is minimal).
• Isolation: Faulty modules should be isolated so errors do not cascade.
• Restart: The host can attempt to restart a module into a safe state.
• Notification: Administrators can be notified of failures and recoveries.

Today, Piccolo.Core already supports isolation at the assembly loading level using collectible AssemblyLoadContext, enabling controlled unloading of modules. Health checks and automatic restarts can be layered on top in your host.

What’s in Piccolo.Core?

• IModule — Basic contract that modules implement:

  • Name: string
  • ConfigureServices(IServiceCollection services, IConfiguration configuration): Register services in the module's isolated container.
  • Initialize(IServiceProvider serviceProvider): Async initialization logic (e.g., subscribing to events).
  • Shutdown(): Cleanup logic.

• ModuleLoader — Discovers, loads, initializes, and shuts down modules. It supports two modes:

  1. Discovery from already loaded assemblies (default AssemblyLoadContext)
  2. Explicit assembly paths for modules, each loaded into its own collectible AssemblyLoadContext

• IEventBus — Abstraction for event-driven communication. Piccolo provides:

  • InMemoryEventBus: Simple in-process event bus.
  • EventRouter: Routes events to the appropriate bus based on configuration.
  • Note: The Example project includes an MqttEventBus implementation demonstrating how to create distributed buses.

Configuration

ModuleLoader reads configuration from the Piccolo section in appsettings.json:

• Modules: Optional list of module type names to enable (filter). If empty or missing, all discovered IModule types are loaded.
• ModuleAssemblies: Optional list of module assembly file paths. If provided, each is loaded into its own AssemblyLoadContext and scanned for IModule implementations.
• SharedAssemblies: List of assembly names that should be shared across all modules (loaded in the default context). This is critical for sharing types like Events or Interfaces between the host and modules.
• Routing: Configuration for the Event Bus routing.

Event Routing

Piccolo supports a flexible event routing system. You can define:

• DefaultBus: The bus to use if no specific rule matches.
• Publishers: Which buses an event should be published to (can be multiple).
• Subscribers: Which bus a handler should subscribe to for a given event.

Example appsettings.json

{
  "Piccolo": {
    "Modules": [
      "HelloModule"
    ],
    "ModuleAssemblies": [
      "Example/Modules/HelloModule/bin/Debug/net9.0/HelloModule.dll"
    ],
    "SharedAssemblies": [
      "Piccolo.Example.Core"
    ],
    "Routing": {
      "DefaultBus": "in-memory",
      "Publishers": {
        "OrderCreatedEvent": ["in-memory", "queue"],
        "OrderProcessedEvent": ["queue"]
      },
      "Subscribers": {
        "OrderCreatedEvent": "in-memory",
        "OrderProcessedEvent": "queue"
      }
    }
  }
}

Notes:

• Paths in ModuleAssemblies can be absolute or relative to the host process working directory.
• SharedAssemblies ensures that types defined in those assemblies are treated as the same type across different load contexts.

Quick Start

1. Open the solution:

   • Piccolo.NET.sln

2. Build the solution:

   • This repository includes an Example host and a HelloModule.

3. Run the Example host (Example/Piccolo.Example):

   • Optionally create an appsettings.json next to the executable with the configuration shown above to load HelloModule via its assembly path and/or filter by module name.

4. Exit cleanly:

   • Press Ctrl+C to shut down; ModuleLoader will call Shutdown() on each module and unload collectible AssemblyLoadContexts.

Creating a Module

1. Create a class library that references Piccolo.Core.
2. Implement IModule:

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Piccolo.Core;

public class MyModule : IModule
{
    public string Name => "MyModule";

    public void ConfigureServices(IServiceCollection services, IConfiguration configuration)
    {
        // Register services here
        // services.AddTransient<IMyService, MyService>();
    }

    public Task Initialize(IServiceProvider serviceProvider)
    {
        // Subscribe to events, start background work, etc.
        return Task.CompletedTask;
    }

    public void Shutdown()
    {
        // Clean up resources
    }
}

3. Build the module and provide its DLL path via Piccolo:ModuleAssemblies (or ensure it is already loaded in the host AppDomain).

Advantages of Piccolo

• Independent Development: Teams can develop modules in parallel.
• Selective Scalability: Optimize or replace individual modules without reshaping the entire app.
• Easier Maintenance: Update or replace functionality by swapping a module.
• Higher Resilience: Isolation and the regeneration vision improve fault tolerance.

Roadmap

• Health monitoring and restart strategies for modules (regeneration).
• Advanced Event Bus features (e.g., Sagas, Outbox pattern).
• Better tooling for module discovery and diagnostics.

License

This project is licensed under the MIT License. See the LICENSE file for details.