⟡ Table of Contents
A web-based semantic network editor with a canvas-centric interaction model. Users build directed knowledge graphs by double-clicking to place nodes, dragging edges between them, and labeling relationships inline. A built-in inference engine traverses is-a hierarchies to propagate inherited relationships and surface conflicts in real time.
The backend is a Python/Flask REST API backed by NetworkX for graph logic. The frontend is pure HTML, CSS, and Vis.js — no framework dependencies. Projects are saved in a custom .snet format that bundles graph data, node positions, color palettes, and a base64-encoded canvas preview.
| Component | Details | |
|---|---|---|
| ⚙️ | Architecture | Python Flask backend with a REST API. Pure HTML/CSS/Vis.js frontend. Client-server model with CORS-enabled endpoints. Custom .snet project format stores graph state, positions, palettes, and preview images. |
| 🧠 | Inference Engine | Traverses is-a edges in the NetworkX directed graph to propagate inherited relationships from parent nodes to child nodes. Runs in both dry-run (count) and mutating modes, and reports edge conflicts to the frontend. |
| 🖱️ | Canvas Interactions | Double-click on the canvas to create a node. Single-click a node or edge to open a context menu with color swatches, link-creation, and deletion. Drag from a node to initiate "Add Relation" mode, then label the new edge inline. |
| 🗂️ | Project Management | Load from a preset grid, import a .snet file from disk, or export the current graph as a downloadable .snet file with an embedded canvas preview thumbnail. |
| 🔌 | Integrations | GitHub Actions (deploy.yml) automates Docker builds and pushes to the production VPS on every push to main. flask-cors enables cross-origin frontend-backend communication. |
| 🧩 | Modularity | Frontend JavaScript is split across focused modules: api.js (fetch calls), graph.js (Vis.js config), interactions.js (event handling), orbit.js (physics), and main.js (entry point). |
| ⚡️ | Performance | Gunicorn WSGI server for production request handling. NetworkX provides efficient in-memory graph traversal. Static HTML frontend avoids client-side framework overhead. |
└── semantic-net-visualizer/
├── .github/
│ └── workflows/
│ └── deploy.yml
├── Dockerfile
├── README.md
├── app.py
├── inference.py
├── project_manager.py
├── requirements.txt
├── semantic_net.py
├── projects/
│ ├── Animal Kingdom.snet
│ ├── Default.snet
│ └── RPG World.snet
├── static/
│ ├── style.css
│ └── js/
│ ├── api.js
│ ├── graph.js
│ ├── interactions.js
│ ├── main.js
│ └── orbit.js
└── templates/
└── index.htmlRoot
| File | Summary |
|---|---|
| app.py | Central Flask application and REST API gateway. Exposes endpoints for graph CRUD operations (/add_node, /add_relation, /remove_node, /remove_relation), inference (/inference, /check_inference), project persistence (/load, /save, /export), and static asset serving. |
| semantic_net.py | Core graph model wrapping a NetworkX DiGraph. Manages node and edge creation with arbitrary attributes (color, position, type), delegates inference to the Inference engine, and serializes graph state to the JSON schema consumed by the frontend. |
| inference.py | Ontological inference engine. Traverses is-a edges to propagate inherited relationships from parent nodes to child nodes. Exposes a dry-run count() mode and a mutating run() mode that injects inferred edges and returns detected conflicts. |
| project_manager.py | Handles .snet file I/O for the projects/ directory. Provides listing, loading, and saving of named projects, translating between the filesystem representation and the SemanticNet graph model. |
| Dockerfile | Builds a python:3.10-slim image, installs dependencies from requirements.txt, and runs the app via python -m flask run. Exposes port 4300. |
| requirements.txt | Python dependencies: flask, flask-cors, networkx, gunicorn. |
.github/workflows
| File | Summary |
|---|---|
| deploy.yml | CD pipeline triggered on push to main. SSH-connects to the production VPS, pulls the latest code, rebuilds the Docker container, and prunes unused images. |
projects/
| File | Summary |
|---|---|
| Default.snet | Bundled starter project loaded on first run. Contains a minimal sample graph demonstrating basic node/edge structure. |
| Animal Kingdom.snet | Preset semantic network modeling an animal taxonomy hierarchy, useful for demonstrating is-a inference propagation. |
| RPG World.snet | Preset semantic network modeling an RPG entity hierarchy, showcasing cross-domain relationship modeling. |
templates/ & static/
| File | Summary |
|---|---|
| templates/index.html | Single-page HTML shell. Contains the Vis.js canvas container, context menu markup, project management modal, and inference control. Loads the JS modules and links the stylesheet. |
| static/style.css | Application stylesheet. Defines canvas layout, modal overlays, context menus, and color swatch components. |
| static/js/api.js | All fetch() calls to the Flask API. Abstracts HTTP transport from UI logic. |
| static/js/graph.js | Vis.js network initialization, physics configuration, and graph rendering helpers. |
| static/js/interactions.js | Canvas event handlers: double-click to add nodes, click to open context menus, edge drag-and-label flow. |
| static/js/main.js | Application entry point. Initializes the graph and wires API calls to interaction events. |
| static/js/orbit.js | Physics and layout utilities for the Vis.js network. |
- Python 3.10+
- pip
- Docker (optional, for containerized deployment)
Option A — pip (local development)
-
Clone the repository:
git clone https://github.com/omarg-dev/semantic-net-visualizer cd semantic-net-visualizer -
Install dependencies:
pip install -r requirements.txt
Option B — Docker
-
Clone the repository:
git clone https://github.com/omarg-dev/semantic-net-visualizer cd semantic-net-visualizer -
Build the image:
docker build -t semantic-net-visualizer .
Using pip:
python app.pyThen open http://localhost:5000 in your browser.
Using Docker:
docker run -p 4300:5000 semantic-net-visualizerThen open http://localhost:4300 in your browser.
There is no automated test suite at this time. The bundled .snet preset files (Default.snet, Animal Kingdom.snet, RPG World.snet) serve as functional fixtures for manual verification of graph loading, inference, and export flows.
- Canvas-centric node/edge creation (double-click, context menus)
-
is-ainheritance inference with conflict detection - Project save, load, and export in
.snetformat with embedded previews - Preset grid with thumbnail previews
- Docker deployment with GitHub Actions CD pipeline
- Undo/redo stack (client-side JS state history)
- Node and edge rename by double-clicking
- Per-user local storage: cache project files on the client machine rather than the server, removing server-side file persistence
- Sidebar showing node list and properties
- Unsaved-changes indicator and in-place preset saving
- Custom color palette picker per project
- Real-time collaboration via Flask-SocketIO
- 💬 Join the Discussions: Share your insights, provide feedback, or ask questions.
- 🐛 Report Issues: Submit bugs or log feature requests.
- 💡 Submit Pull Requests: Review open PRs and submit your own.
Contributing Guidelines
-
Fork the Repository: Fork the project to your GitHub account.
-
Clone Locally: Clone the forked repository.
git clone https://github.com/omarg-dev/semantic-net-visualizer
-
Create a New Branch: Use a descriptive branch name.
git checkout -b feature/my-feature
-
Make Your Changes: Develop and test changes locally.
-
Commit Your Changes: Write a clear commit message.
git commit -m 'Add my feature' -
Push to GitHub: Push to your fork.
git push origin feature/my-feature
-
Submit a Pull Request: Open a PR against
main. Describe the change and its motivation clearly. -
Review: PRs are merged after review and approval.
Contributor Graph
Semantic-net-visualizer is protected under the LICENSE License. For more details, refer to the LICENSE file.
- Vis.js — network visualization library
- NetworkX — graph data structure and algorithms
- Flask — web framework
- contrib.rocks — contributor avatar grid
