docs: add frontend replacement design spec

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

@@ -0,0 +1,74 @@
+# 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