--- title: Dashboard description: Extensible micro-frontend shell for admin dashboards with contributor system, real-time updates, and Go-JS bridge --- ## Overview `github.com/xraph/forge/extensions/dashboard` provides an extensible micro-frontend dashboard shell for Forge applications. It is powered by ForgeUI and uses a **contributor-based architecture** where extensions register pages, widgets, and settings that are merged into a unified admin dashboard. The dashboard supports both **local contributors** (in-process, rendering gomponents nodes) and **remote contributors** (separate HTTP services whose HTML fragments are proxied and embedded). Navigation, layout, and theming are handled automatically by the shell. ## What It Registers | Service | DI Key | Type | |---|---|---| | Dashboard extension | `dashboard` | `*Extension` | Routes are mounted on the Forge HTTP router during `Start()` at the configured base path (default `/dashboard`). ## Quick Start ```go package main import ( "log" "time" "github.com/xraph/forge" "github.com/xraph/forge/extensions/dashboard" ) func main() { app := forge.New( forge.WithAppName("my-app"), forge.WithAppVersion("1.0.0"), ) if err := app.RegisterExtension(dashboard.NewExtension( dashboard.WithTitle("My Dashboard"), dashboard.WithBasePath("/dashboard"), dashboard.WithRealtime(true), dashboard.WithRefreshInterval(30 * time.Second), dashboard.WithExport(true), dashboard.WithTheme("auto"), )); err != nil { log.Fatalf("failed to register dashboard: %v", err) } // Dashboard available at http://localhost:8080/dashboard if err := app.Run(); err != nil { log.Fatalf("application error: %v", err) } } ``` ## Programmatic Access Retrieve the dashboard extension from the DI container to access its subsystems: ```go ext, _ := forge.InjectType[*dashboard.Extension](app.Container()) // Data collection collector := ext.Collector() overview := collector.CollectOverview(ctx) health := collector.CollectHealth(ctx) metrics := collector.CollectMetrics(ctx) // Historical data history := ext.History() all := history.GetAll() // Contributor registry registry := ext.Registry() // Bridge (Go-JS function calls) bridge := ext.DashboardBridge() // SSE real-time broker broker := ext.SSEBroker() // Auth checker (when auth is enabled) checker := ext.AuthChecker() ``` ## HTTP Endpoints All routes are under the configured base path (default `/dashboard`): ### Pages (ForgeUI) | Method | Path | Description | |---|---|---| | GET | `/` | Dashboard overview | | GET | `/health` | Health status page | | GET | `/metrics` | Metrics page | | GET | `/services` | Services page | | GET | `/ext/:name/pages/*` | Contributor extension pages | | GET | `/ext/:name/widgets/:id` | Widget HTMX fragments | | GET | `/remote/:name/pages/*` | Remote contributor pages | | GET | `/remote/:name/widgets/:id` | Remote contributor widgets | ### Authentication (when `EnableAuth` is true) | Method | Path | Description | |---|---|---| | GET | `/auth/login` | Login page | | POST | `/auth/login` | Login form submission | | GET | `/auth/logout` | Logout page | | GET | `/auth/register` | Register page (if provider supplies it) | | POST | `/auth/register` | Register form submission | Auth page paths are configurable. The table above shows defaults. ### JSON API | Method | Path | Description | |---|---|---| | GET | `/api/overview` | Application overview | | GET | `/api/health` | Health status | | GET | `/api/metrics` | Current metrics | | GET | `/api/services` | Service list | | GET | `/api/service-detail?name=X` | Service detail | | GET | `/api/history` | Metric history | | GET | `/api/metrics-report` | Aggregated metrics report | | GET | `/api/search?q=X` | Federated search (if enabled) | | GET | `/api/sse/status` | SSE connection status | ### Export | Method | Path | Description | |---|---|---| | GET | `/export/json` | Full JSON snapshot | | GET | `/export/csv` | Metrics as CSV | | GET | `/export/prometheus` | Prometheus text format | ### Real-Time and Bridge | Method | Path | Description | |---|---|---| | GET | `/sse` | SSE event stream | | POST | `/bridge/call` | Bridge function call | | GET | `/bridge/stream/` | Bridge streaming (SSE) | ### Settings | Method | Path | Description | |---|---|---| | GET | `/settings` | Aggregated settings index | | GET | `/ext/:name/settings/:id` | Contributor settings form | | POST | `/ext/:name/settings/:id` | Submit settings form | ## Key Concepts - **Contributor System** -- extensions register pages, widgets, and settings via a manifest. Local contributors render gomponents; remote contributors serve HTML fragments over HTTP. - **ForgeUI Shell** -- layouts (root, dashboard, base, full, settings, auth), HTMX partial navigation, Alpine.js state management, and automatic sidebar construction from contributor manifests. - **Authentication** -- optional page access levels (public, protected, partial), auth page provider for login/register flows, auth-aware user menu in topbar, HTMX-aware redirects. Decoupled from any specific auth provider. - **Go-JS Bridge** -- call Go functions from the browser via Alpine.js `$go()` magic helpers. 8 built-in dashboard functions plus custom function registration. - **SSE Real-Time** -- server-sent events push metric, health, and contributor state updates to connected browsers. - **Federated Search** -- contributors implementing `SearchableContributor` are searched in parallel across the entire dashboard. - **Data Export** -- export metrics and health data in JSON, CSV, or Prometheus format. ## Detailed Pages Dashboard capabilities: shell, contributors, authentication, bridge, SSE, search, export, security. Full config reference with all options, YAML example, and validation rules. Complete public API: 15+ methods, error sentinels, and REST endpoints. Contributor system: interfaces, manifests, local and remote contributors. Go-JS bridge: built-in functions, custom registration, and JS client usage.