Skip to content

explorer

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

explorer

README.md

Semantica Knowledge Explorer

A real-time visual interface for exploring knowledge graphs, decision intelligence, entity resolution, ontologies, and graph analytics built on top of the Semantica library.

Requirements

Dependency Minimum Version
Node.js 18.x or higher (20.x recommended)
npm 9.x or higher
Python 3.8+
Semantica backend running on http://127.0.0.1:8000

Check your versions:

node --version
npm --version
python --version

Quick Start (Local Development)

1. Clone the repository

git clone https://github.com/Hawksight-AI/semantica.git
cd semantica

2. Install the Semantica Python package

pip install semantica

Or install from source if you have the repo:

pip install -e .

3. Start the Semantica backend

The Explorer proxies all /api and /ws requests to http://127.0.0.1:8000. The backend must be running before you open the UI.

# From the repo root
python -m semantica.server

The backend starts on port 8000 by default. Keep this terminal open.

4. Install frontend dependencies

Open a second terminal:

cd explorer
npm install

Note: This project uses Vite 5 and requires Node 18+. If you are on Node 16 or earlier, upgrade first.

5. Start the dev server

npm run dev

Vite starts on http://localhost:5173 by default. Open that URL in your browser.

What you should see

The Explorer opens with a persistent left sidebar and six workspace tabs:

Tab What it shows
Knowledge Graph Interactive Sigma.js canvas — nodes, edges, zoom, ForceAtlas2 layout
Timeline Temporal event scrubber over the graph
Decisions Causal chain viewer with outcome badges and decision filter
Registry Live audit log of every graph mutation (add-node, add-edge, etc.)
Entity Resolution Duplicate detection and entity merge workflow
KG Overview Aggregate stats, community breakdown, centrality heatmap
Ontology SKOS/OWL vocabulary hierarchy and schema summary

Project structure

explorer/
├── src/
│   ├── App.tsx                        # Root layout, tab routing, workspace wiring
│   ├── index.css                      # Global resets, fonts, keyframe animations
│   ├── store/
│   │   └── registryStore.ts           # Pub/sub audit registry (no external state lib)
│   └── workspaces/
│       ├── GraphWorkspace/            # Sigma.js graph canvas + inspector panel
│       ├── DecisionWorkspace/         # Causal flow diagram + decision list
│       ├── TimelineWorkspace/         # vis-timeline temporal scrubber
│       ├── ManageWorkspace/           # Registry, KG Overview, Ontology tabs
│       └── EnrichWorkspace/           # Entity resolution tab
├── index.html
├── vite.config.ts                     # Dev proxy → 127.0.0.1:8000, build → ../semantica/static
└── package.json

Available scripts

Run these from inside the explorer/ directory:

# Start the dev server with hot module replacement
npm run dev

# Type-check and build a production bundle into ../semantica/static
npm run build

# Preview the production build locally
npm run preview

# Run ESLint over all source files
npm run lint

# Run the graph store multi-edge unit tests
npm run test:graph-store

API & WebSocket proxy

During development, Vite forwards requests automatically — no CORS configuration needed:

Pattern Forwarded to
/api/* http://127.0.0.1:8000/api/*
/ws ws://127.0.0.1:8000/ws

If you run the backend on a different port, update server.proxy in vite.config.ts.

Production build

cd explorer
npm run build

The compiled assets are written to ../semantica/static/. The Semantica Python server serves this folder automatically at its root URL — no separate web server needed.

Troubleshooting

Blank graph / no data loads

  • Make sure the Semantica backend is running (python -m semantica.server) before opening the UI.
  • Check the browser console for failed /api/graph requests — the proxy target may need updating in vite.config.ts.

npm install fails or hangs

  • Ensure you are using Node 18 or 20. Node 16 and Vite 5 are incompatible.
  • Delete node_modules/ and package-lock.json, then re-run npm install.

Port 5173 already in use

  • Vite will automatically try the next available port and print it in the terminal. Use that URL instead.

WebSocket not connecting (real-time mutations not appearing)

  • Confirm the backend exposes a /ws WebSocket endpoint.
  • Check browser DevTools → Network → WS tab for the connection status.

Tech stack

  • React 19 + TypeScript (strict noUnusedLocals)
  • Vite 5 with babel-plugin-react-compiler
  • Sigma.js 3 + Graphology — graph rendering and in-memory graph store
  • ForceAtlas2 — physics-based layout worker
  • @tanstack/react-query — data fetching for ontology and vocab tabs
  • vis-timeline — temporal event visualization
  • lucide-react — icon set

Contributing

See the root CONTRIBUTING.md and open issues on the main Semantica repository.