Modulus

Modulus is a modern, cross-platform, plugin-based application framework designed to help developers quickly build extensible, maintainable, and AI-ready tools.

🖼️ Screenshots

Home (Light)

Home (Dark)

✨ Features

Multi-Host Architecture

• UI-Agnostic Core: Business logic independent of any UI framework
• Pluggable Hosts: Supports Avalonia (desktop) and Blazor Hybrid (MAUI)
• Shared Core Logic: Same Domain/Application code runs across all hosts

Extension System

• VS Extension Compatible: Uses extension.vsixmanifest (XML) format
• Hot-Reloadable: AssemblyLoadContext-based isolation for dynamic load/unload
• Explicit Installation: Extensions installed via CLI or UI, not auto-discovered
• Type-Safe Entry Points: ModulusPackage base class similar to VS VsPackage

Developer Experience

• Extension SDK with declarative attributes
• AI Agent plugin support (LLM integration)
• Signature verification and version control
• Cross-platform: Windows / macOS / Linux

🏗️ Architecture

src/
├── Modulus.Core/              # Runtime, module loader, DI
├── Modulus.Sdk/               # SDK: ModulusPackage, attributes
├── Modulus.UI.Abstractions/   # UI contracts (IMenuRegistry, INavigationService)
├── Hosts/
│   ├── Modulus.Host.Avalonia/ # Avalonia desktop (ID: Modulus.Host.Avalonia)
│   └── Modulus.Host.Blazor/   # Blazor Hybrid (ID: Modulus.Host.Blazor)
└── Modules/
    ├── EchoPlugin/            # Example: Echo plugin
    ├── SimpleNotes/           # Example: Notes module
    └── ComponentsDemo/        # Example: UI components demo

📦 Extension Structure

MyExtension/
├── extension.vsixmanifest     # XML manifest (VS Extension format)
├── MyExtension.Core.dll       # Core logic (host-agnostic)
├── MyExtension.UI.Avalonia.dll
└── MyExtension.UI.Blazor.dll

🚀 Quick Start

Install CLI and Templates

# Install the Modulus CLI
dotnet tool install -g Agibuild.Modulus.Cli

# Install project templates
dotnet new install Agibuild.Modulus.Templates

Create Your First Module

# Create a new module
modulus new -n MyModule

# Or use dotnet new
dotnet new modulus-avalonia -n MyModule

# Navigate to module directory
cd MyModule

# Build the module
modulus build

# Package for distribution
modulus pack

# Install to test
modulus install ./output/MyModule-1.0.0.modpkg

Run the Host

# Run Avalonia Host
dotnet run --project src/Hosts/Modulus.Host.Avalonia

# Run Blazor Host (Windows only)
dotnet run --project src/Hosts/Modulus.Host.Blazor

🛠️ CLI Tool

Modulus provides a comprehensive command-line tool for module development and management.

Commands

Command	Description
modulus new	Create a new module project
modulus build	Build the module in current directory
modulus pack	Build and package as .modpkg
modulus install <source>	Install a module
modulus uninstall <name>	Uninstall a module
modulus list	List installed modules

Create Host App (plugin-based application)

# Avalonia desktop host app
modulus new avaloniaapp -n MyApp

# Blazor Hybrid (MAUI) host app
modulus new blazorapp -n MyApp

Notes:

• blazorapp is a MAUI host template and typically requires Windows to build.

Create Module

modulus new [<template>] -n MyModule [options]

Options:
  -n, --name <name>               Module name (PascalCase)
  -o, --output <dir>              Output directory
  --force                         Overwrite existing

Build and Package

# Build the module
modulus build

# Package for distribution
modulus pack

# Package options
modulus pack -o ./dist --verbose

Install and Manage

# Install from .modpkg file
modulus install ./MyModule-1.0.0.modpkg

# Install from directory (development)
modulus install ./artifacts/bin/Modules/MyModule/

# Force overwrite existing installation
modulus install ./MyModule-1.0.0.modpkg --force

# Uninstall
modulus uninstall MyModule

# List installed modules
modulus list --verbose

🔌 Creating an Extension

1. Create Projects

modulus new -n MyExtension

This creates:

MyExtension/
├── MyExtension.sln
├── extension.vsixmanifest
├── MyExtension.Core/
│   ├── MyExtensionModule.cs
│   └── ViewModels/MainViewModel.cs
└── MyExtension.UI.Avalonia/
    ├── MyExtensionAvaloniaModule.cs
    └── MainView.axaml

2. Define Entry Point

// MyExtension.Core/MyExtensionModule.cs
public class MyExtensionModule : ModulusPackage
{
    public override void ConfigureServices(IModuleLifecycleContext context)
    {
        context.Services.AddSingleton<IMyService, MyService>();
        context.Services.AddTransient<MainViewModel>();
    }
}

3. Create Manifest

The manifest is auto-generated by templates. Key sections:

<!-- extension.vsixmanifest -->
<?xml version="1.0" encoding="utf-8"?>
<PackageManifest Version="2.0.0" 
    xmlns="http://schemas.microsoft.com/developer/vsx-schema/2011">
  <Metadata>
    <Identity Id="your-guid" Version="1.0.0" Publisher="You" />
    <DisplayName>My Extension</DisplayName>
    <Description>My awesome extension</Description>
  </Metadata>
  <Installation>
    <InstallationTarget Id="Modulus.Host.Avalonia" Version="[1.0,)" />
    <InstallationTarget Id="Modulus.Host.Blazor" Version="[1.0,)" />
  </Installation>
  <Assets>
    <Asset Type="Modulus.Package" Path="MyExtension.Core.dll" />
    <Asset Type="Modulus.Package" Path="MyExtension.UI.Avalonia.dll" 
           TargetHost="Modulus.Host.Avalonia" />
    <!-- Menus are NOT declared in the manifest.
         Declare menus via [AvaloniaMenu]/[BlazorMenu] on the host-specific module entry type
         and project them to the database at install/update time (metadata-only). -->
  </Assets>
</PackageManifest>

4. Build, Package, and Install

cd MyExtension
modulus build
modulus pack
modulus install ./output/MyExtension-1.0.0.modpkg

📚 Documentation

• Getting Started Guide
• CLI Reference
• Module Development Guide
• Host App Development Guide
• OpenSpec Specifications
• Contributing Guide

🏭 Build System

The project uses Nuke for build automation:

# Build all
nuke compile

# Run tests
nuke test

# Package modules
nuke pack-module

# Package CLI templates
nuke pack-templates

# Publish NuGet packages
nuke publish-libs

Project Status

• Phase: Active Development
• Test Coverage: 30+ tests passing
• Platforms: Windows, macOS, Linux

NuGet Packages

Package	Description
Agibuild.Modulus.Sdk	SDK for module development
Agibuild.Modulus.UI.Abstractions	UI contracts and abstractions
Agibuild.Modulus.UI.Avalonia	Avalonia UI components
Agibuild.Modulus.UI.Blazor	Blazor UI components
Agibuild.Modulus.Cli	CLI tool
Agibuild.Modulus.Templates	Project templates

Note: modulus new generates a Directory.Build.props with ModulusCliLibDir so newly generated modules can compile against the same Modulus assemblies shipped with the CLI.

Contributing

Pull requests and issues are welcome! See CONTRIBUTING.md for guidelines.

License

MIT License