Spotlight

Spotlight is the in-app global search and quick-link system. It provides a search UI (typically triggered by keyboard shortcut) that indexes navigation targets, quick links, and other providers so users can jump to pages or run actions quickly.

Overview

Search backend: When MEILI_URL is set, Spotlight uses Meilisearch for full-text search. When it is not set, the Spotlight service runs without a search engine (no-op); quick links are still registered but search results will not include Meilisearch-backed content.
Quick links: Modules register links via app.QuickLinks().Add(...) using spotlight.NewQuickLink(trKey, link). These appear in Spotlight and are indexed (when Meilisearch is enabled) for search. The first argument is a translation key (e.g. NavigationLinks.Expenses or Expenses.List.New); the second is the URL (e.g. /finance/expenses or /finance/expenses/new).
Other providers: The framework and modules can register additional search providers (e.g. knowledge base, entities). Quick links are one built-in provider.

Environment Variables

Variable	Required	Description
`MEILI_URL`	No	Meilisearch instance URL (e.g. `http://localhost:7700`). If set, Spotlight is enabled and health-checked at startup.
`MEILI_API_KEY`	No	Meilisearch API key when the instance requires authentication. Leave empty for local dev without auth.

Defined in pkg/configuration and used in pkg/application when creating the Spotlight service and Meilisearch engine.

Registering Quick Links

Basic Quick Links (Public)

In your module’s Register:


import (
	"github.com/iota-uz/iota-sdk/pkg/application"
	"github.com/iota-uz/iota-sdk/pkg/spotlight"
)
 
func (m *Module) Register(app application.Application) error {
	// ... register services, controllers ...
 
	app.QuickLinks().Add(
		spotlight.NewQuickLink("NavigationLinks.Expenses", "/finance/expenses"),
		spotlight.NewQuickLink("Expenses.List.New", "/finance/expenses/new"),
	)
	return nil
}

First argument (trKey): Translation key for the link label. Use a key that exists in your module’s locale files (e.g. NavigationLinks.Expenses, Expenses.List.New) so the label is localized.
Second argument (link): Absolute path or URL for the quick link target.

Quick links are registered on the application’s QuickLinks provider; when Meilisearch is configured, they are indexed and searchable.

Quick Links with RBAC

Use QuickLinkBuilder to create quick links with access control. This ensures links are only visible to users with the appropriate permissions, roles, or user IDs.


import (
	"github.com/iota-uz/iota-sdk/pkg/spotlight"
)
 
func (m *Module) Register(app application.Application) error {
	app.QuickLinks().Add(
		// Require specific permissions
		spotlight.NewQuickLinkBuilder("NavigationLinks.AdminPanel", "/admin").
			WithPermissions("admin.panel.view").
			Build(),
 
		// Require specific roles
		spotlight.NewQuickLinkBuilder("NavigationLinks.Reports", "/reports").
			WithRoles("manager", "admin").
			Build(),
 
		// Restrict to specific users
		spotlight.NewQuickLinkBuilder("NavigationLinks.Private", "/private").
			WithUsers("user-42").
			Build(),
 
		// Owner-only visibility
		spotlight.NewQuickLinkBuilder("NavigationLinks.MyDashboard", "/my-dashboard").
			WithOwner("owner-id").
			Build(),
 
		// Explicitly public (equivalent to NewQuickLink)
		spotlight.NewQuickLinkBuilder("NavigationLinks.Help", "/help").
			Public().
			Build(),
	)
	return nil
}

Note: NewQuickLink(trKey, link) creates a public link for backward compatibility. Use NewQuickLinkBuilder when you need RBAC controls.

Quick Links with Search Keywords

Add keywords/aliases to quick links to improve searchability. Keywords are indexed and searchable but not displayed in the UI.


app.QuickLinks().Add(
	spotlight.NewQuickLinkBuilder("NavigationLinks.Expenses", "/finance/expenses").
		Public().
		WithKeywords("costs", "spending", "outflows", "money out").
		Build(),
)

Users can now search for “costs” or “spending” and find the Expenses link even if those words aren’t in the translation.

Combining RBAC and Keywords


app.QuickLinks().Add(
	spotlight.NewQuickLinkBuilder("NavigationLinks.FinancialReports", "/finance/reports").
		WithPermissions("finance.reports.view").
		WithKeywords("PnL", "profit and loss", "income statement").
		Build(),
)

API Summary

Basic API

app.QuickLinks() — returns the shared *spotlight.QuickLinks instance (same for all modules).
app.QuickLinks().Add(links ...*QuickLink) — appends one or more quick links.
spotlight.NewQuickLink(trKey, link string) — creates a public quick link; both arguments are strings (translation key and URL).

Builder API (RBAC and Keywords)

spotlight.NewQuickLinkBuilder(trKey, link string) — creates a builder with restricted visibility by default.
.WithPermissions(permissions ...string) — requires users to have any of the specified permissions.
.WithRoles(roles ...string) — requires users to have any of the specified roles.
.WithUsers(userIDs ...string) — restricts access to the specified user IDs.
.WithOwner(ownerID string) — restricts access to the owner with the given ID.
.WithAccess(policy AccessPolicy) — sets a custom access policy.
.Public() — makes the link visible to everyone.
.WithKeywords(keywords ...string) — adds searchable keywords/aliases.
.Build() — returns the configured *QuickLink.