nexu-io/open-design / plugins/_official/examples/live-dashboard
live-dashboard
VerifiedNotion-style team dashboard rendered as a Live Artifact. A single-page, self-contained HTML dashboard with KPIs, a 7-day sparkline, a real-time activity feed and a linked-database task table — wired to Notion via the Composio connector catalog. Refreshes on demand and when the artifact is opened. Falls back to seeded mock data when no connector is bound, so it works offline / in screenshots / in the picker preview.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
| assets/template.html | other | 29.9 KB |
| example.html | other | 36.5 KB |
| open-design.json | config | 12.0 KB |
| references/checklist.md | markdown | 4.0 KB |
| references/components.md | markdown | 6.5 KB |
| references/connectors.md | markdown | 7.1 KB |
| references/layouts.md | markdown | 3.2 KB |
references/connectors.md
View on GitHub# Connectors
`live-dashboard` is a **Live Artifact**. The values it shows are not
hard-coded — they are polled from a connector at runtime. The OD daemon
(0.4.0+) ships a Composio connector catalog and a `connectors.json`
contract that artifacts emit alongside `index.html`.
When `inputs.connector === mock` (or the daemon cannot resolve the
configured connector), the artifact falls back to seeded sample data.
This keeps screenshots, the picker preview, and offline use working.
> **Status — relationship to `design-templates/live-artifact/`.**
>
> The canonical, currently-shipping live-artifact contract lives in
> [`design-templates/live-artifact/SKILL.md`](../../live-artifact/SKILL.md): it is
> *file-shaped* (`artifact.json` + `template.html` + `data.json` +
> `provenance.json`) and *CLI-shaped* on the agent side (the agent calls
> `"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts {create,update}` and
> `tools connectors {list,execute}` rather than HTTP). The renderer is
> scalar-only `html_template_v1` (`apps/daemon/src/live-artifacts/render.ts`).
>
> `live-dashboard` is a **complementary** browser-runtime variant: the
> artifact is rendered as a single self-contained HTML page, and the
> live behaviors (refresh-on-open, manual Refresh, auto-refresh, stale
> pill) run in-page rather than at template-render time. Polling
> therefore needs an HTTP shape, which is what the rest of this file
> describes (`POST /api/od/connectors/poll`).
>
> Treat the HTTP shape below as a **forward-looking proposal** that
> sits alongside the file/CLI contract: the daemon does not yet expose
> `POST /api/od/connectors/poll` (`apps/daemon/src/server.ts` /
> `apps/daemon/src/live-artifacts/`), so out-of-the-box the artifact
> renders against the seeded sample data and the Refresh button only
> tweens the fixture. When the daemon-team route lands, only
> `seedNextChange()` in the template needs to be replaced with the
> `poll()` helper documented here — the `connectors.json` shape is
> already a usable declarative source-of-truth that downstream tooling
> (the live-artifact CLI, MCP wrappers, audit logs) can read today.
---
## `connectors.json` schema
Emit one `connectors.json` at the project root next to `index.html`:
```json
{
"schema": "od.connector/1",
"primary": "notion",
"freshness": {
"auto_refresh_seconds": 30,
"warn_after_seconds": 90,
"fail_after_seconds": 600
},
"bindings": {
"notion": {
"provider": "composio.notion",
"auth_ref": "media-config.json#notion.token",
"reads": [
{
"id": "tasks_active",
"endpoint": "databases.{id}.query",
"params": { "id": "${notion.tasks_db_id}",
"filter": { "property": "Status", "status": { "does_not_equal": "Done" } },
"sorts": [{ "property": "Updated", "direction": "descending" }] },
"shape": "task[]"
},
{
"id": "kpi_total",
"endpoint": "databases.{id}.query",
"params": { "id": "${notion.tasks_db_id}", "page_size": 1 },
"extract": "$.metadata.total_count",
"shape": "integer"
},
{
"id": "activity_recent",
"endpoint": "search",
"params": { "filter": { "property": "object", "value": "page" },
"sort": { "direction": "descending", "timestamp": "last_edited_time" },
"page_size": 8 },
"shape": "activity[]"
}
],
"events": [
{ "id": "task_changed", "type": "page.updated", "selector": "$.tasks_db_id" }
]
}
}
}
```
The shape is intentionally close to Notion's REST API — the daemon's
connector adapter rewrites `endpoint` and `params` into the live
provider call. Other connectors (Linear, Stripe, Posthog) follow the
same shape with provider-specific `endpoint` strings.
---
## Resolution order (what the daemon does)
1. Read `connectors.json` from the artifact dir.
2. Look up `bindings[primary].provider` in the Composio catalog.
3. Resolve `auth_ref` against the daemon-owned media configuration. The narrow
`OD_MEDIA_CONFIG_DIR` override applies to `media-config.json` only;
otherwise the daemon must derive the file from its already-resolved
`RUNTIME_DATA_DIR`. Do not infer a path from the project cwd or restate one
here. Before changing this lookup, read root `AGENTS.md` → **Daemon data
directory contract** and
[`apps/daemon/src/media/config.ts`](../../../../../apps/daemon/src/media/config.ts).
The artifact never opens any of these paths itself — it always goes
through the daemon poll endpoint, and the daemon enforces the
correct lookup order. **Never** read tokens from the artifact.
4. For each `reads[].endpoint`, the daemon constructs the live HTTP
request with the resolved auth and substitutes `${...}` placeholders
from the resolved `media-config.json#<provider>.*` values.
5. Cache responses for `freshness.auto_refresh_seconds`. The
`Refresh` button issues an explicit poll that bypasses the cache.
---
## Wiring inside `index.html`
The artifact does **not** call Composio directly. It calls the OD
daemon's local proxy:
```js
async function poll(readId) {
const res = await fetch(`/api/od/connectors/poll`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ project: "<project_id>", read: readId })
});
if (!res.ok) throw new Error(`poll ${readId} failed: ${res.status}`);
return res.json();
}
```
`<project_id>` is injected by the daemon at render time via a
`<meta name="od:project" content="...">` tag. The artifact reads it
once on mount.
---
## Fallback behavior
- On `fetch` error: keep the previously-rendered values, swap the
live-pill to amber `Stale · <ago>`, write a small grey hint into the
footer (`Source: Notion · last good poll 4 min ago`).
- On `inputs.connector === mock`: skip `poll()` entirely, use the
`seedMock()` function in `index.html`. The live-pill displays
`Sample data` in grey with no dot animation.
- On 401/403: surface a one-time toast `Reconnect Notion in Settings →
Connectors` and stop further polls until the next manual Refresh.
---
## Provider-specific cheat sheet
| Connector | `provider` | Shape of one row | Typical KPI |
|--- |--- |--- |--- |
| Notion | `composio.notion` | `task = {title, status, assignee, due, prio, updated}` | total tasks · done this week · members · review |
| Linear | `composio.linear` | `issue = {title, state, assignee, priority, updated}` | backlog · in progress · blocked · cycle progress |
| Stripe | `composio.stripe` | `event = {type, amount, customer, created}` | MRR · churn · new subs · refunds |
| Posthog | `composio.posthog` | `event = {name, distinct_id, $current_url, ts}` | DAU · signups · feature adoption · errors |
Do not invent per-provider shapes. If the user wants something not in
this table, fall back to `mock` and surface a footer hint asking the
user to extend the connector catalog.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |