Embedded Operator Web UI
GoRoute AI Gateway embeds a high-performance Operator Web UI compiled with React 19, TypeScript, Vite, and Tailwind CSS. The entire console is bundled directly into the compiled Go binary using Go's //go:embed directive, eliminating external frontend hosting, CDN dependencies, or CORS setup.
The console is accessible by default at:
http://localhost:8080/ui/
[!NOTE] The gateway automatically redirects non-trailing slash requests (
/ui) to/ui/(HTTP 301) to ensure relative static asset resolution functions properly across reverse proxies and ingress controllers.
1. Architecture: Single-Binary Go Embedding
The Operator Web UI resides in the repository under web/. When built for production, Vite compiles the React SPA into static HTML, JavaScript, and CSS bundles located in web/dist/, which are mirrored to internal/ui/dist/.
Go embed.FS Integration (internal/ui/ui.go)
The Go HTTP handler utilizes embed.FS and http.FileServer with tailored caching headers and HTML5 History API fallback routing:
package ui
import (
"embed"
"io"
"io/fs"
"net/http"
"strings"
"github.com/go-chi/chi/v5"
)
//go:embed all:dist
var embeddedDist embed.FS
// DistFS returns the sub-filesystem for the embedded dist directory.
func DistFS() (fs.FS, error) {
return fs.Sub(embeddedDist, "dist")
}
// RegisterRoutes mounts the embedded operator dashboard on the Chi router at /ui.
func RegisterRoutes(r chi.Router) {
distFS, err := fs.Sub(embeddedDist, "dist")
if err != nil {
return
}
fileServer := http.FileServer(http.FS(distFS))
// Redirect /ui to /ui/ with trailing slash for proper relative asset resolution
r.Get("/ui", func(w http.ResponseWriter, r *http.Request) {
http.Redirect(w, r, "/ui/", http.StatusMovedPermanently)
})
// Serve static assets or fallback to index.html for SPA client-side routing
r.Get("/ui/*", func(w http.ResponseWriter, r *http.Request) {
trimmedPath := strings.TrimPrefix(r.URL.Path, "/ui")
if trimmedPath == "" || trimmedPath == "/" {
trimmedPath = "/index.html"
}
cleanPath := strings.TrimPrefix(trimmedPath, "/")
// If the specific file exists and is not index.html, serve it
if cleanPath != "index.html" {
if f, err := distFS.Open(cleanPath); err == nil {
_ = f.Close()
if strings.HasPrefix(trimmedPath, "/assets/") {
// Immutable caching for hashed assets
w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
}
http.StripPrefix("/ui", fileServer).ServeHTTP(w, r)
return
}
}
// HTML5 History API fallback: serve index.html for client-side routing
indexFile, err := distFS.Open("index.html")
if err != nil {
http.NotFound(w, r)
return
}
defer indexFile.Close()
stat, err := indexFile.Stat()
if err != nil {
http.NotFound(w, r)
return
}
w.Header().Set("Content-Type", "text/html; charset=utf-8")
w.Header().Set("Cache-Control", "no-cache")
http.ServeContent(w, r, "index.html", stat.ModTime(), indexFile.(io.ReadSeeker))
})
}
HTML5 History API Client-Side Routing
The web application uses client-side routing (/ui/playground, /ui/models, /ui/finops, etc.). When a user bookmarks, reloads, or directly navigates to a deep URL:
- Chi receives the request at
/ui/{route}. - The router checks if a physical file matches
{route}. If not, it executes the fallback block. - The server responds with
index.html(HTTP 200,Cache-Control: no-cache), allowing the React client router to parsewindow.location.pathnameand render the matching view without 404 errors. - Assets under
/ui/assets/*contain cryptographic content hashes generated by Vite (e.g.index-B1x48z.js) and are served withCache-Control: public, max-age=31536000, immutable.
2. Production Bundle Budget Validation
To ensure the embedded gateway binary remains lightweight and does not bloat memory footprint or container images, the frontend build enforces a strict bundle budget under 400 KB uncompressed across all compiled files.
Budget enforcement is automated via web/scripts/check-budget.mjs:
| Artifact Category | Uncompressed Budget Threshold | Gzip Budget Threshold |
|---|---|---|
| Max Single JavaScript Chunk | 150 KB max | 45 KB max |
| Max Single CSS File | 35 KB max | 8 KB max |
| Total Production Distribution | 380 KB max (budget ceiling 400 KB) | 110 KB max |
Verifying Bundle Budgets
Run the build script from the repository root:
make ui-build
Or execute directly inside web/:
cd web
npm run build
node scripts/check-budget.mjs
Sample output: