Overview

Architecture & Concepts

Four building blocks — Dataset, VizSpec, Cockpit, and Lenses — compose the entire platform. Understanding how they relate makes everything else predictable.

Dataset
network data + schema

→

VizSpec
visual recipe (JSON)

→

Lab
single-view explorer

Cockpit
multi-panel viewer

Dataset

A dataset is a folder that contains everything the engine needs to render a network: the node list, one or more edge files, and a dataset.json schema that describes each attribute and edge layer.

The schema is the contract between your data and the visualization engine. It declares which attributes are categorical, continuous, or boolean — and the engine uses those types to decide which color palettes and legend formats to apply. Nothing is guessed.

Edge layers

A single dataset can hold multiple types of relationships simultaneously. Each type is an edge layer — for example, communication and hierarchy. Each layer has its own CSV file and its own visual style (color, line width). In the Lab, layers can be toggled independently. A VizSpec declares which layers are visible by default.

VizSpec — the visual grammar

A VizSpec is a JSON file that describes a named visualization. It answers one question: how should this dataset be presented? It does not contain data — it references a dataset and defines presentation rules.

Core principle

A VizSpec is a description of what to see, not code that draws it. The engine reads the VizSpec and renders accordingly — no programming required to create a new view.

A VizSpec controls six areas:

Section	What it defines	Example
Identity	Unique ID, display label, source dataset	`id: "viz-dept"`
Defaults	Color attribute, size attribute, edge opacity, visible edge layers	`node_color: "department"`
Interactions	Pre-selected filter attribute (drives filter panel and lens triggers)	`filter: "department"`
Lenses	Which analytical lenses are enabled and on which trigger	`bridge: { enabled: true, trigger: "filter_1" }`
Shell	Visible UI panels (legend, metrics, compute), topbar, sidebar, motion effects	`panels: ["legend", "metrics"]`
Theme	CSS custom property overrides (accent color, etc.)	`"--color-accent": "#e55a2b"`

VizSpecs are created with the VizSpec Editor and stored as viz-*.json files inside the dataset folder. Multiple VizSpecs can reference the same dataset, each offering a different view.

Attribute types and visual mappings

The dataset schema declares each attribute's type, which determines what the engine can do with it:

Attribute type	Color by	Size by	Legend
categorical	✓	—	Color swatches
ordinal	✓	✓	Gradient
continuous	✓	✓	Gradient
boolean	✓	—	Green / Red
computed (degree, betweenness, PageRank)	✓	✓	Gradient

Cockpit

A Cockpit is a multi-panel layout that displays two to six VizSpecs simultaneously. Each panel renders an independent graph, but all panels share a selection state: clicking a node in any panel highlights the same node in every other panel.

Cockpit layouts available:

Split Horizontal

2 columns

Split Vertical

2 rows

3 Columns

3 columns

2 × 2 Grid

4 panels

Cockpits are created with the Cockpit Editor and saved as cockpit-*.json files at the project root. The Cockpit viewer reads those files and renders them — no editor is exposed to end users.

Lenses

A lens is an analytical overlay that highlights specific structural patterns in the graph — bridges, silos, ego networks, and more. Lenses are activated automatically by triggers: actions the user takes in the interface, such as selecting a filter value or clicking a node.

Trigger types

Trigger	When it fires
`filter_1`	Exactly one filter value is active in the sidebar
`filter_2`	Exactly two filter values are active (Shift+click)
`node_click`	A node is selected (clicked or found via search)

Available lenses

Lens	Default trigger	What it reveals
bridge	`filter_1`	Nodes with cross-group edges — structural brokers. Shown in gold, enlarged.
isolation	`filter_1`	Nodes with no cross-group edges — pure silos. Shown in red.
periphery	`filter_1`	Intra-group degree distribution — core nodes (large) vs periphery (small).
weak_ties	`filter_1`	Intra-group weak ties highlighted. Based on Granovetter (1973).
contrast	`filter_2`	Cross-group edges between two selected groups. Structural bridges.
density	`filter_2`	Edge thickness = flow weight. Shows where inter-group exchange is dense.
ego	`node_click`	The N-hop neighbourhood of a selected node. Hop depth is configurable per VizSpec.

Each VizSpec declares which lenses are enabled and on which trigger. When multiple lenses share a trigger, a lens switcher appears in the Lab sidebar, letting the user toggle between them without losing the filter state.

Tip

You don't need to activate a lens manually. As soon as you select a filter value in the Lab, the lens assigned to filter_1 activates automatically. Shift-click a second value to trigger filter_2 lenses.

← Previous Introduction Next → QS 1 · Explore a Network