Minimact Architecture Diagrams

About These Diagrams

This page contains comprehensive visual documentation for the Minimact architecture, showing how components interact, data flows, messaging patterns, and the integration of the Minimact Punch extension.

Minimact Core Architecture

System components showing all layers from TSX development to DOM rendering, including the Babel compilation pipeline, ASP.NET Core runtime, Rust reconciliation engine, and client-side SignalR integration.

Complete Data Flow

Sequence diagram showing the complete request/response cycle, from initial render through predictive pre-caching to user interactions with both cache hits and misses.

Predictive Rendering Pipeline

Flowchart showing how the prediction engine determines whether to send predictions, the confidence threshold, and the verification/correction flow.

State Synchronization NEW

Critical Update: The new auto-sync pattern ensures client state changes are immediately synchronized to the server, preventing stale data issues that could cause the Rust reconciler to overwrite client updates.

Minimact Punch Architecture 🍹

useDomElementState integration showing how DOM observers feed into the reactive state system, enabling DOM-driven predictions.

Integration Patterns

Hook integration showing the symmetry between useState and useDomElementState, both following the same MES-compliant pattern.

Complete System Overview

End-to-end architecture showing all components from developer experience through build-time compilation, server runtime, Rust engine, SignalR layer, client runtime, and Minimact Punch extension.

Performance Characteristics

Latency comparison showing the performance benefits of cache hits in both traditional Minimact and Minimact Punch scenarios.

Component Lifecycle & Initial Load

Initial Page Load Flow

How does the initial page load work? This diagram shows the progression from SSR → HTML → SignalR connection upgrade, demonstrating how the page works without JavaScript and is progressively enhanced with JavaScript.

Component ID Tracking

Components are identified and tracked between server and client using GUIDs embedded in data-component-id attributes.

Prediction Engine Deep Dive

Learning & Pattern Detection

The prediction engine learns patterns through frequency analysis, sequence detection, and conditional pattern recognition. It assigns confidence scores and only sends predictions with ≥70% confidence.

Prediction Triggers

Three types of triggers: explicit usePredictHint, automatic pattern learning, and user behavior patterns (e.g., hover → click probability).

Babel Plugin Transformation

TSX to C# Example

Concrete before/after example showing how TypeScript/JSX transforms into C# with VNode trees.

import { useState } from 'minimact';

export function Counter() {
    const [count, setCount] = useState(0);

    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={() => setCount(count + 1)}>
                Increment
            </button>
        </div>
    );
}

using Minimact.AspNetCore.Core;
using Minimact.AspNetCore.VNodes;

namespace MyApp.Components
{
    public partial class Counter : MinimactComponent
    {
        [State]
        private int count = 0;

        protected override VNode Render()
        {
            return new VElement("div",
                new VElement("p", $"Count: {count}"),
                new VElement("button",
                    new VAttribute("onClick", nameof(Increment)),
                    "Increment"
                )
            );
        }

        private void Increment()
        {
            count++;
            SetState(nameof(count), count);
        }
    }
}

Transformation Pipeline

🎨 Template Patch System NEW

Build-Time Template Generation

The Template Patch System revolutionizes predictive rendering by generating parameterized patch templates at build time through Babel AST analysis. This provides 100% coverage of all possible state values with zero learning phase.

Template Types & Examples

<h1>Welcome to Minimact</h1>

// Template:
{
  "type": "static",
  "template": "Welcome to Minimact",
  "bindings": []
}

<p>Count: {count}</p>

// Template:
{
  "type": "dynamic",
  "template": "Count: {0}",
  "bindings": ["count"],
  "slots": [{ "index": 0, "binding": "count" }]
}

<span>{todo.done ? '✓' : '○'}</span>

// Template:
{
  "type": "conditional",
  "template": "{0}",
  "bindings": ["item.done"],
  "conditionalTemplates": {
    "true": "✓",
    "false": "○"
  }
}

{todos.map(todo => <li>{todo.text}</li>)}

// C# Attribute:
[LoopTemplate(
    itemsBinding: "todos",
    template: "<li>{0}</li>",
    bindings: ["item.text"]
)]

Runtime: Template Filling Flow

At runtime, when state changes, the client fills template slots with actual values for instant updates. No server round-trip needed!

Template vs Hint Queue Comparison

🔌 Plugin System Architecture NEW

Overview

Minimact's Plugin System enables 100% server-side plugins distributed as NuGet packages. Plugins have zero client bundle overhead and leverage the Template Patch System for instant client updates.

Plugin Rendering Flow

From JSX to rendered output, showing how plugins integrate seamlessly with Minimact's architecture.

Plugin Asset Serving

Plugins can include CSS, JavaScript, images, and fonts as embedded resources, served automatically with versioning and caching.

Plugin Example: Clock Widget

