feat(visualization): add biological network viewer

[dsk-dev-ai]

Summary

Implements Phase 6.6 of the GenomeAI Visualization Platform by introducing a reusable 2D Biological Network Viewer.

The viewer provides a generic graph visualization foundation for biological relationships while remaining independent of any specific external biological database.

Features

Network Visualization

• Generic typed graph model
• Biological nodes and relationships
• Deterministic graph layout
• Node labels
• Edge rendering
• Node selection
• Hover interactions
• Zoom and pan
• Fit-to-view/reset controls

Biological Graph Support

Supports extensible node types including:

• Gene
• Protein
• Variant
• Disease
• Drug
• Transcript
• Study
• Publication

Supports generic relationship types including:

• interacts_with
• associated_with
• regulates
• expressed_in
• causes
• targets
• encodes
• participates_in
• related_to

Filtering

• Node-type filtering
• Relationship filtering
• Combined filtering
• Dangling-edge removal
• Deterministic graph transformations

Architecture

• Reusable graph data model
• API-to-graph transformation layer
• Rendering separated from data transformation
• Strong TypeScript typing
• Extensible layout architecture
• Prepared for future GenomeAI relationship APIs

Accessibility

• Accessible viewer controls
• Keyboard interaction where supported
• Visible focus states
• Meaningful labels
• Non-color-only state indicators
• Loading, empty, and error states

Scope

This phase intentionally does NOT introduce:

• C++
• WebAssembly
• WebGPU
• Three.js
• 3D rendering
• External biological database ingestion
• External database synchronization
• Large-scale graph infrastructure

External biological data will eventually enter GenomeAI through the connector/ingestion architecture and be consumed by the viewer through normalized GenomeAI graph data.

Tests

Added coverage for:

• Graph normalization
• Node and edge handling
• Duplicate handling
• Invalid references
• Node filtering
• Edge filtering
• Dangling-edge removal
• Deterministic layout
• API-to-graph transformation
• Empty/loading/error states
• Viewer interactions
• Accessibility behavior

Verification

• make setup
• make lint
• make typecheck
• make test
• pnpm turbo build
• Manual /visualization verification
• Existing visualization functionality verified
• No console errors
• git diff --check

Roadmap

Completed:

• Phase 6.1 — Visualization Foundation
• Phase 6.2 — Genome Browser
• Phase 6.3 — Gene/Transcript Visualization
• Phase 6.4 — Variant Visualization
• Phase 6.5 — Protein Viewer
• Phase 6.6 — Biological Network Viewer

Next:

Phase 6.7 — Scientific Charts / Expression Visualization

Summary by Sourcery

Introduce a deterministic, dependency-free Biological Network Viewer and integrate its demo into the visualization page.

New Features:

• Add a reusable Biological Network Viewer SVG component with pan/zoom, fit-to-view, node/edge selection, and type-based filtering.
• Provide a Network Viewer hook and typed graph/viewport model to compose loading, layout, filtering, and interaction state.
• Add a TP53-based network fixture and a NetworkDemo wired into the /visualization page to showcase the viewer.

Enhancements:

• Document Phase 6.6 Biological Network Viewer architecture, layout design decision, API contract, accessibility, and tests in new docs.
• Update visualization roadmap and README to mark Phase 6.6 as implemented and describe its deterministic pure-SVG layout.
• Refine the network visualization module description to emphasize deterministic 2D relationship networks and typed graph support.

Tests:

• Add unit tests for network graph modeling, normalization, filtering, deterministic layout, viewport math, geometry, labels, API adapter, and the useNetworkViewer hook.
• Add component tests for NetworkViewer covering loading/empty/error states, accessibility, filtering behavior, zoom/fit controls, and selection/detail panel interactions.

[sourcery-ai]

Sorry @dsk-dev-ai, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[qodo-code-review]

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

[coderabbitai]

Warning

Review limit reached

@dsk-dev-ai, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 8 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c37fee02-644f-4161-9e2e-3da24ba61d85

📥 Commits

Reviewing files that changed from the base of the PR and between ac1991b and ab12081.

📒 Files selected for processing (28)

• apps/web/src/app/visualization/NetworkDemo.tsx
• apps/web/src/app/visualization/page.tsx
• apps/web/src/components/network/NetworkViewer.test.tsx
• apps/web/src/components/network/NetworkViewer.tsx
• apps/web/src/lib/network/api.test.ts
• apps/web/src/lib/network/api.ts
• apps/web/src/lib/network/filter.test.ts
• apps/web/src/lib/network/filter.ts
• apps/web/src/lib/network/geometry.test.ts
• apps/web/src/lib/network/geometry.ts
• apps/web/src/lib/network/labels.test.ts
• apps/web/src/lib/network/labels.ts
• apps/web/src/lib/network/layout.test.ts
• apps/web/src/lib/network/layout.ts
• apps/web/src/lib/network/model.test.ts
• apps/web/src/lib/network/model.ts
• apps/web/src/lib/network/network.fixtures.ts
• apps/web/src/lib/network/normalize.test.ts
• apps/web/src/lib/network/normalize.ts
• apps/web/src/lib/network/types.ts
• apps/web/src/lib/network/useNetworkViewer.test.tsx
• apps/web/src/lib/network/useNetworkViewer.ts
• apps/web/src/lib/network/viewport.test.ts
• apps/web/src/lib/network/viewport.ts
• apps/web/src/lib/visualization/visualizationModules.ts
• docs/visualization/README.md
• docs/visualization/network-viewer.md
• docs/visualization/roadmap.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

