backpack-viewer 0.1.3 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -67
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,94 +1,56 @@
|
|
|
1
|
-
# Backpack
|
|
1
|
+
# Backpack Viewer
|
|
2
2
|
|
|
3
|
-
A web-based graph visualizer for [backpack-ontology](
|
|
3
|
+
A web-based graph visualizer for [backpack-ontology](https://www.npmjs.com/package/backpack-ontology). Renders ontology graphs on a Canvas 2D surface with force-directed layout, interactive navigation, and live reload.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Installation
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
|
|
9
|
-
cd ../backpack-ontology && npm run build
|
|
10
|
-
|
|
11
|
-
# Install and start the viewer
|
|
12
|
-
cd ../backpack-viewer
|
|
13
|
-
npm install
|
|
14
|
-
npm run dev
|
|
8
|
+
npm install -g backpack-viewer
|
|
15
9
|
```
|
|
16
10
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
## How It Works
|
|
20
|
-
|
|
21
|
-
### Architecture
|
|
11
|
+
## Usage
|
|
22
12
|
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
│
|
|
26
|
-
Viewer (Vite plugin) ──reads via─────┘
|
|
27
|
-
│
|
|
28
|
-
HTTP API ──> Browser ──> Canvas 2D
|
|
13
|
+
```bash
|
|
14
|
+
backpack-viewer
|
|
29
15
|
```
|
|
30
16
|
|
|
31
|
-
|
|
17
|
+
Opens a browser at `http://localhost:5173` with the viewer interface. The sidebar lists all ontologies stored by backpack-ontology. Click any ontology to visualize its graph.
|
|
32
18
|
|
|
33
|
-
|
|
34
|
-
- `loadOntology(name)` — returns the full graph (nodes + edges)
|
|
19
|
+
### Navigation
|
|
35
20
|
|
|
36
|
-
|
|
21
|
+
- **Pan**: Click and drag the canvas
|
|
22
|
+
- **Zoom**: Scroll wheel or trackpad pinch
|
|
23
|
+
- **Inspect**: Click any node to view its properties, connections, and metadata
|
|
24
|
+
- **Filter**: Type in the sidebar search to filter ontologies by name
|
|
37
25
|
|
|
38
26
|
### Live Reload
|
|
39
27
|
|
|
40
|
-
|
|
28
|
+
When running alongside Claude Code with backpack-ontology, the viewer automatically detects changes to ontology data and re-renders the active graph. Add a node via MCP and watch it appear in real time.
|
|
41
29
|
|
|
42
|
-
###
|
|
30
|
+
### Environment
|
|
43
31
|
|
|
44
|
-
|
|
45
|
-
- **Nodes**: Colored circles. Colors are deterministic by node type (hash → palette). Label below, type badge above.
|
|
46
|
-
- **Edges**: Straight lines with arrowheads. Edge type label at midpoint. Self-loops rendered as small circles.
|
|
47
|
-
- **Navigation**: Mouse drag to pan. Scroll wheel to zoom. Trackpad pinch to zoom. Touch drag/pinch on mobile.
|
|
48
|
-
- **Node inspection**: Click any node to open a detail panel showing all properties, connections, and timestamps. Selected nodes glow and highlight their connected edges. Non-connected nodes dim to focus attention.
|
|
32
|
+
The viewer reads ontology data from the same location as backpack-ontology:
|
|
49
33
|
|
|
50
|
-
|
|
34
|
+
| Variable | Effect |
|
|
35
|
+
|----------|--------|
|
|
36
|
+
| `PORT` | Override the default port (default: `5173`) |
|
|
37
|
+
| `XDG_DATA_HOME` | Override data location (default: `~/.local/share`) |
|
|
38
|
+
| `BACKPACK_DIR` | Override data directory |
|
|
51
39
|
|
|
52
|
-
|
|
40
|
+
## Architecture
|
|
53
41
|
|
|
54
|
-
-
|
|
55
|
-
- **Colors**: Deterministic hash of `node.type` into a 16-color palette — no hardcoded type lists
|
|
56
|
-
- **Properties**: Iterated dynamically, never assumed to have specific keys
|
|
57
|
-
- **Edge cases**: Self-loops, multiple edges between same pair, nodes with no string properties, empty edge properties
|
|
58
|
-
|
|
59
|
-
## API Endpoints
|
|
60
|
-
|
|
61
|
-
The Vite dev server exposes two endpoints (served by the ontology-api plugin):
|
|
62
|
-
|
|
63
|
-
| Endpoint | Returns |
|
|
64
|
-
|----------|---------|
|
|
65
|
-
| `GET /api/ontologies` | `OntologySummary[]` — name, description, nodeCount, edgeCount |
|
|
66
|
-
| `GET /api/ontologies/:name` | `OntologyData` — full graph with all nodes and edges |
|
|
67
|
-
|
|
68
|
-
## Project Structure
|
|
42
|
+
The viewer connects to backpack-ontology through the `StorageBackend` interface — the same abstraction the engine uses for persistence. This means the viewer works with any storage backend (JSON files, SQLite, remote API) without modification.
|
|
69
43
|
|
|
70
44
|
```
|
|
71
|
-
backpack-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
└── src/
|
|
75
|
-
├── main.ts # Entry point, wires sidebar + canvas + live reload
|
|
76
|
-
├── api.ts # fetch() wrappers returning backpack-ontology types
|
|
77
|
-
├── sidebar.ts # Ontology list with text filter
|
|
78
|
-
├── canvas.ts # Canvas 2D rendering + pan/zoom/pinch + node selection
|
|
79
|
-
├── info-panel.ts # Node detail panel (properties, connections, timestamps)
|
|
80
|
-
├── layout.ts # Force-directed graph layout algorithm
|
|
81
|
-
├── colors.ts # Deterministic type → color mapping
|
|
82
|
-
└── style.css # Dark theme
|
|
45
|
+
backpack-ontology (MCP) ──writes──> StorageBackend
|
|
46
|
+
│
|
|
47
|
+
backpack-viewer ──reads──────────────────┘
|
|
83
48
|
```
|
|
84
49
|
|
|
85
|
-
##
|
|
86
|
-
|
|
87
|
-
- **Runtime**: `backpack-ontology` (local sibling — `StorageBackend` interface + types)
|
|
88
|
-
- **Dev**: `vite`, `typescript`
|
|
50
|
+
## Support
|
|
89
51
|
|
|
90
|
-
|
|
52
|
+
For questions, feedback, or sponsorship inquiries: **support@backpackontology.com**
|
|
91
53
|
|
|
92
54
|
## License
|
|
93
55
|
|
|
94
|
-
Apache
|
|
56
|
+
Licensed under the [Apache License, Version 2.0](./LICENSE).
|
package/package.json
CHANGED