Skip to main content

Lookout

Lookout is Kilimanjaro's dashboarding extension. Lookout composes chart visualisations (line, area, bar, bubble, scatter, pie, donut, polar, radar, table, KPI tile) sourced from project collections or saved queries into dashboards that operators and the boardroom both trust. Dashboards are first-class records with their own permission policy, sharing and embedding controls, branded theming, and audit-attributed access history.

Lookout is built on the same extension framework available to every extension class — Anchor and Circuit extensions ship against the same contract.

1. What Lookout covers​

SurfaceRole
Chart compositionConsole authoring UI for binding a chart to a data source (collection or saved query) with field-to-axis mapping, aggregation, and styling controls
Dashboard layoutDrag-and-resize grid for arranging charts, KPI tiles, and text blocks into a dashboard
Theme tokensPer-project theme overrides — colour palettes, typography, chart spacing, brand-mark insertion
Sharing + embeddingPer-dashboard share links (Console-authenticated or signed-URL public), iframe-embed for external websites with origin allowlisting
Permission policyPer-dashboard roles[] and JSON-policy expressions binding who can see, who can edit, who can share
Refresh + cachingLive, polled, or scheduled refresh per chart; cached payloads with TTL; cache-bust on source data mutation
Audit attributionEvery dashboard render emits a lookout.dashboard.viewed audit event with viewer identity and which dashboard

Lookout is a full-surface extension: Console UI + runtime API for embed-mode + background-logic functions for scheduled cache refresh.

2. Composing a chart​

The canonical workflow:

  1. Bind a data source. A collection or a saved query — both are first-class options. Saved queries enable complex aggregations (joins across collections, derived fields, filtered subsets) that a raw collection binding cannot express directly.
  2. Choose a chart type. The platform suggests reasonable defaults based on the data shape (numeric series → line / bar; categorical with magnitude → pie / donut; tabular → table / KPI tile).
  3. Map fields to axes / dimensions. X-axis, Y-axis, series-grouping field, KPI value field, etc., depending on chart type.
  4. Aggregate if needed. sum, avg, min, max, count, count-distinct, percentile(n), or none for raw-row charts.
  5. Style. Colour palette (from the project theme), label formatting, legend placement, axis bounds, tooltip behaviour.
  6. Save. A chart is its own record — re-usable across dashboards.

3. Dashboards​

A dashboard composes chart records into a layout. Dashboards carry:

  • Layout — grid placement of each chart, KPI tile, and text block.
  • Title + description — what the dashboard is for, surfaced in the Console list and in shared views.
  • Permission policy — see §5.
  • Sharing configuration — which surfaces the dashboard is visible on (Console only, signed-URL public, embed-allowed origins).
  • Refresh policy — per-chart or dashboard-level default (live / polled-every-N-seconds / scheduled-at-cron).

4. Sharing and embedding​

ModeAuthenticationWhen to use
Console-internalStandard platform session; the viewer must hold one of the dashboard's authorised rolesInternal operator dashboards
Signed-URL publicA signed URL with embedded permission claims; valid for a configurable TTL; revocableRead-only sharing with external stakeholders without provisioning them platform identities
Iframe embedOrigin-allowlist binding on the dashboard; the embedding page must be served from an allowed origin; same-origin authentication propagated via postMessageEmbedding into a customer-facing application

All three surfaces emit the same lookout.dashboard.viewed audit event with viewer identity and dashboard ID — signed-URL views carry the URL-issuer as the actor identity for forensic attribution.

5. Per-dashboard permission policy​

Dashboard access is governed by the same two-layer pattern the platform applies everywhere: a role floor + a JSON-policy expression.

FieldEffect
viewerRoles[]Closed enumeration of platform roles permitted to view (PROJECT_VIEWER, PROJECT_ANALYST, etc.) — the role-level floor
editorRoles[]Roles permitted to edit the dashboard's composition (typically PROJECT_AUTHOR+)
sharerRoles[]Roles permitted to create signed-URL or iframe-embed shares
viewPolicyAn optional JSON-policy expression that further narrows view access (e.g., row-level data filtering applied to underlying chart sources)

The policy applies at chart-rendering time: even after the role check passes, the JSON policy is evaluated for each chart's underlying data, and rows that fail the policy are silently filtered out of the rendered visualisation. A dashboard rendered for two viewers with different policy outcomes will show different data with no UI seam.

6. Refresh and caching​

ModeBehaviour
LiveEvery dashboard load queries the source data; no cache. Best for low-traffic dashboards where freshness matters.
PolledConfigurable interval; the platform caches the last query result; viewers see the cached version up to the next poll.
ScheduledCron expression; the cache refreshes on the schedule; viewers see whichever version was rendered at the most recent run.

The cache invalidates automatically on document.updated events touching the chart's source collection — so even a polled or scheduled chart picks up newly-written records quickly without needing to wait for the next refresh tick.

7. Permissions Lookout requests at enable​

PermissionWhy
documents/read/*Reading source records to render charts
collections/read/*Reading collection schemas for field-to-axis binding
users/read/*Resolving viewer identity for audit attribution
functions/invoke/lookout:refreshScheduled cache-refresh job
webhooks/subscribe/*Cache invalidation on document.updated events

The grant binds at enable time; PROJECT_ADMIN reviews each line before authorising. Collection-list qualifiers tighten through the Lookout Console UI per dashboard.

8. Events​

EventFired when
lookout.dashboard.createdA dashboard is saved
lookout.dashboard.viewedAny dashboard render — Console, signed-URL, or iframe-embed
lookout.dashboard.sharedA share link or embed binding is created

9. See also​