NodeBallz

A browser-based, interactive node-graph visualizer and knowledge-organization tool. See the project proposal (submitted separately) for full details.

Status

Initial scaffold: routing for all five views (Login, Dashboard, Graph Canvas, Node Detail Panel, Graph Settings Modal), the force-directed canvas (react-force-graph-2d), and the Photo node type with camera capture (getUserMedia, with a file-upload fallback) are wired up and click-through-able.

The app currently runs on in-memory mock data (src/lib/mockData.js) so the UI can be built and tested before a real Firebase project exists. Swap in real Firestore/Storage calls in src/lib/graphs.js (each function has a TODO(real firebase) comment showing what to replace) once the steps below are done.

Setup

npm install
cp .env.example .env   # then fill in your Firebase project's config
npm run dev

Connect a real Firebase project

1. Create a project at https://console.firebase.google.com
2. Enable Authentication -> Email/Password
3. Create a Cloud Firestore database
4. Create a Cloud Storage bucket (for node photos)
5. Project Settings -> General -> Your apps -> add a Web app, copy the config into .env
6. Deploy the security rules in this repo:

   firebase deploy --only firestore:rules,storage:rules

Once VITE_FIREBASE_API_KEY is set, USE_MOCKS in src/firebase.js automatically flips to false and the app starts reading/writing real data.

Data model

• users/{uid}
• graphs/{graphId}
• graphs/{graphId}/nodes/{nodeId} — type: note | link | document | photo | sub-graph
• graphs/{graphId}/edges/{edgeId}
• invites/{inviteId} (stretch goal)

Photo nodes store photoUrl and upload to graphs/{graphId}/nodes/{nodeId}/photo.jpg in Cloud Storage.

Project structure

src/
  firebase.js              Firebase init (mock-mode aware)
  context/AuthContext.jsx
  lib/graphs.js             Data access layer (Firestore or mocks)
  lib/mockData.js            In-memory sample graphs/nodes/edges
  pages/Login.jsx             View 1
  pages/Dashboard.jsx         View 2
  pages/GraphCanvas.jsx       View 3 (+ toolbar, breadcrumb, side panel)
  components/NodeDetailPanel.jsx    View 4 (incl. camera capture)
  components/GraphSettingsModal.jsx View 5

Next steps (see proposal timeline)

• Create the real Firebase project, fill in .env
• Deploy firestore.rules / storage.rules
• Wire src/lib/graphs.js to real Firestore reads/writes
• Persist node drag position (x/y) on canvas
• Hierarchical sub-graph navigation polish + breadcrumb history
• Collaborator invite flow

AI assistance

Parts of this scaffold (project structure, component skeletons, Firestore/ Storage security rules) were generated with help from Claude (Anthropic). See AI_USAGE.md for prompts, responses, and how they were used.