Ginlix AI Langalpha Langalpha

Interactive Dashboard

Build interactive web dashboards inside the sandbox and expose them to the user via GetPreviewUrl. Use this skill for any request involving dashboards, trackers, monitors, live visualizations, or interactive web apps.

When to Use

Use this skill for a live, served web app — one that needs a running server, not a single file:

• User asks for a dashboard, tracker, or monitor that refreshes live data (polling, auto-update)
• The app needs server-side logic — filtering/screening over a large dataset, on-demand fetches, computed endpoints
• Multi-page / routed apps, or anything that needs React-level component interactivity
• The dataset is too large to embed in a single HTML file
• User explicitly says "preview", "web view", "web app", or wants it running at a URL

Do NOT use if:

• User wants a self-contained HTML report — even an interactive one (sortable tables, tabs, hover/zoom charts) over a data snapshot. That's .agents/skills/html-report/SKILL.md: one file in results/, keepable, printable, PDF-exportable, share-linkable. Interactivity by itself does not require a dashboard.
• User wants a static chart image → matplotlib/plotly savefig.
• User wants an in-chat figure → inline-widget (ShowWidget).

Dashboard vs. HTML Report

Both can be interactive, so the divide is live served app vs. self-contained snapshot file, not static vs. interactive:

Architecture

Choose the tier based on complexity:

Decision rule: Start with Simple. Escalate to FastAPI + HTML when user needs live data refresh or server-side logic. Escalate to Complex only when user needs React-level component interactivity, client-side routing, or a multi-page SPA.

Port convention: Use port 8050 (default). Range 8050-8059 for dashboards.

CSP / Iframe Safety

The preview iframe enforces Content Security Policy (CSP). Certain patterns are silently blocked — no error banner, just dead UI elements. Always use the safe alternatives:

Quick self-check — run before serving to catch violations:

import subprocess
result = subprocess.run(
    ["grep", "-rnE", r'on(click|input|change|focus|blur|submit|load|error|mouse|key)\s*=',
     "work/dashboard/"],
    capture_output=True, text=True
)
if result.stdout.strip():
    raise RuntimeError(f"CSP-unsafe inline handlers found:\n{result.stdout}")

Template literal hygiene — when building HTML strings in JS template literals, CSS semicolons inside ${} expressions cause silent parse failures:

// BAD — semicolon inside ${} terminates the expression early
const el = `<div style="color:${positive ? 'green' : 'red'; font-weight:600}">`;

// GOOD — close the expression first, then continue the attribute string
const el = `<div style="color:${positive ? 'green' : 'red'};font-weight:600">`;

Rule: never put a CSS semicolon inside ${} — always close } before the semicolon.

How Preview Serving Works

GetPreviewUrl is a platform-level tool available only to the main agent runtime. It is NOT a Python function — do not import it or call it from execute_code. The agent invokes it as a tool call.

When you call GetPreviewUrl(port, command, title):

1. The command is persisted to the database automatically
2. The platform starts the command in a dedicated sandbox session for that port
3. It polls until the port is listening, then generates a signed URL
4. If the port is already reachable, the command start is skipped entirely

Sub-agent fallback: Sub-agents cannot call GetPreviewUrl. Instead, build the dashboard files, start the server for verification, then return the serve details so the orchestrating agent can call GetPreviewUrl.

All tiers — use the Bash tool with run_in_background=true to start the server:

# Simple tier — Bash tool with run_in_background=true
cd work/<task> && python -m http.server 8050 --bind 0.0.0.0

# Docker tiers — Bash tool with run_in_background=true
cd work/<task> && bash start.sh

Then verify it's up in a separate (foreground) Bash call:

for i in $(seq 1 15); do curl -sf http://127.0.0.1:8050/ > /dev/null && echo "Server ready" && exit 0 || sleep 1; done; echo "FAIL"; exit 1

Then return all three fields to the orchestrating agent (it needs the command for DB persistence / restart recovery):

port: 8050
command: "cd work/<task> && python -m http.server 8050 --bind 0.0.0.0"  # or "bash work/<task>/start.sh"
title: "AAPL Stock Dashboard"

The orchestrating agent calls GetPreviewUrl(port=8050, command="...", title="...") which persists the command.

On workspace restart (user closes and reopens later):

