Network Canvas is a suite of tools for designing and conducting network research interviews. This monorepo contains the current browser applications, maintenance-mode desktop and mobile applications, shared libraries, websites, and supporting services used across the Network Canvas ecosystem.
Architect creates .netcanvas interview protocols. Interviewer installs and
runs those protocols locally, stores interview data offline, and exports the
resulting networks for analysis. The shared packages provide the protocol
schema, interview runtime, design system, data utilities, and canonical protocol
content used by those applications.
The pnpm workspace is organized into four main categories.
| App | Description |
|---|---|
architect |
Offline-capable Vite/React PWA for designing, validating, and previewing Network Canvas interview protocols |
architect-classic |
Maintenance-mode Electron version of the original Architect protocol designer |
documentation |
Localized Next.js documentation site built from Markdown/MDX, with DocSearch and generated protocol downloads |
interviewer |
Offline-first Vite/React PWA for managing protocols, conducting interviews, storing local sessions with optional encryption, and exporting data |
interviewer-classic |
Maintenance-mode Interviewer application for desktop (Electron) and native mobile (Capacitor) |
networkcanvas.com |
Localized Next.js project website, including product information, research resources, publications, team information, and getting-started guidance |
| Package | Description |
|---|---|
@codaco/art |
Shared animated backgrounds, blobs, patterns, and network-weave visuals |
@codaco/development-protocol |
Published compatibility package for the canonical development protocol in @codaco/protocols |
@codaco/fresco-ui |
Reusable React components, forms, dialogs, styles, and utilities built with Base UI and Tailwind CSS |
@codaco/interface-images |
Generated responsive screenshots of the interview interfaces, plus the React component used to display them |
@codaco/interview |
Embeddable React interview engine containing the participant-facing interfaces, navigation, state management, and host session contract |
@codaco/network-exporters |
Effect pipeline for exporting Network Canvas interview data as CSV and GraphML |
@codaco/network-query |
Network filtering and querying utilities |
@codaco/protocol-utilities |
Deterministic synthetic-network generation and a fluent interview-payload builder |
@codaco/protocol-validation |
Zod schemas and utilities for validating, hashing, and migrating Network Canvas protocol files |
@codaco/protocols |
Private canonical source for development and sample protocols, Architect templates, documentation downloads, and E2E fixtures |
@codaco/sample-protocol |
Published compatibility package for the canonical sample protocol in @codaco/protocols |
@codaco/shared-consts |
Shared constants and TypeScript definitions |
@codaco/site-navigation-element |
Self-contained <nc-site-navigation> web component for non-React websites |
| Worker | Description |
|---|---|
development-protocol-worker |
Cloudflare Worker that resolves and serves the latest released Development.netcanvas artifact |
posthog-proxy-worker |
Cloudflare Worker that proxies PostHog API and static-asset requests with CORS support |
| Tooling | Description |
|---|---|
@codaco/tailwind-config |
Shared Tailwind theme, design tokens, fonts, and plugins, with v3 compatibility and the preferred v4 surface |
@codaco/tsconfig |
Shared TypeScript configurations |
oxlint |
Shared oxlint rule sets for React and accessibility |
- Node.js 24, using the exact version in
.nvmrc - pnpm 11, using the exact version pinned by
packageManagerinpackage.json
git clone https://github.com/complexdatacollective/network-canvas-monorepo.git
cd network-canvas-monorepo
corepack enable
pnpm install# Start every workspace that has a development task
pnpm dev
# Build the workspace through Turborepo's dependency graph
pnpm build
# Run tests across the workspace
pnpm testThe root scripts invoke turbo run/turbo watch, so workspace dependencies are
built or watched in the correct order. Prefer them over calling a package script
directly when that task consumes another workspace package.
# Work with a specific app or package
pnpm --filter @codaco/protocol-validation build
pnpm --filter @codaco/architect dev
pnpm --filter @codaco/documentation dev
# Run commands across multiple packages
pnpm --filter "./packages/*" build
pnpm --filter "./apps/*" dev# Develop workers locally
pnpm --filter development-protocol-worker dev
pnpm --filter posthog-proxy-worker dev
# Deploy workers to Cloudflare
pnpm --filter development-protocol-worker deploy
pnpm --filter posthog-proxy-worker deploy- Workspace orchestration: pnpm workspaces and Turborepo
- Application builds: Vite for the current web apps and shared libraries, Next.js for the websites, Electron Vite for the classic desktop apps, and Wrangler for Cloudflare Workers
- UI: React, Tailwind CSS, Base UI, and the shared Fresco design system
- Code quality: TypeScript, oxlint, oxfmt, and knip
- Testing: Vitest, Storybook/Chromatic, and Playwright
- CI/CD and releases: GitHub Actions, Changesets, Netlify, npm, and Cloudflare Workers
This project uses oxlint for linting and oxfmt for formatting. Style settings: 2-space indentation, 80-character line width, and single quotes.
# Check formatting and linting
pnpm lint
# Auto-fix formatting and linting issues
pnpm lint:fix
# Format only
pnpm format
# Check formatting only
pnpm format:checkPre-commit hooks automatically lint and format staged files.
# Run all tests
pnpm test
# Run tests for a specific package
pnpm --filter @codaco/protocol-validation test
# Run tests in watch mode
pnpm test:watch
# Type check the workspace
pnpm typecheck
# Check for unused files, exports, and dependencies
pnpm knipThis project uses Changesets for version management and automated releases.
# Add a changeset for your changes
pnpm changesetPublishable library packages under packages/* share the npm release lane.
Architect, Interviewer, Documentation, and networkcanvas.com each have an
independent gated product release PR. Keep each changeset to one release lane:
do not mix a gated product with libraries, or two gated products, in the same
changeset. Classic apps are maintained and released separately.
@codaco/interface-images ships generated screenshots of every interview interface (Sociogram, Name Generator, …), rendered from dedicated Storybook "capture" stories in @codaco/interview with Playwright + sharp. They are consumed by architect (stage thumbnails) and the documentation site (the hero image on each interface-documentation page).
The generated WebP variants in
packages/interface-images/src/generated/assets/ and their
packages/interface-images/src/generated/manifest.ts are committed. Architect,
the documentation site, CI, and Netlify consume those committed files; CI and
Netlify do not regenerate them.
Chromatic snapshots the Interview capture stories. Treat a relevant Chromatic diff as the review signal that the committed interface images may need to be refreshed, then regenerate them locally:
pnpm generate:interface-imagesThis builds the Interview Storybook and captures the images. It requires a
Chromium browser (pnpm exec playwright install chromium) and, for the
Geospatial map, STORYBOOK_MAPBOX_TOKEN. Review the results and commit
packages/interface-images/src/generated/assets/ and
packages/interface-images/src/generated/manifest.ts together. See
packages/interface-images for details.
These interface screenshots are separate from the committed Playwright PNG
baselines. For intentional Architect or Interview E2E pixel changes, use
the regenerating-e2e-visual-snapshots skill and the manual
Regenerate E2E Visual Snapshots GitHub Actions workflow.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Add a changeset when the change affects a releasable package or product
- Run
pnpm lint:fix,pnpm knip,pnpm typecheck, and the relevant tests - Submit a pull request
Built by the Complex Data Collective team