Mycelia Kernel

A sophisticated message-driven architecture framework with composable hooks, built-in security, and multi-backend support.

🎯 What is Mycelia Kernel?

Mycelia Kernel is a production-ready framework for building message-driven systems with:

• 🔌 Hook-based composition - Extend subsystems without modification
• 📨 Pure message-driven - Zero direct references between components
• 🔒 Built-in security - PKR-based identity and fine-grained permissions
• 🔄 Multi-backend - SQLite, IndexedDB, Memory with identical API
• 🌐 Web server adapters - Fastify, Express, Hono support
• 📊 Production features - Observability, tracing, health checks
• 🚀 High performance - 50k+ queue ops/sec with circular buffer

⚡ Quick Start

🚀 Recommended: Use the CLI for the best developer experience!

# Install
npm install mycelia-kernel

# Initialize a new project (recommended)
npx mycelia-kernel init --name my-app

# Generate a subsystem with proper structure
npx mycelia-kernel generate subsystem UserService --use-defaults-async

# Generate test utilities and test files
npx mycelia-kernel generate test-utilities
npx mycelia-kernel generate test UserService

# Run health checks
npx mycelia-kernel doctor

# Learn terminology
npx mycelia-kernel glossary subsystem

Or use manually:

# Install
npm install mycelia-kernel

# Create your first subsystem
import { MessageSystem, BaseSubsystem } from 'mycelia-kernel';

// Bootstrap the system
const messageSystem = new MessageSystem('my-app');
await messageSystem.bootstrap();

// Create a subsystem with hooks
class MySubsystem extends BaseSubsystem {
  constructor(name, ms) {
    super(name, { ms });
    this.use(useRouter);
    this.use(useQueue);
  }
}

// Register and use
const subsystem = new MySubsystem('api', messageSystem);
await subsystem.build();
await messageSystem.registerSubsystem(subsystem);

// Register routes
subsystem.router.registerRoute('users/{id}', async (message, params) => {
  return { user: { id: params.id } };
});

// ✅ CORRECT: Send messages from a subsystem using identity.sendProtected()
// This ensures proper security, caller authentication, and access control
const message = new Message('api://users/123', {});
const result = await subsystem.identity.sendProtected(message);

// ❌ INCORRECT: Don't use messageSystem.send() from within subsystems
// const result = await messageSystem.send(message); // Wrong!

💡 Tip: The CLI provides code generation, health checks, and a comprehensive glossary. See CLI Documentation for details.

🌟 Key Features

Message-Driven Architecture

• Path-based routing: subsystem://path/to/resource
• Loose coupling between components
• Async-first design
• Built for distributed systems

Sending Messages from Subsystems:

// ✅ CORRECT: Use subsystem.identity.sendProtected()
// This ensures proper security, caller authentication, and access control
const message = new Message('other-subsystem://action', { data: 'value' });
const result = await subsystem.identity.sendProtected(message);

// ❌ INCORRECT: Don't use messageSystem.send() from within subsystems
// This bypasses security and caller authentication
// const result = await messageSystem.send(message); // Wrong!

Why use identity.sendProtected()?

