Building the Knowledge Graph: Visualizing Fezcodex in 3D
The idea was simple: Fezcodex is growing. With hundreds of blog posts, apps, and project logs, a standard list or grid view just wasn't cutting it anymore. I wanted a way to visualize the connections between everything. To see the "brain" of the website.
Enter the Knowledge Graph Visualization Protocol.
The Concept
I wanted a 3D, interactive network graph where:
- Nodes represent content (Blog Posts, Apps, Projects).
- Links represent relationships (Shared tags, Categories).
- Interaction allows users to fly through the data and navigate to content.
It needed to feel like a "cyberspace" visualization from a sci-fi movie—immersive, dark, and slightly chaotic but organized.
The Tech Stack
- React: The core framework.
- react-force-graph-3d: The heavy lifter. This library uses WebGL (via Three.js) to render force-directed graphs with great performance.
- PIML: My custom markup language for parsing project data.
- Tailwind CSS: For the overlay UI and brutalist styling.
Implementation Details
1. Data Extraction (graphDataManager.js)
The first challenge was aggregating data from three different sources:
posts.json: A static JSON file containing blog metadata.apps.json: A structured list of all the mini-apps.projects.piml: A custom file format for my project portfolio.
I created a utility function fetchGraphData that pulls all three.
export const fetchGraphData = async () => { const nodes = []; const links = []; const tagMap = new Map(); // ... fetching logic ...For each item, I created a primary node. Then, I looked at its tags, category, or technologies. For every tag found, I created a tag node (if it didn't exist) and created a link between the item and the tag.
This automatically creates clusters. If five posts are tagged "React", they all link to the "React" tag node, pulling them together in the 3D space.
2. The 3D Component (KnowledgeGraphPage.js)
I used <ForceGraph3D> to render the data.
<ForceGraph3D ref={fgRef} graphData={graphData} backgroundColor="#050505" nodeLabel="name" nodeColor="color" onNodeClick={handleNodeClick} // ... />3. Camera Controls
The "cool factor" comes from the camera movement. When you click a node, I didn't want a hard jump. I wanted a smooth flight.
const handleNodeClick = useCallback((node) => { // Calculate a position slightly "outside" the node const distance = 40; const distRatio = 1 + distance/Math.hypot(node.x, node.y, node.z); if (fgRef.current) { fgRef.current.cameraPosition( { x: node.x * distRatio, y: node.y * distRatio, z: node.z * distRatio }, // new pos node, // lookAt 3000 // ms duration ); } }, []);This calculates a vector from the center (0,0,0) to the node, extends it by a fixed distance, and moves the camera there while focusing on the node.
Challenges
- PIML Parsing: My custom language parser needed to be robust enough to handle the varying structures of the
projects.pimlfile. - Performance: Rendering hundreds of text labels in 3D can be heavy. I kept the UI minimal and only showing detailed info on hover.
- Theme: Matching the "Brutalist/Cyberpunk" aesthetic required careful tuning of node colors (Emerald for Apps, Red for Posts) and link opacity.
The Result
The result is a living, breathing map of Fezcodex. It reveals patterns I didn't explicitly plan—like the massive cluster around "React" or the isolated islands of specific game experiments. It's not just a navigation tool; it's a piece of generative art powered by my own work.
Go check it out at /graph and fly through the system.