admin-gui

name: admin-gui description: Documentation of the HTMX admin GUI including template rendering, session management, CRUD patterns, and the GUIHandler structure. license: MIT

Overview

The admin GUI is an HTMX-powered web interface at /gui/*. It provides a complete management dashboard for the Auth API platform. The main handler is internal/admin/gui_handler.go (4976 lines, the largest file in the project).

Architecture

GUIHandler (internal/admin/gui_handler.go)
  |-- AccountService   -> admin auth, sessions, 2FA, CSRF
  |-- DashboardService -> stats aggregation
  |-- Repository       -> data access (tenants, apps, users, etc.)
  |-- SettingsService  -> system settings management
  |-- EmailService     -> email template/server management
  |-- RBACService      -> role/permission management
  |-- PasskeyService   -> WebAuthn for admin accounts

Template Rendering (web/renderer.go)

Embedded filesystem: //go:embed templates in web/renderer.go

Template structure:

web/templates/
  layouts/     -> base layout files (*.tmpl)
  partials/    -> reusable fragments (*.tmpl) -- also served as standalone for HTMX
  pages/       -> full page templates (*.tmpl)

Parsing strategy:

• Full pages = layouts + partials + page file (rendered via c.HTML())
• HTMX fragments = partials rendered standalone (for dynamic swaps)

Template data struct (web.TemplateData):

type TemplateData struct {
    ActivePage    string      // Current page identifier for nav highlighting
    AdminUsername string      // From auth context
    AdminID       string      // From auth context
    CSRFToken     string      // From CSRF middleware
    FlashSuccess  string      // Flash messages
    FlashError    string
    Error         string      // Login-specific error
    Username      string      // Pre-filled username on login error
    Redirect      string      // Post-login redirect URL
    TempToken     string      // 2FA temp token
    TwoFAMethod   string      // "totp" or "email"
    Data          interface{} // Page-specific arbitrary data
}

Template functions available (web.defaultFuncMap):

• formatDate, formatDateTime, formatDateTimeFull -- date formatting
• timeAgo -- human-readable relative time
• upper, lower, title -- string transforms
• safeHTML, safeURL -- mark content as safe (no escaping)
• eq -- string equality
• deref -- dereference *time.Time (nil-safe)
• isExpired -- check if time is in the past
• add, sub -- arithmetic for pagination

Authentication Flow

Standard Login

GET  /gui/login          -> LoginPage (render login form)
POST /gui/login          -> LoginSubmit [rate limited: 5/min]
  -> accountService.Authenticate(username, password)
  -> If 2FA: CreatePending2FASession -> redirect to /gui/2fa-verify
  -> If no 2FA: CreateSession -> set cookie -> redirect to /gui/

2FA Verification

GET  /gui/2fa-verify     -> TwoFAVerifyPage (render 2FA form)
POST /gui/2fa-verify     -> TwoFAVerifySubmit
  -> Validate TOTP code, email code, or recovery code
  -> PromotePendingSession -> set cookie -> redirect

Passkey Login (passwordless)

POST /gui/passkey-login/begin  -> PasskeyLoginBegin (returns JSON challenge)
POST /gui/passkey-login/finish -> PasskeyLoginFinish (validates assertion)
  -> CreateSession -> set cookie -> return JSON success

Magic Link Login (passwordless)

POST /gui/magic-link-login         -> MagicLinkLoginRequest
  -> Generate token in Redis (10 min) -> send email
GET  /gui/magic-link-login/verify  -> MagicLinkLoginVerify
  -> Validate token -> CreateSession -> set cookie -> redirect

Session Cookie

• Name: admin_session (constant: web.AdminSessionCookie)
• Path: /gui
• Flags: HttpOnly, SameSite=Strict, Secure (auto-detected)
• Set via web.SetSessionCookie(), cleared via web.ClearSessionCookie()

HTMX CRUD Pattern

Every entity domain follows a consistent pattern. Example for tenants:

GET  /gui/tenants              -> TenantPage (full page with layout)
GET  /gui/tenants/list         -> TenantList (HTMX partial, paginated table)
GET  /gui/tenants/new          -> TenantCreateForm (HTMX partial, form)
POST /gui/tenants              -> TenantCreate (creates, returns alert + triggers list refresh)
GET  /gui/tenants/form-cancel  -> TenantFormCancel (empty response, cancels form)
GET  /gui/tenants/:id/edit     -> TenantEditForm (HTMX partial, pre-filled form)
PUT  /gui/tenants/:id          -> TenantUpdate (updates, returns alert + triggers list refresh)
GET  /gui/tenants/:id/delete   -> TenantDeleteConfirm (HTMX partial, confirmation modal)
DELETE /gui/tenants/:id        -> TenantDelete (deletes, triggers list refresh)

HTMX signals: Methods set HX-Trigger headers to signal events:

• Entity events: tenantDeleted, roleDeleted, sessionListRefresh, socialAccountUnlinked, permissionsSaved, etc.
• These trigger list refreshes and modal closes on the client side

Error handling: Errors are returned as Bootstrap alert HTML snippets via c.String() or c.HTML().

GUIHandler Method Groups

CSRF Protection

Middleware: internal/middleware/csrf.go

• GET requests: generate CSRF token, set in context as csrf_token
• POST/PUT/DELETE: read from X-CSRF-Token header (HTMX) or _csrf form field
• Token validated against session via sessionValidator.ValidateCSRFToken()

HTMX sends CSRF token via header: templates set hx-headers='{"X-CSRF-Token": "{{.CSRFToken}}"}'

Rate Limiting (GUI-specific)

GUI rate limiting sets web.RateLimitErrorKey in context (doesn't abort), letting the handler render the error in the form.

Static Assets

Embedded via web/static/embed.go using //go:embed. Served at /gui/static/*.

Key Dependencies

• admin.AccountService implements web.SessionValidator (for GUI auth + CSRF middleware)
• admin.Repository implements web.ApiKeyValidator (for admin/app API key middleware)
• Both interfaces defined in web/context_keys.go to avoid import cycles

When To Use This Skill

Load this skill when working on the admin web interface, HTMX templates, GUI authentication, or any /gui/* route.