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

# 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 } };
});

// Send messages
const message = new Message('api://users/123', {});
const result = await messageSystem.send(message);

🌟 Key Features

Message-Driven Architecture

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

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

📚 Documentation

Extensive documentation with 151+ markdown files:

• Documentation Index - Start here for 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