Prerequisites
Before you begin, make sure you have:- Node.js 20 or higher installed
- A Google AI API key (get one at Google AI Studio)
- A modern web browser with WebGL support
Installation
Install dependencies
Install all required packages using your preferred package manager:
The installation includes key dependencies like Next.js, React Three Fiber, Three.js, and the Google Generative AI SDK.
Configure environment variables
Create a You can use the provided Then edit
.env.local file in the root directory and add your Gemini API key:.env.local
.env.example as a template:.env.local to add your actual API key.Start the development server
Launch the application in development mode:The server will start on
http://localhost:3000.Open in your browser
Navigate to http://localhost:3000 to see your Intelligence Space in action.
Your First Knowledge Graph
Once the application is running, follow these steps to create your first interactive knowledge graph:Enter an interest
In the search bar at the bottom of the screen, type a topic you’re interested in exploring. For example:
- “Quantum Physics”
- “Renaissance Art”
- “Machine Learning”
- “Ancient Philosophy”
Submit and watch the expansion
Press Enter or click the sparkle icon. The system will:
- Create a central node for your topic in 3D space
- Query the Gemini AI model for related subtopics
- Automatically generate 3-5 connected nodes around your main topic
Interact with the graph
Explore your knowledge graph using these controls:
- Click and drag to rotate the view
- Scroll to zoom in and out
- Click any node to expand it with more related subtopics
- Hover over nodes to see them highlight in white
Understanding the Code
Intelligence Space is built with a modern React and Next.js architecture. Here are the key files:Core Application Files
| File | Purpose |
|---|---|
src/app/page.tsx | Main page component with the search interface and Canvas setup |
src/app/actions.ts | Server Actions for AI integration with Gemini API |
src/components/ThreeGraph.tsx | 3D graph rendering, physics simulation, and node interactions |
src/store/useInterestStore.ts | Zustand store managing nodes, links, and graph state |
How It Works
User Input Flow
User Input Flow
When you enter a topic in The system creates a root node, then automatically calls the AI to generate related subtopics.
page.tsx:17-39:src/app/page.tsx
AI Integration
AI Integration
The
generateSubInterests function in actions.ts:7-47 uses Google’s Gemini 2.5 Flash model:src/app/actions.ts
The function includes fallback mock data if the API key is missing, allowing you to test the UI without AI.
3D Rendering
3D Rendering
The
ThreeGraph.tsx component handles all 3D visualization:- NodeComponent (lines 10-67): Renders individual spheres with labels
- LinksRenderer (lines 69-109): Draws connections between related nodes
- PhysicsEngine (lines 111-196): Simulates forces to position nodes naturally
- Repulsion forces: Push nodes apart to prevent overlap
- Spring forces: Pull connected nodes toward their ideal distance
- Center attraction: Keep the graph from drifting too far away
- Damping: Slow down movement for smooth, natural animation
State Management
State Management
The Key functions:
useInterestStore.ts uses Zustand for global state:src/store/useInterestStore.ts
addNode: Creates a single node with physics propertiesaddNodes: Batch creates multiple child nodes- Automatically generates links between parent and child nodes
Troubleshooting
API Key Not Working
API Key Not Working
If you see mock data instead of AI-generated topics:
- Verify your API key is correct in
.env.local - Make sure the file is named exactly
.env.local(not.env) - Restart the development server after adding the key
- Check that your API key has proper permissions in Google AI Studio
Graph Not Rendering
Graph Not Rendering
If you see a black screen without the 3D graph:
- Check browser console for WebGL errors
- Ensure your browser supports WebGL (test at get.webgl.org)
- Update your graphics drivers
- Try a different browser (Chrome and Firefox have the best WebGL support)
Slow Performance
Slow Performance
If the graph becomes laggy with many nodes:
- Close other browser tabs to free up GPU resources
- Reduce the number of nodes by refreshing the page
- Disable auto-rotate by removing
autoRotateprop inpage.tsx:58 - Lower the star count in
page.tsx:61(currently 5000)
Installation Errors
Installation Errors
If you encounter errors during
npm install:- Ensure you’re using Node.js 20 or higher:
node --version - Clear your package manager cache:
- Delete
node_modulesandpackage-lock.json, then reinstall: - Check for version conflicts in the error message
Port Already in Use
Port Already in Use
If port 3000 is already taken:
- Kill the process using port 3000:
- Or run on a different port:
Next Steps
Now that you have Intelligence Space running, explore these topics:Architecture Overview
Learn how the 3D graph, AI integration, and state management work together
Physics Engine
Understand the custom force-directed graph algorithm
3D Visualization
Explore the WebGL rendering and visual effects
API Reference
Detailed documentation of server actions and store methods