• The sandbox filesystem persists (files, installed packages, Docker image cache all survive)
• Only processes die — the platform looks up the saved command and re-executes it
• The preview URL auto-recovers

Implication: Write commands that are idempotent — they must work whether run for the first time or re-run after a restart. The platform handles the rest. Docker image cache survives restart so rebuilds are fast (~2-5s with warm cache).

Sandbox Capabilities

All pre-installed in the Daytona sandbox snapshot — no pip install or apt-get needed:

• Python 3.12 + pandas, numpy, plotly, matplotlib, requests, httpx, yfinance
• FastAPI + uvicorn (available via fastmcp transitive dependency)
• Node.js 24 + npm (host sandbox) / Node.js 20 (Docker apt install nodejs) — scaffold Vite/React projects with npm create vite@latest
• Docker Engine — for complex tier containerized dashboards (backend + frontend in one image)
• Playwright + Chromium — available for verification testing

Workflow

Step 1: Clarify Scope

Before writing any code:

• What data? (specific tickers, sector, portfolio, screener results)
• What visualizations? (price chart, comparison table, heatmap, etc.)
• Static snapshot or live refresh?
• How complex? (determines simple vs complex tier)

Step 2: Fetch Data

Use YF MCP servers as the default financial data source (no API keys needed):

from tools.yf_price import get_stock_history, get_multiple_stocks_history
from tools.yf_fundamentals import get_company_info, compare_valuations
from tools.yf_analysis import get_analyst_price_targets, get_news
from tools.yf_market import get_sector_info, screen_stocks

Always fetch and validate data before writing any HTML/React code. Check for empty responses.

Step 3: Process Data

Use pandas to clean, aggregate, and compute derived metrics:

import pandas as pd
import json

# Fetch
history = get_stock_history("AAPL", period="1y", interval="1d")
info = get_company_info("AAPL")

# Process
df = pd.DataFrame(history)
df['change_pct'] = df['close'].pct_change() * 100

# Prepare for frontend
chart_data = json.dumps({
    "dates": df['date'].tolist(),
    "prices": df['close'].tolist(),
    "volumes": df['volume'].tolist(),
})

Step 4: Build Dashboard

Simple tier — write a self-contained HTML file:

html = f"""<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AAPL Dashboard</title>
    <script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
    <style>
        /* See references/ui-components.md for dark theme CSS */
    </style>
</head>
<body>
    <script>const DATA = {chart_data};</script>
    <script>
        /* Chart rendering code */
    </script>
</body>
</html>"""

with open("work/dashboard/index.html", "w") as f:
    f.write(html)

FastAPI + HTML tier — write a FastAPI server with API routes + StaticFiles mount, and a single static/index.html with fetch() polling (see FastAPI + HTML Tier section below).

Complex tier — scaffold a FastAPI + Vite/React project (see Complex Tier section below).

Step 5: Verify Before Serving

Tier 1 — Syntax check (required, < 1 second)

Extract <script> blocks from the HTML and check with node --check:

import re, subprocess, tempfile, os

with open("work/dashboard/index.html") as f:
    html = f.read()

scripts = re.findall(r'<script(?![^>]*src)[^>]*>(.*?)</script>', html, re.DOTALL)
for i, src in enumerate(scripts):
    with tempfile.NamedTemporaryFile(suffix=".js", mode="w", delete=False) as tmp:
        tmp.write(src)
        tmp_path = tmp.name
    result = subprocess.run(["node", "--check", tmp_path], capture_output=True, text=True)
    os.unlink(tmp_path)
    if result.returncode != 0:
        raise RuntimeError(f"JS syntax error in script block {i+1}:\n{result.stderr}")
print("Syntax check passed")

Also run the CSP self-check grep from the CSP section above.

Tier 2 — Browser verification (recommended for interactive dashboards)

Run when the dashboard has buttons, filters, or tabs. Skip for static data displays.

After GetPreviewUrl starts the server, run a Playwright check to catch runtime errors:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    js_errors = []
    page.on("pageerror", lambda exc: js_errors.append(str(exc)))
    page.goto("http://127.0.0.1:8050/", wait_until="networkidle", timeout=20000)
    assert not js_errors, f"JS runtime errors: {js_errors}"
    assert len(page.locator("body").inner_text().strip()) > 20, "Page appears blank"
    page.screenshot(path="work/dashboard/verify-screenshot.png", full_page=True)
    browser.close()
