Core Architecture

The Matrix Framework is built on a hierarchical, tree-based architecture that enables flexible message routing and middleware composition. This document covers the core architectural components and concepts.

Overview

The framework follows a tree-based architecture where:

• Nodes are middleware components that can process and transform messages
• Trees organize nodes in a hierarchical structure for routing
• Routers handle message distribution through the middleware tree

flowchart TD
    subgraph "Middleware Tree"
        root[Root Node]
        auth[Auth Middleware]
        logging[Logging Middleware]
        mqtt[MQTT Handler]
        ws[WebSocket Handler]
    end

    root --> auth
    auth --> logging
    logging --> mqtt
    logging --> ws

    client1[Client] -->|Message| mqtt
    client2[Client] -->|Message| ws

Core Components

Node Layer

The node layer represents individual middleware components that can process messages and form the tree structure.

class MiddlewareNode {
    // Process incoming messages
    async handle(context: Context, next: NextFunction): Promise<void> {
        // Pre-processing logic
        await next();
        // Post-processing logic
    }

    // Add child nodes
    addChild(node: MiddlewareNode): void
    
    // Remove child nodes
    removeChild(node: MiddlewareNode): void
}

Router Layer

The router layer manages message flow through the middleware tree, ensuring proper traversal and handling.

class MessageRouter {
    // Route a message through the middleware tree
    async route(message: Message): Promise<void> {
        // Create routing context
        const context = new Context(message);
        
        // Start routing through tree
        await this.rootNode.handle(context, async () => {
            // Terminal handling
        });
    }
}

Context Layer

The context layer maintains state and metadata throughout message processing.

class Context {
    message: Message;
    metadata: Map<string, any>;
    path: string[];

    // Add metadata to context
    setMeta(key: string, value: any): void
    
    // Retrieve metadata
    getMeta<T>(key: string): T
}

Message Flow

1. Message Reception: A message enters the system through a handler node (e.g., MQTT, WebSocket)
2. Pre-processing: The message flows down the tree, with each node performing pre-processing
3. Terminal Handling: The message reaches its terminal node for main processing
4. Post-processing: The message flows back up, with nodes performing post-processing
5. Response: The final response is returned to the client

Key Features

Tree-based Routing

Messages are routed through a hierarchical tree of middleware nodes, allowing for:

• Organized message processing
• Flexible middleware composition
• Isolated processing branches

Middleware Composition

Nodes can be composed to create complex processing pipelines:

// Create middleware tree
const root = new MiddlewareNode();
const auth = new AuthMiddleware();
const logging = new LoggingMiddleware();
const mqtt = new MQTTHandler();

// Compose middleware
root.addChild(auth);
auth.addChild(logging);
logging.addChild(mqtt);

Context Propagation

Context is maintained throughout the message journey:

• Carries the original message
• Stores processing metadata
• Tracks message path
• Enables middleware communication

Common Patterns

After initialization, the following patterns are supported:

• Pipeline Processing: Messages flow through a series of middleware nodes
• Branch Processing: Different message types follow different paths
• Bidirectional Processing: Nodes can process during both downward and upward flow