Skip to content

Architecture

Jump to bottom
Edgar Mesquita edited this page Jan 26, 2026 · 10 revisions

eQuantic.UI Architecture

eQuantic.UI is a self-contained UI framework for .NET that compiles C# into optimized JavaScript/TypeScript, eliminating the dependency on Node.js, npm, or external tools in the development workflow.

🏗️ Core Principles

  1. 100% .NET: UI logic, state, and events written purely in C#.
  2. Self-Contained: ASP.NET Core serves as both host and compiler.
  3. Hybrid Compilation: Intelligent separation between static structure (Shell) and dynamic logic.
  4. Clean Architecture: Native support for DDD and CQRS.

📐 Architectural Pillars

The framework is supported by three main pillars that clearly separate responsibilities:

1. Compiler (eQuantic.UI.Compiler)

The heart of transformation. It uses Roslyn to analyze C# code and generate intermediate TypeScript code and optimized JavaScript.

  • Strategy: Converts C# classes into native web components.
  • Source Maps: Native support for C# debugging in the browser via VLQ-encoded maps.
  • Output: Generates optimized bundles using an embedded Bun binary and extracts Static CSS for zero-runtime overhead.

2. Runtime (eQuantic.UI.Runtime)

A lightweight library (~15kb) running in the browser.

  • Virtual DOM: Efficient reconciliation algorithm for UI updates.
  • State Management: Reactive system inspired by React/Flutter, but without the overhead of heavy frameworks.
  • Dispatcher: Manages events and server communication.

3. Server (eQuantic.UI.Server)

ASP.NET Core middleware that integrates the framework into the HTTP request pipeline.

  • Routing: Discovers pages marked with [Page] attributes.
  • Server Actions: Secure RPC channel for C# -> C# calls.
  • SSR: Initial server-side rendering for SEO and performance (LCP).

🔄 Hybrid Compilation Flow

The compiler decides what is static and what should be dynamic to optimize the final bundle.

graph TD
    A[C# Component] --> B{Analyser}
    B -->|Structure| C[Static Shell (.static.js)]
    B -->|Behavior| D[Dynamic Logic (.logic.js)]
    C --> E[Bun Bundler]
    D --> E
    E --> F[Optimized Assets]
Loading
  1. Static Shell: Immutable widget tree compiled at build time.
  2. Dynamic Logic: Event handlers and state executing on the client.
  3. Server Actions: Methods marked with [ServerAction] remain on the server and receive automatic proxies on the client.

⚡ Server-Side Rendering (SSR) and Hydration

The framework supports native SSR for better SEO and initial load time.

Phase 1: Rendering (Server)

The server executes the Build() method of C# components and generates pure HTML.

  • Automatic SEO: Meta tags and OpenGraph generated automatically.
  • Performance: The user sees content immediately, before the JS download.

Phase 2: Hydration (Client)

Upon loading, the Runtime does not discard existing HTML.

  • Reconciliation: It "walks" over the existing DOM.
  • Event Attachment: Attaches only necessary event listeners without recreating elements.
  • State: Restores initial state serialized in the HTML.

🛡️ Security and Server Actions

Communication between client and server via Server Actions is protected by default.

  • Authorization: Support for ASP.NET Core [Authorize] attributes, Roles, and Policies.
  • Validation: Payloads are sanitized and validated (1MB limit, type whitelist).
  • No API Exposure: No need to create manual Controllers; the framework generates secure RPC endpoints internally.

Clone this wiki locally