print("Browser verification passed")

See references/verification.md for extended templates with button-click testing and API response validation.

Step 6: Serve & Expose

# Simple tier
GetPreviewUrl(port=8050, command="cd work/dashboard && python -m http.server 8050 --bind 0.0.0.0", title="AAPL Dashboard")

# FastAPI + HTML tier / Complex tier
GetPreviewUrl(port=8050, command="bash work/dashboard/start.sh", title="Stock Dashboard")

Local verification before GetPreviewUrl — if you need the server running for Playwright verification, use the Bash tool with run_in_background=true (see sub-agent fallback above for the pattern). Do NOT use subprocess.Popen from execute_code — the process becomes a zombie when the tool-call shell exits.

Step 7: Iterate

After the user sees the preview, adjust layout, data, or charts based on feedback.

Data Integration — YF MCP Servers

Default data sources for common dashboard needs:

Yahoo Finance Field Conventions

Many fields are already in display units — do NOT multiply by 100:

get_predefined_screen Response Structure

Quotes are nested — not at the top level:

result = get_predefined_screen("day_gainers")
quotes = result["data"]["quotes"]  # nested at result["data"]["quotes"], NOT result["quotes"]
# Each quote: symbol, regularMarketPrice, regularMarketChangePercent, marketCap, ...

Direct yfinance Usage (Docker / without MCP)

Inside Docker containers, MCP tool modules are unavailable. Use yfinance directly:

import yfinance as yf

# Stock screener (yfinance 1.2.0+)
result = yf.screen("day_gainers", count=5)
quotes = result.get("quotes", [])

# Stock data
ticker = yf.Ticker("AAPL")
info = ticker.info
hist = ticker.history(period="1y")

UI Design Rules

Read .agents/skills/ui-design/SKILL.md for design quality (typography, color, avoiding generic AI aesthetics).

Dark Theme (Default)

Match the Ginlix platform aesthetic:

Layout

• KPI cards in a row at top (price, change, volume, market cap)
• Charts in a responsive 2-column grid below
• Tables full-width at bottom
• No horizontal scroll — everything fits the iframe width
• Use CSS Grid with auto-fit and minmax() for responsive columns

Typography

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

Financial Data Formatting

• Prices: 2 decimal places with $ prefix ($182.52)
• Percentages: 2 decimal places with % suffix, color-coded green/red (+2.34% / -1.56%)
• Large numbers: Abbreviated with suffix ($2.87T, $142.5B, $3.2M)
• Volumes: Comma-separated (12,345,678) or abbreviated (12.3M)
• Dates: MMM DD, YYYY format (Mar 15, 2026)

See references/ui-components.md for complete CSS and component code.

FastAPI + HTML Tier — Project Structure

For live-data dashboards without React. FastAPI serves API endpoints and static HTML directly — no npm, no build step. Use the copy-ready template files with .fastapi-html suffix in references/:

work/<task>/
├── Dockerfile           # cp references/Dockerfile.fastapi-html Dockerfile
├── start.sh             # cp references/start.sh start.sh
├── server/
│   ├── main.py          # cp references/server-main.fastapi-html.py server/main.py
│   └── requirements.txt # cp references/requirements.txt server/requirements.txt
└── static/
    └── index.html       # Single HTML file with fetch() polling

Setup Workflow

1. Copy template files — all four cp commands above, then add your API routes to server/main.py
2. Add your Python deps to server/requirements.txt (append pandas, yfinance, etc.)
3. Write static/index.html with fetch() calls to your API routes for live data
4. Serve: GetPreviewUrl(port=8050, command="bash work/<task>/start.sh", title="Dashboard")

Template Files

Dockerfile (references/Dockerfile.fastapi-html) — Python 3.12-slim only (no Node/npm). Uses uv pip install for fast deps.

server/main.py (references/server-main.fastapi-html.py) — FastAPI skeleton with CORS, HEAD /, /healthz, and StaticFiles mount for static/ directory. StaticFiles is the last mount (catches all unmatched routes).

start.sh — same references/start.sh template (works unchanged for all Docker tiers).

Key Differences from Complex Tier

