latticelm/docs/ADMIN_UI.md

Admin Web UI

The LLM Gateway includes a built-in admin web interface for monitoring and managing the gateway.

Features

System Information

• Version and build details
• Platform information (OS, architecture)
• Go version
• Server uptime
• Git commit hash

Health Status

• Overall system health
• Individual health checks:
  • Server status
  • Provider availability
  • Conversation store connectivity

Provider Management

• View all configured providers
• See provider types (OpenAI, Anthropic, Google, etc.)
• List models available for each provider
• Monitor provider status

Configuration Viewing

• View current gateway configuration
• Secrets are automatically masked for security
• Collapsible JSON view
• Shows all config sections:
  • Server settings
  • Providers
  • Models
  • Authentication
  • Conversations
  • Logging
  • Rate limiting
  • Observability

Setup

Production Build

1. Enable admin UI in config:

admin:
  enabled: true

2. Build frontend and backend together:

make build-all

This command:

• Builds the Vue 3 frontend
• Copies frontend assets to internal/admin/dist
• Embeds assets into the Go binary using embed.FS
• Compiles the gateway with embedded admin UI

3. Run the gateway:

./bin/llm-gateway --config config.yaml

4. Access the admin UI: Navigate to http://localhost:8080/admin/

Development Mode

For faster frontend development with hot reload:

Terminal 1 - Backend:

make dev-backend
# or
go run ./cmd/gateway --config config.yaml

Terminal 2 - Frontend:

make dev-frontend
# or
cd frontend/admin && npm run dev

The frontend dev server runs on http://localhost:5173 and automatically proxies API requests to the backend on http://localhost:8080.

Architecture

Backend Components

Package: internal/admin/

• server.go - AdminServer struct and initialization
• handlers.go - API endpoint handlers
• routes.go - Route registration
• response.go - JSON response helpers
• static.go - Embedded frontend asset serving

API Endpoints

All admin API endpoints are under /admin/api/v1/:

• GET /admin/api/v1/system/info - System information
• GET /admin/api/v1/system/health - Health checks
• GET /admin/api/v1/config - Configuration (secrets masked)
• GET /admin/api/v1/providers - Provider list and status

Frontend Components

Framework: Vue 3 + TypeScript + Vite

Directory: frontend/admin/

frontend/admin/
├── src/
│   ├── main.ts              # App entry point
│   ├── App.vue              # Root component
│   ├── router.ts            # Vue Router config
│   ├── api/
│   │   ├── client.ts        # Axios HTTP client
│   │   ├── system.ts        # System API calls
│   │   ├── config.ts        # Config API calls
│   │   └── providers.ts     # Providers API calls
│   ├── components/          # Reusable components
│   ├── views/
│   │   └── Dashboard.vue    # Main dashboard view
│   └── types/
│       └── api.ts           # TypeScript type definitions
├── index.html
├── package.json
├── vite.config.ts
└── tsconfig.json

Security Features

Secret Masking

All sensitive data is automatically masked in API responses:

• API keys show only first 4 and last 4 characters
• Database connection strings are partially hidden
• OAuth secrets are masked

Example:

{
  "api_key": "sk-p...xyz"
}

Authentication

In MVP version, the admin UI inherits the gateway's existing authentication:

• If auth.enabled: true, admin UI requires valid JWT token
• If auth.enabled: false, admin UI is publicly accessible

Note: Production deployments should always enable authentication.

Auto-Refresh

The dashboard automatically refreshes data every 30 seconds to keep information current.

Browser Support

The admin UI works in all modern browsers:

• Chrome/Edge (recommended)
• Firefox
• Safari

Build Process

Frontend Build

cd frontend/admin
npm install
npm run build

Output: frontend/admin/dist/

Embedding in Go Binary

The internal/admin/static.go file uses Go's embed directive:

//go:embed all:dist
var frontendAssets embed.FS

This embeds all files from the dist directory into the compiled binary, creating a single-file deployment artifact.

SPA Routing

The admin UI is a Single Page Application (SPA). The static file server implements fallback to index.html for client-side routing, allowing Vue Router to handle navigation.

Troubleshooting

Admin UI shows 404

• Ensure admin.enabled: true in config
• Rebuild with make build-all to embed frontend assets
• Check that internal/admin/dist/ exists and contains built assets

API calls fail

• Check that backend is running on port 8080
• Verify CORS is not blocking requests (should not be an issue as UI is served from same origin)
• Check browser console for errors

Frontend won't build

• Ensure Node.js 18+ is installed: node --version
• Install dependencies: cd frontend/admin && npm install
• Check for npm errors in build output

Assets not loading

• Verify Vite config has correct base: '/admin/'
• Check that asset paths in index.html are correct
• Ensure Go's embed is finding the dist folder

Future Enhancements

Planned features for future releases:

• RBAC with admin/viewer roles
• Audit logging for all admin actions
• Configuration editing (hot reload)
• Provider management (add/edit/delete)
• Model management
• Circuit breaker reset controls
• Real-time metrics and charts
• Request/response inspection
• Rate limit management