Documentation
Architecture
Tree Geometry

Tree Geometry

The Matrix Framework organizes services in a hierarchical tree structure that determines message flow, state propagation, and service relationships.

Tree Structure

Service Hierarchy

Services are organized in parent-child relationships:

<Matrix xmlns="http://schemas.matrix.com/network/2024">
    <!-- Root service -->
    <ServiceNode Name="OrderSystem">
        <!-- Child services -->
        <ServiceNode Name="OrderProcessor">
            <ServiceNode Name="Validation" />
            <ServiceNode Name="Fulfillment" />
        </ServiceNode>
        
        <ServiceNode Name="InventorySystem">
            <ServiceNode Name="StockManager" />
            <ServiceNode Name="Replenishment" />
        </ServiceNode>
    </ServiceNode>
</Matrix>

Logical Regions

Group related services into regions:

<ServiceNode Name="OrderSystem">
    <!-- Processing Region -->
    <Region Name="Processing">
        <ServiceNode Name="OrderProcessor" />
        <ServiceNode Name="PaymentProcessor" />
    </Region>
    
    <!-- Fulfillment Region -->
    <Region Name="Fulfillment">
        <ServiceNode Name="InventoryManager" />
        <ServiceNode Name="ShippingManager" />
    </Region>
</ServiceNode>

Message Paths

Path Resolution

Messages follow the tree structure:

<ServiceNode Name="OrderSystem">
    <MessageRouter>
        <!-- Upward path through parents -->
        <Route Path="/orders/created" 
               Direction="Up" />
               
        <!-- Downward path through children -->
        <Route Path="/inventory/update" 
               Direction="Down" />
               
        <!-- Lateral path through siblings -->
        <Route Path="/notifications" 
               Direction="Lateral" />
    </MessageRouter>
</ServiceNode>

Path Optimization

Configure efficient message routing:

<ServiceNode Name="OrderSystem">
    <!-- Direct routing bypasses tree traversal -->
    <DirectRoutes>
        <Route From="OrderProcessor" 
               To="InventorySystem" 
               Path="/stock/check" />
    </DirectRoutes>
    
    <!-- Cached routes for frequent messages -->
    <CachedRoutes>
        <Route Path="/metrics/*" 
               CacheDuration="5m" />
    </CachedRoutes>
</ServiceNode>

Service Placement

Load Distribution

Balance services across the tree:

<ServiceNode Name="OrderSystem">
    <!-- Distribute processing load -->
    <LoadBalancer>
        <Rule Path="/orders/*" 
              Strategy="RoundRobin" />
        <Rule Path="/payments/*" 
              Strategy="LeastLoaded" />
    </LoadBalancer>
    
    <!-- Service instances -->
    <ServiceNode Name="OrderProcessor" 
                 Instances="3" />
</ServiceNode>

Dynamic Topology

Adapt the tree structure at runtime:

<ServiceNode Name="OrderSystem">
    <!-- Dynamic service creation -->
    <DynamicServices>
        <Template Name="Processor">
            <ServiceNode Name="{InstanceName}" />
        </Template>
    </DynamicServices>
    
    <!-- Scaling rules -->
    <ScalingRules>
        <Rule Metric="MessageRate" 
              Threshold="1000/s"
              Action="CreateService" 
              Template="Processor" />
    </ScalingRules>
</ServiceNode>

Best Practices

  1. Tree Design

    • Keep tree depth manageable
    • Group related services
    • Balance load distribution
    • Consider message flow patterns

  2. Path Optimization

    • Use direct routes for frequent messages
    • Cache common paths
    • Monitor routing performance
    • Document routing decisions

  3. Service Organization

    • Define clear service boundaries
    • Use regions for logical grouping
    • Plan for scaling
    • Monitor tree health
Core ElementsBindings and Data Context