• No frontend/ directory — HTML lives in static/
• No npm/Node — Dockerfile uses python:3.12-slim only
• StaticFiles mount — serves static/ directory with html=True (auto-serves index.html)
• fetch() for live data — HTML uses setInterval(() => fetch('/api/data').then(...), 30000) for auto-refresh
• No SPA routing — single index.html, no client-side router needed

Complex Tier — Project Structure

When using FastAPI + Vite/React, scaffold this structure using the copy-ready template files in references/:

work/<task>/
├── Dockerfile           # Copy from references/Dockerfile
├── start.sh             # Copy from references/start.sh
├── server/
│   ├── main.py          # Copy from references/server-main.py, add your API routes
│   ├── requirements.txt # Copy from references/requirements.txt, add your deps
│   ├── routes/          # API route modules (stocks.py, sectors.py)
│   └── models.py        # Pydantic response models
├── frontend/
│   ├── package.json     # Vite + React + chart libraries
│   ├── vite.config.js   # Copy from references/vite.config.js
│   ├── index.html
│   └── src/
│       ├── App.jsx      # Main app with routing/tabs
│       ├── components/  # Chart, KPI, Table components
│       ├── hooks/       # useStockData, useSectorData, etc.
│       └── utils/       # formatters, color helpers
└── verify.py            # Copy from references/verification.md (optional)

Setup Workflow

1. Copy template files from references/ into work/<task>/ — they work with zero modifications for port 8050
2. Add your API routes to server/main.py (the template includes CORS, HEAD /, /healthz, and static file serving)
3. Add your Python deps to server/requirements.txt (template includes fastapi + uvicorn)
4. Write frontend code in frontend/src/ (vite.config.js template proxies /api to backend on port 8051)
5. Serve: GetPreviewUrl(port=8050, command="bash work/<task>/start.sh", title="Dashboard")

Template Files

Dockerfile (references/Dockerfile) — Python 3.12 + Node + uv + tzdata. Builds frontend at image time, serves static files from FastAPI. Uses uv pip install for fast dependency installation.

start.sh (references/start.sh) — Cold-boot safe Docker wrapper. Starts dockerd if needed, builds image (uses layer cache on re-runs), removes old container, starts new one, health-checks with log dump on failure. Env var overrides: PORT (default 8050), NAME (default "dashboard").

server/main.py (references/server-main.py) — FastAPI skeleton with CORS, HEAD / (liveness for platform proxy), /healthz, SPA catch-all route for client-side routing (/tab/news, /stocks/AAPL → index.html), and a 503 fallback if the frontend build is missing.

server/requirements.txt (references/requirements.txt) — Minimal: fastapi + uvicorn. Append project-specific packages (pandas, yfinance, etc.).

frontend/vite.config.js (references/vite.config.js) — Vite + React with /api proxy to backend on port 8051.