Implements a reusable Phase 6.6 Biological Network Viewer: a typed graph data model and normalization/filtering/layout/viewport math in lib/network; a view-model hook composing data lifecycle, layout, viewport, filtering, and selection; an accessible SVG NetworkViewer component plus dev fixture, demo integration, and documentation/tests, all wired into the visualization roadmap and README.

Sequence diagram for loading and rendering a network in the viewer

sequenceDiagram
  actor User
  participant VisualizationPage
  participant NetworkDemo
  participant useNetworkViewer
  participant useVisualizationData
  participant fetchNetworkGraph
  participant createLayout
  participant filterGraph
  participant fitViewport
  participant NetworkViewer

  User->>VisualizationPage: visit /visualization
  VisualizationPage->>NetworkDemo: render
  NetworkDemo->>useNetworkViewer: useNetworkViewer({ loader | networkId })
  useNetworkViewer->>useVisualizationData: useVisualizationData(loader)
  useVisualizationData->>fetchNetworkGraph: fetchNetworkGraph(networkId,signal)
  fetchNetworkGraph-->>useVisualizationData: Graph
  useVisualizationData-->>useNetworkViewer: data=Graph,status="success"
  useNetworkViewer->>createLayout: createLayout(Graph,"concentric")
  createLayout-->>useNetworkViewer: GraphLayout
  useNetworkViewer->>fitViewport: fitViewport(GraphLayout,width,height)
  fitViewport-->>useNetworkViewer: NetworkViewport
  useNetworkViewer->>filterGraph: filterGraph(Graph,filter=null)
  filterGraph-->>useNetworkViewer: filteredGraph
  useNetworkViewer-->>NetworkDemo: NetworkViewerResult
  NetworkDemo->>NetworkViewer: render NetworkViewer(result)
  NetworkViewer-->>User: interactive SVG (pan/zoom/filter/select)

Loading

File-Level Changes

