Repository for the Visualisation Enabled Search Application. It is a visual exploration and search tool that assists users in navigating through a knowledge graph in an intuitive way. Different visualisations assist in finding information across different dimensions. For example: Map → Spatial Context, Line Charts → Temporal context, Network Diagrams or graphs → interrelations, Word Cloud → Thematic context. Data is ingested from external sources into a local ArangoDB knowledge graph at setup time. All runtime queries run against the local graph — no live external calls.
[[TOC]]
You can find a list of the latest changes in the CHANGELOG
Before you begin, ensure you have the following installed on your machine:
That is the only requirement to run the full application stack.
💡 For local development without Docker You will additionally need Node.js v20+ and a locally running ArangoDB instance on port 8529.
Follow these steps to get the application running:
-
Clone the Repository:
git clone <repository-url> cd vesa2
-
Start the Application:
docker compose up --build
Docker will build and start all three services in the correct order (ArangoDB → Backend → Frontend).
| Service | URL |
|---|---|
| Frontend | http://localhost:3000 |
| Backend | http://localhost:5000 |
| ArangoDB | http://localhost:8529 |
ArangoDB credentials: root / root
💡 TIP To stop the application run
docker compose down. To also remove the database volume rundocker compose down --volumes.
On first run the database is empty. VESA2 ingests data through a local proxy API that fetches records from an external source and transforms them into the VESA Data Adapter (IDataAdapter) contract. The built-in proxies for PANGAEA and GBIF are ready-to-use examples and starting points for custom sources:
Once a proxy is running, use the Setup page in the frontend to ingest data:
- Open http://localhost:3000 and navigate to Setup
- Enter the proxy URL, a source prefix, batch size, and record limit
- Click Validate — the system fetches one record to verify the
IDataAdapterschema - Click Start Sync — data is ingested in batches into the local graph
- Once complete, the main dashboard is populated and ready to explore
💡 TIP Any proxy that returns the VESA Data Adapter (
IDataAdapter) schema integrates without any backend changes.
-
Run Backend:
cd BACKEND cp .env.template .env npm install npm run devBefore running, open the
.envfile and setARANGO_URL,ARANGO_DB_NAME,ARANGO_USER, andARANGO_PASS. -
Run Frontend:
cd FRONTEND cp .env.template .env npm install npm startBefore running, open the
.envfile and setVITE_API_URLto point to your running backend.
Whenever you encounter a 🐛 bug or have a 💡 feature request, report this via GitHub issues.
We are happy to receive contributions to VESA2 in the form of pull requests via GitHub. Feel free to fork the repository, implement your changes and create a pull request to the develop branch.
💡 Further info about Contribution Fork the repository, implement your changes, and open a pull request to the
mainbranch. Please describe the motivation and scope of your change in the PR description.
Documentation is located in the BACKEND/docs/ directory and covers API routes, AQL queries, database structure, architecture, and tests.
In the interest of an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
We are committed to making participation in this project a harassment-free experience for everyone. Contributors are expected to uphold respectful communication in all project spaces including issues, pull requests, and discussions.