mirror of
https://github.com/OFFIS-ESC/constellation-analyzer
synced 2026-04-27 18:05:51 +00:00
89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`
|
|
|
|
```typescript
|
|
// ✅ 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
|
|
|
|
```bash
|
|
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
|