Architecture Guide

Overview

Webui is built as a high-performance, serverless-first platform designed to transform visual designs into production-ready web applications. The architecture prioritizes modularity, developer experience, and horizontal scalability to support thousands of concurrent projects.

The platform operates on a multi-tenant SaaS model with strict data isolation, leveraging edge computing for content delivery and serverless functions for dynamic logic. All state is managed through a centralized orchestration layer.

Core Principles

• Serverless-First: Compute resources scale to zero and burst instantly under load.
• Component-Driven: UI is built as a tree of isolated, reusable web components with strict contracts.
• Zero-Downtime Deploys: Canary releases, blue-green deployment, and instant rollbacks are standard.
• Security by Default: Defense-in-depth strategy with encrypted data at rest/in transit and role-based access control (RBAC).
• Observability: Comprehensive logging, metrics, and distributed tracing across all services.

System Architecture

Webui follows a layered, event-driven architecture. The diagram below illustrates the high-level topology:

Component Layers

1. Frontend Runtime

The Webui editor uses a virtualized DOM tree synchronized with a CRDT-based state manager. This enables real-time collaboration without lock conflicts. Components are compiled to Web Components (Shadow DOM) for strict encapsulation.

2. Backend Microservices

Each domain (auth, projects, assets, billing) runs as an independent service. Communication occurs via gRPC for internal calls and HTTP/JSON for external APIs. Services are stateless and containerized.

3. Rendering Engine

Built in Rust for performance, the rendering engine parses the design AST, applies CSS-in-JS rules, and outputs optimized HTML/CSS/JS bundles. It runs in a sandboxed environment to prevent SSRF and resource exhaustion.

// Component compilation pipeline
async function compile(ast: DesignTree): Promise<Bundle> {
  const validated = validateSchema(ast);
  const optimized = treeShake(validated);
  return emitWebpackConfig(optimized);
}

Request Lifecycle

Understanding how a user action translates into a system response:

1. Client Dispatch: User interacts with the editor. Action is serialized and sent via WebSocket for real-time sync or HTTP/2 for mutations.
2. Gateway Validation: JWT is verified. Rate limits and IP reputation checks are applied.
3. Service Processing: Request is routed to the appropriate microservice. Business logic executes with idempotency keys to prevent duplicate operations.
4. Data Persistence: Writes go to PostgreSQL with optimistic locking. Reads are cached in Redis with cache-aside invalidation.
5. Event Broadcasting: State changes are published to the message queue. Collaborators receive diffs over WebSocket. Async tasks (e.g., image optimization) are queued.
6. Response Delivery: Success payload is returned. CDN edge nodes cache static assets for subsequent requests.

Security & Compliance

• Authentication: OAuth 2.0 / OpenID Connect with support for SAML SSO and MFA.
• Authorization: RBAC with project-level scopes (owner, admin, editor, viewer). Custom claims injected into JWTs.
• Data Encryption: AES-256 at rest, TLS 1.3 in transit. Customer encryption keys (CMK) supported on Enterprise plans.
• Isolation: Multi-tenancy enforced via row-level security (RLS) in PostgreSQL. Tenant IDs are required in all query parameters.
• Compliance: SOC 2 Type II, GDPR, CCPA compliant. Automated data retention and right-to-erasure workflows.

Deployment & Scaling

Webui infrastructure is provisioned via Terraform and managed through GitOps (ArgoCD). The CI/CD pipeline enforces:

• Automated unit, integration, and E2E tests (Jest, Playwright)
• Static code analysis (ESLint, SonarQube) and SAST scanning
• Container image signing and vulnerability scanning (Trivy)
• Progressive delivery: 5% → 25% → 100% rollout with automated rollback on error rate spikes

Horizontal scaling is handled by Kubernetes HPA based on CPU/memory metrics and custom business metrics (e.g., WebSocket connections per pod). Database read replicas are auto-promoted during failover events.

Guidelines & Best Practices

Development Standards

• Use functional components with hooks. Avoid class-based patterns.
• Prefer immutable state updates. Use Immer for complex mutations.
• All async operations must handle loading, success, and error states explicitly.
• Enforce TypeScript strict mode. No any types without technical debt tickets.

Performance Rules

• Virtualize lists exceeding 100 items.
• Debounce user input (300ms default) before API calls.
• Preload critical assets, lazy-load non-essential components.
• Keep initial bundle size under 150KB gzipped.

Error Handling

try {
  await syncProject(projectId);
} catch (err: unknown) {
  if (err instanceof ValidationError) {
    toast.error(err.message);
  } else {
    logger.error('Sync failed', { err, projectId });
    toast.error('Something went wrong');
  }
}

Consistent error boundaries, user-friendly fallbacks, and structured logging ensure rapid debugging without compromising UX.