[MinimactPlugin("Clock", "1.0.0")]
public class ClockPlugin : MinimactPlugin<ClockState>
{
    public override string Name => "Clock";
    public override string Version => "1.0.0";

    [LoopTemplate(
        template: "<div class='clock'><h2>{0}:{1}</h2><p>{2}</p></div>",
        bindings: ["hours", "minutes", "period"]
    )]
    public override VNode Render(ClockState state)
    {
        return new VElement("div",
            new VAttribute("class", "clock"),
            new VElement("h2", $"{state.Hours}:{state.Minutes:D2}"),
            new VElement("p", state.Period)
        );
    }

    public override IEnumerable<PluginAsset> GetAssets()
    {
        yield return new PluginAsset(
            "clock-widget.css",
            PluginAssetType.Stylesheet
        );
    }
}

public class ClockState
{
    public int Hours { get; set; }
    public int Minutes { get; set; }
    public string Period { get; set; } // "AM" or "PM"
}

export function Dashboard() {
    const [time, setTime] = useState({ hours: 1, minutes: 23, period: 'PM' });

    return (
        <div>
            <h1>Dashboard</h1>
            <Plugin name="Clock" state={time} />
        </div>
    );
}

Plugin Discovery & Registration

PluginManager automatically discovers plugins at startup or supports explicit registration for fine-grained control.

Multi-Version Plugin Support

Multiple versions of the same plugin can coexist, with semver-based compatibility checking.

Security & Authorization Model

Method Invocation Security

Multi-layer security ensures only authenticated, authorized users can invoke component methods with validated parameters.

State Validation Flow

All client state updates go through type checking, range validation, sanitization, and custom validators before being applied.

Attack Prevention Examples

Demonstrating how the security layers block malicious state updates, unauthorized component access, and protected method invocation attempts.

Project Setup & Scaffolding NEW

Generated Project Structure

When you create a new Minimact project, this is the directory structure you get. Understanding where files go and what they do is crucial for development.

Development Loop NEW

Inner Development Loop

The file-save-to-browser-update cycle happens automatically. File watchers detect changes, trigger Babel transformation, compile C#, and update the browser—all in ~2-3 seconds.

Hot Reload System NEW

Template-Based Hot Reload

Minimact uses a template-based hot reload system that extracts text node templates at build time and caches them on both server and client. When you edit a TSX file, only the changed templates are sent to the browser, achieving 3-5ms hot reload latency with 98% less memory than prediction-based approaches.

Complete System Flow

This diagram shows the entire lifecycle: build-time template extraction, runtime initialization, hot reload updates, and automatic state change integration.

Template Extraction (Build Time)

During the Babel transformation, templates are extracted from JSX text nodes and saved to .templates.json files alongside the generated C# code.

Template Loading (Runtime Init)

When a component first registers, the server reads the .templates.json file and sends the template map to the client, which caches it in memory (~2KB per component).

Hot Reload Update (Template Patch)

When you save a TSX file, the FileSystemWatcher detects the change, Babel regenerates the templates, and the server sends only the changed templates to the browser with the current state values filled in.

State Change Integration

When useState triggers a state change, the template system automatically finds all templates bound to that state variable and re-renders them.

Memory & Performance Comparison

Template-based hot reload uses 98% less memory than prediction-based caching while achieving 100% coverage of all possible state values.

Code-Behind Pattern NEW

When to Use Code-Behind

The code-behind pattern separates UI logic (TSX) from business logic (C#). Use .codebehind.cs for database queries, API calls, and complex server-side operations.

export function Counter() {
  const [count, setCount] = useState(0);
  const data = useServerData();

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>+</button>
    </div>
  );
}

// ⚠️ DO NOT EDIT - Auto-generated
public partial class Counter {
  [State] private int count = 0;

  protected override VNode Render() {
    var data = UseServerData();
    return new VElement(...);
  }

  private void increment() {
    count++;
    SetState("count", count);
  }
}

public partial class Counter {
  private readonly AppDbContext _db;

  public Counter(AppDbContext db) {
    _db = db;
  }

  private async Task<UserData> UseServerData() {
    return await _db.Users
      .Where(u => u.Id == UserId)
      .Include(u => u.Orders)
      .FirstOrDefaultAsync();
  }
}

Debugging Tools NEW

Debugging Across Layers

Minimact provides debugging tools for every layer: IDE breakpoints for C# server code, browser DevTools for client code, and the Playground Bridge for visual inspection.

Integration Points NEW

Adding Database (EF Core)

Integrating Entity Framework Core is straightforward. Install packages, create DbContext, register in DI, and use in .codebehind.cs files.

Full-Stack Integration

Minimact components can access the entire ASP.NET Core ecosystem through dependency injection in .codebehind.cs files.