• ✅ Automatic caller authentication (uses subsystem's PKR)
• ✅ Prevents message spoofing
• ✅ Enforces access control and permissions
• ✅ Proper security guarantees
• ✅ Works with all communication types (routes, commands, queries, requests)

Hook-Based Composition

subsystem
  .use(useRouter)           // Add routing
  .use(useQueue)            // Add message queue
  .use(useAuthStrategies)   // Add authentication
  .use(useSQLiteStorage)    // Add SQLite storage
  .build();

Security System

• PKR-based identity management
• Reader-Writer-Set (RWS) permissions
• Scope-based access control
• Protected messaging with caller authentication

Multi-Backend Storage

// Use SQLite
subsystem.use(useSQLiteStorage, {
  config: { storage: { dbPath: './data.db' } }
});

// Or IndexedDB (browser)
subsystem.use(useIndexedDBStorage, {
  config: { storage: { dbName: 'myapp' } }
});

// Or Memory (testing)
subsystem.use(useMemoryStorage);

HTTP Server Adapters

// Choose your server
subsystem.use(useFastifyServer);  // Fastify
// OR
subsystem.use(useExpressServer);  // Express
// OR
subsystem.use(useHonoServer);     // Hono

🛠️ CLI Tools

The Mycelia Kernel CLI makes development easier:

• mycelia-kernel init - Initialize new projects with proper structure
• mycelia-kernel generate subsystem - Generate subsystems with correct patterns
• mycelia-kernel generate hook - Generate custom hooks
• mycelia-kernel generate test-utilities - Generate testing utilities (mocks, helpers)
• mycelia-kernel generate test <subsystem> - Generate test file scaffolding
• mycelia-kernel doctor - Run health checks (missing handlers, dependencies, etc.)
• mycelia-kernel glossary - Learn Mycelia terminology (30+ terms)
• mycelia-kernel routes/commands/queries - Discover subsystem capabilities

See CLI Documentation for complete reference.

📚 Documentation

Extensive documentation with 151+ markdown files:

• CLI Documentation - Start here! Code generation and project management
• Documentation Index - Organized docs
• Design Patterns - 20+ patterns explained
• Architecture Overview - Hook-based plugin system
• Security Model - PKR identity & RWS permissions
• Performance Guide - Optimization strategies
• Real-World Usage - Production patterns
• API Reference - Detailed API documentation

🧪 Testing

Comprehensive test suite with 713 tests (99.8% pass rate):

# Run all tests
npm test

# Watch mode
npm run test:watch

# Run benchmarks
npm run bench

🚀 Performance

Queue Performance:

• 50,000+ operations/sec with circular buffer
• 16x faster than array-based implementation for large queues
• <1ms latency at p95

Benchmarks:

npm run bench:queue

See Performance Optimization Plan for details.

🎨 Design Patterns

Mycelia implements 20+ design patterns:

• Hook Pattern (composable extensions)
• Strategy Pattern (pluggable algorithms)
• Factory Pattern (object creation)
• Observer Pattern (events/listeners)
• Repository Pattern (storage abstraction)
• Adapter Pattern (multi-backend support)
• And 14 more...

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│              MessageSystem                      │
│        (Central Coordinator)                    │
└─────────────────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        │            │            │
        ▼            ▼            ▼
   ┌────────┐  ┌────────┐  ┌────────┐
   │ Kernel │  │  API   │  │  DB    │
   │Subsystem  │Subsystem  │Subsystem
   └────────┘  └────────┘  └────────┘
        │            │            │
     Messages    Messages    Messages

🔧 Use Cases

Perfect for:

• Canvas/Drawing Applications - Layer management, tool coordination
• Workflow Systems - Task orchestration, state machines
• Microservices - Service coordination, message-based communication
• Real-Time Apps - WebSocket, event broadcasting
• Modular Backends - Plugin-based architecture, multi-tenant systems

Already Used In:

• Math Whiteboard - Collaborative tutoring application

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Code of conduct
• Development setup
• Pull request process
• Coding standards

📄 License

MIT License - see LICENSE for details.

🌐 Links

• GitHub: https://github.com/lesfleursdelanuitdev/mycelia-kernel
• Documentation: Comprehensive docs
• Issues: https://github.com/lesfleursdelanuitdev/mycelia-kernel/issues

📊 Stats

• 301 JavaScript files
• 713 tests (99.8% pass rate)
• 151+ documentation files
• 20+ design patterns
• 8.5/10 code quality rating

🙏 Acknowledgments

Built with modern tools:

• Vite for build system
• Vitest for testing
• ESLint for code quality

Made with ❤️ by @lesfleursdelanuitdev