From a4e1f3ba512ef183cc3c509adebecb0c4cbba2b6 Mon Sep 17 00:00:00 2001 From: Jan-Henrik Bruhn Date: Tue, 31 Mar 2026 11:47:26 +0200 Subject: [PATCH] Fix README: localStorage not IndexedDB, port 3000 not 5173 Co-Authored-By: Claude Sonnet 4.6 --- README.md | 325 +++++++++--------------------------------------------- 1 file changed, 51 insertions(+), 274 deletions(-) diff --git a/README.md b/README.md index d68bb5d..460f487 100644 --- a/README.md +++ b/README.md @@ -1,312 +1,89 @@ # Constellation Analyzer -A React-based visual editor for creating and analyzing Constellation Analyses. Build interactive graphs to examine actors (nodes) and their relationships (edges) with a powerful drag-and-drop interface. +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. It presently does not contain hand-written code. Hence, please take the whole code-base with a grain of salt. +> **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 -- **Interactive Graph Visualization**: Built on React Flow for smooth, performant graph editing -- **Customizable Node Types**: Define and configure multiple actor types with distinct visual properties -- **Flexible Edge Types**: Create various relationship categories with different styles and colors -- **Drag-and-Drop Interface**: Intuitive node manipulation and edge creation -- **Real-time Updates**: Instant visual feedback as you build your constellation -- **Type-Safe**: Full TypeScript support for robust development -- **State Management**: Zustand for lightweight, efficient state handling -- **Responsive Design**: Tailwind CSS for modern, adaptive UI +- **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 -## Technology Stack +## Tech Stack -- **React 18.2** - UI framework -- **TypeScript 5.2** - Type safety -- **Vite 5.1** - Build tool and dev server -- **React Flow 11.11** - Graph visualization library -- **Zustand 4.5** - State management -- **Tailwind CSS 3.4** - Styling framework +| | | +|---|---| +| 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 -### Prerequisites - -- Node.js 20.x or higher -- npm 9.x or higher - -### Installation - ```bash -# Install dependencies npm install -``` - -### Development - -```bash -# Start development server (opens at http://localhost:3000) -npm run dev -``` - -### Build - -```bash -# Build for production +npm run dev # http://localhost:3000 npm run build - -# Preview production build -npm run preview -``` - -### Lint - -```bash -# Run ESLint npm run lint +npm test ``` ## Project Structure ``` -constellation-analyzer/ -├── src/ -│ ├── components/ # React components -│ │ ├── Editor/ # Main graph editor -│ │ │ └── GraphEditor.tsx -│ │ ├── Nodes/ # Custom node components -│ │ │ └── CustomNode.tsx -│ │ ├── Edges/ # Custom edge components -│ │ │ └── CustomEdge.tsx -│ │ └── Toolbar/ # Editor controls -│ │ └── Toolbar.tsx -│ ├── stores/ # Zustand state stores -│ │ ├── graphStore.ts # Graph state (nodes, edges, types) -│ │ └── editorStore.ts # Editor settings -│ ├── types/ # TypeScript definitions -│ │ └── index.ts -│ ├── utils/ # Utility functions -│ │ ├── nodeUtils.ts -│ │ └── edgeUtils.ts -│ ├── styles/ # Global styles -│ │ └── index.css -│ ├── App.tsx # Root component -│ ├── main.tsx # Entry point -│ └── vite-env.d.ts # Vite types -├── public/ # Static assets -├── index.html # HTML template -├── package.json # Dependencies -├── tsconfig.json # TypeScript config -├── vite.config.ts # Vite config -├── tailwind.config.js # Tailwind config -└── README.md # This file +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 ``` -## Usage - -### Adding Actors (Nodes) - -1. Click any of the actor type buttons in the toolbar (Person, Organization, System, Concept) -2. A new node will appear on the canvas -3. Drag the node to position it - -### Creating Relations (Edges) - -1. Click and drag from any colored handle (circle) on a node -2. Release over a handle on another node to create a connection -3. The edge will automatically appear with default styling - -### Deleting Elements - -- **Delete Node**: Select a node and press `Delete` or `Backspace` -- **Delete Edge**: Select an edge and press `Delete` or `Backspace` - -### Navigation - -- **Pan**: Click and drag on empty canvas space -- **Zoom**: Use mouse wheel or pinch gesture -- **Fit View**: Use the controls in bottom-left corner -- **MiniMap**: View overview and navigate in bottom-right corner - -## Core Concepts - -### Actors (Nodes) - -Actors represent entities in your analysis. Each actor has: -- **Type**: Category (person, organization, system, concept) -- **Label**: Display name -- **Description**: Optional details -- **Position**: X/Y coordinates on canvas -- **Metadata**: Custom properties - -### Relations (Edges) - -Relations connect actors to show relationships. Each relation has: -- **Type**: Category (collaborates, reports-to, depends-on, influences) -- **Label**: Optional description -- **Style**: Visual representation (solid, dashed, dotted) -- **Source/Target**: Connected actors - -### Node Types - -Pre-configured actor categories: -- **Person**: Individual (Blue) -- **Organization**: Company/group (Green) -- **System**: Technical system (Orange) -- **Concept**: Abstract idea (Purple) - -### Edge Types - -Pre-configured relationship categories: -- **Collaborates**: Working together (Blue, solid) -- **Reports To**: Hierarchical (Green, solid) -- **Depends On**: Dependency (Orange, dashed) -- **Influences**: Impact (Purple, dotted) - -## Customization - -### Adding New Node Types - -Edit `/src/stores/graphStore.ts`: - -```typescript -const defaultNodeTypes: NodeTypeConfig[] = [ - // Add your custom type - { - id: 'custom-type', - label: 'Custom Type', - color: '#ff6b6b', - description: 'My custom actor type' - }, -]; -``` - -### Adding New Edge Types - -Edit `/src/stores/graphStore.ts`: - -```typescript -const defaultEdgeTypes: EdgeTypeConfig[] = [ - // Add your custom type - { - id: 'custom-relation', - label: 'Custom Relation', - color: '#ff6b6b', - style: 'solid' - }, -]; -``` - -## Architecture Decisions - -### Why React Flow? -- React-native components for seamless integration -- Excellent performance with large graphs -- Rich API for customization -- Active community and maintenance - -### Why Zustand? -- Lightweight (< 1KB) -- Simple, hook-based API -- No boilerplate compared to Redux -- Perfect for graph state management - -### Why Vite? -- Lightning-fast HMR (Hot Module Replacement) -- Modern build tool with ES modules -- Optimized production builds -- Better DX than Create React App - -### Why Tailwind CSS? -- Rapid UI development -- Consistent design system -- Small production bundle (unused classes purged) -- Easy responsive design - ## Development Guidelines -### ⚠️ Important: Always Use History-Tracked Operations - -When modifying graph state in components, **always use `useGraphWithHistory()`** instead of `useGraphStore()` directly: +### Graph Mutations — Always Use `useGraphWithHistory` ```typescript -// ✅ CORRECT: Uses history tracking (enables undo/redo) +// ✅ Correct — history tracked, undo/redo works import { useGraphWithHistory } from '../../hooks/useGraphWithHistory'; +const { addNode, updateNode, deleteNode, addEdge, ... } = useGraphWithHistory(); -function MyComponent() { - const { addNode, updateNode, deleteNode } = useGraphWithHistory(); - - const handleAddNode = () => { - addNode(newNode); // Automatically tracked in history - }; -} -``` - -```typescript -// ❌ WRONG: Bypasses history (undo/redo won't work) +// ❌ Wrong — bypasses history import { useGraphStore } from '../../stores/graphStore'; - -function MyComponent() { - const graphStore = useGraphStore(); - - const handleAddNode = () => { - graphStore.addNode(newNode); // History not tracked! - }; -} ``` -**Exception**: Read-only access in presentation components (CustomNode, CustomEdge) is acceptable since it doesn't modify state. +Read-only access in display components (CustomNode, CustomEdge) can use `useGraphStore` directly. -### History-Tracked Operations +### Tests -All these operations automatically create undo/redo history entries: -- Node operations: `addNode`, `updateNode`, `deleteNode` -- Edge operations: `addEdge`, `updateEdge`, `deleteEdge` -- Type operations: `addNodeType`, `updateNodeType`, `deleteNodeType`, `addEdgeType`, `updateEdgeType`, `deleteEdgeType` -- Utility: `clearGraph` +```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 +``` -See `src/hooks/useGraphWithHistory.ts` for complete documentation. - -## Next Steps - -### Suggested Enhancements - -1. **Data Persistence** - - Save/load graphs to/from JSON - - Local storage integration - - Export to PNG/SVG - -2. **Advanced Editing** - - Multi-select nodes - - Copy/paste functionality - - ✅ Undo/redo history (implemented - per-document with 50 action limit) - -3. **Node/Edge Properties Panel** - - Edit labels and descriptions - - Change types dynamically - - Add custom metadata - -4. **Layout Algorithms** - - Auto-arrange nodes - - Hierarchical layout - - Force-directed layout - -5. **Analysis Tools** - - Calculate graph metrics - - Find shortest paths - - Identify clusters - -6. **Collaboration** - - Real-time multi-user editing - - Version control - - Comments and annotations - -## Contributing - -This is a new project. Contributions are welcome! +Always update tests when modifying store logic. See `CLAUDE.md` for testing patterns. ## License MIT - -## Support - -For issues and questions, please open an issue on the repository.