kafka/docs/superpowers/specs/2026-03-22-frontend-replacement-design.md

Frontend Replacement: search-zen-50 Integration

Status

Approved

Overview

Replace the current Go template-based frontend (HTMX + Go templates) with the search-zen-50 React SPA. The React app is built statically and embedded into the Go binary, serving as a single binary deployment.

Architecture

• Build: React/Vite app builds to dist/ directory
• Embed: Go's //go:embed embeds the dist folder into the binary
• Serve: Go HTTP server serves static files and handles API routes
• SPA routing: Non-API routes serve index.html for React Router

Changes

Go Side

1. Create internal/spa/spa.go

   • Embeds the React build (dist/) using //go:embed
   • Serves static files (JS, CSS, images)
   • Handles SPA fallback: serves index.html for all non-API routes
   • Provides SPAHandler that wraps API routes

2. Modify cmd/kafka/main.go

   • Import the embedded SPA files
   • Route /, /preferences, and unknown routes to SPA handler
   • Keep existing API routes: /search, /autocompleter, /healthz, /opensearch.xml

React Side

1. Modify use-search.ts

   • Replace mock data with real API call: fetch("/search?format=json&q=${encodeURIComponent(query)}")
   • Map response to existing SearXNGResponse type (already matches)

2. Add autocomplete (optional enhancement)

   • Call /autocompleter?q=${encodeURIComponent(query)}
   • Display suggestions while typing

3. Keep unchanged

   • All UI components
   • Preferences page (localStorage-based)
   • Routing (React Router)

Data Flow

Browser → GET / → Go serves embedded index.html
Browser → GET /search?format=json&q=... → Go search handler → JSON
Browser → React renders results via use-search hook

API Compatibility

The existing kafka API (/search?format=json) already matches the expected SearXNGResponse interface in the React code:

• query: string
• number_of_results: number
• results: SearchResult[]
• suggestions: string[]
• unresponsive_engines: string[][]

File Changes

• New: internal/spa/spa.go
• Modified: cmd/kafka/main.go (wire SPA handler)
• Modified: src/hooks/use-search.ts (use real API)
• Build step: npm run build or bun run build in search-zen-50

Dependencies

• React app uses @tanstack/react-query for API calls (already in package.json)
• No new Go dependencies needed