Skip to content

Architecture

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

Arquitetura do eQuantic.UI

O eQuantic.UI é um framework UI self-contained para .NET que compila C# para JavaScript/TypeScript otimizado, eliminando a dependência de Node.js, npm ou ferramentas externas no fluxo de desenvolvimento.

🏗️ Princípios Core

  1. 100% .NET: Lógica de UI, estado e eventos escritos puramente em C#.
  2. Self-Contained: O ASP.NET Core serve como host e compilador.
  3. Hybrid Compilation: Separação inteligente entre estrutura estática (Shell) e lógica dinâmica.
  4. Clean Architecture: Suporte nativo a DDD e CQRS.

📐 Pilares da Arquitetura

O framework é sustentado por três pilares principais que separam responsabilidades de forma clara:

1. Compiler (eQuantic.UI.Compiler)

O núcleo de transformação. Utiliza Roslyn para analisar o código C# e gerar código TypeScript intermediário e JavaScript otimizado.

  • Estratégia: Converte classes C# em componentes web nativos.
  • Output: Gera bundles otimizados usando um binário Bun embarcado, garantindo performance de build superior (até 8x mais rápido que Webpack/Vite tradicional).

2. Runtime (eQuantic.UI.Runtime)

Uma biblioteca leve (~15kb) executada no browser.

  • Virtual DOM: Algoritmo eficiente de reconciliação para atualizações de UI.
  • State Management: Sistema reativo inspirado em React/Flutter, mas sem o overhead de frameworks pesados.
  • Dispatcher: Gerencia eventos e comunicação com o servidor.

3. Server (eQuantic.UI.Server)

Middleware ASP.NET Core que integra o framework ao pipeline de requisição HTTP.

  • Routing: Descobre páginas marcadas com [Page] attributes.
  • Server Actions: Canal RPC seguro para chamadas C# -> C#.
  • SSR: Renderização inicial server-side para SEO e performance (LCP).

🔄 Fluxo de Compilação Híbrida

O compilador decide o que é estático e o que deve ser dinâmico para otimizar o bundle final.

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: Árvore de widgets imutável compilada em tempo de build.
  2. Dynamic Logic: Event handlers e estado que executam no cliente.
  3. Server Actions: Métodos marcados com [ServerAction] permanecem no servidor e ganham proxies automáticos no cliente.

⚡ Server-Side Rendering (SSR) e Hydration

O framework suporta SSR nativo para melhor SEO e tempo de carregamento inicial.

Fase 1: Renderização (Server)

O servidor executa o método Build() dos componentes C# e gera HTML puro.

  • SEO Automático: Meta tags e OpenGraph gerados automaticamente.
  • Performance: O usuário vê o conteúdo imediatamente, antes do download do JS.

Fase 2: Hydration (Client)

Ao carregar, o Runtime não descarta o HTML existente.

  • Reconciliação: Ele "caminha" sobre o DOM existente.
  • Event Attachment: Anexa apenas os event listeners necessários, sem recriar elementos.
  • Estado: Restaura o estado inicial serializado no HTML.

🛡️ Segurança e Server Actions

A comunicação entre cliente e servidor via Server Actions é protegida por padrão.

  • Autorização: Suporte aos atributos [Authorize], Roles e Policies do ASP.NET Core.
  • Validação: Payloads são sanitizados e validados (limite de 1MB, whitelist de tipos).
  • Sem Exposição de API: Não é necessário criar Controllers manuais; o framework gera endpoints RPC seguros internamente.

Clone this wiki locally