wave-ui-architect

Wave UI Architect

Expert on Wave Terminal integration, Tsunami framework internals, and Go backend architecture for applications that work across multiple frontend surfaces (Wave widgets, standalone web apps, mobile).

When to Use

• Wave Terminal integration — Building widgets, understanding blocks, widget registration
• Multi-frontend architecture — One backend serving Wave + web + mobile
• Tsunami framework decisions — Whether to use Tsunami VDOM or alternatives
• Go-to-Web integration — Patterns for Go backends driving React/web frontends

Three Architecture Patterns

Pattern 1: Tsunami VDOM Server (Tightest Coupling)

• Go backend generates Virtual DOM, React frontend renders from JSON
• Best for: Maximum Go control, Wave-native development

Pattern 2: Backend-Driven UI (Medium Coupling)

• Go sends UI state as JSON, React components render structures
• Best for: Balanced control, leverage React ecosystem

Pattern 3: Traditional REST/GraphQL API (Loosest Coupling)

• Go serves pure data API, React is standard SPA
• Best for: Standard web architecture, clean separation

Critical Discovery: Wave WebView Support

Wave Terminal does NOT require Tsunami widgets. It has native WebView support:

{
  "my-widget": {
    "icon": "zap",
    "label": "My Widget",
    "blockdef": {
      "meta": {
        "view": "web",
        "url": "http://localhost:8765",
        "web:hidenav": true
      }
    }
  }
}

Standard web apps can integrate with Wave without Tsunami-specific code.

Decision Framework

Question	If Yes	If No
Wave Terminal is primary interface?	Consider Tsunami	Traditional web
Team knows Go well?	Tsunami viable	Traditional web
Need React ecosystem components?	Traditional web	Tsunami can work
Static deployment required?	Traditional web	Both work
Deep Wave integration needed?	Tsunami	WebView is fine

Recommended Architecture (Go + Web)

Go Backend (Single Binary)
  - Core logic, API endpoints, embedded React build (embed.FS)
        |  HTTP + SSE
React Frontend (Standard SPA)
  - shadcn/ui, Tailwind, Jotai, Vite build
        |               |
  Wave WebView    Browser/Mobile

Tooling Recommendations

Go Backend: gorilla/mux or chi, embed.FS, air (hot reload) React Frontend: Vite, shadcn/ui + Tailwind, Jotai (atomic state) Wave Terminal: wsh CLI, tsunami run --open, ~/.config/waveterm/

Anti-Patterns

• Do not try to reuse Tsunami's React frontend with a different backend
• Do not build separate backends for Wave and web
• Do not use Tsunami if you just need basic WebView
• Do not use plain HTTP polling for real-time updates (use SSE or WebSocket)

Trade-Off Summary

Aspect	Traditional Web	Tsunami VDOM
Go control	Backend only	Full stack
React ecosystem	Full access	Limited
Wave integration	WebView	Native
Deployment	Flexible	Go binary required
Complexity	Low	Medium