Change	Details	Files
Introduce a typed graph/domain model and pure helpers for biological networks, including normalization, filtering, layout, viewport, geometry, labels, and API adapters, under lib/network.	Define Graph, GraphNode, GraphEdge, GraphLayout, NetworkViewport, GraphFilter, and related types for a generic typed relationship graph. Add model helpers for node/edge lookups, degree calculations, available types, and graph validation. Implement graph normalization to dedupe ids, drop self-loops and dangling edges, and enforce deterministic ordering. Implement graph filtering by node and edge types with guarantees that no dangling edges remain after filtering. Implement deterministic concentric layout strategy with a pluggable LayoutStrategy registry and layoutFromPositions utility. Add viewport utilities for identity, pan, zoom-around-point, and fit-to-view based on layout bounds, mirroring existing viewers’ zoom factor. Add geometry helpers to convert layout coordinates into SVG screen geometry for edges and nodes (endpoints, midpoints, hit boxes, constants). Add label/color helpers to map node/edge types to stable colors, generate human-readable labels, accessible names, and detail-panel rows. Define an API adapter layer describing the future GET /networks/{id} contract, with raw record normalization, graphFromRecords, and fetchNetworkGraph that surfaces backend limitations. Add deterministic dev network fixtures (TP53 network and a synthetic test network) that flow through the same normalizers as the adapter.	apps/web/src/lib/network/types.ts apps/web/src/lib/network/model.ts apps/web/src/lib/network/normalize.ts apps/web/src/lib/network/filter.ts apps/web/src/lib/network/layout.ts apps/web/src/lib/network/viewport.ts apps/web/src/lib/network/geometry.ts apps/web/src/lib/network/labels.ts apps/web/src/lib/network/api.ts apps/web/src/lib/network/network.fixtures.ts
Add the useNetworkViewer view-model hook that composes data loading, deterministic layout, viewport control, filtering, and selection for the Network Viewer.	Implement useNetworkViewer to load a Graph via useVisualizationData, compute a deterministic layout once per graph, and expose a NetworkViewerResult to consumers. Ensure layout is derived from the full graph and remains stable across filter changes, with filteredGraph recomputed client-side. Manage NetworkViewport state (identity, fit-to-view on load, panBy, zoomIn/zoomOut/zoomAt, resetView) and clamp zoom scale. Track GraphFilter state with setFilter/resetFilter and node/edge selection state with selectNode/selectEdge/clearSelection, resetting on new graph IDs. Provide options for custom loader, networkId-based loading via fetchNetworkGraph, and configurable layout strategies/options.	apps/web/src/lib/network/useNetworkViewer.ts
Implement the NetworkViewer SVG UI component and demo integration, wiring it into the visualization page and modules with accessible controls and detail panels.	Create NetworkViewer component that consumes NetworkViewerResult and renders VisualizationContainer content: network summary, controls, SVG graph, and detail panel. Implement NetworkSummary, NetworkControls, NetworkGraph, and NetworkDetail subcomponents to provide node/edge counts, zoom/fit controls, filter dropdowns, SVG pan/zoom, node/edge selection, and a labelled detail panel. Use geometry and label helpers to render nodes/edges with colors, labels, keyboard-accessible hit targets, and ARIA attributes (role=button, aria-pressed, aria-label, aria-live, etc.). Add pointer-based drag-to-pan and wheel-based zoom-at-cursor for the SVG, with fallbacks when filters produce an empty graph. Introduce NetworkDemo that uses useNetworkViewer with the TP53_NETWORK_FIXTURE loader and render it on the /visualization page, updating metadata description and including the demo in the page content. Update visualizationModules entry for the network viewer to describe deterministic 2D relationship networks and existing milestone. Add a dedicated NetworkViewer.test.tsx verifying loading/empty/error states, controls, selection, detail panels, filtering behavior, and keyboard interaction.	apps/web/src/components/network/NetworkViewer.tsx apps/web/src/app/visualization/NetworkDemo.tsx apps/web/src/app/visualization/page.tsx apps/web/src/lib/visualization/visualizationModules.ts apps/web/src/components/network/NetworkViewer.test.tsx
Document Phase 6.6 Biological Network Viewer and update roadmap/README to reflect the new milestone and design decisions.	Update visualization roadmap to mark Phase 6.6 as current, describe delivered artifacts (types, helpers, normalization, filtering, layout, viewport, labels, adapter, hook, component, demo, tests), and list constraints honored (determinism, no Cytoscape.js/D3/etc., no backend endpoints yet). Adjust roadmap table to remove the prior Cytoscape.js note and align future milestones with the deterministic pure-SVG layout approach. Update docs/visualization/README.md to mark 6.5 and 6.6 as implemented, describe what Phase 6.6 provides, and link to the new Network Viewer doc; update technology notes to defer Cytoscape.js and point to the layout seam. Add docs/visualization/network-viewer.md describing scope, design decision (deterministic pure-SVG layout, no Cytoscape.js), architecture/data flow, coordinate conventions, accessibility behavior, API limitations, tests, and involved files. Ensure documentation is consistent with the dev fixture boundary and future backend network API contract.	docs/visualization/roadmap.md docs/visualization/README.md docs/visualization/network-viewer.md
Add comprehensive unit tests for the new network modules (model, normalize, filter, layout, viewport, geometry, labels, api, hook) to enforce determinism, correctness, and API boundaries.	Add model.test.ts to validate node/edge lookups, degree calculations, available types, graph validity checks, and test network builder behavior. Add normalize.test.ts to verify deduping logic, removal of self-loops and dangling edges, deterministic sorting of nodes/edges, and immutability of input graphs. Add filter.test.ts to cover node/edge-type filters, combined filters, dangling-edge removal, empty-filter results, and isActiveFilter semantics. Add layout.test.ts to confirm concentric layout properties (hub in center, deterministic positions, ring ordering, bounding-box computation, strategy registry behavior, ring spacing options). Add viewport.test.ts to exercise identityViewport, clampGraphScale, projectPoint, panViewport, zoomViewport (including zoom-around-point and clamping), and fitViewport behavior for typical and degenerate layouts. Add geometry.test.ts to validate edgeEndpoints shortening, edgeMidpoint, edgeScreenPoints with and without dangling edges, and nodeScreenBox sizing/zoom scaling. Add labels.test.ts to verify type-to-color mappings, label generation, accessible labels, and detail-line construction for nodes/edges. Add api.test.ts to assert raw record normalization (toGraphNode/toGraphEdge), graphFromRecords correctness, fetchNetworkGraph error handling and URL formation, and fixture integrity. Add useNetworkViewer.test.tsx to validate lifecycle transitions (success/empty/error/refetch), layout stability under filters, viewport operations, selection exclusivity, reset-on-new-graph, and default networkId loading behavior.	apps/web/src/lib/network/model.test.ts apps/web/src/lib/network/normalize.test.ts apps/web/src/lib/network/filter.test.ts apps/web/src/lib/network/layout.test.ts apps/web/src/lib/network/viewport.test.ts apps/web/src/lib/network/geometry.test.ts apps/web/src/lib/network/labels.test.ts apps/web/src/lib/network/api.test.ts apps/web/src/lib/network/useNetworkViewer.test.tsx

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.