cadguide.tools

Posted on Sep 30 Originally published at chanzong.space

Engineering a Scalable Digital Humanities Knowledge Graph for 130+ Zen Classics with Next.js 14 & D3.js

#react #webdev #programming #javascript

Engineering a Scalable Digital Humanities Knowledge Graph for 130+ Zen Buddhist Classics with Next.js 14 & D3.js

When preserving and exploring classical philosophical canons, traditional digitized archives often suffer from fragmented flat texts, clunky navigation, and poor contextual interlinking.

Over the past few months, we designed and built ChanZong Knowledge Base (chanzong.space), a modern open-access digital humanities platform indexing over 130 canonical Zen Buddhist scriptures, 500+ philosophical concepts, and hundreds of historical lineages.

In this article, we share our architectural decisions, focusing on:

D3.js v7 Force-Directed Graph Engine with custom dampening & anti-jitter algorithms.
Next.js 14 App Router SSG with automated Simplified/Traditional Chinese dual-track routing.
Structured Taxonomy Schema maintaining a zero-dangling-reference network.

1. The Challenge of Visualizing Dense Philosophical Networks

In classical Zen literature (ranging from the Platform Sutra and Huangbo's Essential Dharma of Mind Transmission to The Blue Cliff Record and Gateless Gate), concepts and historical masters do not exist in isolation. Every master links to lineage transmissions, koans, and doctrinal paradoxes.

Rendering 3,000+ interconnected entities inside a web canvas introduces three common pitfalls:

Hairball problem: Extreme edge density causing visual overlap.
Continuous jitter: The force simulation never reaching equilibrium, draining GPU/CPU resources.
Search latency: Client-side filtering stuttering on low-powered mobile devices.

D3.js Multi-Stage Equilibrium Simulation

To resolve dynamic jitter and provide an interactive exploration canvas, we implemented a multi-stage physics model in D3 v7:

import * as d3 from 'd3';

export function createZenKnowledgeForceSimulation(
  nodes: KnowledgeNode[], 
  links: KnowledgeLink[], 
  width: number, 
  height: number
) {
  const simulation = d3.forceSimulation(nodes)
    // 1. Many-Body Repulsion with dynamic distance bounds
    .force("charge", d3.forceManyBody()
      .strength((d: any) => d.isCenter ? -800 : -260)
      .distanceMax(600)
    )
    // 2. Elastic Link Spring scaled by semantic weight
    .force("link", d3.forceLink(links)
      .id((d: any) => d.id)
      .distance((l: any) => l.weight * 60)
      .strength(0.6)
    )
    // 3. Centering force to retain canvas boundary
    .force("center", d3.forceCenter(width / 2, height / 2).strength(0.08))
    // 4. Collision prevention protecting node text labels
    .force("collide", d3.forceCollide().radius((d: any) => (d.radius || 12) + 12).iterations(3));

  // Auto-freezing after 3.2 seconds to eliminate jitter & conserve battery
  simulation.alphaTarget(0).alphaDecay(0.0228);

  return simulation;
}

By tuning alphaDecay to 0.0228, the physics engine naturally converges and freezes within ~3 seconds, switching seamlessly from a dynamic layout engine to a static SVG pan-zoom canvas.

Experience the live graph: Interactive D3.js Global Zen Knowledge Graph.

2. Next.js 14 App Router & Dual-Track Static Site Generation (SSG)

Classical East Asian humanities must cater to both Simplified Chinese (Mainland China academic circles) and Traditional Chinese (Hong Kong, Taiwan, and international sinology scholars).

Instead of relying on fragile client-side text replacement (which ruins SEO indexation and causes layout shifts), we engineered an automated Dual-Track SSG Pipeline:

Simplified Root: /classics/[id], /concepts/[id], /methods/[id]
Traditional Root: /zh-tw/classics/[id], /zh-tw/concepts/[id], /zh-tw/methods/[id]
Bidirectional Alternate Links: Embedded directly in the HTML <head> and sitemap.xml:

  <link rel="alternate" hreflang="zh-Hans" href="https://chanzong.space/classics/liuzutan-jing" />
  <link rel="alternate" hreflang="zh-Hant" href="https://chanzong.space/zh-tw/classics/liuzutan-jing" />

During the pre-rendering build phase, raw texts and annotations from lib/taxonomy.ts are converted via opencc-js with contextual dictionary optimizations, achieving 100% static HTML generation (0ms TTFB) across all 130+ classics.

Explore the traditional portal: 禪宗知識庫 (chanzong.space) 正體學術通道.

3. Strict Taxonomy & Ontology Schema

To prevent broken links across thousands of entities, our system defines a unified Type-Safe Ontology Schema:

export interface ClassicMetadata {
  id: string;              // e.g. "huangbo", "liuzutan-jing"
  title: string;           // Classic title
  author: string;          // Author / Patriarch
  category: ClassicCategory;
  summary: string;         // 80-120 word modern overview
  relatedConcepts: string[]; // Concept IDs
  relatedPersons: string[];  // Patriarch IDs
  relatedMethods: string[];  // Practicing Method IDs
}

A continuous verification script (tools/verify_taxonomy.py) asserts that:

Every relatedBooks identifier maps to a published markdown canon;
Every relatedConcepts points to a validated node;
Zero dangling nodes or circular crashes exist in the graph.

4. Open-Access Philosophy & Live Links

Digital humanities should be open, accessible, and fast. By combining static pre-rendering with interactive vector visualization, we hope to offer scholars, practitioners, and curious minds a clean, zero-distraction sanctuary for inner peace and scholarly inquiry.

Key entry points:

Official Home: https://chanzong.space
130+ Zen Classics Index: https://chanzong.space/classics
Interactive Knowledge Graph: https://chanzong.space/graph
Patriarch Biographies & Lineages: https://chanzong.space/persons

We welcome any feedback, contributions, and discussions regarding digital humanities visualization and modern text processing!

DEV Community