How-to: run the Organismo dashboard¶

The Motion UI Design System ships as a live, browser-based dashboard backed by a FastAPI server that reads from the runtime modules. This guide shows the three ways to run it.

What it shows¶

Anatomy — 20 body systems mapped to framework camadas (atlas-level SVG)
3 themes — Editorial / X-Ray / Operations Center (persists in localStorage)
Project health — health ring, sparkline, sprint/wave/epic, current story
Hormones — 7 cards (cortisol, oxytocin, dopamine, adrenaline, serotonin, melatonin, insulin) with current levels + ECG animation
Pixel Agents — 1 monitor per agent, live state (ok/warn/alert)
Analytics — DAG of story deps, agent load heatmap, cost graph
Decisions — pending ADRs with "ask AI" button
Event Bus marquee — canonical events streaming at the bottom
AI chat drawer — proxied to Anthropic via /api/chat

Install¶

pip install -e ".[dashboard,llm]"     # adds fastapi + uvicorn + anthropic

Optional: .[observability] if you want OTel + a Prometheus endpoint.

Mode 1 — full stack (recommended)¶

Live dashboard wired to a real StateAggregator reading from a HormoneSystem, WorldState, AgentRegistry, etc.

# run_dashboard.py
import uvicorn
from src.ai.metrics import AgentMetrics
from src.agent_expansion import AgentRegistry
from src.autonomy import EventBus, ProposalBoard, WorldState
from src.body import HormoneSystem
from src.dashboard import StateAggregator, create_app

# Compose the runtime
bus = EventBus(jsonl_path="_framework/observability/events.jsonl")
world = WorldState(); world.attach(bus)
hormones = HormoneSystem()
metrics = AgentMetrics(base_dir="_framework/observability")
agents = AgentRegistry()
proposals = ProposalBoard()

aggregator = StateAggregator(
    hormone_system=hormones,
    world_state=world,
    agent_registry=agents,
    metrics=metrics,
    proposal_board=proposals,
    event_bus=bus,
)

# Optional: wire Anthropic for real chat
chat_invoker = None
import os
if os.environ.get("ANTHROPIC_API_KEY"):
    from src.ai import AnthropicInvoker
    chat_invoker = AnthropicInvoker(max_tokens=512, system_prompt=(
        "You are the Organismo dashboard assistant. The user is monitoring a "
        "multi-agent framework. Answer concisely, in Portuguese unless asked otherwise."
    ))

app = create_app(aggregator=aggregator, chat_invoker=chat_invoker)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000, log_level="info")

Then:

export ANTHROPIC_API_KEY=sk-ant-...    # optional — uses mock if absent
export AUDIT_HMAC_KEY=$(openssl rand -hex 32)
python run_dashboard.py

Open http://localhost:8000.

Mode 2 — backend-only (curl-friendly)¶

If you just want the API for integration testing:

uvicorn src.dashboard.server:create_app --factory --port 8000

Then poke endpoints:

curl http://localhost:8000/healthz
curl http://localhost:8000/api/world-state | jq
curl http://localhost:8000/api/hormones | jq
curl -N http://localhost:8000/api/events/stream    # SSE stream
curl -X POST http://localhost:8000/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "what is the framework status?", "model_tier": "simple"}'

Mode 3 — frontend-only (offline / demo)¶

The dashboard works standalone — open docs/dashboard/index.html directly in a browser. window.Organismo.live shows disconnected; the bundled body-data.js provides demo state.

API surface (cheat sheet)¶

Endpoint	Returns
`GET /`	`index.html` (static)
`GET /dashboard/<file>`	CSS, JSX, JS assets
`GET /api/world-state`	`WorldStateResponse` (full snapshot)
`GET /api/hormones`	`{ hormones: [...] }`
`GET /api/pixel-agents`	`{ pixelAgents: [...] }`
`GET /api/decisions`	`{ decisions: [...] }`
`GET /api/events/stream`	SSE, emits `event: worldstate` every ~3s
`POST /api/chat`	`ChatResponse` (uses mock if no Anthropic key)
`GET /metrics`	Prometheus text exposition
`GET /healthz`	`{"status":"healthy"}`
`GET /readyz`	`{"status":"ready"}`

Full OpenAPI at http://localhost:8000/docs.

How `live.js` connects¶

When served from the FastAPI backend, index.html loads dashboard/live.js which:

Waits for window.Organismo.ready()
Fetches /api/world-state and calls Organismo.applyWorldState(data)
Opens an EventSource on /api/events/stream for live re-snapshots
Overrides window.claude.complete to POST to /api/chat
Exposes Organismo.live.{refresh, disconnect, reconnect, status} for debugging

When index.html is opened directly (file://), live.js errors are swallowed and the dashboard runs on the bundled body-data.js demo state.

Docker¶

docker compose up -d
curl http://localhost:8080/api/world-state    # via container's mapped port

(docker-compose.yml maps the dashboard's port. Use docker compose logs -f to trail the FastAPI output.)

Production hardening checklist¶

Set enable_cors=False (or restrict to your origin) in create_app(...)
Set OTEL_EXPORTER_OTLP_ENDPOINT if you want metrics collected
Mount _framework/ as a read-only volume in the container
Rotate AUDIT_HMAC_KEY on incidents
Behind a reverse proxy with TLS + auth (the dashboard endpoints are unauth'd)