mirror of
https://github.com/semantica-agi/semantica.git
synced 2026-08-29 04:26:20 +00:00
docs(explorer): replace default Vite README with full local setup guide
Covers requirements (Node 18+/Python 3.8+), backend start command, npm install, dev server, all 6 workspace tabs, available npm scripts, API/WebSocket proxy table, production build, troubleshooting steps, and tech stack summary. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
KaifAhmad1
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
670027fd22
commit
aca15d3694
+186
-64
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user