Critical: Vite proxy is dev-only. The proxy setting in vite.config.js only applies during npm run dev. The production build outputs plain static files with no proxy. In the Docker image, FastAPI serves both the built SPA from frontend/dist/ and all /api/* routes from the same port. The reference server-main.py template already does this correctly — do NOT use a two-process architecture with separate static file server and API server.

Docker Gotchas

• MCP tools are host-only: The tools/ modules (e.g., from tools.yf_price import ...) exist only in the host workspace Python environment — they are NOT copied into the Docker image. FastAPI server code inside Docker must call yfinance directly. Add yfinance to server/requirements.txt
• --network host: Required for the container to reach external APIs (yfinance, MCP servers). Already set in start.sh template
• tzdata: Required for yfinance timezone handling. Already in Dockerfile template
• Image cache: Persists across workspace restarts. First build: 30-60s. Subsequent builds: ~2-5s (cached layers)
• Logs: Use docker logs dashboard to debug startup failures
• Fallback without Docker: If Docker is unavailable, build the frontend and run FastAPI directly:

  fuser -k 8050/tcp 2>/dev/null || true
  cd frontend && npm install --prefer-offline && npm run build && cd ..
  cd server && uvicorn main:app --host 0.0.0.0 --port 8050
  

Chart Libraries

Simple Tier (CDN-loaded, no install)

Default to Chart.js. Use Plotly for candlesticks/heatmaps. Lightweight Charts only for TradingView-style.

Complex Tier (npm packages)

Default to Recharts. Use Plotly for advanced financial charts.

See references/chart-patterns.md for ready-to-use code snippets.

Common Dashboard Patterns

1. Single Stock Dashboard

Data: get_stock_history, get_company_info, get_analyst_price_targets, get_news

Layout:

• KPI row: current price, day change %, 52-week range, market cap, P/E
• Price chart (line/candlestick) with volume bars
• Analyst price target range (horizontal bar)
• Recent news list

2. Multi-Stock Comparison

Data: get_multiple_stocks_history, compare_valuations, compare_financials

Layout:

• Normalized price overlay chart (base 100)
• Performance bar chart (YTD, 1Y, 3Y returns)
• Valuation comparison table (P/E, EV/EBITDA, P/B, etc.)
• Revenue/earnings growth comparison

3. Sector Heatmap

Data: get_sector_info, screen_stocks with sector filters, get_predefined_screen

Layout:

• Treemap colored by daily/weekly performance
• Sector summary cards (top movers, average P/E)
• Top gainers/losers table
• Sector rotation chart

4. Earnings Tracker

Data: get_earnings_calendar, get_earnings_data, get_earnings_estimates

Layout:

• Calendar view with upcoming earnings dates
• Beat/miss history chart (bar chart with surprise %)
• EPS estimate vs actual trend line
• Revenue estimate revision chart

5. Portfolio Monitor

Data: get_multiple_stocks_history, compare_valuations, get_company_info for each holding

Layout:

• Holdings table (ticker, shares, price, value, weight, day P&L)
• Allocation pie chart (by sector/stock)
• Total portfolio value line chart
• Sector exposure bar chart

Best Practices

General

• Data-first: Fetch and validate ALL data before writing any HTML/React code
• Fail gracefully: If a ticker is invalid or API returns empty, show "No data available" — don't crash
• No console errors: Verify chart rendering works before calling GetPreviewUrl
• Responsive: CSS Grid auto-fit for layouts. No horizontal scroll at any width
• Performance: Resample data if > 1000 rows. Don't load unused chart libraries

Simple Tier

• Embed data as JSON: <script>const DATA = ${json.dumps(data)}</script> — never inline raw Python dicts
• Escape properly: Always use json.dumps() with ensure_ascii=False for safe JSON embedding
• Self-contained: All CSS in <style>, all JS in <script>, libraries via CDN <script src="...">
• One HTML file: Keep everything in a single index.html — eliminates path bugs

Complex Tier

• Separation of concerns: FastAPI = data API, Vite/React = UI rendering
• Pydantic models: Define response schemas for type safety
• Component per widget: One React component per chart/card/table
• Shared hooks: useStockData(ticker), useSectorData(key) for data fetching
• Error boundaries: Wrap chart components so one failure doesn't crash the whole page
• Single-port production: Vite proxy is dev-only. In production Docker builds, FastAPI serves both /api/* and the SPA from one port
• host: '0.0.0.0': Both FastAPI and Vite must bind to 0.0.0.0, not 127.0.0.1 or localhost

Error Handling & Debugging

Quality Checklist

Before calling GetPreviewUrl:

Data & Code

• All data fetched and validated (no empty dataframes or None values)
• Files written to work/<task>/ directory
• JSON data properly escaped with json.dumps()
• All chart containers exist in HTML before JS tries to reference them

CSP Safety

• No inline event handlers (onclick, oninput, onchange, etc.) — all events via addEventListener
• No eval(), new Function(), or string-based setTimeout()
• No javascript: URLs
• CSP self-check grep passes (no matches)

Verification

• Tier 1: JS syntax check passed (node --check on extracted script blocks)
• Tier 2: Playwright verification passed (for interactive dashboards with buttons/filters/tabs)

Serving

• Server binds to 0.0.0.0 (not 127.0.0.1 or localhost)
• Correct port used (default 8050)
• Command passed to GetPreviewUrl is idempotent (works on re-run after restart)
• Complex tier: start.sh and Dockerfile copied from templates
• Complex tier: FastAPI includes HEAD / endpoint (use server-main.py template)

UI Quality

• Dark theme applied consistently (see color table above)
• Responsive layout — no horizontal scroll
• Financial numbers properly formatted (currency, %, abbreviations)
• Title passed to GetPreviewUrl is descriptive (e.g., "AAPL Stock Dashboard", not "Preview")

Source: ginlix-ai/LangAlpha — distributed by TomeVault.