diff --git a/explorer/README.md b/explorer/README.md index c3c21da2..2bb6b2c4 100644 --- a/explorer/README.md +++ b/explorer/README.md @@ -1,75 +1,197 @@ -# React + TypeScript + Vite +# Semantica Knowledge Explorer -This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +A real-time visual interface for exploring knowledge graphs, decision intelligence, entity resolution, ontologies, and graph analytics built on top of the [Semantica](https://github.com/Hawksight-AI/semantica) library. -Currently, two official plugins are available: +--- -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) +## Requirements -## React Compiler +| 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` | -The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information. +Check your versions: -Note: This will impact Vite dev & build performances. - -## Expanding the ESLint configuration - -If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: - -```js -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... - - // Remove tseslint.configs.recommended and replace with this - tseslint.configs.recommendedTypeChecked, - // Alternatively, use this for stricter rules - tseslint.configs.strictTypeChecked, - // Optionally, add this for stylistic rules - tseslint.configs.stylisticTypeChecked, - - // Other configs... - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +```bash +node --version +npm --version +python --version ``` -You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: +--- -```js -// eslint.config.js -import reactX from 'eslint-plugin-react-x' -import reactDom from 'eslint-plugin-react-dom' +## Quick Start (Local Development) -export default defineConfig([ - globalIgnores(['dist']), - { - files: ['**/*.{ts,tsx}'], - extends: [ - // Other configs... - // Enable lint rules for React - reactX.configs['recommended-typescript'], - // Enable lint rules for React DOM - reactDom.configs.recommended, - ], - languageOptions: { - parserOptions: { - project: ['./tsconfig.node.json', './tsconfig.app.json'], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]) +### 1. Clone the repository + +```bash +git clone https://github.com/Hawksight-AI/semantica.git +cd semantica ``` + +### 2. Install the Semantica Python package + +```bash +pip install semantica +``` + +Or install from source if you have the repo: + +```bash +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. + +```bash +# 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: + +```bash +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 + +```bash +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: + +```bash +# 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](vite.config.ts). + +--- + +## Production build + +```bash +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](../CONTRIBUTING.md) and open issues on the main [Semantica repository](https://github.com/Hawksight-AI/semantica).