Skip to main content

Dashboard

HappyView ships with a web dashboard that provides a visual interface for everything the admin API offers. It runs as a separate Next.js application alongside the Rust backend and authenticates via atproto OAuth.

On a fresh deployment with no users in the database, the first person to log in to the dashboard is automatically bootstrapped as the super user with all permissions — so log in with the handle you want to own the instance first.

Lexicons​

Navigate to Lexicons to see all uploaded lexicons. Each entry shows the NSID, type (record, query, procedure), and whether a Lua script is attached.

Adding a lexicon​

Click Add Lexicon and choose Local or Network.

Local lexicons are defined by you. The editor shows two side-by-side panels (stacked on mobile):

  • Lexicon JSON (left): define your lexicon schema
  • Lua Script (right): write the handler for query/procedure types

The Lua panel only appears when the lexicon's defs.main.type is query or procedure. For record-type lexicons, only the JSON panel is shown.

HappyView generates a default Lua script when you first set the type to query or procedure. The template updates when the type changes, but once you edit the script your changes are preserved.

Toggle Enable backfill to index historical records when uploading a record-type lexicon.

Network lexicons are fetched from the atproto network. Enter an NSID (e.g. xyz.statusphere.status) and HappyView resolves the schema automatically. If found, the lexicon JSON is displayed in a read-only editor. Click Add to track it. Network lexicons are kept up to date via the Jetstream subscription. See Lexicons - Network lexicons for how resolution works.

JSON editor​

The JSON editor provides real-time validation against the atproto Lexicon v1 schema:

  • Validation for Lexicon format
  • Auto-complete for definition types (record, query, procedure, subscription), property types (string, integer, boolean, ref, union, blob, cid-link, etc.), and schema structure (defs, main, properties, required)
  • Enforces the required top-level shape: lexicon, id, and defs.main

Lua editor​

The Lua editor provides context-aware code completions, including suggestions for the Record, db, input, and params APIs as well as Lua keywords, builtins, and standard library functions. It also has snippets for if, for, function, etc.

See Lua Scripting for the full runtime reference and examples.

Records​

Navigate to Records to browse all indexed atproto records. Records are grouped by collection and searchable. Each record shows its AT URI, author DID, and the raw record JSON.

Backfill​

Navigate to Backfill to view and manage backfill jobs. You can start a new backfill for any record-type lexicon to import historical records from the network. The page shows job status, progress (repos processed / total), and record counts. See Backfill for how the process works.

Users​

Navigate to Users to manage who can access the admin API and dashboard. You can add users by DID, assign permissions individually or via a template (viewer, operator, manager, full_access), and remove users. The super user is highlighted and has all permissions by default. See Permissions for what each permission grants.

Events​

Navigate to Events to view the audit log of admin actions. Events include user creation, lexicon uploads, permission changes, backfill starts, and more. Each entry shows the event type, severity, actor, subject, and timestamp. Events are retained for the number of days configured by EVENT_LOG_RETENTION_DAYS (default 30).

Settings​

The Settings section contains several sub-pages:

General​

Configure instance-level settings: application name, logo, terms of service URL, and privacy policy URL. These values appear on OAuth authorization screens and can also be set via environment variables — dashboard values take precedence.

API Clients​

Register and manage third-party API clients. Each client gets an hvc_… client key and hvs_… client secret. You can configure the client type (confidential or public), allowed origins, scopes, and per-client rate limits. See Authentication — API client identification for how clients are used.

API Keys​

Create and revoke admin API keys for automation. Each key is scoped to specific permissions and tied to the creating user. See API Keys for details.

Users​

An alternative path to the top-level Users page for managing user accounts and permissions.

Plugins​

Manage installed plugins and configure plugin secrets. Plugins extend HappyView with additional functionality. Plugin secrets are encrypted at rest when TOKEN_ENCRYPTION_KEY is configured. See Plugins for details.

Labelers​

Configure labeler subscriptions for content labeling. See Labelers for details.

Environment Variables​

View the current values of all environment variables that affect HappyView's behavior. This is a read-only view — values are set via your deployment environment, not the dashboard.

Accounts​

Manage connected atproto accounts used by the instance.

Next steps​

  • Lexicons — how lexicons drive HappyView's indexing and routing
  • Lua Scripting — write custom query and procedure logic
  • Permissions — manage user access to admin features
  • Configuration — full list of environment variables