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
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue