mirror of
https://github.com/OFFIS-ESC/constellation-analyzer
synced 2026-04-27 18:05:51 +00:00
Fix README: localStorage not IndexedDB, port 3000 not 5173
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
ebe2d4b493
commit
a4e1f3ba51
1 changed files with 51 additions and 274 deletions
325
README.md
325
README.md
|
|
@ -1,312 +1,89 @@
|
||||||
# Constellation Analyzer
|
# 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
|
> **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.
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Interactive Graph Visualization**: Built on React Flow for smooth, performant graph editing
|
- **Multi-document workspace** — open multiple analyses in tabs, persist to localStorage
|
||||||
- **Customizable Node Types**: Define and configure multiple actor types with distinct visual properties
|
- **Graph editor** — drag-and-drop actors and relations with custom types, shapes, colors, and directionality
|
||||||
- **Flexible Edge Types**: Create various relationship categories with different styles and colors
|
- **Groups** — cluster actors into named, collapsible groups
|
||||||
- **Drag-and-Drop Interface**: Intuitive node manipulation and edge creation
|
- **Timeline / States** — branching constellation states within a document (parallel scenarios or time evolution)
|
||||||
- **Real-time Updates**: Instant visual feedback as you build your constellation
|
- **Presentation mode** — fullscreen view with timeline overlay for presenting analyses
|
||||||
- **Type-Safe**: Full TypeScript support for robust development
|
- **Undo / Redo** — per-document history with operation descriptions
|
||||||
- **State Management**: Zustand for lightweight, efficient state handling
|
- **Bibliography** — citation management via Citation.js (BibTeX, RIS, DOI, CSL)
|
||||||
- **Responsive Design**: Tailwind CSS for modern, adaptive UI
|
- **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
|
| Framework | React 18.2, TypeScript 5.2, Vite 5.1 |
|
||||||
- **React Flow 11.11** - Graph visualization library
|
| Graph | @xyflow/react 12.3 |
|
||||||
- **Zustand 4.5** - State management
|
| State | Zustand 4.5 |
|
||||||
- **Tailwind CSS 3.4** - Styling framework
|
| 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
|
## Getting Started
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- Node.js 20.x or higher
|
|
||||||
- npm 9.x or higher
|
|
||||||
|
|
||||||
### Installation
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install dependencies
|
|
||||||
npm install
|
npm install
|
||||||
```
|
npm run dev # http://localhost:3000
|
||||||
|
|
||||||
### Development
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Start development server (opens at http://localhost:3000)
|
|
||||||
npm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
### Build
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Build for production
|
|
||||||
npm run build
|
npm run build
|
||||||
|
|
||||||
# Preview production build
|
|
||||||
npm run preview
|
|
||||||
```
|
|
||||||
|
|
||||||
### Lint
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Run ESLint
|
|
||||||
npm run lint
|
npm run lint
|
||||||
|
npm test
|
||||||
```
|
```
|
||||||
|
|
||||||
## Project Structure
|
## Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
constellation-analyzer/
|
src/
|
||||||
├── src/
|
├── components/
|
||||||
│ ├── components/ # React components
|
│ ├── Config/ # Node/edge/tangible/bibliography config dialogs
|
||||||
│ │ ├── Editor/ # Main graph editor
|
│ ├── Editor/ # Main graph editor (GraphEditor.tsx)
|
||||||
│ │ │ └── GraphEditor.tsx
|
│ ├── Edges/ # Custom edge renderers
|
||||||
│ │ ├── Nodes/ # Custom node components
|
│ ├── Menu/ # Menu bar (File, Edit, View, Help)
|
||||||
│ │ │ └── CustomNode.tsx
|
│ ├── Nodes/ # CustomNode, GroupNode, shape renderers
|
||||||
│ │ ├── Edges/ # Custom edge components
|
│ ├── Panels/ # Left/right side panels, property editors
|
||||||
│ │ │ └── CustomEdge.tsx
|
│ ├── Presentation/ # Fullscreen presentation overlay
|
||||||
│ │ └── Toolbar/ # Editor controls
|
│ ├── Timeline/ # Timeline/states UI
|
||||||
│ │ └── Toolbar.tsx
|
│ └── Workspace/ # Document tabs and document manager
|
||||||
│ ├── stores/ # Zustand state stores
|
├── hooks/ # useGraphWithHistory, useDocumentHistory, useTuioIntegration, …
|
||||||
│ │ ├── graphStore.ts # Graph state (nodes, edges, types)
|
├── stores/ # Zustand stores (graph, timeline, workspace, history, bibliography, tuio, …)
|
||||||
│ │ └── editorStore.ts # Editor settings
|
├── types/ # TypeScript definitions
|
||||||
│ ├── types/ # TypeScript definitions
|
└── utils/ # Export, graph analysis, bibliography parsing, migrations
|
||||||
│ │ └── 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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
|
## Development Guidelines
|
||||||
|
|
||||||
### ⚠️ Important: Always Use History-Tracked Operations
|
### Graph Mutations — Always Use `useGraphWithHistory`
|
||||||
|
|
||||||
When modifying graph state in components, **always use `useGraphWithHistory()`** instead of `useGraphStore()` directly:
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// ✅ CORRECT: Uses history tracking (enables undo/redo)
|
// ✅ Correct — history tracked, undo/redo works
|
||||||
import { useGraphWithHistory } from '../../hooks/useGraphWithHistory';
|
import { useGraphWithHistory } from '../../hooks/useGraphWithHistory';
|
||||||
|
const { addNode, updateNode, deleteNode, addEdge, ... } = useGraphWithHistory();
|
||||||
|
|
||||||
function MyComponent() {
|
// ❌ Wrong — bypasses history
|
||||||
const { addNode, updateNode, deleteNode } = useGraphWithHistory();
|
|
||||||
|
|
||||||
const handleAddNode = () => {
|
|
||||||
addNode(newNode); // Automatically tracked in history
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// ❌ WRONG: Bypasses history (undo/redo won't work)
|
|
||||||
import { useGraphStore } from '../../stores/graphStore';
|
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:
|
```bash
|
||||||
- Node operations: `addNode`, `updateNode`, `deleteNode`
|
npm run test:unit # Store unit tests (src/stores/*.test.ts)
|
||||||
- Edge operations: `addEdge`, `updateEdge`, `deleteEdge`
|
npm run test:integration # Integration tests (src/__tests__/integration/)
|
||||||
- Type operations: `addNodeType`, `updateNodeType`, `deleteNodeType`, `addEdgeType`, `updateEdgeType`, `deleteEdgeType`
|
npm test # All tests
|
||||||
- Utility: `clearGraph`
|
```
|
||||||
|
|
||||||
See `src/hooks/useGraphWithHistory.ts` for complete documentation.
|
Always update tests when modifying store logic. See `CLAUDE.md` for testing patterns.
|
||||||
|
|
||||||
## 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!
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT
|
MIT
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
For issues and questions, please open an issue on the repository.
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue