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
| Surface | Role |
|---|---|
| Chart composition | Console authoring UI for binding a chart to a data source (collection or saved query) with field-to-axis mapping, aggregation, and styling controls |
| Dashboard layout | Drag-and-resize grid for arranging charts, KPI tiles, and text blocks into a dashboard |
| Theme tokens | Per-project theme overrides — colour palettes, typography, chart spacing, brand-mark insertion |
| Sharing + embedding | Per-dashboard share links (Console-authenticated or signed-URL public), iframe-embed for external websites with origin allowlisting |
| Permission policy | Per-dashboard roles[] and JSON-policy expressions binding who can see, who can edit, who can share |
| Refresh + caching | Live, polled, or scheduled refresh per chart; cached payloads with TTL; cache-bust on source data mutation |
| Audit attribution | Every 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:
- 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.
- 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).
- Map fields to axes / dimensions. X-axis, Y-axis, series-grouping field, KPI value field, etc., depending on chart type.
- Aggregate if needed.
sum,avg,min,max,count,count-distinct,percentile(n), ornonefor raw-row charts. - Style. Colour palette (from the project theme), label formatting, legend placement, axis bounds, tooltip behaviour.
- 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
| Mode | Authentication | When to use |
|---|---|---|
| Console-internal | Standard platform session; the viewer must hold one of the dashboard's authorised roles | Internal operator dashboards |
| Signed-URL public | A signed URL with embedded permission claims; valid for a configurable TTL; revocable | Read-only sharing with external stakeholders without provisioning them platform identities |
| Iframe embed | Origin-allowlist binding on the dashboard; the embedding page must be served from an allowed origin; same-origin authentication propagated via postMessage | Embedding 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.
| Field | Effect |
|---|---|
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 |
viewPolicy | An 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
| Mode | Behaviour |
|---|---|
| Live | Every dashboard load queries the source data; no cache. Best for low-traffic dashboards where freshness matters. |
| Polled | Configurable interval; the platform caches the last query result; viewers see the cached version up to the next poll. |
| Scheduled | Cron 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
| Permission | Why |
|---|---|
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:refresh | Scheduled 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
| Event | Fired when |
|---|---|
lookout.dashboard.created | A dashboard is saved |
lookout.dashboard.viewed | Any dashboard render — Console, signed-URL, or iframe-embed |
lookout.dashboard.shared | A share link or embed binding is created |
9. See also
- Extensions API reference — the framework contract Lookout installs against.
- API → Data — the source surface Lookout queries against.
- API → Control — the JSON-policy layer that narrows chart-data visibility.
- API → Security — audit-log family for dashboard access.
- Paperless — visualise Paperless capture and workflow records.
- Context — chart against semantic-query result sets.