SquidSonar — Embeddable runtime dashboard for Squid Mesh

SquidSonar is a read-only Phoenix LiveView dashboard for applications that run Squid Mesh workflows.

Mount it inside a Phoenix host application to inspect recent runs, filter by status, search runtime metadata, and open detail pages with the workflow graph, diagnosis, attempt counts, history counts, and last error information.

Runtime Boundary

SquidSonar is distributed as an embeddable library, not a standalone service. A host Phoenix application owns authentication, authorization, deployment, endpoint configuration, and the Squid Mesh runtime. SquidSonar contributes the router macro, LiveViews, static assets, and a small read boundary over Squid Mesh public APIs.

SquidSonar reads from Squid Mesh through:

• SquidMesh.list_runs/2
• SquidMesh.inspect_run/2
• SquidMesh.inspect_run_graph/2
• SquidMesh.explain_run/2

It does not start, cancel, replay, approve, reject, unblock, lease, or execute workflow work. Host applications still own workers, queue delivery, scheduler setup, and backend leasing or fencing. When a Squid Mesh host uses Bedrock or another delivery backend, that adapter remains part of the host application, not SquidSonar.

Phoenix Host Application
|
+-- Squid Mesh runtime
|   +-- workers
|   +-- scheduler and delivery backend
|   +-- lease or fencing adapter when needed
|
+-- SquidSonar
    +-- router macro
    +-- read-only LiveViews
    +-- embedded assets
    +-- Squid Mesh inspection API client

Dashboard Surface

The UI includes:

• Recent workflow runs sorted by update time
• Status counts and filters
• Search across workflow, trigger, step, status, and run ID
• Page size controls and pagination
• Run detail pages with diagnosis, history counts, last error, and workflow graph visualization
• Step attempt counts on run detail pages
• Light, dark, and system theme controls
• Embedded CSS and JavaScript served by the library

Requirements

• Elixir 1.17 or later
• Phoenix 1.8
• Phoenix LiveView 1.1
• A host application with Squid Mesh installed and configured

Installation

Add SquidSonar to the host application's dependencies:

def deps do
  [
    {:squid_sonar, "~> 0.1.7"}
  ]
end

Then fetch dependencies:

mix deps.get

Mounting

Import SquidSonar.Router in the host router and mount the dashboard under the path that makes sense for the application:

defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  use SquidSonar.Router

  scope "/ops" do
    pipe_through [:browser, :require_authenticated_user]

    squid_sonar "/sonar"
  end
end

Visit /ops/sonar to open the dashboard.

SquidSonar accepts a few route-level options:

squid_sonar "/sonar",
  as: :runtime_sonar,
  socket_path: "/live",
  transport: "websocket"

transport can be "websocket" or "longpoll".

Security

SquidSonar does not ship its own authentication layer. Protect the mounted route with the same browser pipeline, session handling, and authorization rules used for the rest of the host application's operator surface.

The dashboard is read-only, but it displays runtime data returned by Squid Mesh, including workflow names, run IDs, step names, statuses, diagnostic signals, and selected error metadata. Treat the mounted dashboard as operational visibility and expose it only to trusted users.

Example App

The repository includes a Phoenix example app at examples/example_app. It mounts SquidSonar at /sonar and seeds real Squid Mesh workflows that produce completed, failed, retrying, and paused runs.

cd examples/example_app
mix deps.get
mix ecto.create
mix ecto.migrate
mix example.seed
mix phx.server

Open http://localhost:4010/sonar after the server starts.

Library Modules

• SquidSonar.Router mounts the embedded dashboard routes.
• SquidSonar.Runs is the read boundary over Squid Mesh run APIs.
• SquidSonar.Dashboard builds the filtered, paginated dashboard snapshot.
• SquidSonar.Runs.WorkflowGraph turns workflow definitions and persisted run state into a display graph.
• SquidSonarWeb.* contains the embedded LiveViews, components, layout, hooks, and asset controller.

Community

Use the Squid Mesh Elixir Forum thread for public discussion and design context around the runtime and dashboard.

Use GitHub issues for dashboard bugs, feature requests, and release-tracked work.

For informal runtime and Jido-adjacent chat, use the Squid Mesh channel on the Jido Discord.

License

Apache-2.0