Chiseizu (Knowledge Star Map)
A learning site that connects knowledge vocabulary through the genealogy of "why it was born," visualized as a star map.
Production: chiseizu.com
Concept
A glossary sorted alphabetically doesn't become knowledge. A term can only be understood within its genealogy — what premises it stands on and what problem it was born to solve. Chiseizu expresses these prerequisite relationships as a graph.
- Each domain — engineering, accounting, statistics, economics, music theory — is a "galaxy," and each term is a "star"
- Stars are connected by two kinds of edges: genealogy (prerequisite → term) and relation (lateral links). Star size reflects degree; edge width reflects connection strength
- Each term page follows a three-part structure: "Overview → Why it was born → Details," teaching through historical necessity
- Your browsing history becomes a personal constellation called the "Voyage Log" (stored only in the browser's localStorage)
Architecture
- Astro SSG + React Islands: All 271 term pages are statically generated at build time. Only dynamic parts like the star map hydrate as React islands via
client:only/client:visible - Build-time graph construction: Nodes, edges, and degrees are aggregated from all MDX frontmatter at build time; the client just receives one lightweight JSON and renders it
- Cloudflare Workers (assets-only): Pure static delivery with zero server-side processing. Custom domain + global edge delivery on the free tier
- GitHub Actions CD: push → consistency checks → build (Mermaid rendered to SVG via Playwright Chromium) →
wrangler deploy, fully automated
Technology Selection
- SSG, full stop (not serverless — no server at all)
- All content is MDX I author myself; there are no dynamic writes. Even browsing history stays in localStorage, eliminating the need for a database, API, or authentication entirely
- The result: zero operating cost, near-zero attack surface, and effectively unlimited scalability, all at once
- Astro + React Islands
- As a content-first site, Astro was chosen over Next.js. It outputs 0KB-JS HTML by default, hydrating only the star map that needs force simulation
- react-force-graph-2d (Canvas rendering)
- A graph of 235 nodes + 700 genealogy edges is too heavy for SVG DOM. Canvas-based force-graph with runtime d3-force layout enables live zoom, pan, and hover interactions
- The simulation is pre-warmed with 240 ticks before first paint to eliminate initial jank
- Content-as-Code (MDX + Zod)
- Term frontmatter (prerequisites, relations, category, abstraction level) is validated with Zod; references to nonexistent terms or undefined categories fail the build. A link-rot-free graph is structurally guaranteed
Features
Galaxy Star Map
A per-galaxy star map drawn with d3-force physics simulation. Beyond zoom/pan/hover, it supports full-text search in Japanese, English, and readings, category highlighting via legend clicks, and filtering by abstraction level (1–5).
Term Detail Pages
Three-part structure: "Overview → Why it was born → Details." The sidebar shows a neighborhood graph of the focused term and its 1-hop neighbors, with prerequisite/relation weights visualized as bars.
Interactive Learning Components
Over 40 hands-on components are embedded in MDX so readers can learn by touching, not just reading: a rate-limiting lab that fires requests into a token bucket, Raft consensus visualization, an OAuth flow stepper, JWT tampering experiments, and more. All lazy-loaded via client:visible.
Voyage Log
A personal constellation drawn only from the stars you've visited, with visit order shown as numbered vermilion dashed lines. Records live only in localStorage and are never sent anywhere (no analytics either).
Development & Operations
- Append-only registry: The permanent order of all terms is managed in
vocab-registry.json. Since indices serve as numbers in shareable Voyage Log URLs, reordering and deletion are forbidden, enforced by git-diff immutability checks in CI - Build-time content validation: Duplicate terms, missing registry entries, and cross-galaxy references (forbidden to limit complexity) fail the build immediately
- Privacy by design: No user data is held at all. Browsing history stays in the browser, with a delete button provided
- Cost: Runs on the Cloudflare Workers free tier plus the domain fee only