constellation-analyzer/README.md

Constellation Analyzer

A React-based visual editor for Constellation Analysis — mapping actors (nodes) and their relationships (edges) in an interactive graph.

Vibe-Warning: This is a testing ground for agent-based LLM coding. The codebase contains no hand-written code. Take it with a grain of salt.

Features

• Multi-document workspace — open multiple analyses in tabs, persist to localStorage
• Graph editor — drag-and-drop actors and relations with custom types, shapes, colors, and directionality
• Groups — cluster actors into named, collapsible groups
• Timeline / States — branching constellation states within a document (parallel scenarios or time evolution)
• Presentation mode — fullscreen view with timeline overlay for presenting analyses
• Undo / Redo — per-document history with operation descriptions
• Bibliography — citation management via Citation.js (BibTeX, RIS, DOI, CSL)
• TUIO integration — tangible token support over WebSocket/OSC for physical interaction
• Export — PNG, SVG, JSON (document), ZIP (workspace)
• Search & filters — filter graph by actor type, relation type, or label

Tech Stack

Framework	React 18.2, TypeScript 5.2, Vite 5.1
Graph	@xyflow/react 12.3
State	Zustand 4.5
UI	MUI 5.15, Tailwind CSS 3.4
Bibliography	Citation.js 0.7
TUIO	tuio-client 0.1, osc-js 2.4
Testing	Vitest 3.2, Testing Library 16.3

Getting Started

npm install
npm run dev        # http://localhost:3000
npm run build
npm run lint
npm test

Project Structure

src/
├── components/
│   ├── Config/        # Node/edge/tangible/bibliography config dialogs
│   ├── Editor/        # Main graph editor (GraphEditor.tsx)
│   ├── Edges/         # Custom edge renderers
│   ├── Menu/          # Menu bar (File, Edit, View, Help)
│   ├── Nodes/         # CustomNode, GroupNode, shape renderers
│   ├── Panels/        # Left/right side panels, property editors
│   ├── Presentation/  # Fullscreen presentation overlay
│   ├── Timeline/      # Timeline/states UI
│   └── Workspace/     # Document tabs and document manager
├── hooks/             # useGraphWithHistory, useDocumentHistory, useTuioIntegration, …
├── stores/            # Zustand stores (graph, timeline, workspace, history, bibliography, tuio, …)
├── types/             # TypeScript definitions
└── utils/             # Export, graph analysis, bibliography parsing, migrations

Development Guidelines

Graph Mutations — Always Use useGraphWithHistory

// ✅ Correct — history tracked, undo/redo works
import { useGraphWithHistory } from '../../hooks/useGraphWithHistory';
const { addNode, updateNode, deleteNode, addEdge, ... } = useGraphWithHistory();

// ❌ Wrong — bypasses history
import { useGraphStore } from '../../stores/graphStore';

Read-only access in display components (CustomNode, CustomEdge) can use useGraphStore directly.

Tests

npm run test:unit        # Store unit tests (src/stores/*.test.ts)
npm run test:integration # Integration tests (src/__tests__/integration/)
npm test                 # All tests

Always update tests when modifying store logic. See CLAUDE.md for testing patterns.

License

MIT