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.

Citation

Cite the software as a whole:

Bruhn, J.-H., Helfrich, F., Kerker, N., & Rosinger, S. Constellation Analyzer [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.20085913

That DOI is the concept DOI. It always resolves to the newest release.

To cite the exact version you used, use the Cite this repository button in the sidebar. GitHub renders APA and BibTeX from CITATION.cff, which release-please keeps current. The app shows the same citation under Help → About.

License

MIT

Funding

This publication was created as part of the research program “Transforming the Energy System Lower Saxony” (TEN.efzn) at the Energy Research Center of Lower Saxony (efzn).

Funded by zukunft.niedersachsen, the joint science funding program of the Lower Saxony Ministry of Science and Culture and the Volkswagen Foundation.